@intentic/sandbox-contract 1.214.0 → 1.216.0

package/src/schemas.ts

@@ -1725,11 +1725,9 @@ export const SkillRemoveSchema = z.object({ name: SkillNameSchema });
 //                        only. Opt-in (default off); the browser Search box uses iq regardless.
 //   iqSearchHoldout   — conversation-level measurement control for iqSearch (UsageTurn.iqSearchArm). The arm
 //                        stays fixed because teaching already loaded into a session cannot be removed next turn.
-//   iqContext         — retrieves for the user's message BEFORE the turn starts and prepends the ranked answer
-//                        to it, so the model opens with the anchors instead of paying a search round-trip to
-//                        find them. Independent of iqSearch: that one teaches the agent to search, this one
-//                        answers ahead of it.
-//   iqContextHoldout  — measurement control for iqContext, same shape as terseHoldout (UsageTurn.iqContext).
+//   workspaceMap      — computes an AREA index of the project a run starts in and prepends it to the
+//                        conversation's opening message, so the turn does not have to buy its own orientation
+//                        with a directory listing. Generated from the filesystem every time, never stored.
 //   outputCleaners    — the Bash output-cleaner spec (agent-output-filter): "off" = filter disabled (default),
 //                        "" = all cleaners on, else an iq-style allow-list / default-minus
 //                        spec ("git,pnpm" = only those; "-cap" = all except). Threaded to the filter via env.
@@ -1796,21 +1794,23 @@ export const SandboxSettingsSchema = z.object({
      * a valid control here: once the teaching enters a provider session, withholding it from the next request
      * does not make the model forget it. 0 ⇒ no measurement and every conversation receives the teaching. */
     iqSearchHoldout: z.number().min(0).max(1).default(0),
-    /* RETRIEVE BEFORE THE TURN, don't wait to be asked. The daemon runs the user's message through the resident
-     * iq engine and prepends the ranked answer to it, so a turn that would have opened with two or three search
-     * calls opens with the anchors already in hand. Independent of `iqSearch`, which only teaches the agent to
-     * reach for the CLI once it decides to search — this one answers ahead of that decision, and the two
-     * compose: the injected capsule names the anchors, the CLI is there for what it missed.
+    /* THE MAP THE TURN OPENS WITH — which areas the project a run starts in has, one derived line on what each
+     * is for, and where the run is standing among them (agent/workspace-map.ts).
      *
-     * It rides the USER message (turn-context.ts), never the system prompt, for the same reason the setup
-     * notice does: it changes every turn, and the system prefix is kept byte-stable for the prompt cache.
-     * Off by default — it spends input tokens on every eligible turn, and whether that trade pays is exactly
-     * what the holdout below is for. */
-    iqContext: z.boolean().default(false),
-    // Measurement control for the pre-injection, identical in shape to `terseHoldout`: a fraction [0,1] of
-    // otherwise-eligible turns run WITHOUT the retrieved context and stamp their arm onto the ledger
-    // (UsageTurn.iqContext), so the report compares two real populations of turns instead of asserting a saving.
-    iqContextHoldout: z.number().min(0).max(1).default(0),
+     * It answers the question every first turn has whatever it was asked — "what is this and where am I in
+     * it" — which across a hundred sessions of this workspace was being bought with a directory listing in two
+     * turns out of five, and with ~5.3k tokens of tool results before the job was touched.
+     *
+     * ROOTED AT THE RUN'S STARTING FOLDER rather than at the workspace: a persona's start folder, an isolated
+     * conversation's worktree, or wherever the turn's cwd is. It maps the project containing that folder and
+     * names the rest of the workspace on one line, because a run three levels inside one project is not asking
+     * about the others.
+     *
+     * REGENERATED, NEVER STORED, which is the whole reason it is a mechanism rather than a paragraph in the
+     * system prompt or a hand-written CLAUDE.md: in the ten days that motivated it this repo's two busiest
+     * top-level directories stopped existing, and every written-down copy of the layout was wrong by the end of
+     * the window. Off by default — it spends its tokens on the opening message of every conversation. */
+    workspaceMap: z.boolean().default(false),
     outputCleaners: z.string().default("off"),
     outputHoldout: z.number().min(0).max(1).default(0),
     /* The models behind the small automatic jobs that are not a conversation — today the commit message
@@ -2037,34 +2037,17 @@ export type InputSavings = z.infer<typeof InputSavingsSchema>;
 // without it. A mean PER TURN, because the arms never hold the same number of turns.
 export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() });
 
-/* WHAT BECAME OF A TURN'S PRE-TURN RETRIEVAL. `note` is the only outcome that reaches the model; the rest are
- * the ordinary ways it declines, and none of them is an error — each is a turn that proceeded exactly as it
- * would have without the feature.
- *
- *   ineligible — the prompt failed a lexical gate before retrieval ran (it named its own file, or said nothing
- *                to search for). By design, and the largest share by far.
- *   deadline   — the resident engine outran its budget and the turn went on without it.
- *   indexing   — the index had not caught up with disk, so any answer would have been confidently partial.
- *   no-hits    — the query matched nothing.
- *   failed     — retrieval threw; swallowed on purpose, since this is an optimisation nobody asked for.
- *
- * It lives in the contract rather than in the daemon because two things downstream of the daemon have to speak
- * it: the ledger row that records it (UsageTurnSchema.iqContextOutcome) and the experiment that reads it back
- * (TurnExperimentSchema.outcomes). Declared here, above both. */
-export const IqContextOutcomeSchema = z.enum(["note", "ineligible", "deadline", "indexing", "no-hits", "failed"]);
-export type IqContextOutcome = z.infer<typeof IqContextOutcomeSchema>;
-
 /* ONE METRIC'S READING of a turn-level experiment: the two arms, and whatever the arithmetic over them will
  * stand behind. An experiment can carry several — see TurnExperimentSchema.
  *
  * `metric` says what `mean` counts and what `deltaPct` is a delta in, and choosing it is most of the work.
  *   proseChars      — the terse steer: the thing it steers, and the only part of the model's output that
  *                     responds to being asked to be brief (UsageTurn.proseChars has why output tokens cannot).
- *   searchCalls     — pre-injection: the searches a turn ran, which the retrieval directly removes.
- *   openingSearches — pre-injection, narrower: the searches before the turn first touched a file.
- * Pre-injection used to be judged on COST, and could not be. UsageTurn.searchCalls has the nine days of data
- * that settled it — cost is a whole turn's work, retrieval moves one part of it, and the part sat inside the
- * noise of the rest exactly as the steer's effect once sat inside its tool-call arguments. */
+ *   searchCalls     — the search teaching: the searches a turn ran, which the teaching directly changes.
+ *   openingSearches — the same, narrower: the searches before the turn first touched a file.
+ * Search mechanisms must not be judged on COST. Cost is a whole turn's work, a search mechanism moves one part
+ * of it, and the part sits inside the noise of the rest exactly as the steer's effect once sat inside its
+ * tool-call arguments. */
 export const TurnMetricReadingSchema = z.object({
     metric: z.enum(["proseChars", "searchCalls", "openingSearches"]),
     on: SavingsArmSchema,
@@ -2112,11 +2095,11 @@ export type TurnMetricReading = z.infer<typeof TurnMetricReadingSchema>;
  * counted: a turn under a custom system prompt drops the terse steer along with everything else the daemon
  * appends, so it belongs to neither arm.
  *
- * ONE COIN FLIP, SEVERAL READINGS. `metrics` is a list because pre-injection is judged on two — the searches a
- * turn ran, and the ones it ran before touching a file — and they are two readings of the SAME experiment, not
- * two experiments. Splitting them into separate entries would duplicate the arm assignment and the delivery
- * rate below, and let a screen show a turn count on one that disagrees with the other. Headline first: the
- * screens read `metrics[0]` for the big number and the rest as supporting lines. */
+ * ONE COIN FLIP, SEVERAL READINGS. `metrics` is a list because the search teaching is judged on two — the
+ * searches a turn ran, and the ones it ran before touching a file — and they are two readings of the SAME
+ * experiment, not two experiments. Splitting them into separate entries would duplicate the arm assignment and
+ * let a screen show a turn count on one that disagrees with the other. Headline first: the screens read
+ * `metrics[0]` for the big number and the rest as supporting lines. */
 export const TurnExperimentSchema = z.object({
     // A head and a tail rather than a plain array, because an experiment judged on nothing is not an experiment:
     // the screens take the first reading for their headline and stack the rest under it, and this is what makes
@@ -2133,32 +2116,16 @@ export const TurnExperimentSchema = z.object({
     // Content-addressed treatment version. Present where mixing rows from two instruction revisions would turn
     // one experiment into two unnamed ones; the reader filters to this (latest) cohort.
     cohort: z.string().optional(),
-    /* How much of the treatment arm the treatment actually REACHED, when that is knowable and less than all of
-     * it — pre-injection's arm is the coin flip (intention-to-treat, deliberately), and a turn can be assigned
-     * the retrieval and still have nothing to prepend. Measured at four turns in five, which is the difference
-     * between a mechanism worth little and one worth five times what the delta says.
-     *
-     * Absent ⇒ delivery is not a separate question for this experiment (the terse steer always lands) or no
-     * turn in the window recorded it. The screen shows the delta as diluted rather than silently scaling it:
-     * the correction is a division by a rate this small only when the rate is itself well measured. */
-    deliveredPct: z.number().optional(),
-    /* WHERE THE REST OF THE TREATMENT ARM WENT, most common first. `deliveredPct` says a mechanism reached one
-     * turn in five; this says whether the other four were the eligibility gate declining on purpose or a
-     * two-second deadline quietly eating the feature, which are the same number and opposite problems.
-     *
-     * Absent ⇒ the experiment has no delivery question (the terse steer always lands) or no turn recorded one. */
-    outcomes: z.array(z.object({ outcome: IqContextOutcomeSchema, turns: z.number() })).optional(),
 });
 export type TurnExperiment = z.infer<typeof TurnExperimentSchema>;
 
-// `output`/`context` are absent when that experiment isn't running at all (its flag off, or no holdout set) — a
+// `output`/`search` are absent when that experiment isn't running at all (its flag off, or no holdout set) — a
 // section that isn't there reads as "not measured", which is the truth, while zeros would read as "measured,
 // worth nothing".
 export const SavingsReportSchema = z.object({
     input: InputSavingsSchema,
     output: TurnExperimentSchema.optional(),
     search: TurnExperimentSchema.optional(),
-    context: TurnExperimentSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 
@@ -2507,6 +2474,52 @@ export const GitLogQuerySchema = RepoParamSchema.extend({
 // Every real git repo under /work as root-relative dir ids ("root" is implicit — the /work repo itself).
 export const GitReposSchema = z.object({ repos: z.array(z.string()) });
 export type GitRepos = z.infer<typeof GitReposSchema>;
+
+/* WHERE EACH WORKSPACE REPO LIVES ONLINE — one entry per repo that has a parseable remote, as the host and the
+ * `owner/name` project it names. Separate from `repos` above rather than folded into it because that route is
+ * on the file tree's hot path and this costs a `git remote -v` per repo; a caller that wants to recognise a
+ * workspace repo in somebody else's list (the publisher claim does exactly that) asks for it deliberately.
+ *
+ * A repo with no remote, or one naming a local path, is absent rather than present-and-empty: "this repo is
+ * nowhere online" and "this repo is at X" are different answers and only one of them can be matched against. */
+export const GitRemoteRepoSchema = z.object({ repo: z.string(), host: z.string(), project: z.string() });
+export type GitRemoteRepo = z.infer<typeof GitRemoteRepoSchema>;
+export const GitRemoteReposSchema = z.object({ repos: z.array(GitRemoteRepoSchema) });
+export type GitRemoteRepos = z.infer<typeof GitRemoteReposSchema>;
+
+/* PUT ONE FILE ON THE DEFAULT BRANCH AND PUBLISH IT — write, commit that path alone, push, in one call.
+ *
+ * One route rather than three because the interesting states are the ones BETWEEN the steps: a file written but
+ * not committed, or committed but not pushed, is a repo the user now has to clean up by hand, and a browser
+ * making three requests owns that mess without being able to describe it. Here the caller gets one answer that
+ * says how far it got.
+ *
+ * `message` is the caller's because the commit shows up in the user's own history and a generic subject there
+ * is litter. */
+export const GitPublishFileSchema = RepoParamSchema.extend({ path: z.string().min(1), content: z.string(), message: z.string().min(1) });
+
+/* HOW FAR THE PUBLISH GOT, in the terms the screen has to explain it in. `ok` is "the file is on the default
+ * branch of the remote" and nothing less — the only state that makes a public read of it succeed.
+ *
+ * The three steps are reported SEPARATELY because every boundary between them is a state a user can be left
+ * in and would otherwise have to discover: a file written but not committed, a commit that exists locally but
+ * was refused by the remote for credentials. Each of those needs a different sentence and a different next
+ * move, and one `ok: false` cannot carry either. It is also what tells the daemon whether the worktree moved
+ * at all, which decides whether this counts as a user write on the timeline.
+ *
+ * `branch` and `defaultBranch` ride along so a refusal can name both sides of the mismatch rather than saying
+ * "wrong branch" at someone who cannot see which one they are on. */
+export const GitPublishFileResultSchema = z.object({
+    ok: z.boolean(),
+    wrote: z.boolean(),
+    committed: z.boolean(),
+    pushed: z.boolean(),
+    branch: z.string().optional(),
+    defaultBranch: z.string().optional(),
+    reason: z.string().optional(),
+});
+export type GitPublishFileResult = z.infer<typeof GitPublishFileResultSchema>;
+
 export const GitCommitDiffQuerySchema = RepoParamSchema.extend({ sha: ShaSchema });
 // A commit's changed files (vs its first parent; a root commit vs the empty tree) — the graph's detail tree
 // renders these (line stats included) and reuses the diff UI on click. Just GitChanges: the line stats live on
@@ -3871,12 +3884,25 @@ export const CapabilityStatusSchema = z.object({
     code: z.string().optional(),
 });
 export type CapabilityStatus = z.infer<typeof CapabilityStatusSchema>;
-// The list row: manifest entry + live status. Secrets are never returned (an mcp token becomes hasToken).
+/* The list row: manifest entry + live status. Secrets are never returned (an mcp token becomes hasToken).
+ *
+ * `secrets` NAMES them without carrying them — the config keys this connection is actually holding a credential
+ * under. It is what makes an edit form possible at all: `config` is everything the browser may see, so a form
+ * seeded from it alone cannot tell "this tunnel has a pre-shared key I'm not allowed to show you" from "this
+ * tunnel has no pre-shared key", and both render as an empty required box. Saving one then wipes the
+ * credential, which is why changing a routed network used to mean re-typing a key.
+ *
+ * Keys, never values, and never a boolean per known field: the set is derived from what the entry stores, so a
+ * field the user left blank is absent and a card that gained a credential since is present. The form reads it as
+ * "show dots, and let blank mean keep" (VAULTED — capability-secrets.ts). */
 export const CapabilitySummarySchema = z.object({
     id: z.string(),
     kind: CapabilityKindSchema,
     status: CapabilityStatusSchema,
     config: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
+    // Defaulted for the daemon-older-than-browser seam, like `recommendations` below: a required field would
+    // fail the whole list parse against a sandbox predating this, taking the page down to hide some dots.
+    secrets: z.array(z.string()).default([]),
 });
 /* A capability the WORKSPACE asks for but the manifest doesn't carry — derived from what is checked out under
  * /work, not from anything the user configured. It exists because the failures it prevents are illegible: a
@@ -5421,19 +5447,23 @@ export type MachineSandbox = z.infer<typeof MachineSandboxSchema>;
 /* ONE OPERATION ON ONE SANDBOX ON ONE MACHINE — the Computers view's buttons, and the only thing that changes a
  * machine's fleet from a browser.
  *
- * All eight ops travel one route because they are one decision to the person clicking, however differently they
- * behave underneath: three are a docker call that returns in a second, three run the `ic` flow for minutes, one
+ * All nine ops travel one route because they are one decision to the person clicking, however differently they
+ * behave underneath: three are a docker call that returns in a second, four run the `ic` flow for minutes, one
  * deletes, and one only reads. Splitting them by duration would put the same button on two doors and give the
  * view two shapes to render. So every op answers as a STREAM of lines ending in a result — the fast ones simply
  * have little to say, and `logs` is the case where the lines ARE the answer.
  *
- * `logs` is here rather than on a route of its own for the same reason: it is a button in the same row as the
- * other seven, on a container that may be too broken to answer any other way, and the stream shape already
- * carries "many lines, then an outcome" exactly as a log tail wants to arrive.
+ * `prepare` is the one that changes nothing on purpose: it downloads and builds the next update and stops
+ * there, leaving the container running the image it was already running. It is what turns `update` from a wait
+ * of minutes into a restart of seconds, and it is safe to offer at any moment for exactly that reason.
  *
- * The machine enforces which of them it will do: `sandboxes` covers the first six and the log tail, removal takes
- * its own switch, and a refusal comes back as the machine's own sentence naming the control to flip. */
-export const MachineSandboxOpSchema = z.enum(["start", "stop", "restart", "update", "rebuild", "rollback", "remove", "logs"]);
+ * `logs` is here rather than on a route of its own for the same reason the rest share it: it is a button in the
+ * same row as the others, on a container that may be too broken to answer any other way, and the stream shape
+ * already carries "many lines, then an outcome" exactly as a log tail wants to arrive.
+ *
+ * The machine enforces which of them it will do: `sandboxes` covers everything but removal, which takes its own
+ * switch, and a refusal comes back as the machine's own sentence naming the control to flip. */
+export const MachineSandboxOpSchema = z.enum(["start", "stop", "restart", "prepare", "update", "rebuild", "rollback", "remove", "logs"]);
 export type MachineSandboxOp = z.infer<typeof MachineSandboxOpSchema>;
 
 export const MachineSandboxFlowSchema = z.object({
@@ -5512,8 +5542,25 @@ export type MachinePort = z.infer<typeof MachinePortSchema>;
 export const MachineWatcherSchema = z.object({
     running: z.boolean(),
     pid: z.number().int().optional(),
+    /* When the watcher last FINISHED a pass — the field that makes `running` mean something. The agent holds its
+     * SSH transport listeners on its own event loop, so a failure that escapes the loop leaves a process that is
+     * alive and a loop that is gone: pid present, unit "active", mirroring and the git bridge stopped. Absent
+     * means the agent has not reported one (too old to stamp, or its first pass has not landed) — which is not
+     * the same as stalled, and readers must not treat it as either state. */
     lastTickAt: z.number().optional(),
 });
+export type MachineWatcher = z.infer<typeof MachineWatcherSchema>;
+
+/* How long a watcher may go without finishing a pass before "running" stops being the honest word for it. Its
+ * loop polls every 5s and its slowest step is bounded by two 10s network timeouts per pairing, so a minute is
+ * several passes of slack — the same yardstick the Computers view already ages a whole report by.
+ *
+ * The rule lives HERE, next to the field, because the terminal and the browser both answer this question and a
+ * machine that is "running" in one and "stalled" in the other is worse than either answer alone. */
+export const WATCHER_STALL_AFTER_MS = 60_000;
+
+export const watcherStalled = (watcher: MachineWatcher, now: number): boolean =>
+    watcher.running && watcher.lastTickAt !== undefined && now - watcher.lastTickAt > WATCHER_STALL_AFTER_MS;
 
 export const MachineReportSchema = z.object({
     /* The OS hostname, and the JOIN KEY. A machine can arrive here two ways at once — volunteered by its sync
@@ -6198,6 +6245,31 @@ export const AdapterHealthSchema = z.object({
 });
 export type AdapterHealthReport = z.infer<typeof AdapterHealthSchema>;
 
+/* AN UPDATE ALREADY DOWNLOADED AND BUILT, waiting for the restart that applies it.
+ *
+ * An update is one blocking operation but it was never one kind of work: pulling the new image and re-applying
+ * the environment recipe take the overwhelming majority of the wall clock, and the sandbox is up and serving
+ * through both of them. Only the cutover is downtime, and it is seconds.
+ *
+ * The daemon cannot know any of this by itself — it holds no host Docker socket — so `ic sandbox prepare`
+ * tells it, on the machine that runs the container. That is the whole reason this exists: without it, the
+ * update card had to quote the download as if it were an outage, and "a few minutes, this page loses the
+ * sandbox" is a completely different decision from "about half a minute".
+ *
+ * Advisory only, in the strict sense: it decides what a card SAYS and never what gets installed. The swap
+ * re-derives every one of these facts from the host-side record and refuses the fast path if any has drifted. */
+export const StagedUpdateSchema = z.object({
+    // The version the staged image reports about itself. Absent when the image would not say (an older build,
+    // a probe that failed), which reads as "ready, version unknown" — never as nothing being ready.
+    version: z.string().optional(),
+    // The release channel it was staged FROM, which is not necessarily the one this sandbox follows: preparing
+    // a beta build is not moving onto beta.
+    channel: z.string(),
+    // When it finished downloading, epoch ms — what answers "is this still the update I am being offered?"
+    at: z.number(),
+});
+export type StagedUpdate = z.infer<typeof StagedUpdateSchema>;
+
 export const InfoSchema = z.object({
     name: z.string().optional(),
     image: z.string().optional(),
@@ -6233,6 +6305,9 @@ export const InfoSchema = z.object({
      * turns the update card from an offer into a warning that asks to be read before it hands over the
      * command. Absent for the overwhelming majority of updates, which break nothing. */
     breakingNotes: z.array(z.string()).optional(),
+    /* AN UPDATE THAT HAS ALREADY BEEN DOWNLOADED AND BUILT on the machine that runs this container, and is
+     * waiting for the restart that applies it. Absent for the ordinary case where nothing is staged. */
+    staged: StagedUpdateSchema.optional(),
 });
 export type Info = z.infer<typeof InfoSchema>;
 
@@ -6394,31 +6469,6 @@ export const UsageTurnSchema = z.object({
      * 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 pre-injection experiment this turn ran on (settings.iqContextHoldout), on the same terms
-     * as `terse` above: absent ⇒ outside the experiment.
-     *
-     * TRUE means the turn was ASSIGNED the retrieved context, not that a note was necessarily prepended — a
-     * treatment turn whose retrieval came back empty or unconfident injects nothing. That is deliberate: the
-     * arms have to be the coin flip's populations, and re-labelling a turn by what retrieval happened to find
-     * would sort turns by how searchable their question was, which is a property of the question. The control
-     * arm contains the same unsearchable questions in the same proportion, so they cancel. */
-    iqContext: z.boolean().optional(),
-    /* WHAT ACTUALLY HAPPENED to the retrieval on this turn — the companion to `iqContext`, and the answer to the
-     * question that field's design deliberately refuses to answer.
-     *
-     * Keeping the arm on the coin flip is right, and it costs something: the treatment arm contains turns the
-     * treatment never reached, so the delta it yields is diluted by however many those are. Measured over nine
-     * days of real use that was four turns in five, which makes the difference between "this mechanism is worth
-     * little" and "this mechanism is worth five times what the number says".
-     *
-     * IT RECORDS THE REASON, not merely a yes/no, because the yes/no left the whole loss unexplained. 81% of an
-     * assigned arm delivering nothing is either a gate doing its job or a deadline quietly eating the feature,
-     * and those call for opposite responses — one is working as designed, the other is a two-second timeout to
-     * raise. A boolean cannot tell them apart, so nothing downstream could act on the number it produced.
-     *
-     * `note` is delivery; every other value is a turn that ran exactly as the control arm would have, labelled
-     * with what took the treatment away. Absent ⇒ outside the experiment, exactly as for the arm. */
-    iqContextOutcome: IqContextOutcomeSchema.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.
@@ -6427,10 +6477,6 @@ 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(),
-    /* Wall time spent deciding the pre-turn retrieval outcome, including the full deadline on a timeout.
-     * Absent on rows written before latency was recorded or turns outside the retrieval experiment. Keeping it
-     * per outcome is what lets the report distinguish a slow engine from an eligibility gate. */
-    iqContextDurationMs: z.number().nonnegative().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.
      *
@@ -6449,33 +6495,29 @@ export const UsageTurnSchema = z.object({
     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 pre-injection is judged on, and the same correction `proseChars` is to the terse steer.
+     * What the search teaching is judged on, and the same correction `proseChars` is to the terse steer.
      *
-     * COST PER TURN CANNOT SERVE, which is what this replaced. Nine days of real use reported +27.0% ± 29.9pp on
-     * cost, an interval from −2.9% to +56.9%, and reading it against the transcripts showed the gap was not the
-     * mechanism: every raw per-turn outcome moved with it (reads +58%, duration +73%, cache-read tokens +28%)
-     * and every one of them was flat to within a point once turn size was divided out. It was the coin flip
-     * handing the treatment arm the bigger jobs. Cost is a whole turn's worth of work, and retrieval touches one
-     * part of it, so the part lives inside the noise of the rest — exactly the shape that made output tokens
-     * unable to see the steer.
+     * 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
+     * see the steer. Nine days of a since-removed retrieval experiment proved it with an interval from −2.9% to
+     * +56.9%, driven entirely by which arm had drawn the bigger jobs.
      *
-     * Searches are what the mechanism acts on directly: a turn handed the anchors up front does not go and find
-     * them. Turns that never search stay in the population at zero rather than being filtered out — they dilute
-     * both arms equally, while selecting on "did it search" would select on the treatment itself.
+     * Searches are what the mechanism acts on directly. Turns that never search stay in the population at zero
+     * 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. */
     searchCalls: z.number().optional(),
-    /* …and how many of them came BEFORE the turn first opened or changed a file — the orientation burst, which
-     * is the part retrieval is actually aimed at. A turn that already knows where to look starts working; one
-     * that doesn't goes hunting first, and pre-injection's whole claim is that it removes that hunt.
+    /* …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.
      *
      * The narrower of the two readings and the less confounded: `searchCalls` still grows with the size of the
      * job, while the walk up to the first file is roughly the same act whatever the job turns out to be.
      *
      * A turn that never reads or edits counts all of its searches here — it never arrived, so all of it was
-     * orientation. Dropping those instead would select the population by an OUTCOME the treatment moves (a turn
-     * handed its anchors is likelier to reach a file), which is the one bias an arm-based reading cannot absorb.
+     * orientation. Dropping those instead would select the population by an OUTCOME the treatment moves, which
+     * is the one bias an arm-based reading cannot absorb.
      *
      * Absent ⇒ as for `searchCalls`. */
     openingSearches: z.number().optional(),

package/src/workspace-state.test.ts

@@ -4,6 +4,7 @@ import { describe, expect, it } from "vitest";
 import {
     isLockedWorkspacePath,
     isReportedManifest,
+    isReviewableLockedPath,
     REPORTED_MANIFEST_PATHS,
     staleQueryKeys,
     VERSIONED_STATE_PATHS,
@@ -229,6 +230,45 @@ describe(`isLockedWorkspacePath`, () => {
     });
 });
 
+/* The carve-out the diff routes ask for, and the reason it is derived: a locked entry the root repo TRACKS has
+ * a diff by construction, and refusing to serve it made the Changes panel list a row it could not open. */
+describe(`isReviewableLockedPath`, () => {
+    it(`admits the locked entry the root repo tracks, and nothing else locked`, () => {
+        expect(isReviewableLockedPath(`.intentic/capabilities.json`)).toBe(true);
+        // Every other locked entry is a credential, an identity binding or private runtime state. None is
+        // versioned, so none is reachable through a diff — the carve-out cannot widen without the flag.
+        expect(isReviewableLockedPath(`.intentic/owner.json`)).toBe(false);
+        expect(isReviewableLockedPath(`.intentic/members.json`)).toBe(false);
+        expect(isReviewableLockedPath(`.intentic/ci.json`)).toBe(false);
+        expect(isReviewableLockedPath(`.intentic/auth/codex/auth.json`)).toBe(false);
+        expect(isReviewableLockedPath(`.intentic/sessions/claude/x.jsonl`)).toBe(false);
+        expect(isReviewableLockedPath(`.intentic/browser/Default/Cookies`)).toBe(false);
+        expect(isReviewableLockedPath(`.git/config`)).toBe(false);
+    });
+
+    it(`answers only for the locked set — an ordinary path was never refused to begin with`, () => {
+        // Tracked, but not locked: the guards never ask this of them, and a `true` here would read as "this
+        // path needed a carve-out", which is a different and wrong statement.
+        expect(isReviewableLockedPath(`.intentic/settings.json`)).toBe(false);
+        expect(isReviewableLockedPath(`src/app.ts`)).toBe(false);
+        // A repo's own nested state dir is its project's content, exactly as the lock reads it.
+        expect(isReviewableLockedPath(`myrepo/.intentic/capabilities.json`)).toBe(false);
+    });
+
+    it(`reads a platform path and a dot-relative one the same as a posix one`, () => {
+        expect(isReviewableLockedPath(`.intentic\\capabilities.json`)).toBe(true);
+        expect(isReviewableLockedPath(`./.intentic/capabilities.json`)).toBe(true);
+    });
+
+    it(`stays a strict subset of the lock`, () => {
+        // The carve-out is about which locked paths a DIFF may serve. A path it admits that the lock never
+        // held would mean the guards had stopped agreeing on what the control plane is.
+        for (const path of VERSIONED_STATE_PATHS) {
+            expect([path, isReviewableLockedPath(path) && !isLockedWorkspacePath(path)]).toEqual([path, false]);
+        }
+    });
+});
+
 describe(`VERSIONED_STATE_PATHS`, () => {
     /* THE ONE ASSERTION THAT MUST NEVER GO GREEN BY ACCIDENT.
      *

package/src/workspace-state.ts

@@ -133,7 +133,12 @@ const STATE_FILES = [
      * 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. */
-    { path: ".intentic/capabilities.json", invalidates: ["capabilities", "environment", "panels", "manifests"], portability: "carry", versioned: true },
+    {
+        path: ".intentic/capabilities.json",
+        invalidates: ["capabilities", "environment", "panels", "manifests"],
+        portability: "carry",
+        versioned: true,
+    },
 
     /* Which workspace-derived recommendations the owner has said "not needed" to, and the evidence each was
      * declined against. It rides the `capabilities` key because the catalog is what changes when one lands, and
@@ -692,6 +697,29 @@ export const isLockedWorkspacePath = (relPath: string): boolean => {
     return segments.length >= 2 && segments[0] === STATE_DIR && LOCKED_STATE_ENTRIES.has(segments[1] ?? "");
 };
 
+/* 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
+ * their own: it is `versioned`, because connecting this sandbox to a deployment orchestrator is the largest
+ * change anyone makes to what it can DO and that belongs in review; and it is locked, because a member who
+ * could PUT one through the generic file API would be granting themselves a capability the owner never
+ * approved. The lock was always about that WRITE — its credentials live in the vault, not in the file.
+ *
+ * Together, though, the second silently cancelled the first. The Changes panel listed the file (git tracks it,
+ * so `git status` reports it), and clicking the row asked a diff route that refuses every control-plane path —
+ * a 404 on the one surface `versioned` exists to produce. The bytes were already in `git log`, in every clone
+ * of the root repo and in the workspace search; only the review was missing.
+ *
+ * So the review surfaces ask THIS instead of the flat lock, and it derives from the same flag rather than
+ * naming the file, so marking another locked entry `versioned` cannot reproduce the contradiction. Every other
+ * surface — read, write, move, delete, publish — still asks `isLockedWorkspacePath` and still refuses.
+ *
+ * Accepts either slash, like the rule above it. */
+export const isReviewableLockedPath = (relPath: string): boolean => {
+    const rel = relPath.replaceAll("\\", "/").replace(/^\.\//, "");
+    return isLockedWorkspacePath(rel) && VERSIONED_STATE_PATHS.some((path) => (path.endsWith("/") ? rel.startsWith(path) : rel === path));
+};
+
 /* Every path this table declares, as a type. `as const` above is what makes it one, and it is what finally makes
  * the first sentence of this file's header TRUE rather than aspirational.
  *