LayerFSv1.1.0 releases

Mainline for LayerFS

previewv0.1.0

Git-native engineering memory for coding agents in LayerFS Workspaces.

Mainline contributors · for Mainline

#agents#memory#git#workspaces#multi-agent

Install

Paste this into a coding agent on the machine that will run it. It installs v0.1.0 at 2c146816d4 with LayerFS v1.1.0 at 9f97a7ec95, the commit it was tested with. It runs the author’s build, so read it first.

Install prompt · v0.1.0
Install Mainline for LayerFS 0.1.0 for me.

1. Check for Node 20+, npm 10+, Git and Go 1.22+. Choose two fresh sibling folders:
   `mainline` and `layerfs`. Preserve existing checkouts and local changes; if those
   names are already occupied, inspect them and ask before changing their contents.
2. Clone https://github.com/mainline-org/mainline as `mainline` and check out exactly 2c146816d4bc0d88c85138ed8f63bdcb128f6d38, detached.
   Clone https://github.com/Ephemeral-AI-Lab/layerfs as the sibling `layerfs` and check
   out exactly 9f97a7ec95b662e9cb288704afa165feff132cfa (v1.1.0), detached. Verify both HEADs,
   that Mainline's `layerfs.json` contains the same LayerFS SHA, and both checkouts
   are clean. Do not substitute branches, latest releases or different commits.
3. Read `mainline/plugins/layerfs/README.md`, especially Install, host preparation,
   settings, refusal handling and the verification limits. Read the pinned LayerFS
   `api/README.md`, `api/how-to-use/agent.md`, `api/how-to-use/runtime.md`, and the
   plugin's `skills/mainline-layerfs/SKILL.md` and `skills/layerfs-js-sdk/SKILL.md`.
4. From the Mainline root run `npm --prefix plugins/layerfs ci --offline`. Its hooks
   must verify the pinned clean LayerFS checkout, the installed package sources and
   one shared agent SDK. Leave the LayerFS checkout unchanged. Run
   `node plugins/layerfs/bin/mainline-layerfs --help` and the installed official
   `layerfs` command's help. On Unix add `plugins/layerfs/bin` and
   `plugins/layerfs/node_modules/.bin` to this agent session's PATH; on Windows use
   Node for the adapter entry point and the official CLI's `.cmd` shim.
5. Install the three bundled skills into a fresh directory the agent can load:
   `npm --prefix plugins/layerfs run install-skills -- /absolute/path/to/fresh-skills`.
   Choose that path from the agent's actual configuration; preserve existing skills.
   Read the installed Mainline skill and follow its context and authorization rules.
6. Run `npm --prefix plugins/layerfs test`. These tests build the real Mainline CLI
   and use public-client stand-ins and temporary Git repositories. They require no
   Docker, Store, daemon or native addon. Report them as adapter tests, not proof of
   real LayerFS/FUSE execution.
7. Inspect the host's existing `LAYERFS_*` configuration. Ask for missing project,
   Sandbox, task Branch or deployment settings instead of guessing them. The host
   supplies the pinned bundle/native artifacts and a Sandbox image with Linux
   Mainline, Git, Bash, coreutils and findutils. Follow the README's Dockerfile steps
   only if an image extension is needed and the base image and architecture are known.
   Use an independent actor identity and a complete standalone Git repository.
8. On Linux use the configured local Store mount in the calling process. On macOS
   or Windows use the host's `LAYERFS_WORKER_ENDPOINT`, or use
   `mainline-layerfs launch --` with the agent executable and its arguments. The
   launcher maps the README's `LAYERFS_*` settings to the public runtime options,
   starts the worker once and keeps it alive until the agent exits. Agents call only
   the public agent SDK or the official `layerfs` command.
9. Once the host is configured, execute one explicit `mainline-layerfs run` preflight
   against the supplied project, Sandbox and task Branch, or the README's opt-in
   smoke command. Inspect Mainline's readiness and authority fields as well as the
   exit code, checkpoint and cleanup result. If the host is not ready, report which
   verification was not run and what settings are missing.

Report both pinned commits, commands run, results, installed skill paths and runtime
verification limits. If anything fails, stop and give me the exact error; never
retry or replay a LayerFS operation, force-commit, discard unresolved changes,
restart a worker or create a replacement Sandbox automatically.

What it adds

Mainline lets coding agents read and record the engineering judgment behind code: goals, decisions, rejected approaches, validation and the Git commits carrying the work. This adapter brings that existing workflow into LayerFS Workspaces.

  • mainline-layerfs run executes Mainline in the task’s Linux Workspace and returns its original output, exit code and LayerFS checkpoint.
  • mainline-layerfs launch keeps a macOS or Windows worker alive while the agent runs, and supplies LAYERFS_WORKER_ENDPOINT to the child.
  • Offline installation includes Mainline’s skill, the integration skill, the pinned LayerFS SDK skill with its references, and the official Bash layerfs command.

How it works

Each run opens the existing project, mounts the supplied task Branch in a known Sandbox, executes one Mainline command, checkpoints the Workspace and attempts to unmount it. The complete .git directory and .ml-cache travel with the task tree, so Git refs, notes and local drafts survive the next fresh Workspace.

Mainline continues to use its existing CLI and Git storage format. Agents explicitly choose when to start, append, commit, seal and publish, following Mainline’s skill and the user’s authorization. A completed command’s changes are checkpointed even when its exit code is nonzero. A LayerFS refusal preserves its original error and any cleanup errors; no operation is automatically retried or replayed.

Linux Store calls run in the calling process with its local Store mount. macOS and Windows calls use the existing host’s worker endpoint or the included runtime launcher. On Windows the launcher owns the worker until the agent child exits.

You need

  • Node 20+, npm 10+ and Git; Go 1.22+ to run the default integration test.
  • The pinned LayerFS checkout beside the Mainline checkout. The plugin lives under plugins/layerfs/; its install scripts verify exact source identity and one copy of the agent SDK without changing the LayerFS checkout.
  • A configured LayerFS host, project and running Sandbox. The Sandbox image needs Linux Mainline, Git, Bash, coreutils and findutils. The plugin provides an example Dockerfile for extending an existing LayerFS image.
  • A complete standalone Git repository in the project, a task Branch and a distinct Mainline actor identity for each independent agent. The adapter rejects external .git pointers, alternate object stores and symlinks inside Git metadata.

The pinned Install instructions cover dependencies, skills, worker settings, commands and the optional real-host smoke test.

Verification

The preview’s 29 adapter tests pass without Docker, using public-client stand-ins, real subprocesses and a freshly built Mainline CLI in temporary Git repositories. They cover literal arguments and stdin, refusals and cleanup, worker routing and lifetime, skill distribution, and draft/seal/actor-ref/notes persistence across new Workspaces. Mainline’s existing quick tests and hygiene checks also pass. The Node 20 CI run checks the published plugin commit.

Real LayerFS Docker/FUSE execution and live workers were not exercised for this preview: the build environment lacked a configured bundle, Store and worker endpoint. Platform routing and worker ownership were checked with stand-ins.

Limits

  • One agent owns each task Branch and executes its commands sequentially. Independent LayerFS Branches do not participate in Mainline’s linked-Git-worktree discovery.
  • Shared sealed intents use Mainline’s existing Git remote and refs/notes sync; unshared drafts remain in their task Branch. Combine code through the Git workflow; last-writer-wins merging of .git can lose refs or corrupt metadata.
  • Inputs are limited to 64 KiB; each Mainline execution has a 110-second timeout and five-second termination grace. --cwd is rejected to retain the project root.
  • A refused cleanup can leave a Workspace mounted for inspection. Conflict, Busy, NoSuchSandbox, Capacity and uncertain outcomes require caller judgment; the adapter does not force-commit, discard, restart a worker or replace a Sandbox.

Versions

Each version pins the plugin’s commit and the LayerFS release and commit it was tested with.

VersionDatePlugin commitLayerFS
v0.1.0newestInitial adapter, worker launcher and agent skills; 29 tests pass without Docker.2026-10-252c146816d4v1.1.0 @ 9f97a7ec95