@intentic/sandbox-contract 1.250.0 → 1.252.0

package/dist/state/fix-stance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fix-stance.d.ts","sourceRoot":"","sources":["../../src/state/fix-stance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAYzD,MAAM,MAAM,aAAa,GAEnB,SAAS,GAET,WAAW,GAEX,OAAO,GAEP,QAAQ,GAER,SAAS,GAET,OAAO,CAAC;AAEd,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAE7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAgGD,eAAO,MAAM,SAAS,UAAW,YAAY,KAAG,SAQ/C,CAAC"}

package/dist/state/fix-stance.js

@@ -0,0 +1,79 @@
+const needsYou = (label, hint) => ({ kind: "needs-you", ongoing: true, retry: false, label, hint });
+const ATTENTION = [
+    { flag: "plan", label: "Approval needed", why: "it has proposed a plan and is waiting for a yes" },
+    { flag: "capability", label: "Setup needed", why: "it needs something connected that is not connected yet" },
+    { flag: "question", label: "Question for you", why: "it has asked you something" },
+    { flag: "permission", label: "Permission needed", why: "it wants to use a tool it needs permission for" },
+    { flag: "conflict", label: "Land conflict", why: "its work cannot be merged until somebody resolves a clash" },
+];
+const IN_FLIGHT = new Set(["running", "resuming", "stopping", "dismissing"]);
+const WORKING = {
+    kind: "working",
+    ongoing: true,
+    retry: false,
+    label: "Agent working",
+    hint: "An agent is already working on this failure. Open the conversation to watch it.",
+};
+const READY = {
+    kind: "ready",
+    ongoing: true,
+    retry: false,
+    label: "Fix ready",
+    hint: "The fix is written and held on the agent's branch. Open it to review the diff and land it.",
+};
+const LANDED = {
+    kind: "landed",
+    ongoing: false,
+    retry: false,
+    label: "Fix landed",
+    hint: "The fix is in your workspace. Running the check again is what proves it.",
+};
+const WAITING = {
+    kind: "waiting",
+    ongoing: true,
+    retry: false,
+    label: "Waiting",
+    hint: "The fix agent's allowance is spent. Nothing is owed: the turn goes again when the provider's window reopens.",
+};
+const holdingWork = (agent) => agent.status === "ready" || (agent.status === "idle" && agent.diff !== undefined && agent.diff.files > 0);
+const ENDINGS = {
+    error: { label: "Agent failed", why: "The fix agent's turn failed" },
+    interrupted: { label: "Interrupted", why: "The fix agent's turn was cut off when the sandbox went away" },
+    stopped: { label: "Stopped", why: "The fix agent was stopped before it finished" },
+    idle: { label: "Nothing changed", why: "The fix agent finished without changing any files" },
+};
+const ended = (agent) => {
+    const ending = ENDINGS[agent.status] ?? { label: "Agent stopped", why: "The fix agent's turn ended" };
+    const files = agent.diff?.files ?? 0;
+    const partial = files === 0 ? "" : ` It left ${files} changed file${files === 1 ? "" : "s"} on its branch.`;
+    return {
+        kind: "ended",
+        ongoing: false,
+        retry: true,
+        label: ending.label,
+        hint: `${ending.why}${agent.failure === undefined ? "" : `: ${agent.failure}`}.${partial} Continuing carries on in the same conversation; starting over opens a fresh one.`,
+    };
+};
+const RULES = [
+    (agent) => (agent.status === "error" && agent.failureCode === "rate_limit" ? WAITING : undefined),
+    (agent) => {
+        const parked = ATTENTION.find((entry) => agent.attention[entry.flag]);
+        return parked === undefined ? undefined : needsYou(parked.label, `The fix agent is waiting on you: ${parked.why}.`);
+    },
+    (agent) => agent.status === "awaiting" || agent.status === "conflict"
+        ? needsYou("Needs you", "The fix agent has stopped and is waiting on you.")
+        : undefined,
+    (agent) => (IN_FLIGHT.has(agent.status) ? WORKING : undefined),
+    (agent) => (holdingWork(agent) ? READY : undefined),
+    (agent) => (agent.status === "landed" ? LANDED : undefined),
+];
+export const fixStance = (agent) => {
+    for (const rule of RULES) {
+        const stance = rule(agent);
+        if (stance !== undefined) {
+            return stance;
+        }
+    }
+    return ended(agent);
+};
+//# sourceMappingURL=fix-stance.js.map

package/dist/state/fix-stance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fix-stance.js","sourceRoot":"","sources":["../../src/state/fix-stance.ts"],"names":[],"mappings":"AAqCA,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAE,IAAY,EAAa,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAG/H,MAAM,SAAS,GAAgH;IAC3H,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,iDAAiD,EAAE;IAClG,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,wDAAwD,EAAE;IAC5G,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,kBAAkB,EAAE,GAAG,EAAE,4BAA4B,EAAE;IAClF,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,mBAAmB,EAAE,GAAG,EAAE,gDAAgD,EAAE;IACzG,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,2DAA2D,EAAE;CACjH,CAAC;AAGF,MAAM,SAAS,GAAwC,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC;AAElH,MAAM,OAAO,GAAc;IACvB,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,eAAe;IACtB,IAAI,EAAE,iFAAiF;CAC1F,CAAC;AAEF,MAAM,KAAK,GAAc;IACrB,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,WAAW;IAClB,IAAI,EAAE,4FAA4F;CACrG,CAAC;AAEF,MAAM,MAAM,GAAc;IACtB,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,KAAK;IACd,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,YAAY;IACnB,IAAI,EAAE,0EAA0E;CACnF,CAAC;AAEF,MAAM,OAAO,GAAc;IACvB,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,8GAA8G;CACvH,CAAC;AAIF,MAAM,WAAW,GAAG,CAAC,KAAmB,EAAW,EAAE,CACjD,KAAK,CAAC,MAAM,KAAK,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AAI9G,MAAM,OAAO,GAA8F;IACvG,KAAK,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,6BAA6B,EAAE;IACpE,WAAW,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,6DAA6D,EAAE;IACzG,OAAO,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,8CAA8C,EAAE;IAClF,IAAI,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,mDAAmD,EAAE;CAC/F,CAAC;AAEF,MAAM,KAAK,GAAG,CAAC,KAAmB,EAAa,EAAE;IAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,4BAA4B,EAAE,CAAC;IAEtG,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,gBAAgB,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC;IAC5G,OAAO;QACH,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,MAAM,CAAC,KAAK;QAEnB,IAAI,EAAE,GAAG,MAAM,CAAC,GAAG,GAAG,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,IAAI,OAAO,mFAAmF;KAC9K,CAAC;AACN,CAAC,CAAC;AAKF,MAAM,KAAK,GAAgE;IACvE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,OAAO,IAAI,KAAK,CAAC,WAAW,KAAK,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACjG,CAAC,KAAK,EAAE,EAAE;QACN,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACtE,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,oCAAoC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC;IACxH,CAAC;IAED,CAAC,KAAK,EAAE,EAAE,CACN,KAAK,CAAC,MAAM,KAAK,UAAU,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU;QACtD,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,kDAAkD,CAAC;QAC3E,CAAC,CAAC,SAAS;IACnB,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9D,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACnD,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;CAC9D,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAmB,EAAa,EAAE;IACxD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,MAAM,CAAC;QAClB,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC;AACxB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/sandbox-contract",
-  "version": "1.250.0",
+  "version": "1.252.0",
   "description": "oRPC wire contract for the intentic sandbox daemon, shared by the daemon and its browser client",
   "license": "MIT",
   "type": "module",
@@ -185,9 +185,9 @@
     }
   },
   "dependencies": {
-    "@intentic/constants": "1.250.0",
-    "@intentic/extension-manifest": "1.250.0",
-    "@intentic/registry": "1.250.0",
+    "@intentic/constants": "1.252.0",
+    "@intentic/extension-manifest": "1.252.0",
+    "@intentic/registry": "1.252.0",
     "@orpc/contract": "1.14.13",
     "tslib": "2.8.1",
     "zod": "4.5.4"

package/src/ids/conversation-ids.test.ts

@@ -1,5 +1,16 @@
 import { afterEach, expect, test, vi } from "vitest";
-import { CI_FIX_PREFIX, ciFixConversationId, newConversationId, PUSH_FIX_PREFIX, pushFixConversationId } from "./conversation-ids.js";
+import {
+    CI_FIX_PREFIX,
+    ciFixConversationId,
+    fixAttemptId,
+    fixAttemptOf,
+    fixAttemptsOf,
+    latestFixAttempt,
+    newConversationId,
+    nextFixAttemptId,
+    PUSH_FIX_PREFIX,
+    pushFixConversationId,
+} from "./conversation-ids.js";
 import { ConversationIdSchema } from "../schemas/agent.js";
 
 const mockRandomValues = (values: readonly number[]) => {
@@ -101,3 +112,52 @@ test("every derived push fix id passes the conversation-id guard", () => {
         }
     }
 });
+
+// Attempt 1 is the bare derived id, so every fix conversation minted before attempts existed reads as attempt 1.
+test("the first attempt wears the failure's own id, later ones carry their number", () => {
+    const base = ciFixConversationId(`web`, 41);
+    expect(fixAttemptId(base, 1)).toBe(base);
+    expect(fixAttemptId(base, 2)).toBe(`ci-fix-web-41-attempt2`);
+    expect(fixAttemptOf(base, base)).toBe(1);
+    expect(fixAttemptOf(base, `ci-fix-web-41-attempt2`)).toBe(2);
+    expect(fixAttemptOf(base, `ci-fix-web-41-attempt12`)).toBe(12);
+});
+
+// Read base-relative on purpose: a base ends in a run id, so a neighbouring failure's id can start with this one.
+test("another failure's id is not an attempt at this one", () => {
+    const base = ciFixConversationId(`web`, 41);
+    // Repo `web-41`, run 2: starts with the base and a dash, and is nobody's attempt.
+    expect(fixAttemptOf(base, ciFixConversationId(`web-41`, 2))).toBeUndefined();
+    expect(fixAttemptOf(base, ciFixConversationId(`web`, 412))).toBeUndefined();
+    expect(fixAttemptOf(base, `swift-otter-k9m2`)).toBeUndefined();
+    // One spelling per attempt.
+    expect(fixAttemptOf(base, `ci-fix-web-41-attempt1`)).toBeUndefined();
+    expect(fixAttemptOf(base, `ci-fix-web-41-attempt02`)).toBeUndefined();
+    expect(fixAttemptOf(base, `ci-fix-web-41-attempt`)).toBeUndefined();
+});
+
+test("attempts are read off the roster, earliest first, and the newest is the live answer", () => {
+    const base = pushFixConversationId(`intentic`, `lint`);
+    const roster = [{ id: `swift-otter-k9m2` }, { id: fixAttemptId(base, 3) }, { id: base }, { id: pushFixConversationId(`intentic`, `typecheck`) }];
+    expect(fixAttemptsOf(base, roster).map((entry) => entry.attempt)).toEqual([1, 3]);
+    expect(latestFixAttempt(base, roster)?.agent.id).toBe(fixAttemptId(base, 3));
+    expect(latestFixAttempt(base, [])).toBeUndefined();
+});
+
+// The archive counts: a start-over files the last attempt away, and re-minting its number would un-archive it.
+test("the next attempt is numbered past every known one, archived included", () => {
+    const base = ciFixConversationId(`web`, 41);
+    expect(nextFixAttemptId(base, [])).toBe(base);
+    expect(nextFixAttemptId(base, [base])).toBe(`ci-fix-web-41-attempt2`);
+    expect(nextFixAttemptId(base, [`ci-fix-web-41-attempt3`, `swift-otter-k9m2`])).toBe(`ci-fix-web-41-attempt4`);
+    expect(nextFixAttemptId(base, [ciFixConversationId(`web-41`, 2)])).toBe(base);
+});
+
+test("an attempt id passes the guard and fits, even for the widest run id a forge mints", () => {
+    const widest = ciFixConversationId(`a-repository-name-of-thirty-two-chars-or-more`, 99_999_999_999);
+    for (const attempt of [1, 2, 99]) {
+        const id = fixAttemptId(widest, attempt);
+        expect(ConversationIdSchema.safeParse(id).success).toBe(true);
+        expect(id.length).toBeLessThanOrEqual(64);
+    }
+});

package/src/ids/conversation-ids.ts

@@ -149,7 +149,8 @@ export const newConversationId = (): string => `${pick(ADJECTIVES)}-${pick(NOUNS
 // Derived, not drawn, so a re-computed id says whether an agent is already on this failure and a second press continues
 // it. The repo is included (one run id per project) and slugified, not hashed, since people read it.
 export const CI_FIX_PREFIX = "ci-fix-";
-// Leaves ~24 characters for the run id within the 64-char id limit, twice the widest either forge mints.
+// Leaves ~24 characters for the run id and an attempt suffix within the 64-char id limit; the widest run id either
+// forge mints is eleven digits.
 const REPO_SLUG_MAX = 32;
 const repoSlug = (repo: string): string =>
     repo
@@ -176,3 +177,59 @@ const digest = (text: string): string => {
 };
 
 export const pushFixConversationId = (scope: string, signature: string): string => `${PUSH_FIX_PREFIX}${repoSlug(scope)}-${digest(signature)}`;
+
+// ONE FAILURE, MANY ATTEMPTS, ONE LIVE ANSWER. The derived id above names the FAILURE; an attempt at it is a
+// conversation of its own, so starting over (another model, a clean worktree) never rewrites a record some other window
+// is showing, and every attempt keeps its own transcript, cost and URL. Attempt 1 wears the bare id, so every id minted
+// before attempts existed is attempt 1 of its failure.
+const ATTEMPT_MARK = "-attempt";
+
+export const fixAttemptId = (base: string, attempt: number): string => (attempt <= 1 ? base : `${base}${ATTEMPT_MARK}${attempt}`);
+
+// Which attempt at `base` this id is, or undefined for an id that is none of them. Read base-relative, never the other
+// way round: a base ends in a run id or a digest, so nothing about an id on its own says where an attempt marker would
+// begin, and `ci-fix-web-41-2` is repo `web-41`'s run 2, not a second go at run 41.
+export const fixAttemptOf = (base: string, id: string): number | undefined => {
+    if (id === base) {
+        return 1;
+    }
+    if (!id.startsWith(`${base}${ATTEMPT_MARK}`)) {
+        return undefined;
+    }
+    const rest = id.slice(base.length + ATTEMPT_MARK.length);
+    // One spelling per attempt: the first is the bare id, so `-attempt1` and a zero-padded number are nobody's.
+    return /^[2-9]\d*$|^[1-9]\d+$/.test(rest) ? Number(rest) : undefined;
+};
+
+export interface FixAttempt<T extends { readonly id: string }> {
+    readonly attempt: number;
+    readonly agent: T;
+}
+
+// Every attempt at `base` among `agents`, earliest first. The roster is the record: nothing else files which
+// conversations answered a failure, and none is needed, since the ids say so.
+export const fixAttemptsOf = <T extends { readonly id: string }>(base: string, agents: Iterable<T>): FixAttempt<T>[] => {
+    const attempts: FixAttempt<T>[] = [];
+    for (const agent of agents) {
+        const attempt = fixAttemptOf(base, agent.id);
+        if (attempt !== undefined) {
+            attempts.push({ attempt, agent });
+        }
+    }
+    return attempts.toSorted((left, right) => left.attempt - right.attempt);
+};
+
+// The failure's live answer: its newest attempt, since an older one was set aside by the very act of starting a newer.
+export const latestFixAttempt = <T extends { readonly id: string }>(base: string, agents: Iterable<T>): FixAttempt<T> | undefined =>
+    fixAttemptsOf(base, agents).at(-1);
+
+// The id the next attempt takes: one past every attempt KNOWN, archived ones included. A start-over files the last
+// attempt away rather than deleting it, and a message to an archived conversation un-archives it, so minting a number
+// the archive holds would quietly resurrect the attempt the reader just set aside.
+export const nextFixAttemptId = (base: string, knownIds: Iterable<string>): string => {
+    let highest = 0;
+    for (const id of knownIds) {
+        highest = Math.max(highest, fixAttemptOf(base, id) ?? 0);
+    }
+    return fixAttemptId(base, highest + 1);
+};

package/src/index.ts

@@ -100,6 +100,8 @@ export * from "./state/workspace-state.js";
 export * from "./state/runtime-state.js";
 export * from "./state/state-portability.js";
 export * from "./state/history-state.js";
+export * from "./state/fix-stance.js";
+export * from "./state/fix-attempt-plan.js";
 // Provider vocabulary bottom-up: agent-runtimes, provider-specs, agent-catalog; three modules since the dependency
 // points one way.
 export * from "./models/agent-runtimes.js";

package/src/schemas/ci.ts

@@ -130,6 +130,14 @@ export const CiFixParamSchema = CiRunParamSchema.extend({
     pick: AgentRunPickSchema.describe(
         "Which model to open the conversation on, when somebody chose one. Leave it out for the sandbox's own choice, which is the ordinary path.",
     ),
+    // The verb the picker's bar was ended with, when an attempt already exists (state/fix-attempt-plan.ts). Left out,
+    // an ended attempt is continued and a fresh press opens attempt 1; one still in play answers CONFLICT.
+    mode: z
+        .enum(["continue", "start-over"])
+        .optional()
+        .describe(
+            "What to do about the attempt already made at this run, when there is one. `continue` carries on in that conversation; `start-over` stops it if running, files it away, and opens the next attempt on a clean worktree. Leave it out for the plain press: an attempt that ended is continued, a fresh failure gets attempt 1, and one still in play answers CONFLICT with why.",
+        ),
     force: z
         .boolean()
         .optional()

package/src/schemas/devices.ts

@@ -114,17 +114,44 @@ export type DeviceAgentFlowInput = z.infer<typeof DeviceAgentFlowInputSchema>;
 // command: the same socket carries `run_command`, which would grant a shell on the user's machine.
 // `sync-unpair` runs the machine's own `sync uninstall --sandbox` (terminates both Mutagen sessions, drops the pairing,
 // self-revokes enrollment); revoking from the sandbox side is a different route.
-export const DeviceCommandSchema = z.enum(["mirror-off", "mirror-on", "sync-pause", "sync-resume", "sync-unpair"]);
+// `dev-reload` and `sync-install` are the two whose argv the daemon fills from what only it knows — the dev checkout on
+// that machine, a freshly minted pairing token — which is also why neither takes a path or a token from the caller.
+export const DeviceCommandSchema = z.enum([
+    "mirror-off",
+    "mirror-on",
+    "sync-pause",
+    "sync-resume",
+    "sync-unpair",
+    "dev-reload",
+    "sync-install",
+]);
 export type DeviceCommand = z.infer<typeof DeviceCommandSchema>;
+// The reversible sync switches: the subset a device's own row drives with a pair of buttons, as opposed to the two
+// commands a card elsewhere issues once. Its own type so those button tables stay total without carrying entries for
+// commands they can never send.
+export const DeviceSyncSwitchSchema = DeviceCommandSchema.exclude(["dev-reload", "sync-install"]);
+export type DeviceSyncSwitch = z.infer<typeof DeviceSyncSwitchSchema>;
 // Machine's sandbox id (absent = every paired sandbox); must start alphanumeric, else it parses as a CLI flag.
 export const DeviceSandboxIdSchema = z
     .string()
     .max(200)
     .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+// A folder on the DEVICE for `sync-install` to keep in step. The only caller-supplied string that reaches a command
+// line, so its shape is the guard: `~`, an absolute POSIX path or a drive letter, and none of the characters that would
+// end the argument it sits in. `~` is expanded by the daemon, which is why `$` is not allowed to arrive here.
+export const DeviceLocalDirSchema = z
+    .string()
+    .min(1)
+    .max(4096)
+    .regex(/^(?:~|\/|[A-Za-z]:[\\/])[^"'`$;|&\n\r]*$/);
 export const DeviceCommandInputSchema = z.object({
     id: z.string().min(1),
     command: DeviceCommandSchema,
     sandboxId: DeviceSandboxIdSchema.optional(),
+    // `sync-install` only: which half to enroll (a member's "sync" still comes back mirror, decided daemon-side) and,
+    // for file sync, the folder on that device. The pairing token is minted by the daemon; no caller ever carries one.
+    mode: z.enum(["sync", "mirror"]).optional(),
+    localDir: DeviceLocalDirSchema.optional(),
 });
 export type DeviceCommandInput = z.infer<typeof DeviceCommandInputSchema>;
 // `ok` is the command's own exit status, not this route's: a refusal or non-zero exit is a real answer, not a thrown
@@ -286,6 +313,16 @@ export const DeviceSchema = z.object({
 });
 export type Device = z.infer<typeof DeviceSchema>;
 export const DevicesListSchema = z.object({ devices: z.array(DeviceSchema) });
+
+// The connected, online device whose docker reports a given sandbox slug: the machine that sandbox RUNS ON, as opposed
+// to any machine merely paired with it. Answers the question every "run it there instead of asking the owner to type
+// it" path starts from, and is `undefined` for a sync-only agent, which reports no containers at all.
+export const hostRunningSandbox = (devices: readonly Device[], slug: string | undefined): string | undefined =>
+    slug === undefined || slug === ""
+        ? undefined
+        : devices.find(
+              (device) => device.hostId !== undefined && device.online === true && (device.report?.sandboxes ?? []).some((box) => box.slug === slug),
+          )?.hostId;
 // GET /system/sync: sandbox-level facts only, whether sync is possible, whether anything is enrolled, and raw device
 // reports. Cheap: the sidebar badge reads this and must never fan out to a device.
 export const SyncStatusSchema = z.object({

package/src/state/fix-attempt-plan.test.ts

@@ -0,0 +1,64 @@
+import { expect, test } from "vitest";
+import { ciFixConversationId, fixAttemptId } from "../ids/conversation-ids.js";
+import type { AgentSummary } from "../schemas/agents.js";
+import { planFixAttempt } from "./fix-attempt-plan.js";
+
+const NO_ATTENTION = { plan: false, question: false, permission: false, capability: false, credential: false, conflict: false };
+const BASE = ciFixConversationId(`web`, 41);
+
+const agent = (id: string, over: Partial<AgentSummary> = {}): AgentSummary => ({
+    id,
+    status: `running`,
+    provider: `claude`,
+    harness: `native`,
+    attention: { ...NO_ATTENTION },
+    updatedAt: 1_000,
+    ...over,
+});
+
+test("with nobody on the failure, a press opens attempt 1 under the failure's own id", () => {
+    expect(planFixAttempt(BASE, [], [])).toEqual({ kind: `new`, conversationId: BASE, attempt: 1 });
+});
+
+// The archive counts: attempt 1 was set aside earlier, and re-minting its id would un-archive it.
+test("an archived attempt is skipped over, not resurrected", () => {
+    expect(planFixAttempt(BASE, [], [BASE])).toEqual({ kind: `new`, conversationId: fixAttemptId(BASE, 2), attempt: 2 });
+});
+
+test("a landed attempt is closed: the same gates red again get a fresh attempt", () => {
+    const plan = planFixAttempt(BASE, [agent(BASE, { status: `landed` })], []);
+    expect(plan).toEqual({ kind: `new`, conversationId: fixAttemptId(BASE, 2), attempt: 2 });
+});
+
+test("an attempt that ended is continued by a plain press, and by an explicit Continue", () => {
+    const roster = [agent(BASE, { status: `error`, failure: `no capacity` })];
+    expect(planFixAttempt(BASE, roster, [])).toEqual({ kind: `continue`, conversationId: BASE, attempt: 1 });
+    expect(planFixAttempt(BASE, roster, [], `continue`)).toEqual({ kind: `continue`, conversationId: BASE, attempt: 1 });
+});
+
+test("start over retires the latest attempt and numbers the next past it", () => {
+    const second = fixAttemptId(BASE, 2);
+    const plan = planFixAttempt(BASE, [agent(BASE, { status: `stopped` }), agent(second, { status: `error` })], [], `start-over`);
+    expect(plan).toEqual({ kind: `start-over`, retire: second, stopFirst: false, conversationId: fixAttemptId(BASE, 3), attempt: 3 });
+});
+
+// Only a running turn needs stopping before the archive will take it; a parked one is already still.
+test("starting over on a working attempt stops it first", () => {
+    const plan = planFixAttempt(BASE, [agent(BASE, { status: `running` })], [], `start-over`);
+    expect(plan).toMatchObject({ kind: `start-over`, retire: BASE, stopFirst: true });
+    const parked = planFixAttempt(BASE, [agent(BASE, { status: `awaiting`, attention: { ...NO_ATTENTION, question: true } })], [], `start-over`);
+    expect(parked).toMatchObject({ kind: `start-over`, stopFirst: false });
+});
+
+// A second agent beside a live one is the race the derived id exists to prevent; the press opens the live one instead.
+test.each([`running`, `awaiting`, `ready`] as const)("an attempt still in play (%s) is busy, not a fresh press", (status) => {
+    const plan = planFixAttempt(BASE, [agent(BASE, { status })], []);
+    expect(plan).toMatchObject({ kind: `busy`, conversationId: BASE });
+    // Continue is not a way around it either.
+    expect(planFixAttempt(BASE, [agent(BASE, { status })], [], `continue`).kind).toBe(`busy`);
+});
+
+test("a spent allowance is a wait, not an ending: the press does not spend it again", () => {
+    const plan = planFixAttempt(BASE, [agent(BASE, { status: `error`, failureCode: `rate_limit` })], []);
+    expect(plan.kind).toBe(`busy`);
+});

package/src/state/fix-attempt-plan.ts

@@ -0,0 +1,54 @@
+import { fixAttemptOf, latestFixAttempt, nextFixAttemptId } from "../ids/conversation-ids.js";
+import type { AgentSummary } from "../schemas/agents.js";
+import { type FixStance, fixStance } from "./fix-stance.js";
+
+/* WHAT A PRESS ON A FAILURE'S FIX CONTROL DOES, decided once for every surface that has one — the push question in
+ * the shell, the pipelines board's rows, the daemon's own /ci/fix route — so the browser and the daemon cannot
+ * disagree about whether a press continues an attempt, opens the next one, or has to wait. Pure: the roster in, a
+ * plan out. Carrying the plan out (stopping, archiving, starting) is the caller's, since each side does that
+ * through its own doors.
+ *
+ * THE RULE, in the order it is read: nothing live (or the last answer landed) opens the NEXT attempt; "start over"
+ * sets the latest aside and opens the next; an attempt that ENDED is continued; anything else is still in play and
+ * the reader is sent to it rather than allowed to race a second agent beside it. */
+
+// How the reader ended the picker, when they did; absent is the plain press on the button.
+export type FixResume = "continue" | "start-over";
+
+export type FixAttemptPlan =
+    // Nothing live answers this failure, or the last answer landed: open the next attempt with the full prompt.
+    | { readonly kind: "new"; readonly conversationId: string; readonly attempt: number }
+    // The latest attempt ended without a fix: carry on in it, with a nudge rather than the whole opening prompt.
+    | { readonly kind: "continue"; readonly conversationId: string; readonly attempt: number }
+    // Set the latest attempt aside (stopped first if still running) and open the next one on a clean worktree.
+    | {
+          readonly kind: "start-over";
+          readonly retire: string;
+          readonly stopFirst: boolean;
+          readonly conversationId: string;
+          readonly attempt: number;
+      }
+    // The latest attempt is still in play: working, parked on the reader, or holding a fix to review. Open it instead.
+    | { readonly kind: "busy"; readonly conversationId: string; readonly stance: FixStance };
+
+// `roster` is the live fleet; `knownIds` is every conversation id that exists, archived ones included, since the next
+// attempt's number must clear the archive too (conversation-ids.ts, nextFixAttemptId).
+export const planFixAttempt = (base: string, roster: readonly AgentSummary[], knownIds: Iterable<string>, resume?: FixResume): FixAttemptPlan => {
+    const latest = latestFixAttempt(base, roster);
+    const stance = latest === undefined ? undefined : fixStance(latest.agent);
+    const known = [...knownIds, ...(latest === undefined ? [] : [latest.agent.id])];
+    const next = (): { conversationId: string; attempt: number } => {
+        const conversationId = nextFixAttemptId(base, known);
+        return { conversationId, attempt: fixAttemptOf(base, conversationId) ?? 1 };
+    };
+    if (latest === undefined || stance === undefined || stance.kind === "landed") {
+        return { kind: "new", ...next() };
+    }
+    if (resume === "start-over") {
+        return { kind: "start-over", retire: latest.agent.id, stopFirst: stance.kind === "working", ...next() };
+    }
+    if (stance.retry) {
+        return { kind: "continue", conversationId: latest.agent.id, attempt: latest.attempt };
+    }
+    return { kind: "busy", conversationId: latest.agent.id, stance };
+};

package/src/state/fix-stance.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from "vitest";
+import { fixStance } from "./fix-stance.js";
+import type { AgentSummary } from "../schemas/agents.js";
+
+const NO_ATTENTION = { plan: false, question: false, permission: false, capability: false, credential: false, conflict: false };
+
+const agent = (over: Partial<AgentSummary> = {}): AgentSummary => ({
+    id: `ci-fix-web-42`,
+    status: `running`,
+    provider: `claude`,
+    harness: `native`,
+    attention: { ...NO_ATTENTION },
+    updatedAt: 1_000,
+    ...over,
+});
+
+test("a live turn reads as work in progress, and asks nothing of the reader", () => {
+    const stance = fixStance(agent({ status: `running` }));
+    expect(stance.kind).toBe(`working`);
+    expect(stance.ongoing).toBe(true);
+    expect(stance.retry).toBe(false);
+});
+
+test.each([`resuming`, `stopping`, `dismissing`] as const)("%s still reads as working", (status) => {
+    expect(fixStance(agent({ status })).kind).toBe(`working`);
+});
+
+test("a parked turn is read off the attention flag, not the status", () => {
+    const stance = fixStance(agent({ status: `idle`, attention: { ...NO_ATTENTION, question: true } }));
+    expect(stance.kind).toBe(`needs-you`);
+    expect(stance.label).toBe(`Question for you`);
+    expect(stance.ongoing).toBe(true);
+});
+
+test("a setup that is not connected yet outranks a question raised beside it", () => {
+    const stance = fixStance(agent({ status: `awaiting`, attention: { ...NO_ATTENTION, question: true, capability: true } }));
+    expect(stance.label).toBe(`Setup needed`);
+});
+
+test("a turn parked with no flag yet still says it is waiting on you", () => {
+    expect(fixStance(agent({ status: `awaiting` })).kind).toBe(`needs-you`);
+});
+
+test("held work reads as a fix to review, whether the fleet called it ready or left it idle", () => {
+    expect(fixStance(agent({ status: `ready` })).kind).toBe(`ready`);
+    expect(fixStance(agent({ status: `idle`, diff: { files: 4, insertions: 120, deletions: 8 } })).kind).toBe(`ready`);
+});
+
+// Diff present doesn't change a failed status to ready; it only earns a mention in the hint.
+test("an agent that failed after writing files still reads as failed", () => {
+    const stance = fixStance(agent({ status: `error`, diff: { files: 2, insertions: 34, deletions: 6 } }));
+    expect(stance.kind).toBe(`ended`);
+    expect(stance.retry).toBe(true);
+    expect(stance.hint).toContain(`2 changed files on its branch`);
+});
+
+test("a finished turn that changed nothing offers to try again", () => {
+    const stance = fixStance(agent({ status: `idle` }));
+    expect(stance.kind).toBe(`ended`);
+    expect(stance.label).toBe(`Nothing changed`);
+    expect(stance.retry).toBe(true);
+    expect(stance.ongoing).toBe(false);
+});
+
+test("a landed fix is over, and stops holding the branch's other rows back", () => {
+    const stance = fixStance(agent({ status: `landed`, diff: { files: 2, insertions: 10, deletions: 1 } }));
+    expect(stance.kind).toBe(`landed`);
+    expect(stance.ongoing).toBe(false);
+    expect(stance.retry).toBe(false);
+});
+
+test("a failed turn carries the provider's own sentence into the hint", () => {
+    const stance = fixStance(agent({ status: `error`, failure: `the model endpoint refused the request` }));
+    expect(stance.kind).toBe(`ended`);
+    expect(stance.retry).toBe(true);
+    expect(stance.hint).toContain(`the model endpoint refused the request`);
+});
+
+// Retry is false because retrying would spend the same already-refused allowance.
+test("a spent allowance reads as a wait rather than an error", () => {
+    const stance = fixStance(agent({ status: `error`, failureCode: `rate_limit`, failure: `usage limit reached` }));
+    expect(stance.kind).toBe(`waiting`);
+    expect(stance.retry).toBe(false);
+    expect(stance.ongoing).toBe(true);
+});
+
+test("a stopped turn says so, and offers the press again", () => {
+    const stance = fixStance(agent({ status: `stopped` }));
+    expect(stance.label).toBe(`Stopped`);
+    expect(stance.retry).toBe(true);
+});
+
+// An unknown status can arrive from a newer daemon; the stance must still read rather than crash on a missing ending.
+test("an unknown ending still produces a stance", () => {
+    const stance = fixStance(agent({ status: `teleported` as AgentSummary["status"] }));
+    expect(stance.kind).toBe(`ended`);
+    expect(stance.label).toBe(`Agent stopped`);
+    expect(stance.retry).toBe(true);
+});