@intentic/sandbox-contract 1.213.0 → 1.215.0

package/src/schemas.ts

@@ -832,6 +832,19 @@ export const AgentSummarySchema = z.object({
     // the global toggle meaningful: an agent that never expressed an opinion follows the sandbox wherever it
     // is pointed next. Written by `agents.autoLand`; the UI shows the EFFECTIVE value (this ?? the setting).
     autoLand: z.boolean().optional(),
+    /* This agent's own answer to "re-run my turn when the model provider was what failed?" — the same
+     * two-level shape as `autoLand` above, and here for a sharper reason than symmetry.
+     *
+     * The press that writes this is offered INSIDE one conversation, at the moment that conversation's turn
+     * died, and what a person means by it is "finish THIS piece of work". It used to write the sandbox-wide
+     * setting, so one impatient click at 2 a.m. quietly armed every agent on the board — a blast radius
+     * nothing on screen had asked about. So the chat's offer writes this, the settings toggle writes the
+     * default, and the two stay honestly different things.
+     *
+     * ABSENT ⇒ inherit the sandbox setting, which is what keeps that default meaningful: a conversation that
+     * never expressed an opinion follows the sandbox wherever it is pointed next. Written by
+     * `agents.resumeAfterOutage`; every surface shows the EFFECTIVE value (this ?? the setting). */
+    resumeAfterOutage: z.boolean().optional(),
     // A collaborator asked for this agent's work to be landed (agents.requestLand) — collaborators may drive
     // agents but not merge into the main tree, so the ask rides the summary where every maintainer's board
     // sees it. Cleared by the land or discard that answers it. Absent ⇒ nobody is waiting.
@@ -1048,6 +1061,11 @@ export const AgentPlaceSchema = z.object({ id: z.string().min(1), text: z.string
 // the sandbox setting" — the browser sends it whenever the user toggles back to what the global already says,
 // so agents don't accumulate frozen overrides that quietly stop following the global toggle.
 export const AgentAutoLandSchema = z.object({ id: z.string().min(1), autoLand: z.boolean().nullable() });
+// resumeAfterOutage's input: this ONE conversation's answer to a provider outage. `null` clears the override
+// back to "inherit the sandbox setting" — sent whenever the user toggles back to what the global already says,
+// on the same reasoning as autoLand's null: an agent holding a frozen copy of a default has quietly stopped
+// following it, and nothing on screen would say so.
+export const AgentResumeAfterOutageSchema = z.object({ id: z.string().min(1), resumeAfterOutage: z.boolean().nullable() });
 export const AgentFileDiffQuerySchema = z.object({ id: z.string().min(1), repo: z.string().min(1), path: z.string().min(1) });
 /* WHY a path would not land. The distinction is the whole difference between an actionable report and a dead
  * end, because the three have nothing in common but their symptom:
@@ -1712,6 +1730,9 @@ export const SkillRemoveSchema = z.object({ name: SkillNameSchema });
 //                        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.
@@ -1793,6 +1814,25 @@ export const SandboxSettingsSchema = z.object({
     // 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),
+    /* 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).
+     *
+     * A different answer to the same question `iqContext` answers. That one retrieves for the WORDS of the
+     * message and is only as good as the question; this one 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. The two compose: this says which area, retrieval says which file.
+     *
+     * 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
@@ -1852,15 +1892,23 @@ export const SandboxSettingsSchema = z.object({
     // terminal state: without a sweep the Finished lane grows for the life of the sandbox, and each card it
     // holds is a live worktree checkout, not just a row.
     agentRetentionDays: z.number().min(0).max(365).default(3),
-    /* When a turn dies because the MODEL PROVIDER was failing (500/502/503, a 529 at capacity, a dropped
-     * socket), re-run it on an escalating backoff until it goes through or the attempts are spent.
+    /* THE SANDBOX-WIDE DEFAULT for "when a turn dies because the MODEL PROVIDER was failing (500/502/503, a
+     * 529 at capacity, a dropped socket), re-run it on an escalating backoff until it goes through or the
+     * attempts are spent".
+     *
+     * A DEFAULT, not the whole answer: any one conversation may override it (AgentSummarySchema
+     * .resumeAfterOutage), and the chat's own offer at the moment of failure writes THAT rather than this.
+     * This toggle is the standing policy for every agent that has not said otherwise, which is why it lives in
+     * settings and is not reachable by a single press from inside one chat — flipping how the whole board
+     * behaves should be a thing somebody went to do.
      *
      * OFF by default, on the same reasoning that keeps a spent usage limit out of this pair entirely: a resume
      * re-runs a turn the user sent once, on their own allowance, and only they can say whether the turn was
      * worth paying for twice. Starting off costs nothing, because the failed turn is remembered whatever the
      * toggle says (recordOutageFailure) — the failure frame reports an "available" resume and the chat's offer
-     * arms that very turn the moment it is turned on. Worth turning on for a sandbox whose turns mostly have
-     * nobody in the room (automation wakes, Discord, webhooks), which is the case no browser could rescue. */
+     * arms that very turn the moment it is armed for that conversation. Worth turning ON for a sandbox whose
+     * turns mostly have nobody in the room (automation wakes, Discord, webhooks), which is the case no browser
+     * could rescue and the case a per-conversation press cannot reach. */
     resumeAfterOutage: z.boolean().default(false),
     /* When the daemon dies under a running turn, re-run that turn once it is back (agent/turn-journal.ts records
      * every in-flight turn; the boot pass in agent/turn-resume.ts re-runs what survived). OFF by default, like
@@ -2481,6 +2529,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
@@ -3845,12 +3939,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
@@ -5395,19 +5502,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.
+ *
+ * `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 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"]);
+ * 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({
@@ -6049,6 +6160,26 @@ export const MigrationPlanSchema = z.object({
 });
 export type MigrationPlan = z.infer<typeof MigrationPlanSchema>;
 
+/* One of the owner's own computers, as an import SOURCE — the answer to "where is my setup" that needs no
+ * packing at all. Read on the card's first render for every enrolled machine, so the offer appears before the
+ * owner has read a single instruction.
+ *
+ * `found` absent means "connected, and nothing to import here" — which is a real answer worth rendering
+ * quietly, not an error: the machine may simply be a different one from the machine the assistant runs on. */
+export const MigrationHostSchema = z.object({
+    id: z.string(),
+    online: z.boolean(),
+    found: MigrationSourceSchema.optional(),
+    // Why this machine cannot be read right now, when it cannot — offline, or its own refusal, in its words.
+    detail: z.string().optional(),
+});
+export const MigrationHostsSchema = z.object({ hosts: z.array(MigrationHostSchema) });
+export type MigrationHost = z.infer<typeof MigrationHostSchema>;
+
+// Read the setup off a connected computer instead of an upload. Answers with a plan, exactly as the upload
+// route does — everything after this point is identical whichever door the setup came through.
+export const MigrationScanSchema = z.object({ host: z.string().min(1) });
+
 export const MigrationApplySchema = z.object({
     token: z.string(),
     // The ticked item ids. Ids the re-derived plan does not contain are ignored rather than erroring — the
@@ -6152,6 +6283,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(),
@@ -6187,6 +6343,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>;
 

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.
      *
@@ -268,6 +308,12 @@ describe(`VERSIONED_STATE_PATHS`, () => {
     it(`tracks exactly the configuration slice plus the agent's own authored output`, () => {
         expect(VERSIONED_STATE_PATHS.toSorted()).toEqual([
             `.intentic/automations.json`,
+            /* 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
+             * sandbox can DO, and it used to leave no diff. */
+            `.intentic/capabilities.json`,
             `.intentic/capability-dismissals.json`,
             /* 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,
@@ -279,6 +325,10 @@ describe(`VERSIONED_STATE_PATHS`, () => {
             `.intentic/environment.custom.Dockerfile`,
             `.intentic/environment.d/`,
             `.intentic/extension-enablement.json`,
+            /* Its twin, and the pair is the argument: the SWITCH was already tracked while the configuration
+             * behind it was not, so a commit could record turning an extension on and say nothing about what it
+             * was told to do. Tracked once its declared-secret values moved to the vault. */
+            `.intentic/extension-settings.json`,
             // The owner's per-extension update posture (notify / agent / auto) — a standing decision about
             // what may run unattended, which is exactly the kind of edit worth a line in `git log`.
             `.intentic/extension-update-policy.json`,

package/src/workspace-state.ts

@@ -109,12 +109,36 @@ export interface WorkspaceStateFile extends StateFile {
 const STATE_FILES = [
     /* A capability add/remove recomposes the environment overlay and can add or drop a repo's panel.
      *
-     * Each entry's `config` carries that capability's credential (an mcp server's token, a Komodo key, an ssh
-     * key), so the manifest is a secret in full. It is also what composeEnvironment reads its Dockerfile
-     * fragments from, which makes this the entry where the owner's export choice has the most visible
-     * consequence: a bundle exported WITHOUT secrets rebuilds a stock overlay, and the import report has to
-     * name every capability the target needs re-added before its environment matches again. */
-    { path: ".intentic/capabilities.json", invalidates: ["capabilities", "environment", "panels", "manifests"], portability: "secret" },
+     * SPLIT ALREADY — and this entry's classification had not caught up, which is the whole of what changed here.
+     * It read `secret` on a claim that had stopped being true: that each entry's `config` carries that
+     * capability's credential, so the manifest is a secret in full. It does not. capabilities-store.ts's
+     * 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.
+     *
+     * 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
+     * that starts withholding a new field starts vaulting it on the same commit. That is what makes this
+     * classification a property of the code rather than a promise to re-audit it — the reason the entry can be
+     * reclassified at all, and the reason a hand-kept "these fields are safe" list could not have earned it.
+     *
+     * `carry`, and this is the entry where that earns the most. composeEnvironment reads its Dockerfile fragments
+     * from here, so a bundle that dropped it arrived on a stock overlay with an import report listing every
+     * connection to re-add by hand. It now arrives listing them itself, each visibly unconnected and waiting for
+     * 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
+     * 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,
+    },
 
     /* 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
@@ -290,16 +314,33 @@ const STATE_FILES = [
         why: "Thread bookkeeping (an inbound thread — a Doorbell visitor, a Discord or Slack channel — → sandbox conversation + provider session), written on EVERY inbound message. Nothing in the browser reads it: what a thread produces is a conversation, and the fleet board already learns about that from the agent registry's own push. Naming a key here would bill every connected browser a refetch per inbound message — the request storm this table's own note warns about — to refresh nothing it can see.",
         portability: "carry",
     },
-    /* Values are a primitive union an extension chooses the meaning of, and "an API key for the service I talk
-     * to" is squarely within it — so this is classed by what it CAN hold, not by what any particular extension
-     * happens to put there. The alternative reads the wrong way round: a bundle that leaked one extension's
-     * token would have been correct about all the others. */
+    /* SPLIT, so that "what an extension is configured to do" and "the token it does it with" stop being one file.
+     *
+     * This entry used to be `secret` and untracked, classed by what a value COULD hold: values are a primitive
+     * union an extension chooses the meaning of, and "an API key for the service I talk to" is squarely within
+     * it. That classification was honest about the risk and wrong about the file — it meant an extension's whole
+     * configuration was unreviewable because one of its keys might be a credential, AND the credential was in
+     * there anyway, in a file the workspace API does not lock. A turn could simply read it.
+     *
+     * A descriptor already says which keys those are (`contributes.settings[].secret`), so the values it names
+     * now live in the vault off /work and this file keeps the rest — the capability manifest's split, applied to
+     * the same problem one table over (extensions/extension-settings.ts holds it, and the reasoning). Reads
+     * rehydrate, so no caller changed.
+     *
+     * What the split earns: `carry`, because what is left is an extension's configuration and a bundle should
+     * arrive with it; and `versioned`, because turning an extension's behaviour on is a decision, and the file
+     * that records it can now be read without reading anybody's token. The boot sweep is what keeps that true of
+     * a file the agent can also edit — see vaultExtensionSettingSecrets.
+     *
+     * NO `note`, and the split is why: a note is printed by the import report beside a SKIPPED entry, so an entry
+     * that carries can never show one. "Re-enter the credentials" is now the vault's instruction to give, and the
+     * vault is under `.intentic/auth/` — which is skipped, and says so there. */
     {
         path: ".intentic/extension-settings.json",
         invalidates: [],
         why: "Held in a module-level shallowRef store per extension (web's extensionSettingsStore) with no query observer, and deliberately so: api.settings.get must answer SYNCHRONOUSLY from an extension's first activate() line, and the store outlives every component scope. A module-level QueryObserver is the one shape that would make invalidation refetch, and this app already ruled it out — it detaches on the queryClient.clear() at logout (see useSandbox's sandbox-list mirror). So a remote member's setting edit reaches this browser on its next load, not live.",
-        portability: "secret",
-        note: "Re-enter each extension's settings on the Extensions tab.",
+        portability: "carry",
+        versioned: true,
     },
     /* Unlike the settings file above it, the on/off switch IS observed by a query — the Extensions tab's list,
      * which carries each row's switch position — so a flip made elsewhere (another member, the agent writing the
@@ -346,6 +387,17 @@ const STATE_FILES = [
         why: "Which of the routes each extension DECLARED it has actually called — the evidence behind the permissions list on its row. The one entry here whose empty set is a RATE decision rather than an architectural one: every browser with the app open reports its batch on a timer, so wiring this to the `extensions` query would refetch the whole list every few seconds for a figure nobody is watching change. The tab reads it when it loads, which is when anyone is reading it.",
         portability: "carry",
     },
+    /* THE ONE ENTRY WHERE "HOLDS NO CREDENTIAL" IS TRUE AND `versioned` IS STILL WRONG, which is worth stating
+     * because it looks like the two above it: an email and a role per row, nothing to vault, and "who may drive
+     * this sandbox" is as consequential a fact as any this table tracks.
+     *
+     * It stays out for two reasons that are not about secrecy. It is a MIRROR — the platform's invite records are
+     * the grant, this is the copy the enforcer keeps so a grant it never received is never honoured, and a change
+     * here is the two disagreeing rather than anyone deciding something. Review of the decision already exists,
+     * on the Access tab, against the record that is authoritative. And tracking it would mean reclassifying it
+     * `carry` to satisfy the guard, which is the one thing it must never be: an access list that travelled would
+     * let a source sandbox hand itself the target's ownership. Widening the guard for this single entry is the
+     * worse trade — it protects every `identity` entry, and most of those ARE credentials. */
     {
         path: ".intentic/members.json",
         invalidates: [],
@@ -358,13 +410,20 @@ const STATE_FILES = [
     /* Keep credentials and conversation state in disjoint top-level trees. Provider homes are intentionally
      * classified as a single secret unit: several CLIs mix OAuth, config, and provider-native thread metadata,
      * and no generic export can safely distinguish those files. The broad root also makes a newly-added provider
-     * secret by construction instead of relying on another hand-maintained provider-name list. */
+     * secret by construction instead of relying on another hand-maintained provider-name list.
+     *
+     * IT IS NO LONGER ONLY THE AI LOGINS. Both credential splits put their vault here — `capability-secrets.json`
+     * and `extension-secrets.json`, sited beside the provider homes precisely because this tree is already
+     * outside the file routes, the workspace walk and the search index (composition.ts sites them, and the two
+     * stores argue why). So this is now the ONE entry a secret-less bundle leaves behind, and its note is
+     * therefore the only place the owner is told what to re-enter: the manifests that name those connections
+     * travel, and would otherwise arrive looking complete. */
     {
         path: ".intentic/auth/",
         invalidates: [],
-        why: "AI-provider credentials and runtime homes; each account is rendered through owner-gated provider routes.",
+        why: "AI-provider credentials and runtime homes, plus the capability and extension-settings secret vaults; each account is rendered through owner-gated provider routes.",
         portability: "secret",
-        note: "Sign the agent's AI accounts in again on the Agent tab.",
+        note: "Sign the agent's AI accounts in again on the Agent tab, then re-enter each connection's credential on Capabilities and each extension's secret settings on Extensions — both arrived listed but unauthenticated.",
     },
     /* Agent session transcripts, rewritten on every streamed token.
      *
@@ -538,8 +597,13 @@ export const VERSIONED_STATE_PATHS: readonly string[] = WORKSPACE_STATE_FILES.fi
  * ledger is forgotten from, and the forgetting is silent — it ranked loop iteration history and cloned
  * third-party extension source against the user's own code for months before this derivation existed.
  *
- * Note what falls out without a special case: `capabilities.json` is `secret` and unversioned, so the index
- * stops copying capability tokens into search text — the exact boundary the floor already drew for `auth/`. */
+ * WHAT THE CREDENTIAL SPLITS MOVED ACROSS THIS LINE, since the note that used to sit here said the opposite and
+ * was worth replacing rather than deleting. `capabilities.json` was `secret` and unversioned, and the sentence
+ * celebrated that the index therefore stopped copying capability tokens into search text. It is `versioned` now
+ * and searchable — and the guarantee is unchanged, because the tokens are not in the file any more. The floor
+ * moved from "keep the index away from the file that holds credentials" to "the file holds none", which is the
+ * stronger of the two: it also holds for the shell, which never consulted this list at all. `auth/` — where those
+ * values went, both vaults included — is still denied, and is the entry that was doing the real work all along. */
 export const SEARCHABLE_STATE_PATHS: readonly string[] = WORKSPACE_STATE_FILES.filter((file) => file.versioned || file.authored).map(
     (file) => file.path,
 );
@@ -633,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.
  *