@intentic/sandbox-contract 1.176.2 → 1.176.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/sandbox-contract",
-  "version": "1.176.2",
+  "version": "1.176.3",
   "description": "oRPC wire contract for the intentic sandbox daemon — shared by the daemon and its browser client",
   "license": "MIT",
   "type": "module",
@@ -67,8 +67,8 @@
     "@orpc/contract": "1.14.13",
     "tslib": "2.8.1",
     "zod": "4.4.3",
-    "@intentic/extension-api": "1.176.2",
-    "@intentic/registry": "0.0.0"
+    "@intentic/registry": "0.0.0",
+    "@intentic/extension-api": "1.176.3"
   },
   "devDependencies": {
     "@types/node": "24.13.2",

package/src/chores/probes.ts

@@ -36,6 +36,11 @@ export interface ProbeSpec {
     readonly timeoutMs: number;
     // Exit 0 ⇒ this repo can be measured. Runs in the repo's own directory, like the command.
     readonly available: string;
+    /* What is MISSING when `available` says no, named here rather than derived from the title. The obvious
+     * derivation — "this repository has no security advisories to measure" — states the one thing an unmeasured
+     * probe must never claim, that there are none, and it is the same conflation the block above exists to
+     * prevent. Phrased as a bare clause ("no lockfile"), because the panel groups these under its own lead-in. */
+    readonly unavailable: string;
     // `sh -c`, in the repo's directory. Stdout is the parser's input; a non-zero exit is NOT a failure by itself
     // (pnpm outdated and pnpm audit both exit non-zero precisely when they have something to report), so the
     // runner judges by whether the parser recognised the output.
@@ -216,6 +221,7 @@ export const PROBES: readonly ProbeSpec[] = [
         ttlMs: DAY_MS,
         timeoutMs: 5 * 60_000,
         available: `test -f package.json`,
+        unavailable: `no package.json`,
         // `-r` so a monorepo reports every workspace package, not just the root's own handful. `|| true` because
         // pnpm exits non-zero exactly when it HAS findings, and the runner judges by whether the parse succeeded.
         command: `pnpm outdated -r --json 2>/dev/null || true`,
@@ -231,6 +237,7 @@ export const PROBES: readonly ProbeSpec[] = [
         // A lockfile, not a package.json: auditing resolves the actual installed tree, and without one pnpm
         // reports against nothing.
         available: `test -f pnpm-lock.yaml || test -f package-lock.json`,
+        unavailable: `no lockfile`,
         command: `pnpm audit --json 2>/dev/null || true`,
         parse: parseAudit,
     },
@@ -244,6 +251,7 @@ export const PROBES: readonly ProbeSpec[] = [
         // The repo's OWN knip, never a floating one: `pnpm dlx knip` would download a version that disagrees with
         // the repo's knip.json about what counts as an entry point, and then report its whole public API as dead.
         available: `pnpm exec knip --version >/dev/null 2>&1`,
+        unavailable: `knip is not a devDependency`,
         command: `pnpm exec knip --reporter json --no-exit-code 2>/dev/null || true`,
         parse: parseKnip,
     },
@@ -255,6 +263,7 @@ export const PROBES: readonly ProbeSpec[] = [
         ttlMs: 7 * DAY_MS,
         timeoutMs: 20 * 60_000,
         available: `test -f package.json`,
+        unavailable: `no package.json`,
         // `--threshold 100` so jscpd never fails the command on its own opinion of what is too much duplication —
         // that judgement is the chore's, made from the percentage, not the tool's exit code.
         command:

package/src/chores/verdict.ts

@@ -73,7 +73,13 @@ const unmeasuredDetail = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId
         if (probe.state === `ok`) {
             return [];
         }
-        return [`${spec.title} · ${probe.state === `unavailable` ? `not available in this repository` : `failed`}${probe.reason === undefined ? `` : ` — ${probe.reason}`}`];
+        // An unavailable probe's reason already says what is missing ("no lockfile"), so prefixing it with "not
+        // available in this repository" only says the same thing twice. A failure has to keep its label: its
+        // reason is the tool's own output, which on its own reads as a fact rather than as a breakage.
+        if (probe.state === `unavailable`) {
+            return [`${spec.title} · ${probe.reason ?? `not available in this repository`}`];
+        }
+        return [`${spec.title} · failed${probe.reason === undefined ? `` : ` — ${probe.reason}`}`];
     });
 
 export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLedgerEntry | undefined): ChoreVerdict => {

package/src/history-state.ts

@@ -0,0 +1,100 @@
+import type { StateFile } from "./state-portability.js";
+
+/* WHAT LIVES ON /history — the second half of the daemon's state, and the half nothing declared until an
+ * export had to reason about it.
+ *
+ * `WORKSPACE_STATE_FILES` covers `<workspace>/.intentic/`, which is where the manifests live. It is not where
+ * the machinery lives. Every repo's REAL git dir is here (a repo's in-tree `.git` is a pointer file — see
+ * git/repo-git-dirs.ts for the invariant that forces it), and so are the fleet registry, the turn journal, the
+ * ledgers, the checkpoint scopes and the isolated agents' checkouts. A "workspace export" that took `/work`
+ * alone would carry a tree of repos with dangling gitdir pointers — every git command in the restored sandbox
+ * answering `fatal: not a git repository` — and an empty agent board.
+ *
+ * The two tables stay separate rather than becoming one keyed by volume, because they answer different
+ * questions. A `.intentic` entry also declares which browser QUERY it makes stale, since the file watcher
+ * reports it; nothing here is watched at all (that is the point of the volume), so an `invalidates` field on
+ * these entries would be a column of empty arrays. What they share is the portability class, and that is
+ * imported rather than duplicated.
+ *
+ * `history-state.test.ts` fails when a daemon store builds a `/history` path this list doesn't carry, in both
+ * directions — the same shape-recognizing guard that covers the workspace table.
+ */
+
+// Paths are historyRoot-relative, forward-slash, matched by PREFIX; a directory entry keeps its trailing slash
+// so it cannot prefix-match a sibling file. See stateFileFor for how nesting resolves.
+export const HISTORY_STATE_FILES: readonly StateFile[] = [
+    /* ---- the machinery a restored workspace is inert without ---- */
+
+    /* THE ONE THAT MAKES A BUNDLE A WORKSPACE. Every repo's real git dir, including the /work root's own
+     * ("root"), keyed by URI-encoded repo id. Carrying the working tree without this hands the target files
+     * whose `.git` points at a path that does not exist there — which is not a degraded repo but a broken one,
+     * and it takes the Changes review, the diff, land and every agent branch with it. The agent BRANCHES live
+     * in here too, which is what lets the checkouts below be left out. */
+    { path: "gits/", portability: "carry" },
+    // The checkpoint timeline (one bare repo per scope, snapshots on refs/snapshots/head). Restoring it is what
+    // makes "restore to before that turn" still reach back past the move.
+    { path: "scopes/", portability: "carry" },
+    // The fleet: every conversation card, its branch, its session ids, its standing.
+    { path: "agents.json", portability: "carry" },
+    { path: "turns/", portability: "carry" },
+    { path: "transcripts/", portability: "carry" },
+    { path: "activity.jsonl", portability: "carry" },
+    { path: "usage.jsonl", portability: "carry" },
+    { path: "account-usage.json", portability: "carry" },
+    { path: "provider-refusals.json", portability: "carry" },
+    // The deploy engine's own ledgers — a run's events and the check results the Pipelines view reads back.
+    { path: "apply-events.ndjson", portability: "carry" },
+    { path: "check-events/", portability: "carry" },
+
+    /* ---- regenerated by the target ---- */
+
+    /* THE DELIBERATE OMISSION, and the difference between a bundle of gigabytes and one of hundreds.
+     *
+     * A conversation's worktree is a full checkout of the monorepo per agent (plus its overlay upper dir), and
+     * there can be a hundred of them. None of it is unique: the branch it holds is in `gits/` above, and the
+     * registry entry naming it travels in agents.json — so an imported conversation arrives in exactly the
+     * shape the system already has a name for. `attached()` reports its checkout as absent, the board renders
+     * it, and the next turn's `ensure()` re-creates it from the recorded composition, which is the same path an
+     * archived agent takes when it runs again. The boot sweep's `git worktree prune` clears the stale admin
+     * entries the restored git dirs still carry. */
+    {
+        path: "worktrees/",
+        portability: "derived",
+        note: "Each conversation re-attaches its checkout from its branch on its next turn.",
+    },
+    { path: "overlays/", portability: "derived" },
+    { path: "logs/", portability: "derived" },
+    { path: "trash/", portability: "derived" },
+    { path: ".isolation-probe", portability: "derived" },
+
+    /* ---- credentials ---- */
+
+    // The ssh alias dir ~/.ssh/intentic-hosts symlinks to: per-host config, private keys and passphrases for
+    // every host capability and git remote the sandbox reaches.
+    {
+        path: "ssh-hosts/",
+        portability: "secret",
+        note: "Re-add each ssh host on the Capabilities view — its key does not travel.",
+    },
+    // The cli-proxy's config, which holds the routed subscriptions' provider tokens.
+    {
+        path: "translator/",
+        portability: "secret",
+        note: "Sign the routed AI subscriptions in again on the Agent tab.",
+    },
+
+    /* ---- identity: what binds this sandbox to its owner, its browsers and its host ---- */
+
+    /* Signs every browser session cookie. Carrying it would let a bundle's holder mint sessions against the
+     * target — an export becomes a credential — and the target minting its own costs exactly one sign-in. */
+    { path: "session-secret", portability: "identity", note: "Sign in again — the target signs its own sessions." },
+    {
+        path: "push.json",
+        portability: "identity",
+        note: "Re-enable notifications in the browsers you use — a push subscription is bound to the sandbox that minted it.",
+    },
+    { path: "sync-enrollments.json", portability: "identity", note: "Re-pair desktop sync from the Sync tab." },
+    { path: "sync-pair-consumed.json", portability: "identity" },
+    { path: "host-enrollments.json", portability: "identity" },
+    { path: "local-cert/", portability: "identity" },
+];

package/src/index.ts

@@ -76,6 +76,8 @@ export * from "./events.js";
 export * from "./sse.js";
 export * from "./routes.js";
 export * from "./workspace-state.js";
+export * from "./state-portability.js";
+export * from "./history-state.js";
 export * from "./agent-catalog.js";
 export * from "./host-protocol.js";
 export * from "./hostnames.js";

package/src/schemas.ts

@@ -3207,6 +3207,53 @@ export const EnvironmentSchema = z.object({
 export type Environment = z.infer<typeof EnvironmentSchema>;
 export const EnvironmentApproveSchema = z.object({ hash: z.string().min(1) });
 
+/* ---- portability: exporting a sandbox's environment and restoring it into a fresh one ----
+ *
+ * A sandbox is four stores, not one: `/work` (the workspace and the daemon's manifests), `/history` (every
+ * repo's real git dir, the fleet registry, the ledgers), the CONTAINER (the built overlay image plus the env
+ * the run contract replays) and the AI-provider credential root. A bundle carries the first two, declared entry
+ * by entry in WORKSPACE_STATE_FILES / HISTORY_STATE_FILES. It cannot carry the other two, and the honest
+ * consequence is that an import ends in a REPORT rather than a claim of equivalence — the container has no
+ * docker socket, so only the host can rebuild the image the overlay describes.
+ */
+
+// What the bundle says about itself, written as its first tar entry so a reader learns the shape before the
+// bytes. `secrets` is the owner's export-time choice; the restorer re-derives every decision from the manifests
+// rather than trusting this, and uses it only to explain what is missing.
+export const BundleManifestSchema = z.object({
+    // Bumped when the layout changes in a way an older daemon would misread. Refused rather than guessed at.
+    version: z.literal(1),
+    // Where it came from, for the report's first line. Never used to authorize anything.
+    sandbox: z.object({ name: z.string() }).optional(),
+    createdAt: z.number(),
+    secrets: z.boolean(),
+    /* The environment the target has to reproduce, carried as FACTS rather than as the composed file (which the
+     * target recomposes against its OWN base image on first boot). `customDockerfile` is the owner-approved
+     * source section; `capabilities` names what contributed the remaining fragments, so the report can list what
+     * to re-add when the configs themselves did not travel. */
+    environment: z.object({
+        customDockerfile: z.string().optional(),
+        baseImage: z.string().optional(),
+        approvedHash: z.string().optional(),
+        capabilities: z.array(z.object({ id: z.string(), kind: z.string() })),
+    }),
+    // Every path class the bundle deliberately left out, with the manifest's own note where it has one. This is
+    // what turns "the export skipped things" from a silence into a list the owner can act on.
+    excluded: z.array(z.object({ path: z.string(), portability: z.string(), note: z.string().optional() })),
+});
+export type BundleManifest = z.infer<typeof BundleManifestSchema>;
+
+// What a restore actually did. `needsAction` is the part that matters: the environment rebuild command, the
+// credentials to re-enter, the logins to redo — each one a thing the target cannot do for itself.
+export const ImportReportSchema = z.object({
+    restored: z.object({ workspaceFiles: z.number(), historyFiles: z.number(), repos: z.array(z.string()), bytes: z.number() }),
+    // Entries the bundle carried that this daemon refused to write (an identity file, an escaping path) — empty
+    // for any bundle a matching exporter produced, and a tamper signal when it is not.
+    refused: z.array(z.string()),
+    needsAction: z.array(z.object({ subject: z.string(), detail: z.string() })),
+});
+export type ImportReport = z.infer<typeof ImportReportSchema>;
+
 // ---- secrets: user-supplied env-var secrets the daemon writes to desired-state/.env ----
 // The web posts a Cloudflare token / GitHub PAT / another-host SSH key straight to the sandbox daemon (never
 // through the platform); `apply` reloads .env each run so a new secret is picked up with NO restart. `list`
@@ -3693,7 +3740,10 @@ export const ProbeResultSchema = z.object({
     // deciding whether to force a refresh deserves to know what they are asking for.
     tookMs: z.number().int().nonnegative(),
     facts: ProbeFactsSchema.optional(),
-    // Why it is unavailable, or how it failed — a bounded quote of the tool's own output. Never invented here.
+    // On `failed`, how it broke — a bounded quote of the tool's own output, never a summary of it. On
+    // `unavailable`, what is missing, in the probe spec's own words ("no lockfile"): there is no tool output to
+    // quote when the tool never ran, and the alternative — a sentence built from the probe's name — would have an
+    // unmeasured probe claiming there is nothing to measure.
     reason: z.string().optional(),
 });
 export type ProbeResult = z.infer<typeof ProbeResultSchema>;

package/src/state-portability.ts

@@ -0,0 +1,56 @@
+/* WHETHER A PIECE OF DAEMON STATE TRAVELS — the second thing every state manifest declares.
+ *
+ * A sandbox's environment is not one directory. `/work` holds the workspace and the daemon's manifests,
+ * `/history` holds the real git dirs, the fleet registry and the ledgers, and the container carries the built
+ * image and its env. "Export the environment" therefore means walking state that lives in two volumes and
+ * deciding, per entry, which of four things it is — and that decision has to be written down beside the entry
+ * itself, or the exporter becomes the hand-kept list that workspace-state.ts exists to argue against.
+ *
+ * So each manifest entry carries a class, and both the bundler and the restorer derive from it. Adding a store
+ * without saying whether it travels is a failing coverage test, not a file that silently goes missing from
+ * every bundle.
+ *
+ * The classes are exhaustive on purpose — there is no "unset" — because the failure mode of a default is
+ * exactly the one that matters: a credential store added later would inherit `carry` and ride out of the
+ * sandbox in a file the owner thought was safe to email.
+ */
+export type Portability =
+    /* Ordinary state. Travels in every bundle. */
+    | "carry"
+    /* Holds a credential — a provider token, a webhook secret, an ssh key. Travels ONLY when the owner opts
+     * in at export, and the bundle records that it did. Never the default. */
+    | "secret"
+    /* Binds this sandbox to its owner, its browsers or its host: who may drive it, the session-signing secret,
+     * push subscriptions, enrollments, certificates. Never travels — the target mints its own, and carrying
+     * one would either hand the target's ownership to the source or leave two sandboxes claiming one identity. */
+    | "identity"
+    /* Regenerated by the target from state that does travel: composed files, caches, indexes, checkouts. Left
+     * out for size, not for safety — carrying it would only ship a stale copy of something the daemon rebuilds
+     * on its own. */
+    | "derived";
+
+// One entry of a state manifest: the path it owns and what happens to it at export. `note` is user-facing —
+// the import report prints it beside a skipped entry, so it is written as an instruction to the owner ("log in
+// again"), not as a rationale for the next reader. Rationale belongs in a comment on the entry.
+export interface StateFile {
+    readonly path: string;
+    readonly portability: Portability;
+    readonly note?: string;
+}
+
+/* The entry that owns a path, LONGEST PREFIX FIRST.
+ *
+ * Manifests deliberately nest: `.intentic/claude/` is a provider credential store that also contains
+ * `.intentic/claude/projects/`, the agent's memory notes and transcripts, which are the single most valuable
+ * thing in a bundle. First-match resolution would classify the notes by whichever entry happened to be listed
+ * first, so the specific entry has to win over the general one by construction rather than by list order —
+ * the same reason a .gitignore consults its deepest matcher first.
+ *
+ * Undefined for a path no entry claims. Callers decide what that means: the bundler treats an unclaimed
+ * `.intentic` path as a bug (the coverage test is what makes that safe to assume) and unclaimed ordinary
+ * workspace files as `carry`, which is what they are.
+ */
+export const stateFileFor = <T extends StateFile>(path: string, files: readonly T[]): T | undefined =>
+    files
+        .filter((file) => path === file.path || path.startsWith(file.path) || `${path}/` === file.path)
+        .reduce<T | undefined>((best, file) => (best === undefined || file.path.length > best.path.length ? file : best), undefined);

package/src/workspace-state.test.ts

@@ -117,13 +117,31 @@ describe(`WORKSPACE_STATE_FILES`, () => {
         }
     });
 
-    it(`has no entry that prefix-matches another, so one write can't be billed twice`, () => {
-        for (const file of WORKSPACE_STATE_FILES) {
-            const overlapping = WORKSPACE_STATE_FILES.filter((other) => other !== file && other.path.startsWith(file.path));
+    it(`only nests under an entry that invalidates nothing, so one write can't be billed twice`, () => {
+        // Entries nest when one store answers PORTABILITY in two halves (`.intentic/claude/` is a credential
+        // root whose `projects/` subtree is the thing a bundle exists to carry) — stateFileFor's longest match
+        // is what keeps that unambiguous. Invalidation has no longest-match rule: staleQueryKeys unions every
+        // matching entry, so a nest under an entry that DOES invalidate would bill the outer view's queries for
+        // a write that belongs to the inner one. Nesting is therefore only legal beneath an empty `invalidates`.
+        for (const file of WORKSPACE_STATE_FILES.filter((entry) => entry.invalidates.length > 0)) {
+            const nested = WORKSPACE_STATE_FILES.filter((other) => other !== file && other.path.startsWith(file.path));
             expect(
-                overlapping.map((other) => other.path),
-                `${file.path} is a prefix of another entry`,
+                nested.map((other) => other.path),
+                `${file.path} invalidates ${file.invalidates.join(`, `)} and is a prefix of another entry`,
             ).toEqual([]);
         }
     });
+
+    it(`splits a nested entry from its parent for a reason the parent doesn't already carry`, () => {
+        // A nest that agrees with the entry it sits under is a duplicate: stateFileFor resolves to the same
+        // answer either way, so the split is dead weight the next reader has to diff to discover.
+        for (const file of WORKSPACE_STATE_FILES) {
+            for (const parent of WORKSPACE_STATE_FILES.filter((other) => other !== file && file.path.startsWith(other.path))) {
+                expect(
+                    parent.portability === file.portability && parent.invalidates.join() === file.invalidates.join(),
+                    `${file.path} says nothing its parent ${parent.path} doesn't already say`,
+                ).toBe(false);
+            }
+        }
+    });
 });

package/src/workspace-state.ts

@@ -1,4 +1,5 @@
 import type { FileContribution } from "@intentic/extension-api";
+import type { StateFile } from "./state-portability.js";
 
 /* WHICH WORKSPACE FILE BACKS WHICH CORE VIEW — one declaration, read by both sides of the wire.
  *
@@ -29,16 +30,18 @@ import type { FileContribution } from "@intentic/extension-api";
  * by the automations extension, because the extension had no way to say so itself. A key belongs to whoever
  * queries it. */
 
-// A core entry is an extension's `contributes.files` entry plus the one thing only the core list needs: the
-// right to declare NO invalidations, which for a daemon-owned file is the answer more often than not.
-export interface WorkspaceStateFile {
-    /* Workspace-root-relative, forward-slash — the space `workspaceChanged` paths arrive in. Matching is by
-     * PREFIX, which lets one entry cover three shapes without a second matching rule:
-     *   - an exact file      `.intentic/settings.json`
-     *   - a directory        `.intentic/drafts/`     (one file per draft)
-     *   - a name family      `.intentic/environment.` (…Dockerfile, .custom.Dockerfile, .approved.Dockerfile)
-     * A directory entry keeps its trailing slash so it can never prefix-match a sibling file. */
-    readonly path: string;
+/* A core entry is an extension's `contributes.files` entry plus the two things only the core list needs: the
+ * right to declare NO invalidations (for a daemon-owned file, the answer more often than not), and a
+ * portability class, because the daemon's own state is what an environment export has to reason about.
+ *
+ * `path` is workspace-root-relative, forward-slash — the space `workspaceChanged` paths arrive in. Matching is
+ * by PREFIX, which lets one entry cover three shapes without a second matching rule:
+ *   - an exact file      `.intentic/settings.json`
+ *   - a directory        `.intentic/drafts/`     (one file per draft)
+ *   - a name family      `.intentic/environment.custom.` (…Dockerfile and anything later named beside it)
+ * A directory entry keeps its trailing slash so it can never prefix-match a sibling file. Entries may NEST —
+ * see stateFileFor, which resolves the longest match rather than the first. */
+export interface WorkspaceStateFile extends StateFile {
     /* The browser query keys this file's contents feed. EMPTY is a real answer, not a gap — a file the browser
      * renders nothing from, or one deliberately kept off the push path — and `why` says which. Never a prefix
      * test over `.intentic/` as a whole: one stray write must not cost every view a refetch, which is the
@@ -49,13 +52,39 @@ export interface WorkspaceStateFile {
 }
 
 export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
-    // A capability add/remove recomposes the environment overlay and can add or drop a repo's panel.
-    { path: ".intentic/capabilities.json", invalidates: ["capabilities", "environment", "panels"] },
-    { path: ".intentic/environment.", invalidates: ["environment"] },
-    { path: ".intentic/settings.json", invalidates: ["settings"] },
+    /* 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"], portability: "secret" },
+
+    /* The overlay Dockerfile, four files that a single `.intentic/environment.` prefix used to cover. They are
+     * split here because they answer PORTABILITY differently while answering invalidation identically, and the
+     * split is the whole difference between an export that reproduces an environment and one that reproduces a
+     * stale copy of it:
+     *   - custom is the owner-approved SOURCE OF TRUTH and the only one that must travel;
+     *   - approved is COMPOSED from custom + the capability fragments + this container's base image, and is
+     *     rewritten on the target's first boot — carrying it would ship a FROM naming an image the target may
+     *     not be on (see composeEnvironment's baseImageOf);
+     *   - the proposal and the per-tool drafts under environment.d/ are the agent's pending requests, which the
+     *     owner has not answered yet; they travel so the question survives the move. */
+    { path: ".intentic/environment.custom.Dockerfile", invalidates: ["environment"], portability: "carry" },
+    { path: ".intentic/environment.Dockerfile", invalidates: ["environment"], portability: "carry" },
+    { path: ".intentic/environment.d/", invalidates: ["environment"], portability: "carry" },
+    {
+        path: ".intentic/environment.approved.Dockerfile",
+        invalidates: ["environment"],
+        portability: "derived",
+        note: "The target composes its own overlay on first boot; rebuild it there to install the tools it names.",
+    },
+
+    { path: ".intentic/settings.json", invalidates: ["settings"], portability: "carry" },
     // Written by the AGENT's file tools (the drafts skill), read by the owner's approval inbox — the one entry
     // here whose whole point is that a change arrives from outside the browser that renders it.
-    { path: ".intentic/drafts/", invalidates: ["drafts"] },
+    { path: ".intentic/drafts/", invalidates: ["drafts"], portability: "carry" },
     // ---- declared by the extension that renders them (contributes.files), not here ----
     // The path is the DAEMON's (automations-store writes both), the query keys are the intentic.automations
     // extension's. It declares them in its own manifest and the browser unions the two lists, so uninstalling
@@ -64,11 +93,13 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
         path: ".intentic/automations.json",
         invalidates: [],
         why: "Declared by the intentic.automations extension's contributes.files — `automations` is its query key, not core's.",
+        portability: "carry",
     },
     {
         path: ".intentic/approvals/",
         invalidates: [],
         why: "Declared by the intentic.automations extension's contributes.files — `automation-approvals` is its query key, not core's.",
+        portability: "carry",
     },
 
     /* ---- reached by no query, for reasons that are not oversights ----
@@ -81,16 +112,24 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
         path: ".intentic/webchat-installs.json",
         invalidates: [],
         why: "Which origins have loaded a Doorbell's widget, written on a 30s flush timer while a customer's site serves page views. The install panel that renders it fetches on open and polls itself while it is on screen, which is the whole window in which the answer changes for anyone. Pushing instead would bill every connected browser a refetch per flush, for a panel almost nobody has open.",
+        portability: "carry",
     },
     {
         path: ".intentic/thread-sessions.json",
         invalidates: [],
         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. */
     {
         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.",
     },
     /* 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
@@ -99,11 +138,14 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
     {
         path: ".intentic/extension-enablement.json",
         invalidates: ["extensions"],
+        portability: "carry",
     },
     {
         path: ".intentic/members.json",
         invalidates: [],
         why: "Not this view's source at all: SandboxAccess renders the PLATFORM's invite records (apiClient.invite.list), and this file is the daemon's ENFORCED copy — written first so a grant the enforcer never got is never recorded, then never read back. A change here means the two disagreed, which the write order makes fail-closed rather than stale.",
+        portability: "identity",
+        note: "Re-invite collaborators from the Access tab — a grant is the platform's record, and the target enforces its own copy.",
     },
 
     // ---- daemon-owned, nothing derives from watching them ----
@@ -116,40 +158,76 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
      * is +119 watched directories against ~593 today (a fifth more), with 314 continuously-rewritten transcripts
      * inside the newly-watched set, to make ONE memory directory live. Notes change at agent-turn cadence, so the
      * poll costs a request a minute and the alternative costs a permanent 20% on the watcher. */
+    /* THE STORE THAT IS TWO THINGS, hence two entries — this is the case stateFileFor's longest-match rule
+     * exists for. `.intentic/claude/` is where linkClaudeState parks the Claude CLI's per-conversation state,
+     * and (when AGENT_AUTH_DIR is unset, which is the production layout) it is ALSO the provider credential
+     * root. The subtree under `projects/` is the half a bundle exists to carry — the agent's memory notes and
+     * every conversation's transcript — while its siblings hold the OAuth that must not leave the sandbox. */
     {
         path: ".intentic/claude/",
         invalidates: [],
         why: "Agent session transcripts — see the note above on why the memory notes under it stay polled.",
+        portability: "secret",
+        note: "Sign the agent's AI accounts in again on the Agent tab.",
+    },
+    {
+        path: ".intentic/claude/projects/",
+        invalidates: [],
+        why: "Same store as the entry above; split from it for portability, not for invalidation.",
+        portability: "carry",
     },
     {
         path: ".intentic/ci.json",
         invalidates: [],
         why: "Webhook secret + conclusion memory; the Pipelines view reads it through /ci/runs, not off disk.",
+        portability: "secret",
+        note: "Re-add the CI webhook on the Pipelines view — its secret is per-sandbox.",
     },
     {
         path: ".intentic/komodo.json",
         invalidates: [],
         why: "Per-connection 'when the owner last looked at Deployments'; the view reads it through /komodo/{capability}/overview, not off disk — and it is written BY that view being opened, so invalidating on it would refetch the board in answer to the browser's own click.",
+        portability: "carry",
+    },
+    {
+        path: ".intentic/bridge-tokens.json",
+        invalidates: [],
+        why: "Hashed ACP bridge tokens, listed on demand by the owner.",
+        portability: "identity",
+        note: "Mint fresh ACP bridge tokens — the old ones authenticate against the source sandbox.",
     },
-    { path: ".intentic/bridge-tokens.json", invalidates: [], why: "Hashed ACP bridge tokens, listed on demand by the owner." },
     {
         path: ".intentic/owner.json",
         invalidates: [],
         why: "Bound once on first use; a change here means the sandbox was re-owned, which re-authenticates anyway.",
+        portability: "identity",
+    },
+    {
+        path: ".intentic/workspace.json",
+        invalidates: [],
+        why: "The workspace identity, read from the /events hello frame rather than as a file.",
+        portability: "identity",
     },
-    { path: ".intentic/workspace.json", invalidates: [], why: "The workspace identity, read from the /events hello frame rather than as a file." },
-    { path: ".intentic/templates.json", invalidates: [], why: "Scaffold templates, read when the scaffold dialog opens." },
+    { path: ".intentic/templates.json", invalidates: [], why: "Scaffold templates, read when the scaffold dialog opens.", portability: "carry" },
+    /* Classed `derived` for size rather than for safety, and it is the one entry where that costs the owner
+     * something real: the profiles ARE logged-in sessions. They are also gigabytes of a store Chromium rewrites
+     * constantly and versions against its own build, so carrying them ships bulk that the target's Chromium may
+     * refuse anyway. The note is what keeps the loss visible instead of silent. */
     {
         path: ".intentic/browser/",
         invalidates: [],
         why: "Browser-login profiles: Chromium rewrites these constantly. Descent-ignored by the watcher outright.",
+        portability: "derived",
+        note: "Log the agent's browser back into any site it needs — profiles do not travel.",
     },
     {
         path: ".intentic/extensions/",
         invalidates: [],
         why: "Extension checkouts — whole git clones. The `extensions` query is driven by the capability manifest above, not by their contents.",
+        portability: "derived",
+        note: "Extensions re-clone from the capability manifest on the target's next reconcile.",
     },
-    { path: ".intentic/plugins/", invalidates: [], why: "Agent plugin dirs, read by the SDK's loader each turn." },
+    { path: ".intentic/plugins/", invalidates: [], why: "Agent plugin dirs, read by the SDK's loader each turn.", portability: "carry" },
 ];
 
 /* The query keys a batch of changed paths makes stale, deduped and stable. The browser's `/events` handler calls