@intentic/sandbox-contract 1.317.0 → 1.319.0

package/src/events/sandbox-notice.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+
+// The sandbox's own notice rows (a land, a hold, a renewal, a stop), as a code and the facts they were worded from. The
+// row's `text` stays the English sentence, which older apps, stored transcripts and agents reading their own history
+// go on reading; `noticeCode` beside it is what lets an app say the same thing in the reader's language and words.
+
+// On the wire a code is any string and its facts a flat record: a transcript page carrying a code newer than its reader
+// still parses, and that reader draws `text`. The codes this build writes, with their facts typed, are
+// SandboxNoticeSchema below.
+export const NoticeCodeSchema = z.object({
+    code: z.string().describe("Which of the sandbox's notices this row is, by name. A reader that does not know the name shows the row's text."),
+    params: z
+        .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+        .optional()
+        .describe("The facts the notice was worded from, by name: counts, names, and the provider's own sentence where the notice quotes one."),
+});
+export type NoticeCode = z.infer<typeof NoticeCodeSchema>;
+
+const count = z.number().int().nonnegative();
+
+// A failure's own sentence, which the notice's clause follows: the provider's words, or the sandbox's under `error`, its
+// failure code, for a reader that words a failure it knows itself.
+const failure = {
+    message: z.string(),
+    error: z.string().optional(),
+};
+
+// The re-runs a resumed turn's row can name (events/resume.ts); a reason a reader does not know draws the row's text.
+const ResumeNoticeReasonSchema = z.enum(["auth", "outage", "restart", "stopped", "limit", "switched", "carried", "refused", "door", "overflow"]);
+export type ResumeNoticeReason = z.infer<typeof ResumeNoticeReasonSchema>;
+
+// Every code this build writes, one per sentence shape, each with the facts that shape needs.
+export const SandboxNoticeSchema = z.discriminatedUnion("code", [
+    z.object({ code: z.literal("compacted") }),
+    z.object({ code: z.literal("stopped") }),
+    // The branch was rebased onto `commits` new commits, and/or could not be in the repos named in `blocked`.
+    z.object({ code: z.literal("synced"), params: z.object({ commits: count, blocked: z.string().optional() }) }),
+    z.object({ code: z.literal("intoParent") }),
+    z.object({ code: z.literal("intoParentClash"), params: z.object({ files: count }) }),
+    z.object({ code: z.literal("landHeld") }),
+    z.object({ code: z.literal("landConflict"), params: z.object({ files: count, repos: z.string() }) }),
+    // `deps` dependencies the turn added or changed, installing now, or `queued` behind any other install.
+    z.object({ code: z.literal("landed"), params: z.object({ deps: count.optional(), queued: z.boolean().optional() }).optional() }),
+    z.object({ code: z.literal("retrying"), params: z.object({ ...failure, attempt: count, of: count }) }),
+    z.object({ code: z.literal("retried"), params: z.object({ ...failure, made: count, of: count }) }),
+    z.object({ code: z.literal("outageWaiting"), params: z.object(failure) }),
+    z.object({ code: z.literal("renewing"), params: z.object(failure) }),
+    z.object({ code: z.literal("renewalWithdrawn"), params: z.object(failure) }),
+    z.object({ code: z.literal("reconnect"), params: z.object(failure) }),
+    z.object({ code: z.literal("undelivered"), params: z.object({ ...failure, unattended: z.boolean().optional() }) }),
+    // A turn the sandbox kept whole, its message above; `memory` when a memory hold kept it.
+    z.object({ code: z.literal("kept"), params: z.object({ ...failure, memory: z.boolean().optional() }) }),
+    z.object({ code: z.literal("memoryHeld"), params: z.object(failure) }),
+    // A failure the sandbox names by code and adds nothing to.
+    z.object({ code: z.literal("failed"), params: z.object(failure) }),
+    z.object({ code: z.literal("questionDismissed") }),
+    z.object({ code: z.literal("planApproved") }),
+    z.object({ code: z.literal("keptPlanning") }),
+    // `note` is the agent's own words; `every` the interval, already worded ("5m").
+    z.object({ code: z.literal("watching"), params: z.object({ note: z.string(), every: z.string() }) }),
+    z.object({ code: z.literal("restartInterrupted") }),
+    // A turn that picked up a conversation the sandbox kept warm: `tokens` read from the cache ("305k"), or for
+    // keptCold sent again, after `span` ("2h 5m") and `refreshes` refreshes.
+    z.object({ code: z.literal("keptWarm"), params: z.object({ tokens: z.string(), span: z.string(), refreshes: count }) }),
+    z.object({ code: z.literal("keptCold"), params: z.object({ tokens: z.string(), span: z.string(), refreshes: count }) }),
+    // A turn sent thin for a small window ("16k"): what was left out, and whether the base instructions were swapped too.
+    z.object({ code: z.literal("contextTrim"), params: z.object({ window: z.string(), omitted: z.string().optional(), base: z.boolean() }) }),
+    z.object({ code: z.literal("resumed"), params: z.object({ reason: ResumeNoticeReasonSchema }) }),
+    // An agent's own dependency install starting: into its conversation's own copy (`ownCopy`) or the main tree; the
+    // workspace root (`root`) and up to three project folders named (`projects`, each with its slash, already joined),
+    // and how many `more` were not named.
+    z.object({
+        code: z.literal("installing"),
+        params: z.object({ ownCopy: z.boolean(), root: z.boolean().optional(), projects: z.string().optional(), more: count.optional() }),
+    }),
+]);
+export type SandboxNotice = z.infer<typeof SandboxNoticeSchema>;
+
+/** The wire form of one of this build's notices, facts nobody gave left off rather than sent as nothing. */
+export const noticeCode = (notice: SandboxNotice): NoticeCode => {
+    if (!("params" in notice) || notice.params === undefined) {
+        return { code: notice.code };
+    }
+    const params = Object.fromEntries(
+        Object.entries(notice.params).filter((entry): entry is [string, string | number | boolean] => entry[1] !== undefined),
+    );
+    return Object.keys(params).length === 0 ? { code: notice.code } : { code: notice.code, params };
+};
+
+/** One of this build's notices, read off a row; undefined for a row without one, or with a code or facts this build does not know. */
+export const sandboxNoticeOf = (row: { readonly noticeCode?: NoticeCode | undefined }): SandboxNotice | undefined =>
+    row.noticeCode === undefined ? undefined : SandboxNoticeSchema.safeParse(row.noticeCode).data;

package/src/events/system-events.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { AgentSummarySchema } from "../schemas/agents.js";
 import { AccountUsageSchema, ProviderRefusalSchema } from "../schemas/providers/plan-limits.js";
 import { MemberRoleSchema } from "../schemas/shared.js";
-import { SidecarStatusSchema, WorkspaceTreeDeltaSchema } from "../schemas/workspace/workspace-tree.js";
+import { WorkspaceTreeDeltaSchema } from "../schemas/workspace/workspace-tree.js";
 
 // Frames about the sandbox rather than a turn: liveness, boot progress, what moved (repos, refs, running processes,
 // presence, the fleet), and account headroom. One stream carries them all.
@@ -53,6 +53,13 @@ export const HelloSchema = z.object({
     shapes: z.record(z.string(), z.string()).optional(),
     build: z.string().optional(),
     boot: BootProgressSchema.optional(),
+    // A project sandbox's folder, workspace-relative (`my-app` for /work/my-app): the owner's own folder, synced live
+    // with their computer, which the browser scopes the workspace to on arrival. Absent on every other sandbox.
+    projectDir: z.string().optional(),
+    // What answers: a sandbox's daemon, or the desktop app's sidecar serving a folder on the user's own computer
+    // (_devices/local-files), whose `routes` are the few a folder has rather than a daemon's missing ones. Absent reads
+    // as a sandbox, which every daemon before this field was.
+    surface: z.enum(["sandbox", "folder"]).optional(),
 });
 export type Hello = z.infer<typeof HelloSchema>;
 
@@ -66,10 +73,10 @@ export type ReposChanged = z.infer<typeof ReposChangedSchema>;
 export const WorkspaceChangedSchema = z.object({ kind: z.literal("workspaceChanged"), paths: z.array(z.string()) });
 export type WorkspaceChanged = z.infer<typeof WorkspaceChangedSchema>;
 
-// Files whose markdown shadow was just rewritten, plus where the background pass stands. Shadows live under the state
-// directory the watcher ignores on purpose — a sidecar write must never re-trigger the derivation that wrote it — so
-// `workspaceChanged` structurally cannot carry this, and without it a reader watching a file sees its text land never.
-export const DerivedChangedSchema = z.object({ kind: z.literal("derivedChanged"), paths: z.array(z.string()), queue: SidecarStatusSchema });
+// Files whose rendered text just landed. Renderings live under the state directory the watcher ignores on purpose — a
+// cache write must never read as a workspace change — so `workspaceChanged` structurally cannot carry this, and without
+// it a second reader watching the same file never sees its text land.
+export const DerivedChangedSchema = z.object({ kind: z.literal("derivedChanged"), paths: z.array(z.string()) });
 export type DerivedChanged = z.infer<typeof DerivedChangedSchema>;
 
 // Repos whose refs moved (commit, checkout, branch, rebase); a repo's git dir lives outside /work and the watcher

package/src/events/transcript.ts

@@ -5,6 +5,7 @@ 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 { NoticeCodeSchema } from "./sandbox-notice.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";
 
@@ -105,7 +106,7 @@ export const TranscriptSubagentSchema = z.object({
         .string()
         .optional()
         .describe(
-            "Its own id, where that is not the card's: a spawned subagent is named by its own conversation, which is what the roster, `wait` and its page call it. Absent, the card's id is its id, as it is for one the runtime started in-process.",
+            "Its own id, where that is not the card's: a spawned subagent is named by its own conversation, which is what the roster, `wait` and its own chat call it. Absent, the card's id is its id, as it is for one the runtime started in-process.",
         ),
     kind: SubagentKindSchema,
     agentType: z.string().optional(),
@@ -300,6 +301,11 @@ export const TranscriptRowSchema = z.object({
         .string()
         .optional()
         .describe("Which instance of the wait this notice names, for a kind that can have several running at once."),
+    // The sandbox's own notice by name, beside its English `text` (sandbox-notice.ts); absent on every other row, and
+    // on the notices written before rows carried it, which a reader draws from `text` as it always did.
+    noticeCode: NoticeCodeSchema.optional().describe(
+        "Which of the sandbox's own notices this row is, and the facts it was worded from, so a reader can say it in the reader's own language. The text stays the English sentence.",
+    ),
     // At most one card per row; a card closes its bubble. One field per kind, so a reader reaches it by name.
     plan: TranscriptPlanSchema.optional().describe("The plan this row asked approval for, and the answer."),
     question: TranscriptQuestionSchema.optional().describe("The questions this row asked, and the picks that answered them."),

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:
-// 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.
+// nothing checks inside a conversation, CI checks what the owner pushes (schemas/ci.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/front/generated/browser-wire.json

@@ -131,6 +131,101 @@
     },
     "upgrade": "websocket"
   },
+  "vitals": {
+    "body": {
+      "$defs": {
+        "NodeLink": {
+          "description": "Where the front's control link to Node stands.",
+          "oneOf": [
+            {
+              "const": "starting",
+              "description": "Node has not said hello since the container started.",
+              "type": "string"
+            },
+            {
+              "const": "up",
+              "description": "Node's control link is open and it said hello on it.",
+              "type": "string"
+            },
+            {
+              "const": "restarting",
+              "description": "Node was up or was restarted before, and is not up now: its link dropped, or its process exited and the front is\nstarting it again.",
+              "type": "string"
+            }
+          ]
+        },
+        "Pressure": {
+          "description": "The share of the last 10 seconds, as a percentage, in which some of the container's tasks stalled waiting for each\nresource: cgroup v2's `some avg10` from `cpu.pressure`, `memory.pressure` and `io.pressure`.",
+          "properties": {
+            "cpu": {
+              "format": "float",
+              "type": "number"
+            },
+            "io": {
+              "format": "float",
+              "type": "number"
+            },
+            "memory": {
+              "format": "float",
+              "type": "number"
+            }
+          },
+          "required": [
+            "cpu",
+            "memory",
+            "io"
+          ],
+          "type": "object"
+        }
+      },
+      "description": "The sandbox's proof of life, measured by the front and answered by it at [`VITALS_PATH`] whatever state Node is in:\nthe daemon's own heartbeat rides Node's event loop, so a sandbox busy enough to starve it would otherwise look dead.\nIt carries nothing of the workspace.",
+      "properties": {
+        "lagMs": {
+          "description": "How long Node's event loop takes to answer the front, in milliseconds: the round trip of the last ping it\nanswered, or how long the one outstanding has waited when that is longer. The front pings every 2 s, only once\nthe previous ping is answered. Null before the first ping, and while Node is not `up`.",
+          "format": "uint32",
+          "minimum": 0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "node": {
+          "$ref": "#/$defs/NodeLink"
+        },
+        "pressure": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Pressure"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The container's pressure stall; null where the cgroup's pressure files cannot be read."
+        },
+        "restarts": {
+          "description": "How many times the front restarted Node in the last 10 minutes.",
+          "format": "uint32",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "uptimeS": {
+          "description": "Seconds since the front, and so the container, started.",
+          "format": "uint32",
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "node",
+        "restarts",
+        "uptimeS"
+      ],
+      "title": "SandboxVitals",
+      "type": "object"
+    },
+    "path": "/system/vitals"
+  },
   "webTransport": {
     "alpn": "h3",
     "path": "/system/transport"

package/src/front/generated/browser-wire.ts

@@ -5,6 +5,42 @@
  */
 export type EdgeVerdict = "no-tunnel" | "unknown-sandbox" | "dropped";
 
+/**
+ * Where the front's control link to Node stands.
+ */
+export type NodeLink = "starting" | "up" | "restarting";
+
+/**
+ * The share of the last 10 seconds, as a percentage, in which some of the container's tasks stalled waiting for each
+ * resource: cgroup v2's `some avg10` from `cpu.pressure`, `memory.pressure` and `io.pressure`.
+ */
+export type Pressure = { cpu: number, memory: number, io: number, };
+
+/**
+ * The sandbox's proof of life, measured by the front and answered by it at [`VITALS_PATH`] whatever state Node is in:
+ * the daemon's own heartbeat rides Node's event loop, so a sandbox busy enough to starve it would otherwise look dead.
+ * It carries nothing of the workspace.
+ */
+export type SandboxVitals = { node: NodeLink, 
+/**
+ * How long Node's event loop takes to answer the front, in milliseconds: the round trip of the last ping it
+ * answered, or how long the one outstanding has waited when that is longer. The front pings every 2 s, only once
+ * the previous ping is answered. Null before the first ping, and while Node is not `up`.
+ */
+lagMs: number | null, 
+/**
+ * How many times the front restarted Node in the last 10 minutes.
+ */
+restarts: number, 
+/**
+ * Seconds since the front, and so the container, started.
+ */
+uptimeS: number, 
+/**
+ * The container's pressure stall; null where the cgroup's pressure files cannot be read.
+ */
+pressure: Pressure | null, };
+
 /**
  * What the browser sends on a terminal socket, each a JSON text message.
  */

package/src/front/generated/front-wire.json

@@ -50,6 +50,18 @@
               "plan"
             ],
             "type": "object"
+          },
+          {
+            "properties": {
+              "answer": {
+                "const": "pong",
+                "type": "string"
+              }
+            },
+            "required": [
+              "answer"
+            ],
+            "type": "object"
           }
         ]
       },
@@ -699,6 +711,19 @@
               "query"
             ],
             "type": "object"
+          },
+          {
+            "description": "Whether Node's event loop turns, and how fast: answered `pong` at once, by the link itself. The front sends one\nevery 2 s once the previous one is answered, and reports the round trip as the vitals' lag. An older Node answers\nwith a refusal, or with an answer the front cannot read, and either still counts as answered.",
+            "properties": {
+              "question": {
+                "const": "ping",
+                "type": "string"
+              }
+            },
+            "required": [
+              "question"
+            ],
+            "type": "object"
           }
         ]
       }

package/src/front/generated/wire.ts

@@ -4,7 +4,7 @@ export type Answer = { "answer": "preview", route: PreviewRoute, } | { "answer":
 /**
  * The member whose ticket opened it, lowercased; absent when the daemon runs without auth.
  */
-member?: string, };
+member?: string, } | { "answer": "pong" };
 
 /**
  * A PEM certificate chain and its PEM private key.
@@ -61,7 +61,7 @@ export type PreviewRoute = { "to": "upstream", upstream: Upstream, } | { "to": "
 /**
  * A question the front asks Node.
  */
-export type Question = { "question": "preview", host: string, probe: boolean, } | { "question": "terminal", query: string, };
+export type Question = { "question": "preview", host: string, probe: boolean, } | { "question": "terminal", query: string, } | { "question": "ping" };
 
 export type Scheme = "http" | "https";
 

package/src/front/wire-manifests.test.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { EDGE_VERDICT_HEADER, edgeVerdictOf } from "../protocol/edge-verdict.js";
 import { INGRESS_GRANT_HEADER, INGRESS_TUNNEL_PATH } from "../protocol/ingress-contract.js";
+import { VITALS_PATH } from "../protocol/vitals.js";
 import { EDGE_TRANSPORTS, TERMINAL_PATH, WEBTRANSPORT_PATH } from "./browser-wire.js";
 import { ASK_PATIENCE_MS, FRAME_LENGTH_BYTES, FRONT_SOCKET_ENV, NODE_SOCKET_ENV } from "./front-wire.js";
 
@@ -23,6 +24,7 @@ const socket = manifest("front-wire") as {
 const browser = manifest("browser-wire") as {
     edge: { verdictHeader: string; verdicts: { oneOf: { const: string }[] } };
     terminal: { path: string; upgrade: string };
+    vitals: { path: string; body: { $defs: { NodeLink: { oneOf: { const: string }[] } } } };
     webTransport: { path: string };
 };
 
@@ -58,4 +60,9 @@ describe("the wire outside oRPC, as the Rust crates define it", () => {
             upgrade: browser.terminal.upgrade,
         });
     });
+
+    it("finds the front's vitals where browser-wire says it answers them, in the states it names", () => {
+        expect(VITALS_PATH).toBe(browser.vitals.path);
+        expect(browser.vitals.body.$defs.NodeLink.oneOf.map((state) => state.const)).toEqual(["starting", "up", "restarting"]);
+    });
 });

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

@@ -7,8 +7,6 @@ import {
     latestFixAttempt,
     newConversationId,
     nextFixAttemptId,
-    PUSH_FIX_PREFIX,
-    pushFixConversationId,
 } from "./conversation-ids.js";
 import { ConversationIdSchema } from "../schemas/agent.js";
 
@@ -90,28 +88,6 @@ test("the prefix is carried by every fix id", () => {
     expect(ciFixConversationId(`ci-fix`, 7)).toBe(`ci-fix-ci-fix-7`);
 });
 
-test("a push fix id is the same string every time the same failure derives it", () => {
-    expect(pushFixConversationId(`intentic`, `checkout gates,lint`)).toBe(pushFixConversationId(`intentic`, `checkout gates,lint`));
-    expect(pushFixConversationId(`intentic`, `checkout gates,lint`)).toMatch(/^push-fix-intentic-[0-9a-z]{7}$/);
-});
-
-test("a push fix id separates failures and scopes", () => {
-    expect(pushFixConversationId(`intentic`, `lint`)).not.toBe(pushFixConversationId(`intentic`, `checkout gates`));
-    expect(pushFixConversationId(`web`, `lint`)).not.toBe(pushFixConversationId(`api`, `lint`));
-});
-
-// Signatures cover raw gate output: control characters, unicode, path-like strings, and pathological lengths.
-test("every derived push fix id passes the conversation-id guard", () => {
-    const signatures = [``, `checkout gates`, `✗ lint · pnpm lint`, `a`.repeat(4_000), `../../etc/passwd`, `a\nb\tc`, `résumé`];
-    for (const scope of [`root`, `apps/web`, `my repo`, `___`, `x`.repeat(80)]) {
-        for (const signature of signatures) {
-            const id = pushFixConversationId(scope, signature);
-            expect(ConversationIdSchema.safeParse(id).success).toBe(true);
-            expect(id.startsWith(PUSH_FIX_PREFIX)).toBe(true);
-        }
-    }
-});
-
 // 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);
@@ -136,8 +112,8 @@ test("another failure's id is not an attempt at this one", () => {
 });
 
 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`) }];
+    const base = ciFixConversationId(`intentic`, 7);
+    const roster = [{ id: `swift-otter-k9m2` }, { id: fixAttemptId(base, 3) }, { id: base }, { id: ciFixConversationId(`intentic`, 8) }];
     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();

package/src/ids/conversation-ids.ts

@@ -160,13 +160,9 @@ const repoSlug = (repo: string): string =>
         .replace(/^-+|-+$/g, "") || "repo";
 export const ciFixConversationId = (repo: string, runId: number): string => `${CI_FIX_PREFIX}${repoSlug(repo)}-${runId}`;
 
-// Keyed by when the project's push red began (pushFixBase, `red:<since>`), not a run id (a push has none): a refused push
-// is owed by that red too (push-checks-store.ts). Hashed rather than spelled into the branch name; the fix agent's first
-// message names what it is for.
-export const PUSH_FIX_PREFIX = "push-fix-";
-
 // FNV-1a, not a cryptographic hash: nothing here is secret, the only requirement is the same failure yields the same
-// seven characters in every browser and in node. The one spelling: a push finding's id (push-checks-store.ts) is this too.
+// seven characters in every browser and in node. The one spelling: what a failing main owes is named by it too (a
+// failed job's id, ci/main-fixer.ts).
 const FNV_OFFSET = 0x811c_9dc5;
 const FNV_PRIME = 0x0100_0193;
 export const fnvDigest = (text: string): string => {
@@ -177,14 +173,12 @@ export const fnvDigest = (text: string): string => {
     return (hash >>> 0).toString(36).padStart(7, "0");
 };
 
-export const pushFixConversationId = (scope: string, signature: string): string => `${PUSH_FIX_PREFIX}${repoSlug(scope)}-${fnvDigest(signature)}`;
-
-// A red main-line check that no conversation still holding the work could take: keyed by the project and the moment its
-// red streak began, so every attempt at one streak shares a base and a later streak in the same project starts over.
+// A failing main-line check that no conversation still holding the work could take: keyed by the project and the moment
+// it began failing, so every attempt at one streak shares a base and a later streak in the same project starts over.
 // Seconds in base36 keep it short; the workspace root is spelled `workspace`, since its project folder is empty.
 export const LAND_FIX_PREFIX = "land-fix-";
-export const landFixConversationId = (project: string, redSince: number): string =>
-    `${LAND_FIX_PREFIX}${repoSlug(project === "" ? "workspace" : project)}-${Math.floor(redSince / 1000).toString(36)}`;
+export const landFixConversationId = (project: string, failingSince: number): string =>
+    `${LAND_FIX_PREFIX}${repoSlug(project === "" ? "workspace" : project)}-${Math.floor(failingSince / 1000).toString(36)}`;
 
 // 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

package/src/ids/project-dir.fixture.json

@@ -0,0 +1,65 @@
+{
+    "names": [
+        { "name": "my-app", "valid": true },
+        { "name": "My_App.v2", "valid": true },
+        { "name": "a", "valid": true },
+        { "name": "0", "valid": true },
+        { "name": "Public", "valid": true },
+        { "name": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "valid": true },
+        { "name": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "valid": false },
+        { "name": "public", "valid": false },
+        { "name": "refs", "valid": false },
+        { "name": "site", "valid": false },
+        { "name": "root", "valid": false },
+        { "name": "intent", "valid": false },
+        { "name": "desired-state", "valid": false },
+        { "name": "app", "valid": false },
+        { "name": "AGENTS.md", "valid": false },
+        { "name": "node_modules", "valid": false },
+        { "name": "dist", "valid": false },
+        { "name": "venv", "valid": false },
+        { "name": "claude.json", "valid": false },
+        { "name": "__pycache__", "valid": false },
+        { "name": ".intentic", "valid": false },
+        { "name": ".hidden", "valid": false },
+        { "name": "-flag", "valid": false },
+        { "name": "_under", "valid": false },
+        { "name": "", "valid": false },
+        { "name": "a/b", "valid": false },
+        { "name": "..", "valid": false },
+        { "name": "has space", "valid": false },
+        { "name": "café", "valid": false },
+        { "name": "my-app/", "valid": false }
+    ],
+    "folders": [
+        { "folder": "my-app", "dirName": "my-app" },
+        { "folder": "My App", "dirName": "My-App" },
+        { "folder": "My  App!!", "dirName": "My-App" },
+        { "folder": "Café Menu", "dirName": "Cafe-Menu" },
+        { "folder": "日本語", "dirName": "project" },
+        { "folder": "", "dirName": "project" },
+        { "folder": "...", "dirName": "project" },
+        { "folder": ".config", "dirName": "config" },
+        { "folder": "--flag--", "dirName": "flag" },
+        { "folder": "_private", "dirName": "private" },
+        { "folder": "public", "dirName": "public-project" },
+        { "folder": "site", "dirName": "site-project" },
+        { "folder": "app", "dirName": "app-project" },
+        { "folder": "AGENTS.md", "dirName": "AGENTS.md-project" },
+        { "folder": "dist", "dirName": "dist-project" },
+        { "folder": "node_modules", "dirName": "node_modules-project" },
+        { "folder": "__pycache__", "dirName": "pycache__" },
+        { "folder": "a--b", "dirName": "a-b" },
+        { "folder": "report (final) v2", "dirName": "report-final-v2" },
+        {
+            "folder": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+            "dirName": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+        },
+        {
+            "folder": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa b",
+            "dirName": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        { "folder": "C++ Project", "dirName": "C-Project" },
+        { "folder": "release.2024.", "dirName": "release.2024" }
+    ]
+}

package/src/ids/project-dir.test.ts

@@ -0,0 +1,60 @@
+import { readFileSync } from "node:fs";
+import { MEMORY_FILE, PUBLIC_DIR, REFERENCE_DIR, WORKSPACE_ROOT } from "@intentic/constants";
+import { STARTER_REPO } from "../state/starter.js";
+import { isProjectDirName, projectDirNameFor, projectDirNameOf, projectRemoteDir, RESERVED_PROJECT_DIR_NAMES } from "./project-dir.js";
+
+// The cases `ic` is held to as well (_sandbox/ic/src/sandbox/project_dir.rs), read from the one file both run.
+interface ProjectDirCases {
+    readonly names: readonly { readonly name: string; readonly valid: boolean }[];
+    readonly folders: readonly { readonly folder: string; readonly dirName: string }[];
+}
+// SAFETY: the fixture is this repository's own file, written to this shape; one that drifted fails every case below.
+const CASES = JSON.parse(readFileSync(new URL("./project-dir.fixture.json", import.meta.url), "utf8")) as ProjectDirCases;
+
+test.each([...CASES.names])("the shared name case $name is valid: $valid", ({ name, valid }) => {
+    expect(isProjectDirName(name)).toBe(valid);
+});
+
+test.each([...CASES.folders])("the folder $folder syncs into $dirName", ({ folder, dirName }) => {
+    expect(projectDirNameFor(folder)).toBe(dirName);
+});
+
+test("every folder name the slug produces is one the validation accepts, and slugging it again changes nothing", () => {
+    for (const { folder } of CASES.folders) {
+        const name = projectDirNameFor(folder);
+        expect(isProjectDirName(name)).toBe(true);
+        expect(projectDirNameFor(name)).toBe(name);
+    }
+});
+
+test("the reserved names are the ones the daemon keeps at the workspace root", () => {
+    expect([...RESERVED_PROJECT_DIR_NAMES].toSorted()).toEqual(
+        [
+            PUBLIC_DIR,
+            REFERENCE_DIR,
+            STARTER_REPO,
+            MEMORY_FILE,
+            "root",
+            "intent",
+            "desired-state",
+            "app",
+            "node_modules",
+            "dist",
+            "venv",
+            "claude.json",
+        ].toSorted(),
+    );
+});
+
+test("a project dir is exactly one valid name under the workspace root", () => {
+    expect(projectRemoteDir("my-app")).toBe(`${WORKSPACE_ROOT}/my-app`);
+    expect(projectDirNameOf(`${WORKSPACE_ROOT}/my-app`)).toBe("my-app");
+    expect(projectDirNameOf(WORKSPACE_ROOT)).toBeUndefined();
+    expect(projectDirNameOf(`${WORKSPACE_ROOT}/`)).toBeUndefined();
+    expect(projectDirNameOf(`${WORKSPACE_ROOT}/my-app/`)).toBeUndefined();
+    expect(projectDirNameOf(`${WORKSPACE_ROOT}/my-app/src`)).toBeUndefined();
+    expect(projectDirNameOf(`${WORKSPACE_ROOT}/public`)).toBeUndefined();
+    expect(projectDirNameOf(`${WORKSPACE_ROOT}/../etc`)).toBeUndefined();
+    expect(projectDirNameOf("/workspace/my-app")).toBeUndefined();
+    expect(projectDirNameOf("/srv/work/my-app", "/srv/work")).toBe("my-app");
+});