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.
- CLAUDE.mdCLAUDE.md
- delegatus-conveyorSkill
- delegatus-orchestrationSkill
- live-log-viewer-orchestrationSkill
- llv-conveyorSkill
- review-loopSkill
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
- Distinctive: line 37
Only then the disk-dependent resolvers, as fallbacks:
- Distinctive: line 64
When adding a new agent/worktree layout: prefer a pure path recognizer beside
- Distinctive: line 90
Run git config core.hooksPath .githooks once per clone.
- Distinctive: line 148
After a type, lint or test refusal, a settled producer repair can return to a fresh producer attempt automatically.
- Very specific: line 160
When ~/.config/delegatus/gate-runner.json exists under the account's passwd home ({"ssh": "<alias>"}), a top-level scripts/gate-slot.sh …
- Very specific: line 300
Every long-lived listener in the runtime host attaches its error handler to a connection before the first byte can be written to it.
- Very specific: line 445
When you add a process that legitimately owns live state, give it an owner token at its entry point (see bin/cli.mjs, …
≈ “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.
Files
<!-- 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:
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.worktreeFromPath— Claude worktrees at<repo>/.claude/worktrees/<name>/…worktreeFromNested— thegit worktree add worktrees/<name>(and dotted.worktrees/<name>) convention: the checkout nests inside the repo, so the repo is the path prefix before the firstworktrees/.worktreessegment; specialized.claude/.codexcontainers are left to #2/#4. The first container wins, so a worktree-of-a-worktree groups under the outermost repo.worktreeFromCodexPath— Codex worktrees at~/.codex/worktrees/<hash>/<Repo>
Only then the disk-dependent resolvers, as fallbacks:
worktreeFromGitFile— any linked git worktree, resolved from its.gitfile (gitdir:pointer) — works only while the checkout exists on disk. Every live resolution here is written to a persistent map (below).worktreeFromMemory— replays aworktreeFromGitFileresolution recorded (tostate/worktree-map.json) while the checkout was alive. This is the only thing that saves an arbitrary-pathgit worktree add ../siblingcheckout (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 instate.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
errorhandler 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 unhandlederroron 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.bunthere 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 namesbun-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, onedescribeblock per issue overissue1695Evidence.fixture.tsx, gated byLLV_KANBAN_BROWSER_TEST=1plusCHROME_BIN - the phone —
src/components/mobile/issue1671Evidence.browser.test.tsx, gated byLLV_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:
- Resolution asks who is calling.
stateDir()andinboxDir()hand back the operator's own directory only to a process that declaresLLV_STATE_OWNER—viewer,runtime-host,launcher,deploy-adapter,mcportool. 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 sandboxedXDG_CONFIG_HOME, a$HOMEunder the temp root) is admitted untouched — that is how every test and capture driver isolates itself, and none of it changed. - A state-mutating startup step needs the release fence. Imports,
migrations, backups, integrity swaps and cleanups call
assertStateStartupMutation(directory, step), which admits onlyviewerandruntime-hostagainst the operator's directories and admits everything against a sandbox. A launcher or an MCP server reads what the Viewer already migrated. - 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>/configand never the operator's. Its account home, its transcript root and its Viewer MCP link keep pointing at the real installation — the MCP link becauseviewerMcpServerEnv()pins the real state directory into the server definition itself, not into the agent's environment — andGH_CONFIG_DIRis pinned becauseghused to readXDG_CONFIG_HOME. A restricted stage is handed aTMPDIRunderstatePath("scratch"): the sandbox ignores such aTMPDIRand 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 besidestateOwnership.ts(mcp,tool,deployAdapter), which is whatsrc/lib/mcp/entry.tsand the operator scripts do;- or a claim in the body followed by
await import(...)for everything else, which is whatsrc/runtime-host/main.tsdoes.
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.
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
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.

