8000 Resolve silo paths from configuration instead of hardcoded directory names by simon-inkie · Pull Request #8 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content

Resolve silo paths from configuration instead of hardcoded directory names - #8

Closed
simon-inkie wants to merge 5 commits into
mainfrom
configurable-silo-root
Closed

simon-inkie wants to merge 5 commits into
mainfrom
configurable-silo-root

Conversation

@simon-inkie
Copy link
Copy Markdown
Owner

Four sites were flagged as sharing one root cause: a silo directory name written into the code as a literal, where the surrounding code resolves it from configuration. Reading each one, three were real and one was not, and the two that looked like the same bug turned out to be different bugs.

What changed

1. cron.server.ts - nudge run-state went to a hardcoded directory. The highest-severity of the set, and an outright blocker on the Scheduler against real data. The generated nudge script wrote fired/delivered state to a hardcoded path, and listCrons independently re-derived the same hardcoded path to read it back. Writer and reader agreed with each other and disagreed with the deployment, so on any instance whose agent directories are not at that exact path, state written by a fired nudge was invisible to the UI, and editing a nudge started a second state tree beside the first - splitting the per-fire-slot marker that makes delivery idempotent.

Both halves now resolve from one source, the INBOX_ROOT every other silo-adjacent module already uses. cron-state/ sits beside inbox/ inside each agent's directory, so INBOX_ROOT is the correct root and no new configuration is introduced. Injected through CronDeps like every other side effect here, and resolved lazily so a rejected target still fails as a bad target rather than as a configuration error.

The root is a value rather than a literal now, so it is also shell quoted. It was going into the generated script inside double quotes, where a $ or a backtick in an operator's path would have expanded.

2. review.server.ts - a substring ban the confinement rework missed. Not the same bug as the others. TASK-434 replaced deny-known-bad with allowlist confinement across safe-fs, attachments and projects, for the reason recorded in safe-fs's own header: a substring ban on a silo directory name is a build-era invariant encoded at the wrong layer, and it blocks the very paths production must serve. review.server.ts was not converted with the others.

Two things were wrong with what was left. The banned string is a directory name no deployment is obliged to use, so on most instances it denied nothing while reading like a protection. And resolveReviewRoots ALWAYS appends INBOX_ROOT as an implicit root - so on an instance that did use that name, the ban and the root list contradicted each other outright, and the panel refused every read from the one root it is guaranteed to have.

Containment against realpath'd roots is strictly stronger than a substring test for the traversal and symlink-escape cases the ban was reaching for, so nothing load-bearing goes with it. The tests that asserted the ban are replaced by tests for the property that actually holds the surface: a file inside a silo-shaped root is served, one outside every root is refused, and an escape through an intermediate symlink is refused on the realpath.

3. safe-fs.server.ts - MC_SANDBOX_ONLY could not name what it was guarding. README states FND-04's other half with no directory in it ("a sandbox configuration may never be pointed at a live agent silo"). The implementation could only ever recognise one directory: this project's default silo name joined onto $HOME.

On any deployment keeping its agents elsewhere the flag was not weaker, it was inert - it refused nothing, while .env.example described it as a protection and test/setup.ts set it on every test run.

New optional MC_LIVE_SILO_ROOT names the silo. Unset, the default is exactly the previous behaviour, so no existing instance changes and no existing test moves. Absolute paths only, validated at point of use rather than at boot, because the variable means nothing unless MC_SANDBOX_ONLY is also set and failing a production start over an unused sandbox setting would be the wrong trade.

This also makes the refusal testable for the first time. The single test covering it returned early unless the machine happened to have the default silo directory - which no CI machine does - so it had been passing by skipping. New cases stand a tmpdir up as the live silo and assert the refusal for real: the root itself, a sibling sharing its name prefix, the unset-flag no-op, and a blocked inbox write end to end.

4. create-agent.sh - not the reported bug; a false citation instead. The flagged line is a fallback, not a hardcode: --inbox-root and $INBOX_ROOT both win ahead of it, and when it does fire it warns loudly and prints where the agent went. That design is right and is left alone.

What was wrong was the wording. It announced the value as "the value from the application's .env.example", and that file ships INBOX_ROOT empty because there is no default (FND-03). The citation dressed a guess up as a lookup, which is the one thing a warning about guessing must not do.

No behaviour change. Tests now pin the source ordering, since a fallback firing over something the operator had configured is the failure that would actually matter, and nothing covered it - the existing case passes --inbox-root and never reaches the fallback branch.

Deliberately not done

  • REVIEW_ROOTS is vetted by nothing. The live-silo refusal covers the four roots in safe-fs's ROOT_ENV_VARS table, which validateConfiguredRoots vets once at boot; INBOX_ROOT is in it, so the implicit review root IS covered. REVIEW_ROOTS is not, so a sandbox instance can still name a live silo there explicitly. The obvious fix - assertNoLiveSiloRoot per root inside assertContained - lands on the autolink hot path, whose realpath cost is deliberately measured by a regression test (linkifyBlockBodies shares root resolution precisely for this). It wants a once-per-request home, not a per-path syscall. Recorded in the module header.
  • No shared constant for the silo name. There is not one today, and introducing one would only centralise a default that two of the three call sites should no longer have at all.
  • Existing generated nudge scripts still carry the old path. Anything created before this lands keeps writing where it was told to until the entry is edited through the app, which rewrites the script. Worth a note in release notes rather than a migration.

Also worth knowing

  • assertGitClean in review.test.ts and safe-fs.test.ts allowlists paths like app/ and test/, but git status --porcelain reports repo-root-relative paths, which since the monorepo layout are packages/deck/app/.... The allowlist therefore matches nothing and the assertion fires on any uncommitted change under the package. Green on a committed tree, so CI is unaffected, but it makes the suite unusable mid-edit. Left alone as unrelated to this change.
  • The suite is load-flaky, as the root package.json already documents. Two separate runs each produced one failure (skeleton.test.ts on a 5s dynamic-import timeout; one base case), both passing in isolation and on a clean re-run.

Checks

pnpm test (base 41, deck 1846 + 11 skipped, 89 files), pnpm typecheck, pnpm check:boundaries (583 modules), pnpm check:dashes, pnpm check:licence, leak-gate --self-test (30 rules), leak-gate (clean, 367 files) all green.

leak-gate --messages reports two findings, both pre-existing on historical commits (2dc627dc14, c95abce7bc) and identical to the pre-change baseline. None of the commits here appear.

🤖 Generated with Claude Code

Simon and others added 5 commits August 17, 2026 22:20
serializeHeader's docstring promised HEADER_RE-matching output and did not
deliver it. When parseHeader failed, parseBlock substituted a blank header
(empty timestamp/from/subject, status "read"), and serializeHeader then
interpolated those blanks into "##  - from:  - status: read - subject: ",
which no parser can read. Reading a file and writing it back therefore
destroyed the header permanently, and because the re-blanked line fails
parse again, the damage compounded on every subsequent read-write cycle.

parseBlock now carries the ORIGINAL header line on BlockHeader.rawHeader
whenever parseHeader fails, and serializeHeader emits it verbatim when
present. A re-serialise of a header we cannot parse becomes a no-op rather
than a lossy rewrite.

rawHeader is set ONLY on the failure path. Carrying it on the success path
too would break the counter-property: a legitimate status flip (sent to
read) would serialise the OLD line and never persist. The new test pins
that through the production seam, parseBlock then serializeBlock, because
parse.ts is the exact place a regression would attach it to both arms.

Not fixed by throwing (that pushes the decision onto every caller and one
gets it wrong quietly), and not by deleting the parse fallback (that
fallback exists to stop unparseable blocks nagging as permanently unread).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The generated nudge script wrote its fire/delivered state to a directory
named by a hardcoded silo path, and listCrons independently re-derived the
same hardcoded path to read it back. The two agreed with each other and
disagreed with the deployment, so on any instance whose agent directories
are not at that exact path:

  - run-state written by a fired nudge was invisible to the Scheduler UI,
    which is the whole of the DC4 visibility feature; and
  - editing a nudge through the app rewrote the script against the same
    wrong path, so the per-fire-slot marker that makes delivery idempotent
    started over in a second tree beside the first.

Both halves now come from one configured source, the INBOX_ROOT that every
other silo-adjacent module already resolves through. cron-state sits beside
inbox/ inside each agent's directory, so INBOX_ROOT is the correct root and
no new configuration is introduced. Injected through CronDeps like every
other side effect in this module, and resolved lazily so a rejected target
still fails as a bad target rather than as a configuration error.

The root is now a value rather than a literal, so it is also now shell
quoted. It went into the script inside double quotes, where a dollar sign
or a backtick in an operator's path would have expanded.
…missed

TASK-434 replaced deny-known-bad with allowlist confinement across safe-fs,
attachments and projects, for a reason recorded in safe-fs's header: a
substring ban on a silo directory name is a build-era invariant encoded at
the wrong layer, and it blocks the production paths the app is meant to
serve. review.server.ts was not converted with the others and kept the ban.

Two things were wrong with what was left behind. The banned string is a
directory name no deployment is obliged to use, so on most instances the
check denied nothing while reading like a protection. And resolveReviewRoots
ALWAYS appends INBOX_ROOT as an implicit root, so on an instance that did
use that name the ban and the root list contradicted each other outright:
every read from the one root the panel is guaranteed to have was refused.

Containment against realpath'd roots is strictly stronger than a substring
test for the traversal and symlink-escape cases the ban was reaching for,
so nothing load-bearing goes with it. The tests that asserted the ban are
replaced by tests for the property that actually holds the surface: a file
inside a silo-shaped root is served, one outside every root is refused, and
an escape through an intermediate symlink is refused on the realpath.

Records one gap this deliberately does not close. The sandbox live-silo
refusal covers the four roots in safe-fs's ROOT_ENV_VARS table, which
validateConfiguredRoots vets once at boot, and INBOX_ROOT is in it. Nothing
vets REVIEW_ROOTS. The obvious fix lands on the autolink hot path, whose
realpath cost is measured by a regression test, so it wants a
once-per-request home rather than a per-path syscall.
MC_SANDBOX_ONLY is the half of FND-04 that stops a sandbox configuration
being pointed at a live agent silo. README states that rule with no
directory in it. The implementation could only ever recognise one: the silo
directory name this project ships, joined onto the home directory.

On any deployment that keeps its agents anywhere else, the flag was inert.
Not weaker, inert: it refused nothing at all, while .env.example described
it as a protection and test/setup.ts set it on every test run. A guard that
cannot name the thing it is guarding is a comment.

MC_LIVE_SILO_ROOT names it. Unset, the default is exactly what the code did
before, so no existing instance changes behaviour and no test moves. Set, it
points the refusal at whatever a real fleet actually uses. Absolute paths
only, validated where it is used rather than at boot, because the variable
means nothing unless MC_SANDBOX_ONLY is set too and failing a production
start over an unused sandbox setting would be the wrong trade.

This also makes the refusal testable for the first time. The one test that
covered it returned early unless the machine running it happened to have the
default silo directory, which no CI machine does, so it had been passing by
skipping. The new cases stand a tmpdir up as the live silo and assert the
refusal for real, including the root itself, a sibling sharing its name
prefix, the unset-flag no-op, and a blocked inbox write end to end.
…claims

When INBOX_ROOT is unset and no --inbox-root is passed, create-agent.sh
falls back to this project's default silo layout and says so loudly, which
is the right design: an inbox created in the wrong place should be visible
when it happens, not the first time a message goes missing.

The wording undercut it. It announced the value as "the value from the
application's .env.example", and that file ships INBOX_ROOT empty, because
there is no default (FND-03). The citation dressed a guess up as a lookup,
which is the one thing a warning about guessing must not do. It now says
plainly that nothing here knows where the reader's inbox root is and that
the value below is a guess.

No behaviour change, and the fallback value is deliberately left alone. It
is the last of three sources and both of the ones ahead of it already win.
Tests now pin that ordering, since the fallback firing over something the
operator had configured is the failure that would actually matter, and no
test covered it: the existing case passes --inbox-root and never reaches
the fallback branch at all.
@simon-inkie
Copy link
Copy Markdown
Owner Author

Superseded by #9. This branch was accidentally cut from a commit belonging to the header-roundtrip work rather than from main, so it carried an unrelated commit that belongs to its own branch. #9 has the same four commits replayed onto main, and nothing else.

@simon-inkie
simon-inkie deleted the configurable-silo-root branch August 17, 2026 21:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0