@intentic/sandbox-contract 1.315.0 → 1.317.0

package/src/events/need-wake.test.ts

@@ -0,0 +1,55 @@
+import { unspokenPromptRow } from "./agent-words.js";
+import { needRowText, needWakeOf, needWakePrompt, needWakeRow, type NeedWakeFields, type NeedWakeOutcome } from "./need-wake.js";
+
+const fields = (over: Partial<NeedWakeFields> = {}): NeedWakeFields => ({
+    outcome: "met",
+    id: "need-7k2q",
+    title: "Connect GitHub",
+    why: "to open the pull request for the fix",
+    result: 'GitHub is connected as "github".',
+    use: ["In this turn, prefix a command with GH_TOKEN={{secret:github/token}}."],
+    ...over,
+});
+
+const OUTCOMES: NeedWakeOutcome[] = ["met", "declined"];
+
+describe("need wake", () => {
+    // The composer and the parser are the same piece of knowledge; this holds them together when either is reworded.
+    it.each(OUTCOMES)("round-trips a %s wake back to its fields", (outcome) => {
+        const prompt = needWakePrompt(fields({ outcome }));
+        expect(needWakeOf(prompt)).toEqual({ outcome, title: "Connect GitHub", id: "need-7k2q", sent: prompt });
+    });
+
+    it("tells a met need to carry on and a declined one not to wait", () => {
+        expect(needWakePrompt(fields()).split("\n").at(-1)).toBe("Continue the task that needed it.");
+        expect(needWakePrompt(fields({ outcome: "declined", use: [] }))).not.toContain("Continue the task");
+    });
+
+    it("leaves the agent's reason out when it gave none, rather than printing an empty label", () => {
+        expect(needWakePrompt(fields({ why: undefined }))).not.toContain("You asked because:");
+        expect(needWakePrompt(fields())).toContain("You asked because: to open the pull request for the fix");
+    });
+
+    it("is not a wake once its labelled lines are gone", () => {
+        const prompt = needWakePrompt(fields());
+        expect(needWakeOf(prompt.replace("Need id: need-7k2q\n", ""))).toBeUndefined();
+        expect(needWakeOf(prompt.replace("Need: Connect GitHub\n", ""))).toBeUndefined();
+        expect(needWakeOf("please connect github")).toBeUndefined();
+    });
+
+    it("becomes a notice row that says what happened, and every transcript reader finds it", () => {
+        const prompt = needWakePrompt(fields());
+        const row = needWakeRow(prompt);
+        expect(row).toEqual({
+            role: "notice",
+            text: "Connect GitHub: done, and the agent carries on.",
+            needWake: { outcome: "met", title: "Connect GitHub", id: "need-7k2q", sent: prompt },
+        });
+        expect(unspokenPromptRow(prompt)).toEqual(row);
+        expect(needWakeRow(needWakePrompt(fields({ outcome: "declined" })))?.text).toBe("Connect GitHub: declined, and the agent was told.");
+    });
+
+    it("words a raised need's row for a reader that draws no card", () => {
+        expect(needRowText({ title: "The OPENAI_API_KEY secret" })).toBe("Needs a person: The OPENAI_API_KEY secret");
+    });
+});

package/src/events/need-wake.ts

@@ -0,0 +1,71 @@
+import type { TranscriptNeedWake, TranscriptRow } from "./transcript.js";
+
+// What a need says when its answer reaches a conversation, and how that reads to a person. Delivered as an ordinary
+// turn prompt (a steer into a live turn, or a turn of its own), so composing it and recognising it stay one piece of
+// knowledge, exactly as a condition watch's wake does (watch-wake.ts): the daemon's record, a steered live turn and a
+// provider's session store all turn this prompt back into the same row.
+
+export type NeedWakeOutcome = TranscriptNeedWake["outcome"];
+
+// Per-outcome opening sentence, which is also what the parser anchors on: keep each unique and stable across releases,
+// or a reworded opening un-recognises wakes already in a record and they read as the user's own words.
+const OPENINGS: Record<NeedWakeOutcome, string> = {
+    met: "Need met: a person gave you what you asked for.",
+    declined: "Need declined: a person said no to what you asked for. Carry on without it, and say plainly what it would have enabled.",
+};
+
+// Labels the prompt writes and the parser reads back. `Need` and `Need id` are load-bearing on both sides.
+const NEED = "Need: ";
+const NEED_ID = "Need id: ";
+const ASKED = "You asked because: ";
+
+export interface NeedWakeFields {
+    readonly outcome: NeedWakeOutcome;
+    readonly id: string;
+    readonly title: string;
+    readonly why: string | undefined;
+    // The daemon's sentence on how it ended ("Connected as "github".", "Stored under OPENAI_API_KEY.").
+    readonly result: string;
+    // What the agent can do with it now, and what arrives on its next turn; empty for a decline.
+    readonly use: readonly string[];
+}
+
+export const needWakePrompt = (fields: NeedWakeFields): string =>
+    [
+        OPENINGS[fields.outcome],
+        `${NEED}${fields.title}`,
+        `${NEED_ID}${fields.id}`,
+        ...(fields.why === undefined || fields.why === "" ? [] : [`${ASKED}${fields.why}`]),
+        fields.result,
+        ...fields.use,
+        ...(fields.outcome === "met" ? ["Continue the task that needed it."] : []),
+    ].join("\n");
+
+const headline = (outcome: NeedWakeOutcome, title: string): string =>
+    outcome === "met" ? `${title}: done, and the agent carries on.` : `${title}: declined, and the agent was told.`;
+
+const valueOn = (lines: readonly string[], label: string): string | undefined => lines.find((line) => line.startsWith(label))?.slice(label.length);
+
+// The words a raised need's row carries for a reader that draws no card (search, an export, an older client); the card
+// itself is drawn from the need.
+export const needRowText = (need: { readonly title: string }): string => `Needs a person: ${need.title}`;
+
+// Which need wake a stored prompt is, if any; undefined for every prompt that isn't one, so any reader can ask without
+// checking first. One that opens as a wake but lost its labelled lines is not one.
+export const needWakeOf = (prompt: string): TranscriptNeedWake | undefined => {
+    const outcome = (Object.keys(OPENINGS) as NeedWakeOutcome[]).find((key) => prompt.startsWith(OPENINGS[key]));
+    if (outcome === undefined) {
+        return undefined;
+    }
+    const lines = prompt.split("\n");
+    const title = valueOn(lines, NEED);
+    const id = valueOn(lines, NEED_ID);
+    return title === undefined || id === undefined ? undefined : { outcome, title, id, sent: prompt };
+};
+
+// The row a wake becomes: a notice, since a need being answered happened to the conversation rather than being said by
+// either side. Undefined when the prompt is not a need wake at all.
+export const needWakeRow = (prompt: string): TranscriptRow | undefined => {
+    const wake = needWakeOf(prompt);
+    return wake === undefined ? undefined : { role: "notice", text: headline(wake.outcome, wake.title), needWake: wake };
+};

package/src/events/transcript.ts

@@ -3,6 +3,7 @@ import { AgentHarnessSchema, AgentProviderSchema } from "../schemas/agent.js";
 import { ShareDetailSchema } from "../schemas/share.js";
 import { TurnErrandSchema, TurnSpeakerSchema } from "../schemas/speaker.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
+import { NeedSchema } from "../schemas/needs.js";
 import { RetryLadderSchema } from "../schemas/turn-break.js";
 import type { ToolCallContent, ToolCallLocation, ToolCallStatus, ToolKind} from "./requests.js";
 import { browserHelpRequest, capabilityOfferRequest, CapabilityOutcomeSchema, credentialOfferRequest, CredentialReceiptSchema, paymentOfferRequest, PaymentReceiptSchema, PermissionAskSchema, permissionRequest, planRequest, questionRequest, terminalHelpRequest, TodoItemSchema, ToolCallContentSchema, ToolCallLocationSchema, ToolCallStatusSchema, ToolKindSchema } from "./requests.js";
@@ -155,6 +156,15 @@ export const TranscriptWatchWakeSchema = z.object({
 });
 export type TranscriptWatchWake = z.infer<typeof TranscriptWatchWakeSchema>;
 
+// A need's answer that reached this conversation as a prompt (need-wake.ts); the row keeps the prompt and names the need.
+export const TranscriptNeedWakeSchema = z.object({
+    outcome: z.enum(["met", "declined"]).describe("How the need ended: a person gave it, or said no."),
+    title: z.string().describe("The need, as its card leads with it."),
+    id: z.string().describe("The need's handle, which its live card is keyed by."),
+    sent: z.string().describe("The whole prompt the model received, disclosed under the row."),
+});
+export type TranscriptNeedWake = z.infer<typeof TranscriptNeedWakeSchema>;
+
 // Another agent's words that reached this conversation as a prompt; the row keeps the prompt and names the sender.
 export const TranscriptAgentWordsSchema = z.object({
     kind: z.enum(["peer", "child"]).describe("Who sent it: another conversation in the workspace, or a subagent this one started."),
@@ -299,6 +309,12 @@ export const TranscriptRowSchema = z.object({
     capabilityOffer: TranscriptCapabilityOfferSchema.optional().describe("The capability setup this row asked for, the decision, and the outcome."),
     paymentOffer: TranscriptPaymentOfferSchema.optional().describe("The payment this row asked for, the decision, and the receipt."),
     watchWake: TranscriptWatchWakeSchema.optional().describe("The condition watch that woke this conversation, and the prompt it was woken with."),
+    // A need is not a parked card: it holds no turn open, outlives the one that raised it, and its live state is the
+    // needs store's, keyed by `need.id`. What rides here is the need as it was raised, for a reader with no store.
+    need: NeedSchema.optional().describe(
+        "Something the agent asked a person for, as it was when raised. Its live state (answered, met) is read by its id, since it outlives the turn.",
+    ),
+    needWake: TranscriptNeedWakeSchema.optional().describe("The answered need that reached this conversation, and the prompt it came as."),
     agentWords: TranscriptAgentWordsSchema.optional().describe("Another agent's words that reached this conversation, whose they are, and the prompt they came as."),
     backgroundJob: TranscriptBackgroundJobSchema.optional().describe("The background job this row marks the start of."),
     credentialOffer: TranscriptCredentialOfferSchema.optional().describe(

package/src/events/verify-nudge.ts

@@ -1,7 +1,7 @@
 // The follow-up the daemon USED to send when a turn ended with work it could not confirm. Nothing sends it any more:
-// checks run after work lands, never inside a conversation (schemas/workspace/mainline.ts). It stays on the wire because
-// records already hold it, and the chat has to go on recognising it: a prompt nobody typed must not reach a reader as
-// their own words.
+// nothing checks inside a conversation, CI checks what the owner pushes (schemas/workspace/push-checks.ts). It stays on
+// the wire because records already hold it, and the chat has to go on recognising it: a prompt nobody typed must not
+// reach a reader as their own words.
 
 // Anchored on by the reader, so it must stay unique and stable across releases — a reworded opening un-recognises every
 // nudge already in a record, and they read as the user's own typing again.

package/src/index.ts

@@ -32,6 +32,7 @@ import { netdiskContract } from "./contracts/netdisk.contract.js";
 import { providersContract } from "./contracts/providers.contract.js";
 import { pushContract } from "./contracts/push.contract.js";
 import { safetyContract } from "./contracts/safety.contract.js";
+import { needsContract } from "./contracts/needs.contract.js";
 import { secretsContract } from "./contracts/secrets.contract.js";
 import { sessionsContract } from "./contracts/sessions.contract.js";
 import { settingsContract } from "./contracts/settings.contract.js";
@@ -83,7 +84,7 @@ export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
 export { issuesContract } from "./contracts/issues.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
-export { REQUEST_ID_EVIDENCE_ROUTE, REQUEST_ID_HEADER } from "./protocol/request-id.js";
+export { REQUEST_ID_HEADER } from "./protocol/request-id.js";
 export * from "./protocol/edge-verdict.js";
 export { loopsContract } from "./contracts/loops.contract.js";
 export { panelsContract } from "./contracts/panels.contract.js";
@@ -92,6 +93,7 @@ export { publicContract } from "./contracts/public.contract.js";
 export { providersContract, type RunnableProviders, RunnableProvidersSchema } from "./contracts/providers.contract.js";
 export { pushContract } from "./contracts/push.contract.js";
 export { safetyContract } from "./contracts/safety.contract.js";
+export { needsContract } from "./contracts/needs.contract.js";
 export { secretsContract } from "./contracts/secrets.contract.js";
 export { sessionsContract } from "./contracts/sessions.contract.js";
 export { settingsContract } from "./contracts/settings.contract.js";
@@ -115,6 +117,7 @@ export * from "./events/land-breakage.js";
 export * from "./events/land-conflict.js";
 export * from "./events/verify-nudge.js";
 export * from "./events/errands.js";
+export * from "./events/need-wake.js";
 export * from "./events/watch-wake.js";
 export * from "./policy/request-status.js";
 export * from "./events/child-run.js";
@@ -214,6 +217,7 @@ export * from "./schemas/providers/provider-subscriptions.js";
 export * from "./schemas/public.js";
 export * from "./schemas/push.js";
 export * from "./schemas/git/remote-refs.js";
+export * from "./schemas/needs.js";
 export * from "./schemas/secrets.js";
 export * from "./schemas/netdisk.js";
 export * from "./schemas/sessions.js";
@@ -224,6 +228,7 @@ export * from "./schemas/shared.js";
 export * from "./schemas/system-prompt.js";
 export * from "./schemas/system.js";
 export * from "./schemas/state-plan.js";
+export * from "./schemas/updates.js";
 export * from "./schemas/terminal.js";
 export * from "./schemas/turn-break.js";
 export * from "./schemas/keep-warm.js";
@@ -234,7 +239,7 @@ export * from "./schemas/webext.js";
 export * from "./schemas/workflows.js";
 export * from "./schemas/workspace/workspace-repos.js";
 export * from "./schemas/workspace/workspace-search.js";
-export * from "./schemas/workspace/mainline.js";
+export * from "./schemas/workspace/push-checks.js";
 export * from "./schemas/workspace/workspace-setup.js";
 export * from "./schemas/workspace/workspace-tree.js";
 export * from "./state/arrival.js";
@@ -285,6 +290,7 @@ export const sandboxContract = {
     public: publicContract,
     providers: providersContract,
     push: pushContract,
+    needs: needsContract,
     secrets: secretsContract,
     system: systemContract,
     translator: translatorContract,

package/src/models/agent-runtimes.ts

@@ -181,7 +181,7 @@ export const PI: AgentCapabilities = {
     secrets: "none",
 };
 
-// Cursor's own runtime, driven through `@cursor/sdk` in this daemon's process; an embedding surface, so most seams
+// Cursor's own runtime, driven through `@cursor/sdk` from this daemon's process; an embedding surface, so most seams
 // other runtimes lack are function arguments here. The harness axis doesn't apply: the SDK is the only door.
 export const CURSOR: AgentCapabilities = {
     runtime: "cursor",
@@ -199,11 +199,12 @@ export const CURSOR: AgentCapabilities = {
     // Cursor publishes effort as model parameters, not one scale; true here just means it's forwardable at all.
     effort: true,
     fastMode: false,
-    // cwd: Cursor's loop runs inside the daemon's own process, whose /work must stay the shared checkout.
-    isolation: "cwd",
+    // The SDK agent of an anchored turn runs in a runtime process born in the turn's mount namespace (the daemon keeps
+    // the loop, the tools and the hook gate), so its shell and its edits see the worktree at /work.
+    isolation: "namespace",
     // Cursor's commands are files on disk the SDK loads but doesn't publish back, so there's no list to offer.
     commands: false,
-    // The SDK runs its shell in-process; there is no tmux session for the terminal panel to attach to.
+    // The SDK runs its shell itself, as a plain child; there is no tmux session for the terminal panel to attach to.
     terminals: false,
     // The SDK throws typed errors instead of dissolving a refusal into prose, so the adapter files coded frames.
     recovery: true,

package/src/models/plan-pools.test.ts

@@ -209,6 +209,21 @@ test("a refusal stands until a later reading contradicts it, and never past its
     expect(refusalVerdict(refusal({ kind: "limit", account: "a" }), [])).toBe("standing");
 });
 
+// Codex's usage endpoint kept reading room while every turn was refused "try again at 3:38 PM": the provider's own
+// instant is what ends the refusal, where it is known which account it refused.
+test("a spent allowance with the provider's own reset stands until that instant, whatever a later reading says", () => {
+    const room = at(2_000, window({ kind: "five_hour", utilization: 0 }));
+    const until = { kind: "limit", resetsAt: 10 } as const;
+    expect(refusalVerdict(refusal({ ...until, account: "a" }), [{ account: "a", usage: room }], 9_999)).toBe("standing");
+    expect(refusalVerdict(refusal({ ...until, account: "a" }), [{ account: "a", usage: room }], 10_000)).toBe("answered");
+    // A routed refusal names no account, but with one account there is no doubt whose it was.
+    expect(refusalVerdict(refusal(until), [{ account: "a", usage: room }], 9_999)).toBe("standing");
+    // Over several, the translator benches the one it refused and routes on, so another's room still answers it.
+    expect(refusalVerdict(refusal(until), [{ account: "a", usage: room }, { account: "b", usage: room }], 9_999)).toBe("answered");
+    // Spent until the instant the provider named, not the pool's own reset.
+    expect(serviceStates([{ account: "a", usage: room }], refusal({ ...until, account: "a" }), undefined, 9_999).get("a")).toEqual({ kind: "spent", reopensAt: 10 });
+});
+
 test("a provider's accounts are judged together: a standing refusal lands only on the account it names", () => {
     const room = at(500, window({ kind: "five_hour", utilization: 40 }));
     const states = serviceStates([{ account: "a", usage: room }, { account: "b", usage: room }], refusal({ kind: "entitlement", account: "a" }));

package/src/models/plan-pools.ts

@@ -147,6 +147,9 @@ export interface ServiceFacts {
     readonly seatRefusal?: string | undefined;
     readonly cooling?: { readonly until?: number | undefined; readonly reason?: string | undefined; readonly verify?: string | undefined } | undefined;
     readonly usage?: AccountUsage | undefined;
+    // How the account is named to a person (its label, a routed credential's address); a surface that quotes a figure
+    // says whose it is.
+    readonly label?: string | undefined;
 }
 
 // A spent allowance is over once a reading with room lands after it; a refused credential once any reading does (the
@@ -168,11 +171,22 @@ const answers = (refusal: ProviderRefusal, facts: ServiceFacts): boolean => {
  * the account it named is disconnected, `answered` once that account (or, for a refusal naming none, any account) has a
  * later reading that contradicts it, else `standing`. An empty list is one not loaded yet, so the refusal stands.
  */
-export const refusalVerdict = (refusal: ProviderRefusal, accounts: readonly ServiceFacts[]): "standing" | "answered" | "gone" => {
+export const refusalVerdict = (
+    refusal: ProviderRefusal,
+    accounts: readonly ServiceFacts[],
+    now: number = Date.now(),
+): "standing" | "answered" | "gone" => {
     const named = accounts.filter((facts) => facts.account === refusal.account);
     if (refusal.account !== undefined && named.length === 0) {
         return accounts.length === 0 ? "standing" : "gone";
     }
+    // Where the provider named when to try again, and it is known which account it refused (it named one, or there is
+    // only one), its own words outrank a usage endpoint that kept showing room while it refused: over at that instant,
+    // and not before. A nameless refusal over several accounts is still answered by any of them reading room, since the
+    // translator benches the one it refused and routes on.
+    if (refusal.kind === "limit" && refusal.resetsAt !== undefined && (refusal.account !== undefined || accounts.length <= 1)) {
+        return refusal.resetsAt * 1000 <= now ? "answered" : "standing";
+    }
     return (refusal.account === undefined ? accounts : named).some((facts) => answers(refusal, facts)) ? "answered" : "standing";
 };
 
@@ -215,10 +229,12 @@ const refusedPool = (usage: AccountUsage | undefined, refusal: ProviderRefusal,
     if (usage === undefined || binding === undefined) {
         // No pool to pin: the refusal itself is the evidence, unless it was about a different model than this question.
         const sameModel = refusal.model === undefined || model === undefined || refusal.model === model.id;
-        return sameModel ? { kind: "spent" } : headroomState(usage, model);
+        return sameModel ? spent(refusal.resetsAt) : headroomState(usage, model);
     }
     const pinned = usage.windows.map((window) => (window === binding ? { ...window, utilization: Math.max(window.utilization, SPENT_UTILIZATION) } : window));
-    return headroomState({ ...usage, windows: pinned }, model);
+    const state = headroomState({ ...usage, windows: pinned }, model);
+    // The provider's own "try again at" is when it reopens, over whatever the polled pool last said.
+    return state.kind === "spent" && refusal.resetsAt !== undefined ? spent(refusal.resetsAt) : state;
 };
 
 /**
@@ -262,7 +278,7 @@ export const serviceStates = (
     model?: ModelRef,
     now: number = Date.now(),
 ): ReadonlyMap<string, AccountState> => {
-    const standing = refusal !== undefined && refusalVerdict(refusal, accounts) === "standing" ? refusal : undefined;
+    const standing = refusal !== undefined && refusalVerdict(refusal, accounts, now) === "standing" ? refusal : undefined;
     return new Map(
         accounts.map((facts) => [
             facts.account,

package/src/protocol/ingress-contract.fixture.json

@@ -48,6 +48,7 @@
         "GET /diff/raw",
         "GET /workspace/raw",
         "GET /workspace/media",
+        "GET /workspace/download",
         "POST /workspace/upload",
         "POST /workspace/upload-archive",
         "GET /system/sync/ssh",
@@ -59,6 +60,7 @@
     ],
     "lanes": [
         { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/workspace/media?path=a.mp4", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/workspace/download?ticket=t", "lane": "bulk" },
         { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/workspace/upload?path=a", "lane": "bulk" },
         { "host": "sandbox-abcdef012345.sbx.example.test:443", "method": "GET", "path": "/system/runners/git/app/info/refs?service=git-upload-pack", "lane": "bulk" },
         { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/system/runners/git/app/git-receive-pack", "lane": "bulk" },

package/src/protocol/raw-routes.ts

@@ -18,6 +18,8 @@ export const RAW_ROUTES = {
     "GET /workspace/thumb": { guest: true },
     // Fetched by a <video>/<audio> tag, which sends no header: its scoped ticket is checked in the handler.
     "GET /workspace/media": { auth: "door", guest: true, lane: "bulk" },
+    // Navigated to for a ZIP of a selection, so no header either: the ticket it carries names the selection.
+    "GET /workspace/download": { auth: "door", guest: true, lane: "bulk" },
     // An attachment is part of the message it rides with; any other target edits the shared tree.
     "POST /workspace/upload": { floor: "writer", attachmentFloor: "collaborator", lane: "bulk" },
     "POST /workspace/upload-diff": {},
@@ -81,9 +83,8 @@ export const RAW_ROUTES = {
     "GET /extensions/{id}/bundle": { lane: "bulk" },
     // An extension backend's own namespace, proxied verbatim.
     "ALL /x/*": {},
-    // The `capabilities` CLI: discovery by name, and the ask that parks on an owner-decided card.
+    // The `capabilities` CLI's discovery by name; its ask is the needs door (contracts/needs.contract.ts).
     "GET /capabilities/connectable": { floor: "maintainer", agent: true, control: "never" },
-    "POST /capabilities/ask": { floor: "maintainer", agent: true, control: "never" },
     // The `sandboxes` CLI; every create parks on a card in the owner's chat first.
     "GET /sandboxes": { agent: true },
     "POST /sandboxes": { agent: true },
@@ -91,12 +92,13 @@ export const RAW_ROUTES = {
     "GET /wallet/status": { agent: true, control: "never" },
     "POST /wallet/fetch": { agent: true, control: "never" },
     "GET /wallet/history": { agent: true, control: "never" },
-    // The `agents` CLI's children: start, follow up, answer (never a consent card), list.
+    // The `agents` CLI's children: start, follow up, answer (never a consent card), cancel, list.
     "POST /children/spawn": { agent: true, control: "never" },
     "GET /children/providers": { agent: true, control: "never" },
     "POST /children/wait": { agent: true, control: "never" },
     "POST /children/send": { agent: true, control: "never" },
     "POST /children/answer": { agent: true, control: "never" },
+    "POST /children/cancel": { agent: true, control: "never" },
     "GET /children": { agent: true, control: "never" },
     // The fleet reads, and the one write: words in front of another conversation, which a person can do by typing.
     "GET /fleet": { agent: true },

package/src/protocol/request-id.ts

@@ -1,5 +1,2 @@
 // Correlates a browser call to the daemon request that served it; a token only, never a security boundary.
 export const REQUEST_ID_HEADER = "x-intentic-request-id";
-
-// Confirms daemon CORS accepts this header before sending; no evidence here means don't send, unlike supportsRoute.
-export const REQUEST_ID_EVIDENCE_ROUTE = "logs.report";

package/src/schemas/agent.ts

@@ -131,7 +131,7 @@ export type ForkedFrom = z.infer<typeof ForkedFromSchema>;
 const AgentTurnFieldsSchema = z.object({
     prompt: z.string().describe("What to say to the agent. May be empty if you are only attaching files."),
     errand: TurnErrandSchema.optional().describe(
-        "What the words are for, when the app or the sandbox composed them rather than a person typing them: a land conflict to resolve, a red main line to fix. Shown as the sandbox's words, not yours. Leave it out for your own words.",
+        "What the words are for, when the app or the sandbox composed them rather than a person typing them: a land conflict to resolve, a red CI run to fix. Shown as the sandbox's words, not yours. Leave it out for your own words.",
     ),
     // Minted by the sender so a send whose answer was lost can be sent again without being delivered twice.
     messageId: z

package/src/schemas/agents.ts

@@ -4,6 +4,7 @@ import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, Conversatio
 import { LoopStateSchema } from "./loops.js";
 import { LimitPolicySchema, RetryPolicySchema, TurnBreakPolicySchema, TurnBreakSchema } from "./turn-break.js";
 import { KeepWarmSchema } from "./keep-warm.js";
+import { AgentNeedSchema } from "./needs.js";
 import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
 // A fleet agent is any conversation with a registry entry, keyed by conversationId. Isolated ones own a git worktree
 // (branch agent/<id>); workspace conversations have none, but both share one status/activity/cost lifecycle.
@@ -56,7 +57,7 @@ export const AgentAttentionSchema = z.object({
     plan: z.boolean().describe("It has proposed a plan and is waiting for a yes."),
     question: z.boolean().describe("It has asked you something."),
     permission: z.boolean().describe("It wants to use a tool it needs permission for."),
-    // A missing capability (capabilities/offers/capability-offer.ts); lets the lane say "setup needed" rather than a generic
+    // A missing capability on a card from before needs (docs/architecture/needs.md); lets the lane say "setup needed" rather than a generic
     // pause.
     capability: z.boolean().describe("It needs something connected that is not connected yet."),
     // A gated credential parked on a named person's click; the one pause the board's reader may not be able to clear
@@ -65,6 +66,11 @@ export const AgentAttentionSchema = z.object({
         .boolean()
         .describe("It is waiting for a named person to release a credential. The one pause that may not be yours to clear, whatever your role."),
     conflict: z.boolean().describe("Its work cannot be merged without somebody resolving a clash."),
+    // A need outlives its turn (docs/architecture/needs.md), so this can stand on a card that is not running at all.
+    need: z
+        .boolean()
+        .optional()
+        .describe("It asked a person for something it still needs: a connection, a secret, wider reach, a tool. Absent from a daemon older than needs."),
 });
 export type AgentAttention = z.infer<typeof AgentAttentionSchema>;
 // What the last turn left open, measured at the moment it ended, unlike AgentAttentionSchema's live parked waits.
@@ -88,11 +94,11 @@ export const UnfinishedWorkSchema = z.object({
     check: z
         .string()
         .optional()
-        .describe("The end-of-turn check that was still failing when the turn ended, by name. No longer written: checks run after work lands."),
+        .describe("The end-of-turn check that was still failing when the turn ended, by name. No longer written: nothing checks inside a turn."),
 });
 export type UnfinishedWork = z.infer<typeof UnfinishedWorkSchema>;
 // What the last turn showed of its own work, read off its tool calls and never asked of the model: the record a card
-// badges instead of sending the turn back to prove anything. Checks run after the work lands (mainline.ts).
+// badges instead of sending the turn back to prove anything. CI checks what the owner pushes (push-checks.ts).
 export const TurnProofSchema = z.object({
     at: z.number().describe("When the turn that left this ended, in milliseconds."),
     verification: z
@@ -137,7 +143,7 @@ export const LandedMessageSchema = z.object({
         .optional()
         .describe("Why a test this change weakened is meant to be weaker, in the conversation's own words. Nearly always absent."),
     // Present only when the conversation declared an exception a check should grant this change (`Allow: <check> — <reason>`);
-    // the check after the land and the push read it off the commit.
+    // the push reads it off the commit.
     allows: z
         .array(z.string())
         .optional()
@@ -527,6 +533,13 @@ export const AgentSummarySchema = z.object({
         .describe(
             "Outside conditions this conversation is parked on, each of which will wake it. Absent means none, which is nearly every conversation: an armed watch is why a finished-looking agent starts working by itself, and why a hosted machine will not go idle.",
         ),
+    // Kept in the needs store, so unlike `jobs` this survives a restart and stands while the conversation is idle.
+    needs: z
+        .array(AgentNeedSchema)
+        .optional()
+        .describe(
+            "What it is waiting on people for and has not got yet, oldest first. Absent means nothing: an open need is why an idle-looking agent still needs you.",
+        ),
     // In memory only: a daemon restart leaves transcript rows naming jobs this list no longer carries.
     jobs: z
         .array(
@@ -574,10 +587,8 @@ export const AgentSummarySchema = z.object({
         ),
 });
 export type AgentSummary = z.infer<typeof AgentSummarySchema>;
-// Whether a conversation runs again by itself: the daemon's own reading, or, from a daemon older than it, whether a watch
-// is armed, which was all that one could say.
-export const awaitsWake = (agent: { readonly awaitingWake?: boolean | undefined; readonly watches?: readonly unknown[] | undefined }): boolean =>
-    agent.awaitingWake ?? (agent.watches?.length ?? 0) > 0;
+// Whether a conversation runs again by itself: the daemon's own reading, never guessed from its armed watches.
+export const awaitsWake = (agent: { readonly awaitingWake?: boolean | undefined }): boolean => agent.awaitingWake === true;
 // One armed watch as a card carries it; derived from AgentSummarySchema.watches so the two shapes can't drift apart.
 export type AgentWatch = NonNullable<AgentSummary["watches"]>[number];
 // One background job as a card carries it.

package/src/schemas/automations.ts

@@ -28,8 +28,8 @@ import { ZoneSchema } from "../time/zone.js";
 // reads these.
 // turn.settled: fires once per isolated turn regardless of outcome, while the diff is still on screen
 // agent.landed: fires only once work reaches the main tree, including a later manual Land
-// deps.broken/deps.fixed: edges from the dependency verifier around a landed change, not standing states, so a chore
-// wakes on the transition, never on a tree that stays red
+// deps.broken/deps.fixed: retired with the check that ran after every land (2026-09-27). Nothing emits them any more;
+// they stay so an automation written for them still reads, and it never fires. Main's red CI is the `ci` listener's.
 export const WorkspaceEventKindSchema = z.enum(["turn.settled", "agent.landed", "deps.broken", "deps.fixed"]);
 export type WorkspaceEventKind = z.infer<typeof WorkspaceEventKindSchema>;
 // Payload of a workspace-triggered wake, delivered as JSON in $AUTOMATION_PAYLOAD and appended to the prompt.

package/src/schemas/capabilities.ts

@@ -104,6 +104,15 @@ export const SshConfigSchema = z.discriminatedUnion("auth", [
         user: z.string().min(1).describe("Which user to connect as."),
         privateKey: z.string().min(1).describe("The private key, whole. Stored with tight permissions and never echoed back."),
     }),
+    // The sandbox made this key itself (capabilities.sshKey), so its private half never crossed the wire; stored and
+    // written exactly like a pasted one.
+    z.object({
+        auth: z.literal("generated").describe("Sign in with a key the sandbox generated. Its private half never left the sandbox."),
+        host: z.string().min(1).describe("The machine's address."),
+        port: z.coerce.number().default(22).describe("Which port it listens on."),
+        user: z.string().min(1).describe("Which user to connect as."),
+        privateKey: z.string().min(1).describe("The private half of the generated key. Stored with tight permissions and never echoed back."),
+    }),
     z.object({
         auth: z.literal("password").describe("Sign in with a password."),
         host: z.string().min(1).describe("The machine's address."),
@@ -112,6 +121,14 @@ export const SshConfigSchema = z.discriminatedUnion("auth", [
         password: z.string().min(1).describe("The password. Stored, never echoed back."),
     }),
 ]);
+// What a form sends where a generated key's private half goes: the token capabilities.sshKey answered with, which the
+// add swaps for the key the daemon kept. VAULTED's sibling (policy/capability-secrets.ts) for a value not stored yet; a
+// marker with nothing held behind it is refused, never written.
+const STASHED_PREFIX = "__intentic_stashed__:";
+export const stashedMarker = (token: string): string => `${STASHED_PREFIX}${token}`;
+// The token a marker names; undefined for anything else (a real key, VAULTED, a blank).
+export const stashedToken = (value: unknown): string | undefined =>
+    typeof value === "string" && value.startsWith(STASHED_PREFIX) && value.length > STASHED_PREFIX.length ? value.slice(STASHED_PREFIX.length) : undefined;
 // What is optional about the in-sandbox Docker Engine: `gpu` is an IMAGE option (rides the Dockerfile overlay, needs a
 // rebuild), everything else is an ENGINE option (rewrites daemon.json, restarts dockerd, no rebuild but stops running
 // containers). Flat strings, not nested booleans, to match the manifest's own two-state convention.
@@ -460,3 +477,14 @@ export const CapabilityProbeSchema = z.object({
     who: z.string().optional().describe("Who the service said the credential belongs to, when it said."),
 });
 export type CapabilityProbe = z.infer<typeof CapabilityProbeSchema>;
+// POST /capabilities/ssh-key: a key pair made inside the sandbox for a connection being set up. The public half is the
+// whole answer; the private half stays in the daemon until an add sends `stashedMarker(token)` where it goes.
+export const SshKeySchema = z.object({
+    publicKey: z.string().describe("The public half, as the one line a server's authorized_keys holds: `ssh-ed25519 AAAA… intentic-<sandbox>`."),
+    token: z
+        .string()
+        .describe(
+            "Stands for the private half, which never leaves the sandbox. Sent wrapped as a marker in the private key's place, it installs that key once, and it lapses after thirty minutes.",
+        ),
+});
+export type SshKey = z.infer<typeof SshKeySchema>;

package/src/schemas/ci.ts

@@ -1,6 +1,7 @@
 // ci: pipeline runs on the workspace repos' github/gitlab remotes
 import { z } from "zod";
 import { AgentRunPickSchema } from "./agent.js";
+import { RedDecisionSchema } from "./workspace/push-checks.js";
 // The daemon maps each workspace repo to its CI project via a connected github/gitlab capability, registers a webhook
 // to fire `ci` listener automations instantly, and serves the Pipelines rail from a webhook-freshened, poll-backfilled
 // cache. `host` names which provider API serves a repo; the listener provider is always `ci`, since a trigger narrows
@@ -39,6 +40,9 @@ export const PipelineRunSchema = z.object({
         .describe(
             "What set it off, in the forge's own word rather than flattened into a shared vocabulary, because the forge's word is the precise one.",
         ),
+    // github's workflow name: several workflows run on one push there, and one passing says nothing of another. Absent on
+    // gitlab, where a commit's pipeline is the project's one.
+    workflow: z.string().optional().describe("Which workflow it is a run of, where a push starts several. Absent where a commit has one pipeline."),
     branch: z.string().describe("Which branch."),
     sha: z.string().describe("Which commit."),
     status: PipelineStatusSchema.describe(
@@ -108,10 +112,31 @@ export type CiRepo = z.infer<typeof CiRepoSchema>;
 // Fallback poll interval when a repo's webhook couldn't register; lives here since both the poller and the automation
 // editor need it to tell the owner what a `hookWarning` actually costs (minutes' delay, not the feature).
 export const CI_POLL_INTERVAL_MS = 2 * 60_000;
+// Main's CI while it is red, as the daemon's one fix agent on it sees it (ci/main-fixer.ts): from the first job that
+// failed until a later run of every workflow that failed on it passes, whatever else failed along the way.
+export const CiMainRedSchema = z.object({
+    repo: z.string().describe("Which workspace repository."),
+    branch: z.string().describe("Which main-line branch."),
+    since: z.number().describe("When its first job failed, in milliseconds."),
+    runId: z.number().describe("The newest run that failed on it."),
+    jobs: z.array(z.string()).describe("The jobs failing on it now, by name: the newest red run's failures, and any that failed since."),
+    fixer: z
+        .string()
+        .optional()
+        .describe("The one conversation working on it, which every failure goes to until the branch is green. Absent while nobody is on it."),
+    decision: RedDecisionSchema.optional().describe(
+        "The latest thing decided about it: `fix-up` while the fix agent has it, `spent` once it waits for you (its turns are used up, or it stopped without a fix), `reported` when repairs are off.",
+    ),
+});
+export type CiMainRed = z.infer<typeof CiMainRedSchema>;
 export const CiRunsResponseSchema = z.object({
     repos: z.array(CiRepoSchema).describe("Which workspace repositories are wired to a forge, and how each one's notifications are set up."),
     // Newest first, across all mapped repos.
     runs: z.array(PipelineRunSchema).describe("Runs across all of them, newest first."),
+    reds: z
+        .array(CiMainRedSchema)
+        .optional()
+        .describe("Every main-line branch red right now, with the fix agent on it. Absent from a daemon that keeps none."),
 });
 export type CiRunsResponse = z.infer<typeof CiRunsResponseSchema>;
 // Re-resolves repo → project + token on every call, so a stale card can't act on a mapping the workspace no longer has.