@intentic/sandbox-contract 1.245.0 → 1.247.0

package/src/schemas/terminal.ts

@@ -194,14 +194,14 @@ export type SubagentKind = z.infer<typeof SubagentKindSchema>;
 // an operator acts on differently from "the child is working".
 export const SubagentStatusSchema = z.enum(["pending", "running", "blocked", "completed", "failed", "killed", "paused"]);
 export type SubagentStatus = z.infer<typeof SubagentStatusSchema>;
-/* WHETHER ANYTHING CHECKED WHAT THE HELPER DID, carried beside its report rather than left for the reader to
- * assume. Computed from the helper's own tool calls, the files it edited against the checks that ran after
+/* WHETHER ANYTHING CHECKED WHAT THE SUBAGENT DID, carried beside its report rather than left for the reader to
+ * assume. Computed from the subagent's own tool calls, the files it edited against the checks that ran after
  * them (the daemon's child-verification.ts), so it holds on every provider rather than only where the Claude
  * hooks reach.
  *
  * The four states are deliberately not two. `verified` and `failing` each name the command that spoke, so a
  * targeted test is never read as the suite; `unproven` is the one that matters most, work changed and nothing
- * ran; and `no-code` says the helper edited nothing, which is the honest answer for a research helper and
+ * ran; and `no-code` says the subagent edited nothing, which is the honest answer for a research subagent and
  * must not be rendered as approval. Absent ⇒ the daemon saw no tool calls from it at all. */
 export const SubagentVerificationSchema = z.object({
     state: z
@@ -222,10 +222,10 @@ export const SubagentSessionSchema = z.object({
     id: z
         .string()
         .describe(
-            "The id of the tool call that started it (an SDK child) or the child's own conversation id (a spawned one); either way both sides already hold it, so a card links to its helper with the id it has and the helper points back the same way.",
+            "The id of the tool call that started it (an SDK child) or the child's own conversation id (a spawned one); either way both sides already hold it, so a card links to its subagent with the id it has and the subagent points back the same way.",
         ),
     kind: SubagentKindSchema.describe(
-        "What sort of helper: one the runtime's own Task tool spawned in-process, or a full agent the daemon started for the turn. It changes only how you watch it.",
+        "What sort of subagent: one the runtime's own Task tool spawned in-process, or a full child agent the daemon started for the turn. It changes only how you watch it.",
     ),
     // The conversation whose turn spawned this, what the area groups its rows by, and the way back to the chat
     // the card lives in.
@@ -233,19 +233,19 @@ export const SubagentSessionSchema = z.object({
     // What it is and what it was asked to do: the subagent type (`Explore`, `general-purpose`) or a spawned
     // child's provider label, and the caller's one-line description. The area's row and the card's title read
     // as `Explore · Locate claimIndexer definition`.
-    agentType: z.string().optional().describe("What kind of helper it is."),
+    agentType: z.string().optional().describe("What kind of subagent it is."),
     description: z.string().optional().describe("What it was asked to do, in one line."),
     model: z.string().optional().describe("Which model it runs on."),
     // Which provider serves a `spawned` child (its AgentProvider id), so the row can wear the right logo. An
     // SDK subagent implies its own: it runs on its parent's provider.
-    provider: z.string().optional().describe("Which provider serves it, for a helper spawned across providers."),
+    provider: z.string().optional().describe("Which provider serves it, for a child agent spawned across providers."),
     // How deep in the spawn tree (1 = spawned by the turn itself). From the SDK's meta.json; a subagent may
     // itself delegate, and a flat list that cannot say so reads as though the turn started all of them.
     spawnDepth: z
         .number()
         .optional()
         .describe(
-            "How deep in the chain it sits, where one means the turn itself started it. A helper can start helpers, and a flat list that could not say so would read as though the turn started all of them.",
+            "How deep in the chain it sits, where one means the turn itself started it. A subagent can start subagents, and a flat list that could not say so would read as though the turn started all of them.",
         ),
     // Backgrounded: the parent went on working instead of waiting for it. This is the whole reason the list
     // exists, a backgrounded child used to be invisible until its result landed, sometimes minutes later.
@@ -253,7 +253,7 @@ export const SubagentSessionSchema = z.object({
         .boolean()
         .optional()
         .describe(
-            "The parent carried on working instead of waiting for it. This is the whole reason the list exists: such a helper used to be invisible until its result landed, sometimes minutes later.",
+            "The parent carried on working instead of waiting for it. This is the whole reason the list exists: such a subagent used to be invisible until its result landed, sometimes minutes later.",
         ),
     status: SubagentStatusSchema.describe(
         "How it is going. Blocked means it needs an answer, which a parent and an operator act on differently from it simply working.",
@@ -266,7 +266,7 @@ export const SubagentSessionSchema = z.object({
     tokens: z
         .number()
         .optional()
-        .describe("What it has spent. Its own, so a parent's cost and the sum of its helpers' are two different true numbers."),
+        .describe("What it has spent. Its own, so a parent's cost and the sum of its subagents' are two different true numbers."),
     toolUses: z.number().optional().describe("How many tools it has used."),
     lastTool: z.string().optional().describe("The last one it reached for."),
     // Its report, the last assistant message (SubagentStop) or the task summary. The answer to "what did it
@@ -274,7 +274,7 @@ export const SubagentSessionSchema = z.object({
     summary: z
         .string()
         .optional()
-        .describe("Its report: what it concluded, without opening its record. The question a finished helper gets read for."),
+        .describe("Its report: what it concluded, without opening its record. The question a finished subagent gets read for."),
     error: z.string().optional().describe("Why it failed, when it did."),
     // Whether anything checked the work behind that report (SubagentVerificationSchema). Filled once it ends:
     // a standing read while it is still working would be a verdict on a job half done.
@@ -282,7 +282,7 @@ export const SubagentSessionSchema = z.object({
 });
 export type SubagentSession = z.infer<typeof SubagentSessionSchema>;
 export const SubagentsListSchema = z.object({
-    sessions: z.array(SubagentSessionSchema).describe("Every helper this sandbox's conversations have started."),
+    sessions: z.array(SubagentSessionSchema).describe("Every subagent and child agent this sandbox's conversations have started."),
 });
 export type SubagentsList = z.infer<typeof SubagentsListSchema>;
 export const SubagentIdParamSchema = z.object({ id: z.string() });

package/src/schemas/usage.ts

@@ -83,14 +83,6 @@ export const UsageTurnSchema = z.object({
     cacheCreationTokens: z.number().describe("Tokens written to cache, which cost more up front and less afterwards."),
     costUsd: z.number().describe("What it cost, in dollars."),
     durationMs: z.number().describe("How long it took, in milliseconds."),
-    /* Which arm of the terse experiment this turn ran on (settings.terseHoldout), the only record of it, and
-     * the reason the savings report can say what the steer is worth instead of guessing.
-     *
-     * ABSENT means "not part of the experiment", not "off": a turn under a custom system prompt drops the
-     * steer along with everything else the daemon appends, and a turn run with the experiment switched off has
-     * no control to be compared against. Pooling those into the off-arm would compare steered turns against a
-     * population selected by something other than the coin flip, which is not a control at all. */
-    terse: z.boolean().optional(),
     /* Which arm of the iq SEARCH-TEACHING experiment this conversation runs on
      * (settings.iqSearchHoldout). Stable for every turn in one conversation: the treatment is instruction
      * loaded into a provider session, so flipping it per turn would call a remembered treatment a control.
@@ -99,25 +91,9 @@ export const UsageTurnSchema = z.object({
     // Hash of the plugin nudge + skill body used for this arm. Control turns carry it too, so a report can keep
     // both sides of one treatment revision together and exclude older wording after an upgrade.
     iqSearchCohort: z.string().optional(),
-    /* Characters of the model's own PROSE this turn, the `delta` frames only, so no tool-call arguments and no
-     * thinking. What the terse steer is judged on, and the reason it can be judged at all.
-     *
-     * `outputTokens` cannot serve: measured over a day of real turns it is 91.6% tool-call arguments (an Edit's
-     * old_string and new_string, a Write's whole file body) and 7.8% prose. The steer moves prose. So a fifth
-     * off the model's narration moves the total by 1.6%, against a margin of ±35 points, which is to say the
-     * experiment was structurally unable to see its own treatment, and the number it printed instead was
-     * whichever arm happened to draw the bigger tasks.
-     *
-     * CHARACTERS, not tokens, because the provider bills a total and never breaks it down, a token figure here
-     * would be chars÷4 wearing a unit it had not earned. For a comparison of two arms the constant cancels
-     * anyway, and the honest unit is the one actually counted.
-     *
-     * Absent ⇒ the turn predates this being measured; `armOf` drops it from the population rather than reading
-     * it as a silent turn. */
-    proseChars: z.number().optional(),
     /* SEARCHES THIS TURN RAN, every tool call that went looking for code, the dedicated search tools and the
      * CLI searches alike (isSearchCall owns the rule; `iq q` is Bash and would otherwise not be counted at all).
-     * What the search teaching is judged on, and the same correction `proseChars` is to the terse steer.
+     * What the search teaching is judged on.
      *
      * COST PER TURN CANNOT SERVE: cost is a whole turn's worth of work, a search mechanism touches one part of
      * it, and the part lives inside the noise of the rest, exactly the shape that made output tokens unable to
@@ -128,8 +104,8 @@ export const UsageTurnSchema = z.object({
      * rather than being filtered out, they dilute both arms equally, while selecting on "did it search" would
      * select on the treatment itself.
      *
-     * Absent ⇒ the turn predates this being measured; `armOf` drops it rather than reading it as a turn that
-     * searched nothing. */
+     * Absent ⇒ the turn predates this being measured; the arm's mean drops it (turn-experiments.ts, the filter
+     * inside `conversationExperimentOf`) rather than reading it as a turn that searched nothing. */
     searchCalls: z.number().optional(),
     /* …and how many of them came BEFORE the turn first opened or changed a file, the orientation burst. A turn
      * that already knows where to look starts working; one that doesn't goes hunting first.
@@ -143,6 +119,65 @@ export const UsageTurnSchema = z.object({
      *
      * Absent ⇒ as for `searchCalls`. */
     openingSearches: z.number().optional(),
+    /* THE LISTINGS THIS TURN RAN TO WORK OUT WHERE IT WAS, `ls`, `ls /work`, `tree intentic`, the LS tool
+     * aimed at the same places (isRootListing owns the rule). What the project map is judged on, and the
+     * reason it could not be judged before.
+     *
+     * `searchCalls` counts a directory listing and a ripgrep as one event, deliberately, so that a taxonomy
+     * cannot report whichever spelling of a search the model happened to reach for. That is right for the
+     * search teaching and blind to the map: measured over 468 mapped sessions of this workspace against 497
+     * unmapped ones, searches before the first file moved +7.6% with a margin of ±17.6pp, while the share of
+     * sessions opening with a directory listing fell from 46.3% to 32.1%. The map does not shorten the
+     * orientation burst, it changes what the burst is made of, and only this counts the difference.
+     *
+     * UP TO THE FIRST FILE, exactly like `openingSearches`, which took the corpus to settle. Counted over the
+     * whole turn instead, the same sessions give 66.4% against 73.3%, a gap of 6.9pp where the orientation
+     * window gives 14.2pp. The dilution is not noise: a turn already at work lists the directory it has
+     * narrowed to, and no map could have answered that. The shape of the listing cannot tell the two apart,
+     * because it is the same shape; only when it happened can.
+     *
+     * Absent ⇒ the turn predates this being measured, never a turn that listed nothing. */
+    openingListings: z.number().optional(),
+    /* TOOL CALLS BEFORE THE TURN FIRST TOUCHED A FILE IT WENT ON TO EDIT: how far it walked before reaching
+     * the thing it turned out to be looking for. The corpus study this map was designed from measured the
+     * same quantity by hand (the workspace's docs/agent-exploration-patterns.md §4: median 4, mean 8.2) and called it the one
+     * honest reading of whether orientation got better.
+     *
+     * IT CAN ONLY BE KNOWN AT THE END, which is why it is recorded here and computed nowhere else: whether a
+     * file was the target is a fact about the turn's edits, and the turn has to finish before that is
+     * decided. The route keeps the first call index per path and intersects it with the edit ledger.
+     *
+     * Absent on a turn that edited nothing, which is most short turns, and NOT zero: a turn with no target
+     * never reached one, and averaging that in as "reached it immediately" would report the turns that did
+     * no work as the best targeted. That absence costs the reading three quarters of the population, so it
+     * is a metric to accumulate for months rather than a gate to wait on. */
+    callsBeforeTarget: z.number().optional(),
+    /* WHICH ARM OF THE PROJECT MAP EXPERIMENT this conversation ran (settings.workspaceMapHoldout), and how
+     * many characters the note actually cost when it was sent.
+     *
+     * CONVERSATION-STABLE, and for a plainer reason than the search teaching's: the map is sent once, on the
+     * opening message, so every later turn of a mapped conversation is a turn whose transcript holds a map.
+     * A per-turn flip would label eleven treated turns as controls.
+     *
+     * `mapChars` rather than a token estimate, because characters are what the renderer's budget is in
+     * (workspace-map.ts caps the note at 2,800) and a tokenizer's answer would vary by model. Present only on
+     * the turn that actually sent one, so the ledger says what the feature costs instead of assuming it: the
+     * median note over this workspace's own corpus is 795 characters against a ceiling of 2,800.
+     *
+     * Absent ⇒ no measurement (the holdout is zero, or the row predates it); true/false ⇒ mapped/unmapped. */
+    mapArm: z.boolean().optional(),
+    mapChars: z.number().optional(),
+    /* WHICH TURN OF ITS CONVERSATION THIS WAS, counting from zero, so an opening turn can be recognised from
+     * one row instead of inferred from the rows around it.
+     *
+     * The inference it replaces is wrong at exactly one place and it is the place that matters: a reader
+     * windowed to the last seven days would take each conversation's earliest row IN THE WINDOW as its
+     * opening turn, so every conversation that started the week before would contribute a mid-conversation
+     * turn to a reading about first turns. The project map is sent on turn zero and nowhere else, so that
+     * misreading is not an edge case for it, it is the measurement.
+     *
+     * Absent ⇒ the row predates this, or the turn belonged to no conversation at all. */
+    turnIndex: z.number().optional(),
     /* DID THIS TURN FINISH, OR DID IT STOP TALKING. The fields that tell the two apart, and the reason
      * `outcome` alone could never.
      *

package/src/schemas/version-seam.test.ts

@@ -15,7 +15,6 @@ test("a payload from a build that predates a toggle parses, with the new toggle
         stableSystemPrompt: false,
         skills: [],
         hashlineEdits: false,
-        terseOutput: true,
         iqSearch: true,
         outputCleaners: "-cap",
         outputHoldout: 0.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