agentleFS
LatandLatand/delegatus/AGENTS.md

delegatus

AGENTS.md39 starsChanged 4 days agoMITView on GitHub

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices. <!-- END:nextjs-agent-rules --> # The product is Delegatus This repository is Delegatus, called Agent Log Viewer before the rename (docs/design/rename-delegatus.md). Text a person or an agent reads names it Delegatus. In code, and in these notes, "the Viewer" still names the web server process as distinct from the runtime…

  • Reads credentials
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository6 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Only then the disk-dependent resolvers, as fallbacks:

    line 37
  2. Distinctive:

    When adding a new agent/worktree layout: prefer a pure path recognizer beside

    line 64
  3. Distinctive:

    Run git config core.hooksPath .githooks once per clone.

    line 90
  4. Distinctive:

    After a type, lint or test refusal, a settled producer repair can return to a fresh producer attempt automatically.

    line 148
  5. Very specific:

    When ~/.config/delegatus/gate-runner.json exists under the account's passwd home ({"ssh": "<alias>"}), a top-level scripts/gate-slot.sh …

    line 160
  6. Very specific:

    Every long-lived listener in the runtime host attaches its error handler to a connection before the first byte can be written to it.

    line 300
  7. Very specific:

    When you add a process that legitimately owns live state, give it an owner token at its entry point (see bin/cli.mjs, …

    line 445

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md
<!-- BEGIN:nextjs-agent-rules -->

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

<!-- END:nextjs-agent-rules -->

The product is Delegatus

This repository is Delegatus, called Agent Log Viewer before the rename (docs/design/rename-delegatus.md). Text a person or an agent reads names it Delegatus. In code, and in these notes, "the Viewer" still names the web server process as distinct from the runtime host, and the MCP server keeps the key viewer, so its tools stay mcp__viewer__*.

<!-- BEGIN:worktree-grouping -->

Worktree → project grouping (canonical — do not re-break)

Agents run tasks inside worktree checkouts. Every session that runs from a worktree MUST group in the sidebar under its parent repo's project — never as its own lookalike project. This is one algorithm, enforced in src/lib/scanner/describe.ts by projectInfoFromCwd(cwd), which resolves the parent repo by trying these recognizers in order:

The pure path recognizers run first — they need nothing on disk, so they work identically for live and deleted checkouts:

  1. projectInfoFromClaudeTaskCwd — Claude scratchpad descendants at <tmp>/claude-<uid>/<encoded-cwd>/<session>/scratchpad/…; dotted worktree containers survive in the encoded cwd and recover the parent project.
  2. worktreeFromPath — Claude worktrees at <repo>/.claude/worktrees/<name>/…
  3. worktreeFromNested — the git worktree add worktrees/<name> (and dotted .worktrees/<name>) convention: the checkout nests inside the repo, so the repo is the path prefix before the first worktrees/.worktrees segment; specialized .claude/.codex containers are left to #2/#4. The first container wins, so a worktree-of-a-worktree groups under the outermost repo.
  4. worktreeFromCodexPath — Codex worktrees at ~/.codex/worktrees/<hash>/<Repo>

Only then the disk-dependent resolvers, as fallbacks:

  1. worktreeFromGitFile — any linked git worktree, resolved from its .git file (gitdir: pointer) — works only while the checkout exists on disk. Every live resolution here is written to a persistent map (below).
  2. worktreeFromMemory — replays a worktreeFromGitFile resolution recorded (to state/worktree-map.json) while the checkout was alive. This is the only thing that saves an arbitrary-path git worktree add ../sibling checkout (e.g. ~/.agents/tools/live-log-viewer-<branch>), which has NO recognizable path layout, once it is deleted. Consulted only when no path recognizer matched and the cwd is gone. Automatic recovery of older directory projects supplies the same lookup with atomic recovery rows in state.sqlite; those rows commit their mappings, aliases, board migration and lifecycle reason together. Recovery runs at Viewer startup under the release fence and after a complete catalog rescan. A recorded mapping, agreeing native repository hint or branch hint confirmed against refs must prove the match; a sibling name alone never folds, and conflicts or ambiguity keep the project separate.

The invariant that keeps biting: a worktree's grouping must survive the checkout being deleted. Any mapping that finds the parent repo only by reading on-disk git metadata (#5) silently fails afterward and the session fragments into a phantom lookalike project (-codex-worktrees-<hash>-<Repo>, …-Projects-<Repo>-worktrees-<name>, …-<branch>, …). Recognize each layout by path (#1–#4) wherever the path reveals the repo; fall back to the persisted resolution (#6) only for arbitrary sibling paths that cannot. Live and dead checkouts of the same repo must resolve to the same project name.

When adding a new agent/worktree layout: prefer a pure path recognizer beside #1–#4 and wire it into projectInfoFromCwd; only reach for the persisted map when the path genuinely cannot name the repo. Add a "deleted worktree still groups under its parent repo" case to describe.test.ts. Don't rely on the checkout being present, and don't invent a second naming scheme.

The same folder can change key over time. A plain folder is dir-<path>, a repository with no origin is repo-<local path>, and the same repository once an origin is added is repo-<remote>. Anything recorded before the move (an orchestrator seat, its tasks and conversations) keeps the old key while new pipelines get the new one. src/lib/projects/succession.ts records that move once as an alias in the same map canonicalProject reads, and only for a path-derived source verified against the folder. It runs on scan, at seat tick boot and sweep, and at designation. A remote change is aliased only when the forge proves a rename: src/lib/projects/forgeRename.ts asks GitHub for the old and the new name, and only the same numeric repository id joins them. The old remote comes from state/project-remotes.json, which each machine fills with the remote behind every repository key it resolves, because a key's hash cannot be reversed. A re-pointed origin (a fork, an unrelated repository) is never aliased, and neither is a remote this machine never recorded, because every clone shares a remote id. Shared recorded GitHub remotes also check the forge's current full name once per key per 24 hours, so an unchanged clone origin canonicalizes only after matching numeric repository ids prove the rename.

<!-- END:worktree-grouping --><!-- BEGIN:live-state-and-publication -->

Local hooks mirror the publication gate

Run git config core.hooksPath .githooks once per clone. Worktrees inherit that config and run the hooks from their own checkout. Pre-commit runs staged whitespace and eslint. Pre-push scans each commit's added lines with three lines of context, each new binary blob, messages and identities, using the committed fingerprints and supplied learned-rule texts. The hosted privacy check keeps whole-file coverage. Pre-push checks commit publication, types, changed-file lint, touched tests, and scoped Linux, pinned Bun runtime, native Codex and supply-chain gates. Tests and builds use isolated state roots; heavy commands go through scripts/gate-slot.sh.

For a manual privacy check, run bun scripts/privacy-publication-gate.ts --require-known-values --check-commits --base origin/main. The command defaults to the committed scripts/privacy-known-value-fingerprints.json beside the gate. LLV_PRIVACY_KNOWN_VALUE_FINGERPRINTS_FILE overrides that catalog; an empty value disables the default and still requires another known-value source.

Touched tests run the branch first, up to eight explicit head files at once, each with fresh state, HOME and TMPDIR under the OS temp root. Only files failing on the branch are sampled on the merge base with origin/main, filtered to the failing assertions; runner errors require the full file. A green branch needs no baseline checkout. Only complete baseline assertion samples with two matching fresh observations are cached for 24 hours; diagnostics and confirmation rounds always run fresh. Only new failures block; output retains pre-existing failures, describe ancestry, test names and between-tests errors. An incomplete baseline for a red branch blocks unless both sides are broken the same way, which lists as pre-existing. Samples report elapsed time. Budgets are five minutes per file and fifteen minutes per baseline/head test run. Privacy and isolated checks run concurrently and use the same publication budget as the pipeline's publisher: changes to the pipeline engine source/test family, git.ts or parkedPublication.test.ts get 25 minutes for the push, including one minute for the pack; other changes retain 15 minutes. An explicit caller deadline remains authoritative. The shared rule is src/lib/pipelines/gateBudget.ts. Both must pass; a refusal or timeout stops the peer and waits for owned process cleanup. Privacy retains its refusal text and exit behaviour. Pre-push takes one admission for independent types/lint, test, runtime and native lanes. Pre-commit lint on up to 40 files needs no admission. Privacy, types and ESLint retain their own checks. A push with no changed file against the merge base runs privacy with --check-commits and nothing else; a prose-only push (.md, .mdx, .txt) skips types; scoped Linux tests are compared against the merge base like touched tests. A pipeline's publication runs this hook without the Viewer's own settings (pipelinePublicationHookEnv): on 2026-10-04 the Viewer's LLV_LANG reached a CLI test through the hook and parked five lanes that had changed nothing. A publication stopped only by an execution deadline retries after 1, 5 and 15 minutes, then parks after those three retries with the cause on its first line. CPU admission waits do not spend the check budget, including the handoff into the admitted hook process. A named failing assertion, another failed check or failed cleanup keeps the refusal decisive. Comparator budget exhaustion retains green file checkpoints for automatic retries, and a privacy report containing only configuration_error retries as an interruption when changed paths are known and exclude scripts/privacy-* and scripts/generate-privacy-*. A refused publication of an unchanged head retries after 1, 5 and 15 minutes, then parks with the cause on its first line. A push interrupted by a signal or a stopped Viewer before it reached the remote is counted the same way, whatever the stage changed. A refusal of a head that changes files, or of commits privacy refused, gets one repair turn from the producer that wrote them; its park keeps the cause on the first line. After a type, lint or test refusal, a settled producer repair can return to a fresh producer attempt automatically. The lane permits two fresh repair attempts across controller restarts. retry-stage uses the same repair path once the earlier turn has settled; the original pass and accepted commits stay recorded. Active turns, queued deliveries and live background work fence the replacement. See docs/design/publication-producer-repair.md. LLV_SKIP_HOOKS=1 is the escape hatch for a false positive. Pre-push warns if the branch is behind origin/main. Missing local media tools defer named media files to the required CI OCR gate. See CONTRIBUTING.md for slot settings.

Heavy commands may run on the gate runner

When ~/.config/delegatus/gate-runner.json exists under the account's passwd home ({"ssh": "<alias>"}), a top-level scripts/gate-slot.sh call from a git work tree or a review export with its export.json runs on that SSH host instead of here (docs/design/remote-gate-runner.md, scripts/gate-runner/): the hook's admitted checks, bun test, bunx tsc, local-gate-tests.ts, eslint-changes.ts and the three browser test drivers. Privacy, fetch, push, pre-commit, builds, the board geometry capture and everything else stay here. The client ships the exact working tree as a git bundle after the tree's own privacy scan, and the runner starts nothing unless it reproduces the same tree id. Its lines start with gate-runner:. running here: <reason> means the command ran on this machine as before; a run that started there and lost its end record exits 75 with gate-runner: no verdict: …, which the publication retries, and gates then stay here for 30 minutes. LLV_GATE_RUNNER=off keeps one command here, and a campaign that measures this machine's gates must set it; isolatedEnvironment sets it for every isolated check. Decisions are logged to ~/.cache/delegatus-gate/runner-decisions.log under the passwd home.

Two ways to do real damage here (both happened, 2026-07-24)

Never run this repo's suites against the operator's live state

bun test src/lib/agent/ src/app/api/runtime/ and anything else that sweeps whole runtime/registry directories exercises host lifecycle code against the shared registry under $XDG_CONFIG_HOME/agent-log-viewer/state. Running it on the operator's machine killed the structured host that owned the session the operator was talking to. Their composer started answering structured host ownership is unavailable and they had to recover the conversation by pasting an attach command into a terminal.

Stages run, by path, only the test files their change touches. They run no bunx tsc --noEmit, no full test suite and no bun run build unless the stage brief explicitly names that check. The pre-push at publication is the one full check; the nightly workflow runs the full test suite on main. Any check the brief names still needs an isolated state directory. The same applies to any command that enumerates and acts on runtime processes — pgrep -f <pattern> matches your own command line too.

The shipped role prompts tell a stage agent to isolate "any state-directory variable the project's instruction files name". Here that is LLV_STATE_DIR: besides HOME, XDG_CONFIG_HOME and TMPDIR, isolate LLV_STATE_DIR for every test run.

This repository is public — publication surfaces carry no identities

Docs, issues, PR bodies, commit messages, fixtures, and test data are public the moment they are pushed. Never put an account handle, email, account id, token, or absolute home path into any of them, including evidence tables pasted from a live investigation. Distinguish accounts as "account A / account B" with their plan tier, and keep paths repo-relative or $HOME-relative.

One exemption, and only in a trailer: a Co-Authored-By: / Signed-Off-By: whose address has the local part exactly noreply or no-reply names a tool and identifies nobody, so agent attribution stays and the gate passes it (MACHINE_ATTRIBUTION_TRAILER). It is the standing attribution trailer on agent-written commits here — do not strip it, from your own commit or anyone else's. The exemption is that narrow on purpose: a GitHub users.noreply address reads as a no-reply address and is an account handle with a number in front of it, and the same address written into prose is not attribution, so both are still violations.

The identity git records on a commit is read by a separate rule. A squash merge composes those identities into a Co-authored-by: trailer on the default branch, and there an address on the users.noreply host of the forge passes: the forge issues it so an account's own address is not what its commits carry. That reading is the merge boundary only — it changes nothing about what you may write into a message, a doc or a fixture, where the paragraph above still holds.

privacy-publication on CI uses the committed scripts/privacy-known-value-fingerprints.json from its trusted checkout. The local hooks use the same fingerprints with --require-known-values. The required CI checks stay as enforcement for skipped hooks and media OCR. Scrub before the push, and re-read every table and quote lifted out of logs.

<!-- END:live-state-and-publication --><!-- BEGIN:runtime-host-verification -->

Two processes run under Bun here, and only one of them was ever checked

The Viewer and the runtime host (src/runtime-host/) both run under the Bun pinned in the Dockerfile. The runtime host owns the stable listener and performs the release succession, so when it crash-loops, that is an outage no Viewer health check can see. Moving the pin to 1.4.0 was verified thoroughly and only on the Viewer; the host had never been started under the new runtime when it was promoted, and it died on its first failing socket write (#1254).

A change to a Bun pin is not verified until the runtime host has run under it. Before such a change is proposed for promotion, run:

bun scripts/verify-runtime-host.ts --runtime <the bun binary being pinned>

It starts two runtime-host generations under that interpreter, drives one singleton-fence succession, and holds both endpoints the succession handed over while peers come and go — in a private state directory on an ephemeral port, never the stable one. Half the callers walk away mid-answer without reading a byte of a snapshot-sized reply, which is the write that took production down: run against the host as it was, the rehearsal kills it within a second under 1.4.0 and passes under 1.3.3, exactly as the incident did. The same rehearsal runs inside a container built from the candidate image during verify-candidate, so a candidate whose host cannot boot, cannot take the fence, or cannot hold what it took is refused before promotion rather than after.

Both halves run on every PR into main and nightly on main, under the pin read from the Dockerfile. CI dispatch also runs both unless native_queue_campaign is enabled. The stable runtime-gate context waits for bun-runtime and native Codex on the newest reviewed pin for ordinary PRs. For batch/* PRs into main, nightly runs, main pushes and dispatches without that campaign, it waits for bun-runtime and the full three-version native Codex window. Locally they run when Dockerfile, src/runtime-host/** or bin/** changes. After this workflow lands, the seat adds runtime-gate to main branch protection; older PRs need a new push or reopen. scripts/verify-viewer-runtime.ts loads every compiled server runtime, then serves the build and requires GET / to answer 200. scripts/verify-runtime-host.ts drives two runtime-host generations through succession and holds both endpoints. Held verdict tests cover their red paths; the dispatch job also runs the induced end-to-end failure controls. A moved pin must exercise both processes locally before publication. The image's in-container rehearsal under bun-container remains in verify-candidate before promotion. Docker images still build and publish on main and v* tags; PRs build only when image install, build or runtime inputs change.

verify-candidate also runs the candidate performance gate (src/runtime-host/candidatePerformanceRun.ts, bounds and reasons in docs/design/candidate-performance-gate.md) in another throwaway container, from the candidate-gate image (the candidate plus Chromium, never served): a synthetic registry of 53,299 rows of retained history, two Viewer releases as their own processes, live workers handed from one to the other through the real demotion and startup adoption, two concurrent writers, eight board scopes, and then eight Chromium views of the candidate's own production build while two writers run. Duration thresholds are diagnostic warnings. A missing measurement, a missing report or a successor that fails refuses the candidate and the serving release keeps serving. Run it locally with bun scripts/verify-viewer-runtime.ts --performance after bun run build, with CHROME_BIN set; an empty registry proves nothing about a release that has to read history.

Three consequences worth keeping:

  • A failing socket write is a connection event, never a process event. Every long-lived listener in the runtime host attaches its error handler to a connection before the first byte can be written to it. Bun 1.3.3 dropped failed writes silently, which is why the missing handlers survived so long; 1.4.0 reports them, and an unhandled error on a connection kills the process that owns 8898. Tests must not paper over this: a test harness that attaches its own listener to each accepted connection hides exactly the defect the production server has.
  • Verification has to name the process it exercised. "Loaded every built server module and requested real routes" is a statement about the Viewer. Say which process, or the gap comes back.
  • Inside the image, the interpreter is bun-container. bun there is an nsenter shim onto the operator's own bun, for the agent CLIs; in a container without the host PID namespace it cannot run at all, and it is never the interpreter being promoted. Anything that starts a first-party process inside the image names bun-container, and the rehearsal passes that name down to the generations it starts.
<!-- END:runtime-host-verification -->

The runtime host is this repository's critical runtime: changes to it, to deploys and to the Bun pin are high risk and take three review rounds.

macOS runs the SQLite Apple ships: first-party SQL compiles on 3.39

On macOS bun:sqlite loads the system SQLite (3.39.5 on macOS 13, the oldest macOS Bun supports; 3.43.2 on 14 and 15). On Linux and Windows Bun links its own newer SQLite, so SQL that needs 3.42+ (subsec), 3.44+ (aggregate ORDER BY, concat) or 3.45+ (jsonb_*) passes every local check and fails only on a user's Mac. Releases 1.13.0 to 1.15.0 shipped such triggers and stopped macOS installs from starting. src/lib/state/minimumSqlite.test.ts builds 3.39.4 from the official amalgamation and runs the state store on it. --preload ./src/lib/state/minimumSqlite.preload.ts runs any other suite on it. The Minimum macOS SQLite job in platform-tests.yml does both. A schema statement the running SQLite cannot compile is never treated as a corrupt database (src/lib/state/schemaCompatibility.ts, docs/design/state-sqlite-migration.md §7.4).

Host deploy command and team authentication

scripts/rebuild.sh [full-commit-sha] uses scripts/rebuild-http.ts for both admission and status polling. The client reads the existing host control key to authenticate as controller, plus the Viewer access key when required. It creates no key, sends no member cookie or agent identity, validates and pins a resolved loopback address, and refuses redirects. Keep secrets inside that process and out of arguments and output. Tests run the real command against an isolated port-0 server; never use a live installation for a regression test.

A Deployer working on a Delegatus checkout install reads docs/deploy-checkout.md and runs the committed scripts/deploy-checkout.py procedure with its private plan: preflight first, then its detached start after approval; it writes no replacement switch script. After the restart it reads deploy-verdicts/latest-<install-id>.json and the named run's verdict.json. A restart submission error or an exited old PID is an observation to reconcile; the final serving identities and protected work are judged from the procedure's verdict.

Tests must check behaviour; never check prompts, instructions, mandates, role scaffolds or tool descriptions for the presence or absence of phrases.

Rendered evidence: call the driver that exists, do not write a new one

A rendered surface is part of correctness, so new UI work still owes rendered evidence. What it does not owe is a new one-shot driver: #1761 deleted about 22 000 lines of per-issue capture scripts and browser drivers that no workflow ran and no second issue reused. There is exactly one driver of each kind, and an issue adds a case to it:

  • board geometry in a real browser — scripts/capture-board-geometry.ts
  • run directories — scripts/capture-directory.ts
  • the kanban board — src/components/kanban/kanbanBoard.browser.test.tsx, one describe block per issue over issue1695Evidence.fixture.tsx, gated by LLV_KANBAN_BROWSER_TEST=1 plus CHROME_BIN
  • the phone — src/components/mobile/issue1671Evidence.browser.test.tsx, gated by LLV_SWIPE_BROWSER_TEST=1

The committed evidence/**/*.json files are the record and stay, including the ones whose driver is gone. Do not name a new file after your issue number; a driver whose only caller is the issue that wrote it is dead the day it merges.

A visual critic frames product screens through the kanban board driver (src/components/kanban/kanbanBoard.browser.test.tsx), the conversation-window driver (src/components/conversation/conversationWindow.browser.test.tsx), the phone driver (src/components/mobile/issue1671Evidence.browser.test.tsx) and the board geometry capture (scripts/capture-board-geometry.ts). Run them in isolated state: a private HOME, TMPDIR and state directory, the Viewer control URL on a closed port, a short Chrome TMPDIR. This product ships in en and uk, light and dark.

Only a declared owner resolves the operator's state directory

bun run build in a lane once migrated the operator's live account files and stopped every spawn on the machine for seventy minutes (#1905). Nothing in that build meant to touch state: a route module loaded, it reached a store, the store ran its first-boot import, and the import resolved ~/.config/agent-log-viewer/state because that is what an unset environment resolves to. The mechanism, in src/lib/stateOwnership.ts, is three rules:

  1. Resolution asks who is calling. stateDir() and inboxDir() hand back the operator's own directory only to a process that declares LLV_STATE_OWNER — viewer, runtime-host, launcher, deploy-adapter, mcp or tool. A production build (NEXT_PHASE=…build) and a test run get a throw-away directory under the temp root, stable for the life of the process; anything else is refused with an error naming what to set. A directory the caller chose (LLV_STATE_DIR, a sandboxed XDG_CONFIG_HOME, a $HOME under the temp root) is admitted untouched — that is how every test and capture driver isolates itself, and none of it changed.
  2. A state-mutating startup step needs the release fence. Imports, migrations, backups, integrity swaps and cleanups call assertStateStartupMutation(directory, step), which admits only viewer and runtime-host against the operator's directories and admits everything against a sandbox. A launcher or an MCP server reads what the Viewer already migrated.
  3. A spawned agent gets its own root. Both structured hosts run their child environment through withAgentConfigSandbox, so the commands an agent runs resolve <tmp>/llv-spawn-sandbox/<account>/config and never the operator's. Its account home, its transcript root and its Viewer MCP link keep pointing at the real installation — the MCP link because viewerMcpServerEnv() pins the real state directory into the server definition itself, not into the agent's environment — and GH_CONFIG_DIR is pinned because gh used to read XDG_CONFIG_HOME. A restricted stage is handed a TMPDIR under statePath("scratch"): the sandbox ignores such a TMPDIR and builds under the process temp root instead, and a path under the process temp root is never classified as the operator's, so the suites that agent runs keep driving imports and backups against their own temp directories.

The claim has to run before the entry point's own imports. An import is evaluated before every statement in the file that wrote it, so process.env.LLV_STATE_OWNER = … in an entry's body runs AFTER its whole module graph — and a module that resolves state while it loads (export const INBOX_DIR = inboxDir(), const TASKS_FILE = statePath("tasks.json")) has already been refused by then. The first round of this change claimed that way in five entry points, and every one of them was dead code: the MCP server threw before it could connect, which would have taken the Viewer tools away from every spawned agent, and two operator scripts ran only when the variable was already in the environment. An entry point claims one of two ways:

  • import "@/lib/state/owner/<kind>"; as its first import — one of the side-effect modules beside stateOwnership.ts (mcp, tool, deployAdapter), which is what src/lib/mcp/entry.ts and the operator scripts do;
  • or a claim in the body followed by await import(...) for everything else, which is what src/runtime-host/main.ts does.

bin/cli.mjs and src/instrumentation.ts claim in their bodies and are safe for a different reason: neither reaches a module that resolves state until after the claim. Check that before copying them.

When you add a process that legitimately owns live state, give it an owner token at its entry point (see bin/cli.mjs, src/runtime-host/main.ts, src/instrumentation.ts, src/lib/mcp/entry.ts, the runtime stage of the Dockerfile, and the dev/start scripts), and add it to stateOwnership.entryPoints.test.ts, which starts each real entry point under an operator-shaped home with nothing preset. When you add a script that only needs a state directory, set LLV_STATE_DIR instead — claiming an owner token to silence a refusal is how the seventy minutes come back.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.