@intentic/sandbox-contract 1.343.0 → 1.345.0

package/src/state/auth-state.ts

@@ -0,0 +1,89 @@
+import { STATE_DIR } from "@intentic/constants";
+import type { StateFile } from "./state-portability.js";
+import type { WorkspaceStatePath } from "./workspace-state.js";
+
+// The auth root holds AI-provider logins, the sandbox's secret vaults and the trust files a turn must not edit (mode
+// 0600, off the file routes, tree walk and search index). It lives at `.intentic/secrets/auth/` unless AGENT_AUTH_DIR
+// moved it, and the workspace table names it once, as a `secret` directory. This table classifies what is inside, so
+// an export does not carry this sandbox's own keys and pairings with the credentials, and does not drop the owner's
+// restrictions with them either. auth-state-coverage.test.ts in the daemon keeps it complete.
+//
+// The default for a path no entry claims is `secret`, the class of the directory itself: a provider home (`claude/`,
+// `codex/`, `cliproxy/`, `opencode/`…) is a login, and a new provider lands secret by construction.
+//
+// The classes follow the history table's precedent. A restriction the owner set is `carry`: a secret that travels must
+// not arrive ungated. A yes the owner gave (a grant, a release, a widened rule) is `identity`, like the hook and extension
+// approvals there: a trust decision the target's owner makes again.
+
+// Where the auth root sits inside the workspace when AGENT_AUTH_DIR does not move it; a declared workspace path.
+export const AUTH_ROOT_IN_WORKSPACE = `${STATE_DIR}/secrets/auth/` as const satisfies WorkspaceStatePath;
+
+// Auth-root-relative paths, forward-slash, matched by prefix; a directory keeps its trailing slash.
+export const AUTH_STATE_FILES: readonly StateFile[] = [
+    /* ---- the owner's restrictions: no credential in them, and loosened if left behind ---- */
+
+    // Which credentials need a named person's click (secrets/credential-gates.ts).
+    { path: "credential-gates.json", portability: "carry" },
+    // Where each secret may be sent (secrets/guards/host-guards.ts).
+    { path: "secret-hosts.json", portability: "carry" },
+    // The privacy shield's policy: whether it masks, what it looks for, which providers it trusts.
+    { path: "privacy-shield.json", portability: "carry" },
+    // The execution boundary agents run in (workload/domain/agent-domain-policy.ts).
+    { path: "agent-domain.json", portability: "carry" },
+
+    /* ---- credentials and what holds their values ---- */
+
+    { path: "sandbox-secrets.json", portability: "secret" },
+    { path: "capability-secrets.json", portability: "secret" },
+    { path: "extension-secrets.json", portability: "secret" },
+    // The personal data the shield masked, by token, and the pictures it painted over.
+    { path: "privacy-vault.json", portability: "secret" },
+    { path: "privacy-images/", portability: "secret" },
+    { path: "ssh-keys/", portability: "secret" },
+    // An update's pre-images of the files above; a vault's copy is a vault.
+    { path: "converting/", portability: "secret" },
+
+    /* ---- yeses the owner gave here: decided again on the target ---- */
+
+    // Sandbox-wide permissions ("Always: <line>") and each conversation's own (personas/owner-grants.ts,
+    // conversation-grants.ts); a conversation's card simply asks again, so only the sandbox-wide ones carry a note.
+    { path: "owner-grants.json", portability: "identity", note: "Give sandbox-wide permissions again from the Access tab." },
+    { path: "conversation-grants.json", portability: "identity" },
+    // An approver's release of a gated credential for one conversation.
+    { path: "credential-releases.json", portability: "identity" },
+    // Programs a secret may be typed into unasked; unset, every typing asks.
+    { path: "secret-programs.json", portability: "identity", note: "Allow programs to receive secrets again from Secrets." },
+    // Per-card credential rules and raw delivery, the owner's widening of a connector's own rules.
+    { path: "credential-policy.json", portability: "identity", note: "Set a connection's credential rules and delivery again from Capabilities." },
+
+    /* ---- this sandbox's own keys, and what it is paired with ---- */
+
+    // The keyring keypair the owner's computers pinned their shares to; only the public halves ever leave.
+    { path: "keyring-keys.json", portability: "identity", note: "Passwords shared from your computers are shared again with the new sandbox." },
+    // What each connected computer's keyring said, the entries copied to this sandbox's key, deliveries waiting for a
+    // computer, and the needs raised to them.
+    { path: "keyring-devices.json", portability: "identity" },
+    { path: "keyring-copies.json", portability: "identity" },
+    { path: "keyring-sync-mailbox.json", portability: "identity" },
+    { path: "keyring-needs.json", portability: "identity" },
+    // The credential broker's signing key and the privacy gateway's token key, each minted on first use.
+    { path: "broker-session.key", portability: "identity" },
+    { path: "privacy-gateway.key", portability: "identity" },
+    // The organisation policy the platform hands this sandbox; the target's platform hands its own.
+    { path: "org-policy.json", portability: "identity" },
+
+    /* ---- regenerated by the target ---- */
+
+    // Seat refusals the provider answered, and the model catalogs fetched for each runtime.
+    { path: "claude/seats.json", portability: "derived" },
+    { path: "claude/models.json", portability: "derived" },
+    { path: "cursor/models.json", portability: "derived" },
+    { path: "devin/models.json", portability: "derived" },
+    { path: "gemini/models.json", portability: "derived" },
+    // Each custom endpoint's last discovered model list, fetched again from the endpoint.
+    { path: "endpoints/", portability: "derived" },
+    // Values a computer released for one use each, for masking only; never outlive the process handed them.
+    { path: "keyring-released.json", portability: "derived" },
+    // The shell script and socket OpenCode runs commands through, written at boot.
+    { path: "opencode-shell/", portability: "derived" },
+];

package/src/state/history-state.ts

@@ -25,6 +25,14 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // The tasks this sandbox's conversations handed to linked sandboxes (links/linked-children.ts), followed until they
     // settle: part of the conversations' own record, so it goes where they go.
     { path: "links/linked-children.json", portability: "carry" },
+    // One file per agent a conversation spawned (agent/subagents/spawned-children.ts): what its parent supervises it by
+    // (its run, session, last report and result), read back at boot so a restart does not orphan it. Part of the
+    // conversations' own record, so it goes where they go.
+    { path: "spawned-children/", portability: "carry" },
+    // One file per workflow run a conversation started (agent/subagents/workflows/script-runs.ts): its script, its calls and what
+    // each handed back, so a restart picks it up where it was and a later run can resume from its finished calls. Part of
+    // the conversations' own record, so it goes where they go.
+    { path: "script-runs/", portability: "carry" },
     // The long tool outputs those transcripts name rather than hold, stored once by content for every record naming
     // them; a transcript without them keeps only each output's start.
     { path: "blobs/", portability: "carry" },
@@ -48,6 +56,10 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "audit/", portability: "carry" },
     { path: "usage.jsonl", portability: "carry" },
     { path: "account-usage.json", portability: "carry" },
+    // What each provider's usage answers have been made of (their paths, and one redacted sample), so an answer that
+    // changes is noticed. Carried: the provider answers the same wherever the sandbox runs, and a fresh record would
+    // take the next changed answer as the first one.
+    { path: "provider-answers.json", portability: "carry" },
     // Per-account stay-away for a provider's usage endpoint. Carried, not re-earned: earning one costs the very read it
     // holds off, and is answered with a deadline measured from that moment. Entries past their instant are inert.
     { path: "usage-parks.json", portability: "carry" },
@@ -71,6 +83,14 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "apply-events.ndjson", portability: "carry" },
     { path: "check-events/", portability: "carry" },
 
+    // User-started operator panels resume on this sandbox after a restart; a moved sandbox starts inert.
+    { path: "panels.json", portability: "derived" },
+    // Receipts name kept commands lost with container-local capture storage; never replay arbitrary commands.
+    { path: "kept-jobs/", portability: "derived" },
+    // The last hour's turns `agents message` and each link started (the daemon's store/start-window.ts), so a restart does
+    // not reopen their hourly ceilings; a moved sandbox starts its hour afresh.
+    { path: "turn-starts.json", portability: "derived" },
+
     /* ---- regenerated by the target ---- */
 
     // Deliberately omitted: the branch lives in gits/, the registry in conversations.db; regenerated on the next turn.
@@ -185,7 +205,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
         portability: "identity",
         note: "Re-invite collaborators from the Access tab, a grant is the platform's record, and the target enforces its own copy.",
     },
-    { path: "identity/control-tokens.json", portability: "identity", note: "Mint fresh control tokens, the old ones authenticate against the source sandbox." },
+    {
+        path: "identity/control-tokens.json",
+        portability: "identity",
+        note: "Mint fresh control tokens, the old ones authenticate against the source sandbox.",
+    },
     // The links other sandboxes hand this one tasks through (links/inbound-links.ts): hashed tokens like the control
     // tokens, each minted here, and the tasks filed under them; elsewhere they would let the paired sandboxes reach the
     // target in this one's name.
@@ -223,6 +247,9 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "phone-enrollments.json", portability: "identity", note: "Pair your phone again from its card: the app is still installed." },
     { path: "phone-pair-consumed.json", portability: "identity" },
     { path: "phone-wake.json", portability: "identity" },
+    // Which computers' keyrings each phone paired with for Passwords (phones/phone-pairings.ts): a shortcut over the
+    // keyrings' own pinned keys, keyed by phones paired to this sandbox, so it stays with the pairings above.
+    { path: "phone-pairings.json", portability: "identity" },
     // Setup-device pairing burn list; carrying it would mark another sandbox's fresh pairing as spent.
     { path: "host-pair-consumed.json", portability: "identity" },
     // Lands waiting for the computer whose folder they go to, and which computer last held each attached folder
@@ -256,6 +283,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // person, since the key that signed it stays behind.
     { path: "automation-holds/", portability: "carry" },
     { path: "automation-holds.key", portability: "identity", note: "A held wake that was counting down arrives waiting for your yes instead." },
+    // What waits for an automation fire not journalled yet (the daemon's automations/durable/inbox-store.ts): a channel
+    // message in its debounce or behind a running fire, a workspace event behind its chore. Travels with the turn journal
+    // in conversations.db, which names the rows a fire already took.
+    { path: "automation-listener-inbox.json", portability: "carry" },
+    { path: "automation-workspace-inbox.json", portability: "carry" },
     { path: "local-cert/", portability: "identity" },
 
     /* ---- the state engine's own bookkeeping (the daemon's store/evolution/state-journal.ts) ---- */
@@ -267,4 +299,15 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // Every conversation the import of the pre-1.308 layout settled (the daemon's conversations/registry/pre-1308-import.ts),
     // so one deleted after its import is not brought back from the old files still on disk. About this volume only.
     { path: "pre-1308-import.json", portability: "derived" },
+
+    /* ---- written beside the daemon, by the image, the host's ic and the package manager ---- */
+
+    // The terminal's typed history (the image's HISTFILE, made by docker-entrypoint.sh): the owner's own, kept so its
+    // suggestions survive a rebuild. `secret`, since a typed line can hold a pasted token.
+    { path: "shell/", portability: "secret" },
+    // ic's copy of its records for this sandbox (ic's sandbox/mirror.rs): its channel and rollback target, the machine
+    // that keeps it, its backups and repairs. About the machine it runs on, so the target's ic writes its own.
+    { path: ".ic/", portability: "identity" },
+    // pnpm's package store for installs in a checkout under /history, kept at the top of the mount pnpm finds it on.
+    { path: ".pnpm-store/", portability: "derived" },
 ];

package/src/state/runtime-state.ts

@@ -53,10 +53,11 @@ const RUNTIME_DOMAINS = [
     // Commit subject drafted after landing; arrives too late for the turn-end refresh, needs its own push.
     { domain: "landings", invalidates: [["git", "changes"]] },
 
-    // A pipeline run reached its end (webhook delivery, or the REST poll for a repo with no hook). The board's own
-    // poll is the freshness floor, not the answer: somebody watching a run finish must not wait out a poll interval.
-    // Runs only: the frame doesn't name which run moved, and re-reading every open row's job graph would cost a
-    // vendor call per row. The row re-reads its own graph off the status this invalidation lands (useRunJobs.ts).
+    // A pipeline run or one of its jobs moved: every webhook delivery, in flight or ended (2026-10-20), or the REST poll
+    // for a repo with no hook. The board's own poll is the freshness floor, not the answer: somebody watching a run
+    // must not wait out a poll interval. Runs only: the frame doesn't name which run moved, and re-reading every open
+    // row's job graph would cost a vendor call per row. An open in-flight row re-reads its own graph when the board's
+    // runs land (useRunJobs.ts); the daemon's CI-shaped watches recheck on it too (watchers.ts).
     { domain: "ci", invalidates: [["ci-runs"]] },
 
     // An engine install starting or ending, whoever started it; the card's only feed, since a read costs registry calls.

package/src/text/transcript-fold.test.ts

@@ -113,6 +113,22 @@ describe("foldTurn", () => {
         ]);
     });
 
+    // What a reader needs once nothing in memory remembers the subagent: the card the turn settles into keeps it.
+    it("keeps where the runtime holds an in-process subagent's own record on its card", () => {
+        const events: AgentEvent[] = [
+            { kind: "tool_call", id: "task-1", name: "Agent", category: "other", status: "in_progress" },
+            { kind: "subagent", id: "task-1", subagentKind: "subagent", agentType: "Explore" },
+            { kind: "subagent_update", id: "task-1", sdk: { sessionId: "ses-1", agentId: "a1b2" } },
+            { kind: "subagent_update", id: "task-1", status: "completed" },
+        ];
+        expect(foldOf("delegate", events).at(-1)?.tools?.[0]?.subagent).toEqual({
+            kind: "subagent",
+            agentType: "Explore",
+            status: "completed",
+            sdk: { sessionId: "ses-1", agentId: "a1b2" },
+        });
+    });
+
     // A spawned subagent is named by its own conversation, not the call that started it; the spawn answers with that
     // name, which is how its card is found, so it reads on its card exactly as an in-process one does.
     it("puts a spawned subagent on the card of the call whose result names it", () => {
@@ -931,6 +947,57 @@ describe(`a refusal that ran nothing`, () => {
         expect(fold.ranNothing).toBe(false);
     });
 
+    // The reported row (onboarding review 2026-10-18, F07): the trial ran out on a later step of a turn that had already
+    // edited a file, and the row said the message was not delivered and held to send again. Neither was true: the turn
+    // ran, nothing holds its words (turn-runs keeps only a turn turned away at the door), and a resend repeats its edits.
+    describe(`arriving after the turn already ran`, () => {
+        const SPENT = {
+            kind: `error`,
+            code: `trial-exhausted`,
+            message: `Free trial used up for today: every free agent step is spent. Connect a model to keep going.`,
+        } as const satisfies AgentEvent;
+        const EDITED: readonly AgentEvent[] = [
+            { kind: `tool_call`, id: `t1`, name: `Edit`, category: `edit`, status: `completed`, target: `src/page.tsx` },
+        ];
+
+        it(`says the run stopped partway with its changes kept, and offers another model rather than a resend`, () => {
+            const fold = new TranscriptFold(openingOf(`change the heading`));
+            for (const event of EDITED) {
+                fold.apply(event);
+            }
+            fold.apply(SPENT);
+
+            expect(fold.rows.map((row) => row.role)).toEqual([`user`, `assistant`, `notice`]);
+            expect(fold.rows.at(-1)).toEqual({
+                role: `notice`,
+                text: `${SPENT.message} The run stopped partway. The changes it made so far are kept: continue with another model to pick up from here.`,
+                noticeAction: `switchModel`,
+                noticeCode: { code: `stoppedPartway`, params: { message: SPENT.message, error: `trial-exhausted`, switchModel: true } },
+            });
+            expect(fold.ranNothing).toBe(false);
+        });
+
+        // Another model does not clear a full disk; the row still never claims the words are held.
+        it(`offers no model switch for a refusal another model would not get past`, () => {
+            const disk = { kind: `error`, code: `sandbox-disk-low`, message: `The sandbox's disk is full.` } as const satisfies AgentEvent;
+            expect(foldOf(`change the heading`, [...EDITED, disk]).at(-1)).toEqual({
+                role: `notice`,
+                text: `${disk.message} The run stopped partway. The changes it made so far are kept: send a message to pick up from here.`,
+                noticeCode: { code: `stoppedPartway`, params: { message: disk.message, error: `sandbox-disk-low` } },
+            });
+        });
+
+        it(`keeps the not-delivered row for the same refusal when nothing had run`, () => {
+            expect(foldOf(`change the heading`, [SPENT])).toEqual([
+                {
+                    role: `notice`,
+                    text: `${SPENT.message} Your message was not delivered: it is held for you to send again.`,
+                    noticeCode: { code: `undelivered`, params: { message: SPENT.message, error: `trial-exhausted` } },
+                },
+            ]);
+        });
+    });
+
     // The sandbox, not a composer, keeps a turn it started itself (a fix press, a peer's message): the frame says so
     // with `held`. The bug this exists for: such a refusal took the fix prompt out, and no queue anywhere held a copy.
     describe(`of a turn the sandbox keeps`, () => {

package/src/text/transcript-fold.ts

@@ -15,8 +15,8 @@ import { contextTrimLine, contextTrimNotice } from "../schemas/context-trim.js";
 import { keptWarmLine, keptWarmNotice } from "../schemas/keep-warm.js";
 import { handedOffLine, handedOffNotice } from "../schemas/providers/handoff.js";
 import { isLandConflict } from "../events/land-conflict.js";
-import { turnedAwayCode } from "../policy/turned-away.js";
-import { undeliveredRow } from "../events/undelivered.js";
+import { anotherModelClears, turnedAwayCode } from "../policy/turned-away.js";
+import { stoppedPartwayRow, undeliveredRow } from "../events/undelivered.js";
 import { mentionedPathTokens } from "./mentions.js";
 import { unspokenPromptRow } from "../events/agent-words.js";
 import { needRowText } from "../events/need-wake.js";
@@ -239,8 +239,8 @@ const RENEWAL_WITHDRAWN =
     "The credential was being renewed, but the turn stopped before it could continue: it will not carry on by itself, so press Continue to pick it back up.";
 
 // Row for a turn-ending error: the provider's own message plus one clause on what happens next. The live wait itself is
-// drawn by the chat, not stored here.
-const errorRow = (event: Extract<AgentEvent, { kind: "error" }>): TranscriptRow => {
+// drawn by the chat, not stored here. `ran`: an assistant row stands, so a door refusal stopped the turn partway.
+const errorRow = (event: Extract<AgentEvent, { kind: "error" }>, ran: boolean): TranscriptRow => {
     const { message, code } = event;
     const said = failureOf(event);
     switch (code) {
@@ -281,7 +281,7 @@ const errorRow = (event: Extract<AgentEvent, { kind: "error" }>): TranscriptRow
         // provider's own uncoded words are only ever themselves.
         return code === undefined ? { role: "notice", text: message } : { role: "notice", text: message, noticeCode: noticeCode({ code: "failed", params: said }) };
     }
-    return heldRow(event);
+    return ran && event.held === undefined ? stoppedPartwayRow(said, anotherModelClears(code)) : heldRow(event);
 };
 
 // What a laddered wall's automatic re-runs are doing, said on the failure's own row so the count stays in the record.
@@ -488,7 +488,7 @@ export class TranscriptFold {
             case "error":
                 // Keeps a refusal (no prose from the provider) from reading as a session that ended mid-question.
                 // A refusal that ran nothing takes its message back out ahead of the notice standing in for it.
-                return [...this.retract(event), ...this.withdrawRenewal(event), ...this.pushRow(errorRow(event))];
+                return [...this.retract(event), ...this.withdrawRenewal(event), ...this.pushRow(errorRow(event, this.rows.some((row) => row.role === "assistant")))];
             case "plan": {
                 // Folds a plan into an identical retired prose bubble instead of drawing the same markdown twice.
                 const adjacent = this.rows.at(-1);

package/src/webext/index.ts

@@ -9,3 +9,5 @@ export * from "../protocol/doors/webext-protocol.js";
 export * from "../schemas/webext.js";
 export * from "../schemas/loopback-catch.js";
 export * from "../schemas/peer-enrollment.js";
+// What the extension says to `intentic-keyring native-host` (the Passwords app's browser capture and fill).
+export * from "../schemas/keyring-native.js";