@intentic/sandbox-contract 1.244.0 → 1.246.1

package/src/shell-regions.ts

@@ -0,0 +1,289 @@
+/* WHICH PARTS OF A COMMAND ARE TEXT RATHER THAN A PROGRAM, so the one tier that cannot be argued with stops
+ * firing on a mention of a dangerous verb.
+ *
+ * WHAT THIS IS FOR, precisely, because it bounds how good it has to be. The triage catalog next door
+ * (command-classes.ts) is deliberately over-inclusive: a match only means a judge should look, and a false
+ * positive there costs one model call. That economy holds for every class except the hard-ruled one, where a
+ * match is an interruption no policy and no verdict can waive (safety-policy.ts hardRuleClasses). So
+ * `echo "rm -rf /" >> notes.md` and `rg 'rm -rf /'` raised un-waivable cards over a string being written to a
+ * file and a search of the tree — the exact failure the judge redesign was built to end, surviving in the one
+ * tier the judge cannot reach.
+ *
+ * This says where a fragment sits. A fragment inside a region below is still REPORTED (the class holds, the
+ * judge still reads it, the card still marks it); it just does not trip the hard rule.
+ *
+ * WHICH IS WHY A REGEX-LEVEL SCANNER IS ENOUGH, and this is the design argument rather than an excuse. Both
+ * ways of being wrong are cheap:
+ *
+ *   · MISS a region (call text a program) ⇒ one judge call. Exactly today's behaviour, which is the floor.
+ *   · INVENT a region (call a program text) ⇒ the class is still reported and the judge still rules on it.
+ *     Only the un-waivable tier is skipped, and the judge is the tier that reads the owner's policy.
+ *
+ * Precision has to be good enough to skip tier 1½, never good enough to skip tier 1. Nothing here is a
+ * boundary, for the same reason nothing in command-classes.ts is: `sh -c "$CMD"` and a path assembled from a
+ * variable walk past all of it. The boundaries are structural and elsewhere.
+ *
+ * THREE KINDS OF REGION, and each is a place a shell will not run what it holds:
+ *
+ *   1 A COMMENT, `#` to end of line.
+ *   2 A HEREDOC BODY, the usual way an agent writes a script it is not running yet.
+ *   3 A QUOTED ARGUMENT OF A VERB THAT CANNOT EXECUTE ONE — echo, printf, and the searchers. Plus a quoted
+ *     commit message after -m, whatever the verb, because message text never runs.
+ *
+ * `sed`, `awk` and `perl` are deliberately NOT in that verb list, though they are the obvious next entries:
+ * each can run a shell out of its own quoted program (`awk 'BEGIN{system("…")}'`, `perl -e`, GNU sed's `s///e`),
+ * so their quoted argument is a program and calling it text would be wrong rather than merely imprecise.
+ */
+
+import type { CommandSpan } from "./command-classes.js";
+
+/* Verbs whose quoted arguments this scanner will call text. Every one of them either prints its argument or
+ * matches with it, and none has a documented way to execute it. Widening this list is safe in the sense the
+ * header sets out, but each entry should be able to answer "how would this run its argument?" with "it cannot". */
+const QUOTING_VERBS: ReadonlySet<string> = new Set([
+    "echo",
+    "printf",
+    "rg",
+    "grep",
+    "egrep",
+    "fgrep",
+    "ack",
+    "ag",
+    "ripgrep",
+]);
+
+/* A flag whose value is a message: git's -m, and the long spelling. A quoted string here is prose that reaches
+ * a commit, a tag or a PR, and `git commit -m "rm -rf the old build dir"` is one of the more ordinary ways to
+ * write a dangerous-looking command that is not one. Read on the WORD BEFORE a quoted argument, so it applies
+ * whatever the verb is. */
+const MESSAGE_FLAGS: ReadonlySet<string> = new Set(["-m", "--message", "-am", "--body", "-b"]);
+
+// Where an unquoted word ends: whitespace, a pipeline or list operator, a redirect, a subshell paren.
+const WORD_END = /[\s;|&<>()]/;
+
+// A word that is a variable assignment prefixing a command (`FOO=bar cmd …`), skipped when looking for the verb.
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/* `<<EOF`, `<<-EOF`, `<<'EOF'`, `<<"EOF"`. The delimiter's quoting only decides whether the body expands, which
+ * changes nothing here: an expanded body is still a body being written somewhere rather than run. */
+const HEREDOC_OPEN = /<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/g;
+
+/* The heredoc bodies in a command, as spans. Found first and in their own pass, because a body is line-oriented
+ * and can hold anything at all — an odd number of quotes in it would otherwise throw the word scanner out of
+ * step for the rest of the command. */
+const heredocBodies = (command: string): CommandSpan[] => {
+    const bodies: CommandSpan[] = [];
+    for (const open of command.matchAll(HEREDOC_OPEN)) {
+        const indented = command.slice(open.index, open.index + 3).startsWith("<<-");
+        const newline = command.indexOf("\n", open.index + open[0].length);
+        if (newline === -1) {
+            // `cat <<EOF` with nothing after it: an unterminated heredoc, so there is no body to mark.
+            continue;
+        }
+        const start = newline + 1;
+        const terminator = new RegExp(`^${indented ? "[ \\t]*" : ""}${open[2] as string}[ \\t]*$`, "m");
+        const rest = command.slice(start);
+        const end = terminator.exec(rest)?.index;
+        // An unterminated body runs to the end of the command, which is what the shell would read too.
+        bodies.push({ start, end: end === undefined ? command.length : start + end });
+    }
+    return bodies;
+};
+
+// Is this offset inside one of the spans already found? Heredoc bodies are skipped wholesale by the word scan.
+const within = (spans: readonly CommandSpan[], offset: number): CommandSpan | undefined =>
+    spans.find((span) => offset >= span.start && offset < span.end);
+
+// A substitution inside double quotes, the one thing that makes a quoted argument a program again.
+const EXPANDS = /\$\(|`/;
+
+/* One quoted segment inside a word: the span covers the quotes as well as what is between them, so a region
+ * handed back from here contains the whole `"rm -rf /"` and a match on any part of it reads as contained. */
+interface QuotedSegment {
+    readonly span: CommandSpan;
+    /* Does a shell expand anything in here? `"$(rm -rf /)"` inside an echo is a real delete whose output is
+     * printed, so a double-quoted segment carrying a substitution is NOT text and never becomes a region. Single
+     * quotes expand nothing, so they never set this. */
+    readonly expands: boolean;
+}
+
+interface ShellWord {
+    readonly start: number;
+    // The word with its quoting removed, which is what a verb name and a flag are compared against.
+    readonly text: string;
+    readonly quoted: readonly QuotedSegment[];
+    // Does this word begin a simple command? True for the first word after a separator or at the start.
+    readonly opensCommand: boolean;
+}
+
+// A verb by its bare name: `/bin/echo` and `./echo` are echo, and the path in front of it says nothing new.
+const bareVerb = (text: string): string => text.slice(Math.max(text.lastIndexOf("/"), text.lastIndexOf("\\")) + 1);
+
+// Every list and pipeline operator: past one of these the next word is a verb again.
+const SEPARATORS = new Set(["\n", ";", "|", "&", "(", ")"]);
+const BLANKS = new Set([" ", "\t", "\r"]);
+
+/* One quoted run, from its opening quote to its closing one. An unbalanced quote takes the rest of the
+ * command, which is what a shell waiting for more input would do and keeps the caller advancing. */
+const readQuoted = (command: string, open: number): QuotedSegment & { readonly text: string; readonly end: number } => {
+    const quote = command[open] as string;
+    const close = command.indexOf(quote, open + 1);
+    const end = close === -1 ? command.length : close + 1;
+    const text = command.slice(open + 1, close === -1 ? command.length : close);
+    return { span: { start: open, end }, expands: quote === '"' && EXPANDS.test(text), text, end };
+};
+
+/* One word, from `start` to whatever ends it, with the quoted runs inside it kept as spans. `end === start`
+ * cannot happen: the caller only enters here on a character that is neither blank nor a separator. */
+const readWord = (command: string, start: number): { readonly word: Omit<ShellWord, "opensCommand">; readonly end: number } => {
+    const quoted: QuotedSegment[] = [];
+    let text = "";
+    let index = start;
+    while (index < command.length && !WORD_END.test(command[index] as string)) {
+        const char = command[index] as string;
+        if (char === "'" || char === '"') {
+            const segment = readQuoted(command, index);
+            quoted.push({ span: segment.span, expands: segment.expands });
+            text += segment.text;
+            index = segment.end;
+            continue;
+        }
+        if (char === "\\") {
+            text += command[index + 1] ?? "";
+            index += 2;
+            continue;
+        }
+        text += char;
+        index += 1;
+    }
+    return { word: { start, text, quoted }, end: index };
+};
+
+/* The command taken apart into words, with each word's quoted segments and whether it opens a simple command.
+ * Deliberately a scanner rather than a parser: it tracks quoting and the separators that start a new command,
+ * and it knows nothing about control flow, functions or expansion. Everything it gets wrong is bounded by the
+ * header's argument. */
+const scanWords = (command: string, skip: readonly CommandSpan[]): ShellWord[] => {
+    const words: ShellWord[] = [];
+    let index = 0;
+    let opensCommand = true;
+    while (index < command.length) {
+        const skipped = within(skip, index);
+        if (skipped !== undefined) {
+            index = skipped.end;
+            continue;
+        }
+        const char = command[index] as string;
+        if (SEPARATORS.has(char)) {
+            opensCommand = true;
+            index += 1;
+            continue;
+        }
+        if (BLANKS.has(char)) {
+            index += 1;
+            continue;
+        }
+        if (char === "#") {
+            // A comment runs to the end of the line. Only reached at a word boundary, so `a#b` is one word.
+            const newline = command.indexOf("\n", index);
+            index = newline === -1 ? command.length : newline;
+            continue;
+        }
+        const { word, end } = readWord(command, index);
+        // A character that is neither a separator nor part of a word (a stray redirect): step over it so the
+        // loop always advances.
+        index = end === index ? index + 1 : end;
+        if (end !== word.start) {
+            words.push({ ...word, opensCommand });
+            opensCommand = false;
+        }
+    }
+    return words;
+};
+
+/* WHERE A COMMAND HOLDS TEXT RATHER THAN A PROGRAM, as spans over the command, unsorted and possibly
+ * overlapping — callers ask containment questions of them rather than rendering them.
+ *
+ * Exported for the classifier, which asks it once per command and hands the answer to every table. */
+export const inertRegions = (command: string): CommandSpan[] => {
+    const bodies = heredocBodies(command);
+    const regions: CommandSpan[] = [...bodies];
+    const words = scanWords(command, bodies);
+    // Comments are consumed by the scanner rather than reported, so they are found again here: the scan is
+    // where the quoting state lives, and a `#` inside a quoted string is not a comment.
+    let quotingVerb = false;
+    let previous: ShellWord | undefined;
+    for (const word of words) {
+        if (word.opensCommand) {
+            quotingVerb = QUOTING_VERBS.has(bareVerb(word.text));
+            previous = undefined;
+        }
+        /* An env assignment in front of the verb (`LC_ALL=C grep …`) is not the verb. Re-read the next word as
+         * one instead of giving up on the command. */
+        if (word.opensCommand && ASSIGNMENT.test(word.text) && word.quoted.length === 0) {
+            quotingVerb = false;
+            previous = undefined;
+            continue;
+        }
+        const afterMessageFlag = previous !== undefined && MESSAGE_FLAGS.has(previous.text);
+        if (quotingVerb || afterMessageFlag) {
+            regions.push(...word.quoted.filter((segment) => !segment.expands).map((segment) => segment.span));
+        }
+        previous = word;
+    }
+    regions.push(...commentRegions(command, bodies));
+    return regions;
+};
+
+/* Comments, on the same scan discipline as the words: a `#` only opens one where a word could have started, so
+ * `sha#1` is not a comment, and a quoted `"# …"` is not one either.
+ *
+ * Its own walk rather than a by-product of scanWords, because the two want different things from a quote — the
+ * word scan needs what is INSIDE one, this needs only to be past it. Sharing readQuoted keeps them agreeing on
+ * where one ends, which is the only fact they both depend on. */
+const commentRegions = (command: string, skip: readonly CommandSpan[]): CommandSpan[] => {
+    const comments: CommandSpan[] = [];
+    let index = 0;
+    while (index < command.length) {
+        const skipped = within(skip, index);
+        if (skipped !== undefined) {
+            index = skipped.end;
+            continue;
+        }
+        const char = command[index] as string;
+        if (char === "'" || char === '"') {
+            index = readQuoted(command, index).end;
+            continue;
+        }
+        if (char === "\\") {
+            index += 2;
+            continue;
+        }
+        // A word boundary in front is what makes it a comment rather than part of a word.
+        if (char === "#" && (index === 0 || WORD_END.test(command[index - 1] as string))) {
+            const newline = command.indexOf("\n", index);
+            const end = newline === -1 ? command.length : newline;
+            comments.push({ start: index, end });
+            index = end;
+            continue;
+        }
+        index += 1;
+    }
+    return comments;
+};
+
+/* Is this fragment somewhere a shell would RUN it? The question the hard rule asks of every span triage matched.
+ *
+ * JUDGED ON WHERE THE FRAGMENT STARTS, not on whether a region contains the whole of it, and the difference is
+ * not a relaxation — it is the only reading that answers the question asked. Every pattern in the catalog is
+ * written to BEGIN at the verb (`rm`, `docker volume rm`, `mkfs`, `git push`), so the span's first character is
+ * where the dangerous thing was found. Whether the match then ran on past a closing quote says something about
+ * the regex, not about the command: `rm`'s own parser reads to the end of the invocation and `>` is not a
+ * terminator, so `echo "rm -rf /" >> notes.md` produces a span covering `rm -rf /" >> notes.md`. Requiring
+ * containment made that command live — which is exactly the card this whole change exists to stop raising.
+ *
+ * The conservative direction is preserved where it matters: a fragment whose verb sits OUTSIDE every region is
+ * live no matter what it runs into afterwards, so `echo "tidying" && rm -rf /` and `rm -rf "$(cat list)" # ok`
+ * both stay live. */
+export const isLive = (span: CommandSpan, regions: readonly CommandSpan[]): boolean =>
+    !regions.some((region) => span.start >= region.start && span.start < region.end);

package/src/versions.ts

@@ -1,7 +1,7 @@
 /* COMPARING THE VERSIONS THIS SYSTEM STAMPS ON WHAT IT SHIPS, the daemon, the sandbox image, and the two agents
- * that run on a user's own computer. One release stamps all of them to the SAME version, so "is this one behind
+ * that run on a user's own device. One release stamps all of them to the SAME version, so "is this one behind
  * that one" is one question with one answer, and it lives here because both ends ask it: the daemon compares its
- * own build against the latest published release, and the browser compares a computer's agent against the same.
+ * own build against the latest published release, and the browser compares a device's agent against the same.
  *
  * Shared rather than copied because the two copies would not disagree until the day it mattered: 1.9.0 against
  * 1.10.0 is where a hand-rolled comparator goes wrong, and it goes wrong by reporting "up to date". */

package/src/webext-links.ts

@@ -35,7 +35,7 @@ export const webextLendUrl = (sandboxUrl: string): string => `${sandboxUrl.repla
 
 /* ---- the pairing code: the one string that travels from the sandbox's card into the extension ----
  *
- * A connected computer is paired by a shell one-liner, which can carry two values in two environment variables
+ * A connected device is paired by a shell one-liner, which can carry two values in two environment variables
  * because a terminal is a place where long strings are normal. A browser extension's popup is not: what a
  * person will actually do there is paste ONE thing, once, and anything that asks them to copy a URL into one
  * box and a token into another is a flow that fails on the second box.
@@ -43,7 +43,7 @@ export const webextLendUrl = (sandboxUrl: string): string => `${sandboxUrl.repla
  * So both halves ride in one code. It is not encryption and does not pretend to be — base64url of two fields,
  * so that the thing on the clipboard is opaque enough not to be edited by hand, short enough to paste, and
  * carries its own sandbox address, which is the field a person could not possibly be expected to type. The
- * secret in it is the pairing token, which is single-use and expires in ten minutes (webext-store.ts).
+ * secret in it is the pairing token, which is single-use and expires in ten minutes (the daemon's peer store).
  *
  * The prefix is a version marker, and it is here so that a code from an older sandbox meets a clear "this code
  * is from a different version" in the extension rather than a JSON parse error. */

package/src/webext-protocol.ts

@@ -2,13 +2,13 @@ import { z } from "zod";
 
 /* The handshake on /system/webext/connect, the ONE message on that socket that is not oRPC.
  *
- * Same two-phase shape as a connected computer's (host-protocol.ts) and for the same reason: the daemon has
+ * Same two-phase shape as a connected device's (host-protocol.ts) and for the same reason: the daemon has
  * nothing to call until it knows whose socket this is, so the proof cannot itself be an oRPC call. The browser
  * extension's first frame carries its enrollment token, the daemon resolves WHICH capability it belongs to, and
  * from that message on every byte is `webextContract` with the EXTENSION serving.
  *
  * WHY A SEPARATE PROTOCOL FROM host's, when the frame is the same two fields: because the thing on the other
- * end is not a computer. It has no shell, no filesystem and no screen; what it has is tabs, origins the person
+ * end is not a device. It has no shell, no filesystem and no screen; what it has is tabs, origins the person
  * granted one at a time, and a human watching every click. Sharing the host's schema would have meant a card of
  * switches that mean nothing (`roots`, `sandboxRemove`) and an agent told about a home directory it cannot
  * reach. The two connectors are siblings, not one connector with a flag. */

package/src/workspace-state.test.ts

@@ -6,6 +6,9 @@ import {
     isLockedWorkspacePath,
     isReportedManifest,
     isReviewableLockedPath,
+    LOCKED_STATE_ENTRIES,
+    lockedWorkspaceEntry,
+    PLAN_DOCUMENTS_DIR,
     REPORTED_MANIFEST_PATHS,
     SEARCHABLE_STATE_PATHS,
     SHARED_STATE_PATHS,
@@ -244,6 +247,47 @@ describe(`isLockedWorkspacePath`, () => {
         expect(isLockedWorkspacePath(`.intentic\\secrets\\auth\\codex`)).toBe(true);
         expect(isLockedWorkspacePath(`./.intentic/config/capabilities.json`)).toBe(true);
     });
+
+    it(`lets the plan documents out of the session store around them`, () => {
+        // The plan a card asks the reader to approve, whose full text that card already renders. Refusing the
+        // file left the card's one link into the workspace landing on a padlock about the document it was
+        // asking about; the transcripts it sits beside stay locked.
+        expect(isLockedWorkspacePath(`${PLAN_DOCUMENTS_DIR}/wiggly-spring.md`)).toBe(false);
+        expect(isLockedWorkspacePath(PLAN_DOCUMENTS_DIR)).toBe(false);
+        expect(isLockedWorkspacePath(`.intentic/records/sessions/claude/projects/x.jsonl`)).toBe(true);
+        expect(isLockedWorkspacePath(`.intentic/records/sessions`)).toBe(true);
+        // …and it is the directory that is exempt, not the word: a sibling store named for it is not one.
+        expect(isLockedWorkspacePath(`.intentic/records/sessions/claude/plans-backup/x.md`)).toBe(true);
+    });
+});
+
+/* WHICH entry a locked path belongs to, which is what the refusal screen says a file holds and where to manage
+ * it. Split out from the boolean so the browser can key its sentences on the daemon's own list instead of a
+ * second copy of the rule — the copy it kept drifted through the state regrouping and stranded every locked
+ * file on the generic sentence. */
+describe(`lockedWorkspaceEntry`, () => {
+    it(`names the entry a path matched, not the leaf it ends at`, () => {
+        // A locked FOLDER is one row in the explorer and never descended, so the name worth reporting is the
+        // folder's: "Cookies is kept private" is true of something the reader has never heard of.
+        expect(lockedWorkspaceEntry(`.intentic/local/browser/Default/Cookies`)).toBe(`local/browser`);
+        expect(lockedWorkspaceEntry(`.intentic/secrets/auth/codex/auth.json`)).toBe(`secrets/auth`);
+        expect(lockedWorkspaceEntry(`.intentic/config/capabilities.json`)).toBe(`config/capabilities.json`);
+        expect(lockedWorkspaceEntry(`.git/config`)).toBe(`.git`);
+    });
+
+    it(`answers undefined for everything the lock does not hold`, () => {
+        expect(lockedWorkspaceEntry(`src/app.ts`)).toBeUndefined();
+        expect(lockedWorkspaceEntry(`.intentic/config/settings.json`)).toBeUndefined();
+        expect(lockedWorkspaceEntry(`${PLAN_DOCUMENTS_DIR}/wiggly-spring.md`)).toBeUndefined();
+    });
+
+    it(`answers for every entry the lock declares`, () => {
+        // The set is the daemon's; this is what makes it addressable from the browser. An entry nobody can
+        // resolve back out is one the refusal screen could only describe generically.
+        for (const entry of LOCKED_STATE_ENTRIES) {
+            expect([entry, lockedWorkspaceEntry(`${STATE_DIR}/${entry}`)]).toEqual([entry, entry]);
+        }
+    });
 });
 
 /* The carve-out the diff routes ask for, and the reason it is derived: a locked entry the root repo TRACKS has
@@ -330,10 +374,13 @@ describe(`VERSIONED_STATE_PATHS`, () => {
             /* The connections themselves, and the entry that took the longest to earn its place: it was classed
              * `secret` on the strength of holding each capability's credential, which stopped being true when the
              * vault took the values out and left the shape behind. Connecting a deployment orchestrator, or
-             * granting a connected computer shell and screen control, is the largest change made to what this
+             * granting a connected device shell and screen control, is the largest change made to what this
              * sandbox can DO, and it used to leave no diff. */
             `${STATE_DIR}/config/capabilities.json`,
             `${STATE_DIR}/config/capability-dismissals.json`,
+            // The context shelves: which repositories a conversation opened on one carries. A list of names, and
+            // the decision about what a session may see, which is what a review is for.
+            `${STATE_DIR}/config/context/`,
             /* The two entries the AGENT authors on its own initiative, and the reason `versioned` is not read as
              * config-only. Both are the sandbox acting outward: a draft publishes words under the owner's name,
              * a workspace extension is code that runs in the app and can serve HTTP with the workspace under
@@ -359,6 +406,13 @@ describe(`VERSIONED_STATE_PATHS`, () => {
             // raising that limit is a decision about every session sharing the box, and `git log` is the only
             // thing that answers "since when have we been allowing four of these at a time".
             `${STATE_DIR}/config/heavy-commands.json`,
+            /* The scripts the rules run. Tracked because the exclude list carves entries out BY NAME, so a
+             * directory nobody marked is invisible both to `git add -A` and to the land: that is how 559e896
+             * came to repoint settings.json at two scripts it never staged, and how the pair written in a
+             * worktree never arrived. What the workspace held from then on was settings naming two hooks that
+             * did not exist, and every edit for a day firing `node` at a missing file. A rule is reviewable;
+             * the code it runs on every write has to be. */
+            `${STATE_DIR}/config/hooks/`,
             `${STATE_DIR}/config/loop-designs.json`,
             `${STATE_DIR}/config/personas.json`,
             // A persona's own kit: the prompt it runs on and the skills only its turns reach. Tracked for the

package/src/workspace-state.ts

@@ -135,7 +135,7 @@ const STATE_FILES = [
      * withSecretVault keeps credential VALUES off /work entirely, the manifest holds `__intentic_vaulted__`
      * where one used to be, reads rehydrate so no caller noticed, and main.ts sweeps a hand-written value out at
      * boot. What is left is the SHAPE of a connection: a kind, a URL, a username, a purpose, which permissions a
-     * connected computer was granted.
+     * connected device was granted.
      *
      * WHICH KEYS THOSE ARE IS DERIVED, not listed a second time: `echo` already answers "what of this config may
      * a browser see", and the credential keys are exactly its complement (capabilities/secret-fields.ts). A kind
@@ -149,7 +149,7 @@ const STATE_FILES = [
      * one credential apiece, the shape personas.json has had all along, for the same reason.
      *
      * `versioned`, which is the point. Connecting this sandbox to a deployment orchestrator, or granting a
-     * connected computer shell and screen control, is the largest change anyone makes to what it can DO, and it
+     * connected device shell and screen control, is the largest change anyone makes to what it can DO, and it
      * left a diff nowhere. One consequence worth stating rather than discovering: an identifier that pairs with a
      * credential. Komodo's api key beside its api secret, which its own connector card calls "like a database
      * user", is echoed, and therefore lands in the diff exactly as a database username would. */
@@ -273,6 +273,34 @@ const STATE_FILES = [
      * — raising the limit is a decision about everyone's sessions on that box, and `git log` is the only thing
      * that answers "since when have we allowed four of these at once". */
     { path: ".intentic/config/heavy-commands.json", invalidates: ["settings"], portability: "carry", versioned: true },
+    /* THE SCRIPTS THE RULE TABLE RUNS, one file per reader, at the moments settings.json points them at: the
+     * per-edit linter and byte scan today (`file.edited`), whatever the owner adds beside them tomorrow.
+     *
+     * IT IS HERE BECAUSE IT WAS NOT, and the gap was silent. The root repository excludes `.intentic/config/*`
+     * with one carve-out per tracked entry, derived from this table's `versioned` flags (history.ts
+     * rootExcludes), so a directory nobody marked is ignored — and an ignored file is invisible to the land.
+     * The two scripts were written in an agent's worktree; the rules naming them were written into
+     * settings.json, which IS tracked; and only the rules arrived. What the workspace held from then on was two
+     * hooks pointing at files that did not exist: a per-edit gate that looked armed on the settings screen,
+     * spawned a process on every edit, and read nothing. The linter and the byte scan ran nowhere between an
+     * edit and a push for as long as that stood.
+     *
+     * `versioned` for the strongest form of the reason the config slice generally is. This is not a setting that
+     * decides how the sandbox behaves, it is the CODE that runs when it does, against every file an agent
+     * writes: a change here deserves review more than a change to the rule that calls it. `carry`, because it is
+     * authored text about this workspace's own conventions, holding no credential and nothing about this
+     * machine. Invalidating nothing is a real answer here rather than a gap: the settings screen renders the
+     * RULES, which live in settings.json and have their own key. */
+    {
+        path: ".intentic/config/hooks/",
+        invalidates: [],
+        why: "The settings screen renders the rules that name these scripts, out of settings.json; nothing in the browser reads the scripts themselves.",
+        portability: "carry",
+        versioned: true,
+        // The daemon never BUILDS this path, it only runs what a rule's command names, so there is no statePath
+        // call for the coverage pair to find. Whoever authors a reader is the writer here.
+        outsideWriter: "the owner or an agent, authoring them; the daemon only ever RUNS one, by the path a rule's command names",
+    },
     // The rule table's last-fired stamps, beside the rules themselves. `derived` rather than `carry`: it is a
     // record of what happened in THIS sandbox, and carrying it to a fresh one would date every rule to work
     // that machine never did.
@@ -710,6 +738,12 @@ const STATE_FILES = [
      * behaves, it holds no credential, and it belongs in a pull request, which is also what makes it
      * searchable, since every versioned entry already is. */
     { path: ".intentic/config/personas/", invalidates: ["personas"], portability: "carry", versioned: true },
+
+    /* THE CONTEXT SHELVES, one JSON file per shelf (schemas/context.ts): which part of the workspace a
+     * conversation opened on it carries. `versioned` and `carry` on the persona card's own argument, a shelf is
+     * a list of item ids and holds no credential, and which repositories a session can see is exactly the kind
+     * of decision that belongs in a pull request. */
+    { path: ".intentic/config/context/", invalidates: ["context"], portability: "carry", versioned: true },
 ] as const satisfies readonly WorkspaceStateFile[];
 
 export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = STATE_FILES;
@@ -927,7 +961,7 @@ export const isReportedManifest = (relPath: string): boolean => REPORTED_MANIFES
  * and all of `identity` and `secrets` is in. That is not an accident of the grouping, it is a different question
  *, "would showing the bytes hand someone something" rather than "what kind of thing is this", so it keeps an
  * explicit list, just one that now names the folder each entry lives in. */
-const LOCKED_STATE_ENTRIES: ReadonlySet<string> = new Set([
+export const LOCKED_STATE_ENTRIES: ReadonlySet<string> = new Set([
     "identity/owner.json",
     "identity/members.json",
     "identity/control-tokens.json",
@@ -943,28 +977,59 @@ const LOCKED_STATE_ENTRIES: ReadonlySet<string> = new Set([
     "claude.json",
 ]);
 
-/* Whether a workspace-root-relative path lands in that control plane, and so is shown locked rather than
- * opened. Scoped deliberately tight, matching the guard: only the ROOT `.intentic` counts (a repo's own nested
- * one is ordinary content) and only these entries within it, subtrees included, so a new provider dropped under
- * `auth/` is covered without a second edit.
+/* WHERE THE CLI'S PLAN FILES LAND, workspace-relative — and the one thing inside a locked entry that is not
+ * the sandbox's own state, which is why it is declared here rather than beside the card that draws it.
+ *
+ * `~/.claude/plans` is a symlink onto this directory (sessions/session-store.ts links the SDK's conversation
+ * state onto the workspace volume), so a plan file has a HARNESS-OWNED address: no guessing whether prose is a
+ * plan, no threshold on length, the path says so.
+ *
+ * What lands there is a DOCUMENT ADDRESSED TO THE READER. `records/sessions` is locked because it holds the
+ * provider's own conversation state; a plan is the opposite of that — the chat renders its full text into the
+ * card asking the reader to approve it, so opening the file publishes nothing the transcript had not. Locked
+ * anyway, the one link the card offers into the workspace landed on a padlock reading "it holds something only
+ * the sandbox itself uses", about a document the sandbox had just asked the reader to approve. */
+export const PLAN_DOCUMENTS_DIR = `${STATE_DIR}/records/sessions/claude/plans`;
+
+/* WHICH locked entry a workspace-root-relative path belongs to, or undefined for a path that is not in the
+ * control plane at all. Scoped deliberately tight, matching the guard: only the ROOT `.intentic` counts (a
+ * repo's own nested one is ordinary content) and only these entries within it, subtrees included, so a new
+ * provider dropped under `auth/` is covered without a second edit.
  *
  * The ROOT's own `.git` joins them. It is the pointer to the shadow history repo kept off the workspace so the
  * agent cannot rewrite its own past; a NESTED repo's `.git` is ordinary content and stays browsable.
  *
+ * The ENTRY rather than a boolean, because the screen that reports a refusal has to say what the file holds and
+ * where the thing inside it is actually managed, and it can only do that from the name of the entry the path
+ * matched — never from the leaf, which is a Chromium cookie jar or a mint-fresh session id. Keeping that lookup
+ * keyed on this function's answer is what stops the browser's sentences from drifting off the daemon's list, as
+ * they did through the regrouping: every one of them was still keyed on `sessions` and `auth` while the rule
+ * had moved to `records/sessions` and `secrets/auth`, so every locked file in the product fell through to the
+ * generic sentence and lost its way out.
+ *
  * Accepts either slash so a caller holding a platform path doesn't have to normalize first. */
-export const isLockedWorkspacePath = (relPath: string): boolean => {
+export const lockedWorkspaceEntry = (relPath: string): string | undefined => {
     const segments = relPath.split(/[\\/]/).filter((segment) => segment !== "" && segment !== ".");
     if (segments[0] === ".git") {
-        return true;
+        return ".git";
     }
     if (segments[0] !== STATE_DIR) {
-        return false;
+        return undefined;
+    }
+    const rel = segments.join("/");
+    if (rel === PLAN_DOCUMENTS_DIR || rel.startsWith(`${PLAN_DOCUMENTS_DIR}/`)) {
+        return undefined;
     }
     // Two segments, which covers both spellings in the set above: a grouped entry (`secrets/auth`) matches as
     // written, and a bare root entry (`claude.json`) joins to itself because there is no second segment to add.
-    return LOCKED_STATE_ENTRIES.has(segments.slice(1, 3).join("/"));
+    const entry = segments.slice(1, 3).join("/");
+    return LOCKED_STATE_ENTRIES.has(entry) ? entry : undefined;
 };
 
+// Whether a path lands in that control plane, and so is refused by the file API and shown locked rather than
+// opened. The question every guard asks; the entry above is for the one screen that has to name it.
+export const isLockedWorkspacePath = (relPath: string): boolean => lockedWorkspaceEntry(relPath) !== undefined;
+
 /* THE LOCKED ENTRIES THE ROOT REPO TRACKS, refused by the file API, and diffable anyway.
  *
  * `capabilities.json` is the only one today and the whole reason this exists. Both of its rules are right on