@intentic/sandbox-contract 1.316.0 → 1.318.0

package/src/schemas/settings.ts

@@ -2,7 +2,7 @@
 // itself, which those settings adopt.
 import { STATE_DIR } from "@intentic/constants";
 import { z } from "zod";
-import { CommandJudgeModeSchema } from "../policy/safety-policy.js";
+import { CommandJudgeModeSchema, ProjectInstallModeSchema } from "../policy/safety-policy.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
 import { AdmissionPolicySchema, AdmissionRuleSchema, ModelPinSchema } from "./agent.js";
 import { LimitPolicySchema, RetryPolicySchema } from "./turn-break.js";
@@ -13,10 +13,15 @@ export const SystemPromptModeSchema = z.enum(["intentic", "claude", "custom"]);
 export type SystemPromptMode = z.infer<typeof SystemPromptModeSchema>;
 // Excludes "custom": there is nothing to fetch, it's whatever the owner already typed into the settings field.
 export const BuiltinPromptSchema = z.object({ base: z.enum(["intentic", "claude"]) });
+// Longest an owner's own system prompt may be, the sandbox's or a persona's; named so an editor can refuse a save the
+// daemon would refuse, rather than copy the number.
+export const SYSTEM_PROMPT_MAX = 20_000;
+// Longest the guidance the New chat routing job reads may be (`autoModelGuidance` below).
+export const AUTO_MODEL_GUIDANCE_MAX = 2000;
 // Rules: "at this moment, if this is true, do this". The owner's rules decide (land, hold, version); every command a
 // moment runs is a repository's own check (`<repo>/.intentic/checks.json`), compiled into this same table by the daemon,
-// so no command lives in settings. Nothing verifies inside a turn or after a land: CI checks what the owner pushes, and
-// nothing here holds anything (schemas/workspace/push-checks.ts).
+// so no command lives in settings. Nothing verifies inside a turn, after a land or on the way to a push: CI checks what
+// the owner pushes, and nothing here holds anything (schemas/ci.ts).
 export const RuleMomentSchema = z.enum([
     // A command here runs on the just-written file (`{file}` is its path); the cheapest moment to catch a defect.
     "file.edited",
@@ -50,7 +55,7 @@ export const RuleActionSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("builtin"), name: RuleBuiltinSchema }),
 ]);
 export type RuleAction = z.infer<typeof RuleActionSchema>;
-// `checks-failed` was a clean turn whose `turn.ending` check went red. Nothing produces it now that no check runs inside a
+// `checks-failed` was a clean turn whose `turn.ending` check failed. Nothing produces it now that no check runs inside a
 // turn, and a check never holds work; it stays so older rules naming it still read.
 export const RuleOutcomeSchema = z.enum(["clean", "error", "conflict", "checks-failed"]);
 export type RuleOutcome = z.infer<typeof RuleOutcomeSchema>;
@@ -226,6 +231,19 @@ export const KeepWarmSettingsSchema = z.object({
 });
 export type KeepWarmSettings = z.infer<typeof KeepWarmSettingsSchema>;
 
+// Who the editor's screens are written for: `developer` reads git's own words (branch, land, commit), `maker` plain ones
+// (draft, accept, save) over the same mechanisms. The editor's vocabulary, never anything an agent does. A person's own
+// answer, kept by the sandbox per member rather than in each browser, so the desktop app and a browser tab name one
+// button one way while two people on one sandbox can still read it in their own words.
+export const AudienceSchema = z.enum(["developer", "maker"]);
+export type Audience = z.infer<typeof AudienceSchema>;
+
+// The caller's own answer as the sandbox keeps it; absent until they have given one here.
+export const MemberAudienceSchema = z.object({
+    audience: AudienceSchema.optional().describe("developer for git's own words, maker for plain ones. Absent until this person has chosen here."),
+});
+export type MemberAudience = z.infer<typeof MemberAudienceSchema>;
+
 export const SandboxSettingsSchema = z.object({
     // The zone every WALL-CLOCK RULE in this sandbox is meant in — an automation's cron, and anything else that says
     // "at 09:00" instead of naming an instant. It is not a display preference: nothing formats through it, and an
@@ -276,7 +294,7 @@ export const SandboxSettingsSchema = z.object({
     // every turn pays for it.
     systemPrompt: z
         .string()
-        .max(20000)
+        .max(SYSTEM_PROMPT_MAX)
         .default("")
         .describe(
             "Your own instructions, used only when the mode above says custom. Then it is the whole of them: both built-in bases go, and so does everything this product would otherwise add, including the guidance the chat's own cards are driven by. That is the price of total control.",
@@ -385,7 +403,7 @@ export const SandboxSettingsSchema = z.object({
     // purpose: the reading runs under a 5s deadline, and this text is paid for on every chat that opens on Auto.
     autoModelGuidance: z
         .string()
-        .max(2000)
+        .max(AUTO_MODEL_GUIDANCE_MAX)
         .default("")
         .describe(
             "What you would tell somebody choosing the model for a new chat on your behalf: which model you want the cheap work on, which account to leave alone, when to reach for the strongest one. Read once per chat, alongside the models and allowances this sandbox can actually run, and it overrides the product's own advice where the two disagree. It cannot invent a model: the answer is still a choice from that list.",
@@ -436,14 +454,22 @@ export const SandboxSettingsSchema = z.object({
     ),
     // Worth it since the container is recreated on every update or environment approval — otherwise approving a
     // Dockerfile change costs the run that asked for it.
-    // What happens when main's CI goes red (ci/main-fixer.ts): its first failed job starts one fix agent, which is sent
-    // every later failure on main until main is green, within a few turns, and a failure on the CI fleet itself is re-run
+    // What happens when main's CI fails (ci/main-fixer.ts): its first failed job starts one fix agent, which is sent
+    // every later failure on main until main passes, within a few turns, and a failure on the CI fleet itself is re-run
     // once instead. Off, it is only reported.
     autoRepair: z
         .boolean()
         .default(true)
         .describe(
-            "Whether main's CI going red is repaired without asking. The first job that fails on main starts one fix agent, without waiting for the rest of the run, and every later failure on main goes to that same agent until a run passes. It gets a few turns; when they are spent, or it finishes without changing anything (a failure that is not in the code), the red waits for you. A failure on the CI fleet itself is re-run once instead. Off, all of it is only reported.",
+            "Whether main's CI failing is repaired without asking. The first job that fails on main starts one fix agent, without waiting for the rest of the run, and every later failure on main goes to that same agent until a run passes. It gets a few turns; when they are spent, or it finishes without changing anything (a failure that is not in the code), the failure waits for you. A failure on the CI fleet itself is re-run once instead. Off, all of it is only reported.",
+        ),
+    // What another writer pushes reaches the main tree within minutes instead of at the owner's next pull
+    // (git/remote/follow-origin.ts), so an agent whose work clashes with it meets the clash at its own land.
+    followOrigin: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Whether each workspace repo keeps up with the remote branch it tracks. Every couple of minutes it is fetched, and what arrived is brought into the main tree: a fast-forward when you have no commits of your own, else a merge commit. Only while it is quiet (no turn working in the main tree, no merge or rebase of yours open), and never half-way: a conflict, or an uncommitted file in the way, leaves the repo exactly as it was until the next try. Nothing is ever pushed. Off, nothing is fetched.",
         ),
     // Where heavy work runs: a runner (the same image, on one of the owner's machines) instead of this sandbox. Keyed by
     // the heavy-command rule an agent's command matched (system/resources/heavy-commands.ts), each naming a runner id. A
@@ -457,6 +483,14 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Which heavy work runs on a runner on one of your machines instead of this sandbox: agents' commands by the kind the heavy-command rules sort them into (tests, typechecks, verify…). The code travels as it stands, uncommitted work included; the output streams back, and any file the command changed comes back with it. A machine that is offline, outdated or busy hands the work back to this sandbox, and the output says so.",
         ),
+    // A person answering a need is exactly the moment they want the work to go on (docs/architecture/needs.md), unlike a
+    // restart nobody watched, so this one is on to begin with.
+    continueWhenNeedMet: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Whether a conversation carries on by itself once something it asked a person for arrives: a connection made, a secret given, access allowed, a tool built into the image. Off leaves the answer on the conversation's card until someone sends a message.",
+        ),
     autoResumeOnRestart: z
         .boolean()
         .default(false)
@@ -510,6 +544,11 @@ export const SandboxSettingsSchema = z.object({
     commandJudge: CommandJudgeModeSchema.default("on").describe(
         "Whether a model reads your safety policy before a flagged command runs. Off judges nothing and asks about nothing; Watch judges everything and records it without ever interrupting you, which is how you find out what your policy actually does before you let it stop anything; On lets the verdict decide. Wiping a disk or deleting under /history asks at every setting — that rule is typed rather than judged, and cannot be turned off.",
     ),
+    // Only whether a person is asked: where the install lands (the conversation's own copy, or the daemon's install lane
+    // for a main-tree turn) is the sandbox's business, so no setting names it.
+    projectInstalls: ProjectInstallModeSchema.default("automatic").describe(
+        "What happens when an agent installs a project's packages itself (pnpm add, npm install, uv sync). Automatic lets it run and keep working; Ask first stops for your answer in the chat, once or for the whole conversation; Never refuses, and a dependency the agent added to a manifest is installed when you land its work. A conversation in its own worktree installs into its own copy, and the land review lists every dependency its work adds.",
+    ),
     // Three separate ceilings since they stop different things: width (parallel fan-out), lifetime (per conversation),
     // depth (how far a child may delegate) — raising width alone just hits the lifetime cap sooner. Defaults mirror the
     // CLI's own unset behavior; hitting one stops the agent rather than retrying.
@@ -532,6 +571,24 @@ export const SandboxSettingsWriteSchema = SandboxSettingsSchema.refine((settings
     path: ["rules"],
 });
 
+// A browser's answer to who the screens are written for, for the person signed in to it. `offer` is the one that must
+// not overwrite: a browser handing over the answer it kept on its own, taken only while the sandbox keeps none for them.
+export const AudienceAnswerSchema = z.object({
+    audience: AudienceSchema.describe("developer for git's own words, maker for plain ones."),
+    offer: z
+        .boolean()
+        .optional()
+        .describe("Take it only while this person has no answer kept here yet. Absent or false replaces whatever is kept."),
+});
+export type AudienceAnswer = z.infer<typeof AudienceAnswerSchema>;
+
+// What the sandbox keeps for this person after the answer, and whether this call set it: false is an offer it declined.
+export const AudienceStateSchema = z.object({
+    audience: AudienceSchema.describe("The words this sandbox's editor now uses."),
+    adopted: z.boolean().describe("Whether this call set it. False means an offer met an answer already kept, which stands."),
+});
+export type AudienceState = z.infer<typeof AudienceStateSchema>;
+
 // A browser telling the sandbox which clock IT is on. An offer, not an instruction: see `adoptTimezone`.
 export const TimezoneOfferSchema = z.object({
     timezone: ZoneSchema.describe("The zone the offering machine is in, as an IANA name like Europe/Warsaw."),

package/src/schemas/speaker.ts

@@ -69,11 +69,11 @@ export const speakerOwner = (speaker: TurnSpeaker): Pick<SessionOwner, "email" |
 export const spokenByPerson = (speaker: TurnSpeaker | undefined): boolean => speaker?.kind === "person";
 
 // WHAT A COMPOSED PROMPT IS FOR, when the sandbox or the app wrote it rather than whoever is named as speaking: the brief
-// a fix agent is handed (what a push left, main's red CI, each later failure on main) and its nudges, a land conflict to
-// resolve. Carried on the turn and the row it opens, so a reader shows it as the sandbox's words, not the owner's, and
-// never has to recognise the prompt by its opening; the four openings older rows are recognised by stay what they are
-// (events/errands.ts, errandOfPrompt). `verify-nudge` and the `land-*` errands are retired with the checks that sent them
-// and stay only because records hold them.
+// a fix agent is handed (main's first failed job, each later failure on main) and its nudges, a land conflict to resolve. Carried
+// on the turn and the row it opens, so a reader shows it as the sandbox's words, not the owner's, and never has to
+// recognise the prompt by its opening; the four openings older rows are recognised by stay what they are
+// (events/errands.ts, errandOfPrompt). `verify-nudge`, the `land-*` errands and the `push-fix` pair (the hand-over of
+// what the pre-push hook found) are retired with what sent them and stay only because records hold them.
 export const TurnErrandSchema = z.enum([
     "land-conflict",
     "verify-nudge",

package/src/schemas/state-plan.ts

@@ -40,8 +40,15 @@ export type StatePlan = z.infer<typeof StatePlanSchema>;
 
 // The `state` of `/health`: whether an update's state changes are still uncommitted. The host rolls an update back when
 // the journal stays open, so this rides the same probe as the boot's progress.
+// `failed`: a conversion or structural step threw partway through this boot; the daemon put back every file the episode
+// had touched and keeps running on read-time conversions, and a host rolls the update back as it would an open journal
+// that never commits (this version could not bring the files to its shape, the one before it can read them as they are).
 export const StateStatusSchema = z.object({
-    journal: z.enum(["open", "none"]).describe("Open from the start of a boot that changed stored files until that boot has converged."),
+    journal: z
+        .enum(["open", "none", "failed"])
+        .describe(
+            "Open from the start of a boot that changed stored files until that boot has converged. Failed when a conversion threw partway: the files were put back as they were, and a host takes that as the update not having taken.",
+        ),
     engine: z.number().describe("The running build's conversion count."),
 });
 export type StateStatus = z.infer<typeof StateStatusSchema>;

package/src/schemas/system.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { StatePlanSchema } from "./state-plan.js";
+import { UpdateOutcomeSchema, WithdrawnReleaseSchema } from "./updates.js";
 // version is this build's baked-in version; latest/updateAvailable come from comparing it to the published stable
 // release.
 // Whether a runtime can serve a turn, probed off the turn path. "unknown" reads as available-but-unverified, never as
@@ -82,6 +83,20 @@ export const InfoSchema = z.object({
     staged: StagedUpdateSchema.optional().describe(
         "An update already downloaded and built on the machine running this container, waiting only for the restart that applies it. That restart is seconds, where an unprepared update is minutes, which is a different decision entirely. Absent when nothing is waiting.",
     ),
+    // What the host last did about this sandbox's version (update-outcome.json on /history, written by ic); absent
+    // when no host has said, which is every hosted sandbox and every host older than the file.
+    lastUpdate: UpdateOutcomeSchema.optional().describe(
+        "What the machine running this sandbox last did about its version: an update that took, one it gave up on and why, and until when the previous version stays ready. Absent when that machine has never said.",
+    ),
+    // The running version was taken back after it shipped; absent for every version still standing.
+    withdrawn: WithdrawnReleaseSchema.optional().describe(
+        "Set when the version this sandbox runs was withdrawn after it shipped, which is the moment to go back to the one before it. Absent for every version still standing.",
+    ),
+    // The owner's "not this one" (POST /system/update/skip); updateAvailable reads false while `latest` is it.
+    skippedVersion: z
+        .string()
+        .optional()
+        .describe("A release the owner chose to skip. While it is the newest, no update is offered; a newer one is. Absent when nothing is skipped."),
 });
 export type Info = z.infer<typeof InfoSchema>;
 // What the daemon could not read in its own `.intentic/` state files, and in the files on its volume that

package/src/schemas/terminal.ts

@@ -139,8 +139,9 @@ export const BrowserNameParamSchema = z.object({ name: z.string().describe("Whic
 // only where its record is read from and what else can be done with it, never how it looks.
 export const SubagentKindSchema = z.enum(["subagent", "spawned"]);
 export type SubagentKind = z.infer<typeof SubagentKindSchema>;
-// running/pending/blocked are live, the rest terminal. Uses the SDK's own task vocabulary rather than AgentStatus.
-// `blocked` is the one addition: a spawned child's question/permission/plan card raises it.
+// pending/running/blocked/paused are live, the rest terminal. Uses the SDK's own task vocabulary rather than AgentStatus.
+// `blocked` is one addition: a spawned child's question/permission/plan card raises it. `paused` the other: a spawned
+// child whose turn stopped at a wall the sandbox re-runs it past by itself, its report still to come.
 export const SubagentStatusSchema = z.enum(["pending", "running", "blocked", "completed", "failed", "killed", "paused"]);
 export type SubagentStatus = z.infer<typeof SubagentStatusSchema>;
 // Whether anything checked what the subagent did, computed from its edits against the checks that ran after them; works
@@ -177,7 +178,16 @@ export const SubagentSessionSchema = z.object({
     // Subagent type (Explore, general-purpose) or a child's provider label; description is the one-line ask.
     agentType: z.string().optional().describe("What kind of subagent it is."),
     description: z.string().optional().describe("What it was asked to do, in one line."),
-    model: z.string().optional().describe("Which model it runs on."),
+    model: z
+        .string()
+        .optional()
+        .describe(
+            "Which model it runs on: the exact id its provider served once its own record says so, where the call that started it named only an alias or nothing.",
+        ),
+    effort: z
+        .string()
+        .optional()
+        .describe("How hard it was told to think: its own definition's tier, else the one it inherited from its parent's turn."),
     // Which provider serves a spawned child; an SDK subagent implies its own (its parent's).
     provider: z.string().optional().describe("Which provider serves it, for a subagent spawned across providers."),
     // How deep in the spawn tree; 1 means the turn itself started it. A subagent can itself delegate further.
@@ -192,7 +202,7 @@ export const SubagentSessionSchema = z.object({
         .boolean()
         .optional()
         .describe(
-            "The parent carried on working instead of waiting for it. This is the whole reason the list exists: such a subagent used to be invisible until its result landed, sometimes minutes later.",
+            "The parent carried on working instead of waiting for it. Such a subagent is otherwise invisible until its result lands, sometimes minutes later.",
         ),
     status: SubagentStatusSchema.describe(
         "How it is going. Blocked means it needs an answer, which a parent and an operator act on differently from it simply working.",
@@ -218,7 +228,10 @@ export const SubagentSessionSchema = z.object({
 });
 export type SubagentSession = z.infer<typeof SubagentSessionSchema>;
 export const SubagentsListSchema = z.object({
-    sessions: z.array(SubagentSessionSchema).describe("Every subagent this sandbox's conversations have started, in-process and spawned alike."),
+    sessions: z
+        .array(SubagentSessionSchema)
+        .describe(
+            "The subagents conversations the caller can see have started, in-process and spawned alike: every one still working, and the most recent that have settled. Working ones first, then the most recently active.",
+        ),
 });
 export type SubagentsList = z.infer<typeof SubagentsListSchema>;
-export const SubagentIdParamSchema = z.object({ id: z.string() });

package/src/schemas/updates.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+// WHAT THE HOST LAST DID ABOUT THIS SANDBOX'S VERSION, in the host's own words. Written by `ic` (the swap, its health
+// check and the probation that follows it: _sandbox/ic/src/sandbox/outcome.rs) onto /history as `update-outcome.json`,
+// the same volume whichever container runs, so the version that ends up running reads what happened to the other one.
+// Advisory: the swap and its undoing are the host's; this is only how the sandbox and its owner hear about them.
+export const UpdateOutcomeResultSchema = z.enum(["updated", "kept", "restored", "rolled-back"]);
+export type UpdateOutcomeResult = z.infer<typeof UpdateOutcomeResultSchema>;
+
+export const UpdateOutcomeSchema = z.object({
+    result: UpdateOutcomeResultSchema.describe(
+        "What happened. Updated: the new version passed its first health check and runs, with the previous one kept ready until keepUntil. Kept: that probation ended and the new version stays. Restored: the new version never came up, so the previous container was put back at once. Rolled back: the new version came up and then failed its probation (it kept crashing, never became ready, or lost its tunnel), so the host went back to the previous one by itself.",
+    ),
+    // What the person or program asked for. A string rather than an enum: a newer ic's verb must not make an older
+    // daemon drop the whole outcome.
+    verb: z.string().optional().describe("What was asked for: update, rollback, rebuild, dev, reshape, or the probation watch acting on its own."),
+    at: z.number().describe("When it happened, in milliseconds."),
+    from: z.string().optional().describe("The version (or, when it would not say, the image) that ran before."),
+    to: z.string().optional().describe("The version (or image) that was moved onto, or that was tried and given up on."),
+    // Plain words for the owner: why a version was given up on. Absent for an update that simply worked.
+    reason: z.string().optional().describe("Why the host gave up on the new version, in plain words. Absent when nothing went wrong."),
+    // A path on the machine that runs the sandbox, which only means something to a person on that machine.
+    log: z.string().optional().describe("Where the host kept the full log of the swap, as a path on the machine that runs the sandbox."),
+    keepUntil: z
+        .number()
+        .optional()
+        .describe(
+            "Until when the previous version stays parked and ready, in milliseconds. While it does, going back takes seconds and nothing is downloaded or rebuilt; after it, going back uses the pinned image.",
+        ),
+});
+export type UpdateOutcome = z.infer<typeof UpdateOutcomeSchema>;
+
+// A published release that was taken back after it shipped (the release pipeline's rollback-stable.sh marks it on its
+// GitHub release). A sandbox running one is told, and offered the way back.
+export const WithdrawnReleaseSchema = z.object({
+    version: z.string().describe("The withdrawn version, which is the one this sandbox is running."),
+    reason: z.string().optional().describe("Why it was withdrawn, as the people who withdrew it put it."),
+});
+export type WithdrawnRelease = z.infer<typeof WithdrawnReleaseSchema>;
+
+// The owner's "not this one": no update is offered while the newest release is the skipped one. `null` clears it.
+export const SkipUpdateInputSchema = z.object({
+    version: z
+        .string()
+        .min(1)
+        .nullable()
+        .describe("The release to stop offering, or null to offer the newest release again. A newer release than the skipped one is always offered."),
+});
+export type SkipUpdateInput = z.infer<typeof SkipUpdateInputSchema>;
+
+// One image a sandbox can go back to, as `ic sandbox versions` knows it: the pinned local image and what it says it is.
+export const RollbackTargetSchema = z.object({
+    image: z.string().describe("The local image a rollback would run, pinned under a tag no other flow writes."),
+    version: z.string().optional().describe("What that image says it is. Absent when it would not say."),
+});
+export type RollbackTarget = z.infer<typeof RollbackTargetSchema>;

package/src/schemas/webext.ts

@@ -44,6 +44,9 @@ export const WebExtFactsSchema = object({
     grants: array(WebExtGrantSchema),
     // Kill switch from the extension's popup; true means every tool refuses and reports why.
     paused: boolean(),
+    // The optional procedures this build answers (`loopback-catch`); strings, so a newer build's never fails a read.
+    // Absent from a build older than the field, which answers none of them.
+    features: array(string()).optional(),
 });
 export type WebExtFacts = z.infer<typeof WebExtFactsSchema>;
 export const WebExtSummarySchema = object({

package/src/schemas/workflows.ts

@@ -37,7 +37,7 @@ export const WorkflowStepSchema = z.object({
         .min(1)
         .optional()
         .describe(
-            "What the step is told to do. The goal is the suite is green; this is run the tests, take the top failure, fix it. Leaving it out hands over the run's own request untouched, which is right for a step whose whole job is do what was asked.",
+            "What the step is told to do. The goal is the suite passes; this is run the tests, take the top failure, fix it. Leaving it out hands over the run's own request untouched, which is right for a step whose whole job is do what was asked.",
         ),
     // Steps that must finish first; empty means a root. Must be acyclic with every id existing, checked on save.
     needs: z
@@ -116,7 +116,7 @@ export type GuardOutcome = z.infer<typeof GuardOutcomeSchema>;
 // value is the field as the step wrote it; absent means most blocked verdicts had nothing to read.
 export const GateVerdictSchema = z.object({
     outcome: GuardOutcomeSchema.describe(
-        "Ship it, do not, or we could not tell. That third answer exists because could not reach a judgement is not the product is broken: a gate that reported its own outages as failures is one a team switches off, so it should be the honest answer far more often than the convenient one, and it means a neutral build rather than a red one.",
+        "Ship it, do not, or we could not tell. That third answer exists because could not reach a judgement is not the product is broken: a gate that reported its own outages as failures is one a team switches off, so it should be the honest answer far more often than the convenient one, and it means a neutral build rather than a failed one.",
     ),
     // Why, in one line; realistically the only part of this a pipeline log will show.
     reason: z.string().describe("Why, in one line. Realistically the only part of this a build log will ever show."),
@@ -156,14 +156,14 @@ export const WorkflowSchema = z.object({
 });
 export type Workflow = z.infer<typeof WorkflowSchema>;
 
-// skipped means the step never ran because something it waited on didn't finish; that's why a failed run shows one red
-// node and a trail of grey ones.
+// skipped means the step never ran because something it waited on didn't finish; that's why a failed run shows one
+// failed node and a trail of skipped ones.
 export const WorkflowStepStateSchema = z.enum(["pending", "running", "done", "failed", "skipped", "stopped"]);
 export type WorkflowStepState = z.infer<typeof WorkflowStepStateSchema>;
 export const WorkflowStepRunSchema = z.object({
     stepId: StepIdSchema.describe("Which step this is."),
     state: WorkflowStepStateSchema.describe(
-        "How it went. Skipped carries what the others cannot: it never ran, because something it was waiting on did not finish. That is why a failed run shows one red step and a trail of grey ones.",
+        "How it went. Skipped carries what the others cannot: it never ran, because something it was waiting on did not finish. That is why a failed run shows one failed step and a trail of skipped ones.",
     ),
     // The conversation this step ran on; shared with its predecessor under continue, making them one card.
     conversationId: z

package/src/schemas/workspace/workspace-tree.ts

@@ -182,6 +182,13 @@ export const WorkspaceFilePresentSchema = z.object({
         .describe(
             "Which tree answered. True when no conversation was named, and also when one was but its own copy has no such file, which is the case a reader has to be told about rather than left to assume.",
         ),
+    // Absent means the window decoded cleanly. Set by a server that checks (the desktop app's folder server does).
+    lossy: z
+        .literal(true)
+        .optional()
+        .describe(
+            "The bytes are not valid UTF-8, so `content` holds replacement characters where they failed to decode. Saving that text back would change the file, so treat it as read-only.",
+        ),
 });
 // Nothing there is an answer, not a failure: most reads here are read-it-if-there, and a 404 would spam the browser's
 // network log per miss. A refused read (an escape, a denylisted path) is still an error.

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

@@ -24,7 +24,7 @@ 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", () => {
+test("a landed attempt is closed: the same gates failing again get a fresh attempt", () => {
     const plan = planFixAttempt(BASE, [agent(BASE, { status: `landed` })], []);
     expect(plan).toEqual({ kind: `new`, conversationId: fixAttemptId(BASE, 2), attempt: 2 });
 });

package/src/state/fix-stance.ts

@@ -1,7 +1,7 @@
 import { turnedAwayCode } from "../policy/turned-away.js";
 import { type AgentSummary, awaitsWake } from "../schemas/agents.js";
 
-/* WHAT BECAME OF THE AGENT A SURFACE SENT AFTER A FAILURE — a red pipeline row, a refused push. */
+/* WHAT BECAME OF THE AGENT A SURFACE SENT AFTER A FAILURE — a failed pipeline row, a refused push. */
 
 export type FixStanceKind =
     // A turn is in flight. Nothing is owed by the reader.

package/src/state/history-state.ts

@@ -27,6 +27,10 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "blobs/", portability: "carry" },
     // Index of published-page conversations; the pages travel with /work anyway, this makes one withdrawable.
     { path: "shares.json", portability: "carry" },
+    // Each person's own answer to which words their editor uses here (developer or maker), keyed by sign-in address
+    // (settings/member-audience.ts). Carried: it is theirs, and asking again after a move would be a question already
+    // answered.
+    { path: "member-audience.json", portability: "carry" },
     { path: "activity.jsonl", portability: "carry" },
     { path: "usage.jsonl", portability: "carry" },
     { path: "account-usage.json", portability: "carry" },
@@ -78,6 +82,14 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "engines/", portability: "derived" },
     // An update the host downloaded and built for this sandbox (`ic sandbox prepare`); about this machine only.
     { path: "update-staged.json", portability: "derived" },
+    // What the host last did about this sandbox's version (ic writes it), the owner's skipped release, and why the
+    // last boot could not start (the daemon writes it, the host's probation reads it): all rebuilt by whoever next says.
+    { path: "update-outcome.json", portability: "derived" },
+    { path: "update-skipped.json", portability: "derived" },
+    { path: "boot-failure.json", portability: "derived" },
+    // A rebuild's ask that the next boot resume the turns it cuts (restart-resume.ts): about this machine's next boot only,
+    // read once by it, so a moved sandbox starts without one.
+    { path: "restart-resume.json", portability: "derived" },
 
     /* ---- credentials ---- */
 
@@ -87,6 +99,13 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
         portability: "secret",
         note: "Re-add each ssh host on the Capabilities view, its key does not travel.",
     },
+    // The container sshd's host key (docker-entrypoint.sh generates it once): the sandbox's SSH identity, which desktop
+    // sync pins. A private key, so it stays; the target makes its own on first boot.
+    {
+        path: "ssh-host-keys/",
+        portability: "secret",
+        note: "Clear this sandbox's old host key from your computer's known_hosts before syncing it again.",
+    },
     // The cli-proxy's config, which holds the routed subscriptions' provider tokens.
     {
         path: "translator/",

package/src/state/runtime-state.ts

@@ -58,9 +58,6 @@ const RUNTIME_DOMAINS = [
 
     // The audit log grew or a gateway's status moved or aged out; the log lives outside /work, so no file push carries it.
     { domain: "activity", invalidates: [["activity"], ["activity-status"]] },
-
-    // What the pre-push hook left behind: a push filed, a finding measured gone, dismissed or handed to an agent.
-    { domain: "pushes", invalidates: [["push-checks"]] },
 ] as const satisfies readonly RuntimeDomainBinding[];
 
 export const RUNTIME_DOMAIN_BINDINGS: readonly RuntimeDomainBinding[] = RUNTIME_DOMAINS;

package/src/state/workspace-state.ts

@@ -132,6 +132,10 @@ const STATE_FILES = [
     // needing, not what one machine did. The drift snapshot self-expires on a move since its `bornAt` won't match the
     // new container.
     { path: ".intentic/records/runtime-installs.json", invalidates: ["environment"], portability: "carry" },
+    // What agents are waiting on people for (docs/architecture/needs.md): every open need and the recent closed ones.
+    // Holds no credential (a secret need names the secret, its value goes to the secret store), so it may `carry`: a
+    // question a moved sandbox still has to ask. `needs` is the chat cards', the board's and the inbox's shared read.
+    { path: ".intentic/records/needs.json", invalidates: ["needs"], portability: "carry" },
     // Where each agent engine's version comes from: blessed list, upstream newest, a pin, or the image
     // (schemas/engines.ts). The versions themselves are machine state on the daemon's volume (architecture-specific
     // binaries); the policy here travels. `versioned`: a human decision worth reviewing. Own key, not `environment`'s:
@@ -379,12 +383,6 @@ const STATE_FILES = [
         portability: "derived",
         note: "The target stamps its own daemon version on first boot.",
     },
-    {
-        path: ".intentic/records/push-checks.json",
-        invalidates: [],
-        why: "What each push check found and let through, per project, and what became of every finding: still open, measured gone, or dismissed. Filed from the report the pre-push hook leaves in the repository's git dir; read through GET /workspace/push-checks, which the daemon pushes itself (the `pushes` runtime domain).",
-        portability: "carry",
-    },
     // What an update converted before it booted all the way (the sandbox daemon's state-journal.ts): a copy of every
     // file the new version changed, kept until it commits and for a grace window after. `secret` whatever the source
     // was, since a vault's copy is a vault; locked below for the same reason.

package/src/text/documents.test.ts

@@ -1,4 +1,4 @@
-import { documentOf, documentTitle, isDocumentPath, isPlanDocumentPath } from "./documents.js";
+import { deliverableKindOf, documentOf, documentTitle, isDocumentPath, isPlanDocumentPath } from "./documents.js";
 import { PLAN_DOCUMENTS_DIR } from "../state/workspace-state.js";
 
 const write = (path: string, newText: string, extra: { oldText?: string; truncated?: boolean } = {}) => [
@@ -64,3 +64,27 @@ describe("paths", () => {
         expect(isPlanDocumentPath("docs/plans/anything.md")).toBe(false);
     });
 });
+
+describe("deliverableKindOf", () => {
+    test("names each kind by its extension, in any case, `.htm` a web page too", () => {
+        expect(["q3/report.docx", "deck.PPTX", "numbers.xlsx", "scan.pdf", "site/index.html", "old/page.HTM"].map(deliverableKindOf)).toEqual([
+            "docx",
+            "pptx",
+            "xlsx",
+            "pdf",
+            "html",
+            "html",
+        ]);
+    });
+
+    test("anything else is none: source, markdown, the old binary formats, a dotfile, a directory's dot", () => {
+        expect(["src/app.ts", "notes.md", "letter.doc", ".pdf", "release.v2/README", "docx"].map(deliverableKindOf)).toEqual([
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+        ]);
+    });
+});

package/src/text/documents.ts

@@ -14,6 +14,30 @@ export const isDocumentPath = (path: string): boolean => {
     return DOCUMENT_EXTENSIONS.some((extension) => lower.endsWith(extension));
 };
 
+// A deliverable is a file a turn hands a person to open rather than read as code: an office document, a PDF, a web
+// page. The daemon names the ones a command wrote on its card (agent/tools/produced-documents.ts) and the chat lists a
+// turn's under its answer, so the two ask this one table. Markdown stays out: the chat already draws it as a document.
+export type DeliverableKind = "docx" | "pptx" | "xlsx" | "pdf" | "html";
+
+const DELIVERABLE_BY_EXTENSION = new Map<string, DeliverableKind>([
+    ["docx", "docx"],
+    ["pptx", "pptx"],
+    ["xlsx", "xlsx"],
+    ["pdf", "pdf"],
+    ["html", "html"],
+    ["htm", "html"],
+]);
+
+// The kind of deliverable a path names by its extension, or undefined for any other file (a dotfile included).
+export const deliverableKindOf = (path: string): DeliverableKind | undefined => {
+    const name = path.slice(path.lastIndexOf("/") + 1).toLowerCase();
+    const dot = name.lastIndexOf(".");
+    return dot > 0 ? DELIVERABLE_BY_EXTENSION.get(name.slice(dot + 1)) : undefined;
+};
+
+// Every extension a deliverable is written with, for a reader that has to find the names in free text.
+export const DELIVERABLE_EXTENSIONS = [...DELIVERABLE_BY_EXTENSION.keys()];
+
 // Matched by directory, not name (a mint-fresh phrase like `map-of-this-wiggly-spring.md` carries no signal). The
 // directory is declared in workspace-state.ts, the one exception to its lock.
 export const isPlanDocumentPath = (path: string): boolean => path.startsWith(`${PLAN_DOCUMENTS_DIR}/`);

package/src/text/title.ts

@@ -24,7 +24,7 @@ const OPENERS: readonly RegExp[] = [
     /^(?:quick\s+(?:one|question|q)|one\s+more\s+thing)\b[\s,.:;!—–-]*/i,
 ];
 
-// Terminal punctuation followed by a break; keeps `v1.2` and `foo.ts` intact while still ending `Why is it red?`.
+// Terminal punctuation followed by a break; keeps `v1.2` and `foo.ts` intact while still ending `Why does it fail?`.
 const SENTENCE_END = /[.!?](?=\s|$)/;
 
 // Matches a first sentence reporting past work (`We just landed…`); that is scene-setting, not the ask.