@intentic/sandbox-contract 1.167.0 → 1.169.0

package/src/schemas.ts

@@ -262,6 +262,14 @@ export const AgentSummarySchema = z.object({
     // Completed turns and lifetime tool calls — the card's msgs/tools counters.
     turns: z.number().optional(),
     toolUses: z.number().optional(),
+    /* The agents THIS agent started (SubagentSessionSchema), live and lifetime. Absent ⇒ it has never delegated,
+     * which is most agents — so the card's chip appears on content rather than reading "0" down the board.
+     *
+     * It earns a place on a card because a fleet card is the answer to "what is this agent up to", and an agent
+     * running five children looked exactly like an agent running none: the work was real, the spend was real, and
+     * the board said nothing. The tokens are NOT folded into the parent's cost — a child's spend is its own, and
+     * the Subagents area is where it is attributed. */
+    subagents: z.object({ running: z.number(), total: z.number() }).optional(),
     // The agent's cumulative output (base → branch tip across every repo), refreshed on each land —
     // the card's "12 files · +412 −96" readout. Independent of what has landed.
     diff: z.object({ files: z.number(), insertions: z.number(), deletions: z.number() }).optional(),
@@ -383,9 +391,52 @@ export const AgentLandSchema = z.object({ id: z.string().min(1), mode: LandModeS
 export const KeyedProviderSchema = z.enum(["codex", "grok", "kimi", "gemini"]);
 export type KeyedProvider = z.infer<typeof KeyedProviderSchema>;
 
+// ---- plan-limit usage ----
+// Declared ABOVE both account shapes because both carry it: headroom is one idea in this product, not a Claude
+// idea that other providers imitate. A native account (OauthAccount) and a routed subscription
+// (TranslatorAccount) differ in who holds the credential and how the reading is taken — never in what a
+// reading IS — so every surface that draws a percentage reads this one type and no other.
+
+// One plan-limit pool. `kind` is the provider's own key ('five_hour' | 'seven_day' | 'seven_day_opus' |
+// 'seven_day_sonnet' | 'model:Fable' | …) rather than an enum we'd have to keep in step with the provider: an
+// unrecognised pool is shown under its raw key, which is far better than being silently folded into a
+// neighbour. `label` is the provider's OWN display name where it supplies one (the per-model buckets do) — it
+// wins over anything we'd infer, because the model names in a plan's limits are the provider's to rename.
+// `resetsAt` is epoch SECONDS (matching the SDK's frame).
+export const UsageWindowSchema = z.object({
+    kind: z.string(),
+    label: z.string().optional(),
+    utilization: z.number(), // 0-100
+    resetsAt: z.number().optional(),
+});
+export type UsageWindow = z.infer<typeof UsageWindowSchema>;
+
+// An account's headroom: EVERY window the provider reports, read together, plus when the reading was taken.
+// All of them, not the binding one, because "which pool is binding" changes between turns and a reader
+// comparing accounts needs the same pools on every row. How the reading is TAKEN is per provider and stops at
+// the daemon's readers: Claude's rides the turn's own stream, ChatGPT's and Google's are pulled through
+// CLIProxyAPI's credential-scoped management call. All of them are control requests, so none costs tokens.
+//
+// Within one window utilization only climbs, so an un-reset window stays a valid FLOOR however old it is; past
+// its `resetsAt` it describes a pool that no longer exists and the store drops it. `measuredAt` is epoch MS
+// (matching connectedAt) — deliberately a different unit from the windows' seconds.
+export const AccountUsageSchema = z.object({
+    windows: z.array(UsageWindowSchema),
+    measuredAt: z.number(),
+});
+export type AccountUsage = z.infer<typeof AccountUsageSchema>;
+
 // One connected subscription in the translator. `name` is CLIProxyAPI's auth-file name — the stable store key a
 // disconnect addresses — and `label` the sign-in identity it reported (the account email, else the file name).
-export const TranslatorAccountSchema = z.object({ name: z.string(), label: z.string() });
+export const TranslatorAccountSchema = z.object({
+    name: z.string(),
+    label: z.string(),
+    // The same headroom an OauthAccount carries, on the same field, for the same reason: the account rows are
+    // one list to the reader. Optional because a provider whose quota this sandbox cannot read (Grok, Kimi) —
+    // or one that did not answer — must still render as the connected account it is, with a dot instead of a
+    // ring.
+    usage: AccountUsageSchema.optional(),
+});
 export type TranslatorAccount = z.infer<typeof TranslatorAccountSchema>;
 // Which routed-provider subscriptions are connected in the translator, per provider — a LIST per provider, not
 // a flag: CLIProxyAPI holds any number of auth files per provider side by side and balances requests across
@@ -453,14 +504,8 @@ export const SteerSchema = z
 // True cancel for the conversation's in-flight turn — aborts the agent daemon-side, unlike closing the
 // /agent fetch (which sends no cancel frame).
 export const StopTurnSchema = z.object({ conversationId: z.string().min(1) });
-// Fire the conversation's remembered usage-limit resume NOW instead of waiting out the reset. `account`
-// points the re-run at a different connected account of the same provider — the "resume on another account"
-// action a spent allowance offers when the sandbox holds more than one; omitted, the turn re-runs on
-// whatever served it (a plain "try again now"). NOT_FOUND when nothing is pending (the failure was already
-// superseded by a fresh turn, or the daemon restarted).
-export const ResumeLimitSchema = z.object({ conversationId: z.string().min(1), account: z.string().min(1).optional() });
-
-// ---- claude subscription usage ----
+
+// ---- claude rate-limit gate ----
 // The GATE signal: whether the provider is letting turns through right now, and — when it is refusing — which
 // window is binding and when it lifts. This is the SDK's rate_limit_event, mapped one-to-one, and it is only
 // ever about the CURRENT moment. It is deliberately NOT the thing the headroom displays read: the event names a
@@ -474,34 +519,6 @@ export const RateLimitInfoSchema = z.object({
 });
 export type RateLimitInfo = z.infer<typeof RateLimitInfoSchema>;
 
-// One plan-limit pool. `kind` is the provider's own key ('five_hour' | 'seven_day' | 'seven_day_opus' |
-// 'seven_day_sonnet' | 'model:Fable' | …) rather than an enum we'd have to keep in step with the provider: an
-// unrecognised pool is shown under its raw key, which is far better than being silently folded into a
-// neighbour. `label` is the provider's OWN display name where it supplies one (the per-model buckets do) — it
-// wins over anything we'd infer, because the model names in a plan's limits are the provider's to rename.
-// `resetsAt` is epoch SECONDS (matching the SDK's frame).
-export const UsageWindowSchema = z.object({
-    kind: z.string(),
-    label: z.string().optional(),
-    utilization: z.number(), // 0-100
-    resetsAt: z.number().optional(),
-});
-export type UsageWindow = z.infer<typeof UsageWindowSchema>;
-
-// An account's headroom: EVERY window the provider reports, read together, plus when the reading was taken.
-// All of them, not the binding one, because "which pool is binding" changes between turns and a reader
-// comparing accounts needs the same pools on every row. Sourced from the CLI's own usage endpoint at turn end
-// (see claudeUsageWindows) — a control request, so it costs no tokens.
-//
-// Within one window utilization only climbs, so an un-reset window stays a valid FLOOR however old it is; past
-// its `resetsAt` it describes a pool that no longer exists and the store drops it. `measuredAt` is epoch MS
-// (matching connectedAt) — deliberately a different unit from the windows' seconds.
-export const AccountUsageSchema = z.object({
-    windows: z.array(UsageWindowSchema),
-    measuredAt: z.number(),
-});
-export type AccountUsage = z.infer<typeof AccountUsageSchema>;
-
 // ---- provider oauth ----
 // Claude uses the PKCE authorize-URL + paste-back handshake (start → exchange). Codex uses OpenAI's device-code
 // flow (start → poll): the browser signs in at verificationUri and enters userCode; the daemon polls until done.
@@ -528,8 +545,9 @@ export const OauthAccountSchema = z.object({
     needsReauth: z.boolean().optional(),
     detail: z.string().optional(),
     // The account's last known subscription-usage snapshot, so the picker can show what's left on each account
-    // before the user commits a turn to one. Claude-only (it is the sole provider whose stream reports a usage
-    // window) and absent until that account has run a turn — an unmeasured account reads as unknown, never 0%.
+    // before the user commits a turn to one. Absent until a reading exists for it — an unmeasured account reads
+    // as unknown, never 0%. Claude is the provider that fills it here, because its stream reports the windows;
+    // the routed subscriptions carry the identical field on TranslatorAccount, filled by a pulled reading.
     usage: AccountUsageSchema.optional(),
 });
 export type OauthAccount = z.infer<typeof OauthAccountSchema>;
@@ -669,11 +687,6 @@ export const BuiltinPromptSchema = z.object({ base: z.enum(["intentic", "claude"
 // surface fail to parse the moment a toggle is added — which reaches the user as a page of switches that are
 // silently dead, not as an error. It also means an older on-disk manifest keeps the owner's other picks rather
 // than being discarded whole.
-// Build-wide kill switch for usage-limit auto-resume. Keep the setting and implementation in place while the
-// feature is disabled, but clamp every daemon response and settings write to OFF so a persisted `true` from an
-// older build cannot keep spending a newly reset allowance. The web also reads this constant to render the
-// control unavailable and to distrust a stale daemon that still reports a scheduled resume.
-export const USAGE_LIMIT_AUTO_RESUME_ENABLED: boolean = false;
 
 export const SandboxSettingsSchema = z.object({
     stableSystemPrompt: z.boolean().default(false),
@@ -746,18 +759,12 @@ export const SandboxSettingsSchema = z.object({
      * automation-opened agents (Discord, webhooks, email) finish turns with no browser in the room — a
      * browser-held preference could not govern them. Per-agent override: AgentSummarySchema.autoLand. */
     autoLand: z.boolean().default(true),
-    // Latent opt-in for re-running a turn after the Claude subscription's usage window resets. It defaults off
-    // because an unattended retry spends the fresh allowance without the user in the room, and the build-wide
-    // gate above currently clamps even an older saved opt-in off while the feature is unavailable.
-    autoResumeOnLimit: z
-        .boolean()
-        .default(false)
-        .overwrite((enabled) => USAGE_LIMIT_AUTO_RESUME_ENABLED && enabled),
     /* When a turn dies because the MODEL PROVIDER was failing (500/502/503, a 529 at capacity, a dropped
      * socket), re-run it on an escalating backoff until it goes through or the attempts are spent.
      *
-     * Defaults ON, unlike autoResumeOnLimit, and the difference is not an inconsistency: a spent allowance is
-     * the user's own budget, and resuming into a fresh window spends something they may have been saving. An
+     * Defaults ON, and a spent Claude allowance is the counter-example that explains why: that one is the
+     * user's own budget, and resuming into a freshly reset window spends something they may have been saving —
+     * so a usage limit stops the turn and says when it resets, and nothing re-runs it. An
      * outage resume spends nothing the dead turn had not already committed, resolves in minutes rather than
      * hours, and — the deciding argument — the turns hurt worst by it are the ones with nobody in the room
      * (automation wakes, Discord, webhooks), which no browser-held preference could ever rescue. It is the same
@@ -765,8 +772,8 @@ export const SandboxSettingsSchema = z.object({
     resumeAfterOutage: z.boolean().default(true),
     /* When the daemon dies under a running turn, re-run that turn once it is back (agent/turn-journal.ts records
      * every in-flight turn; the boot pass in agent/turn-resume.ts re-runs what survived). ON by default, where
-     * autoResumeOnLimit is off, and the difference is who broke the turn: a spent allowance is the user's own
-     * budget, while a restart is usually intentic's OWN doing — the container is recreated on every update,
+     * a spent usage limit re-runs nothing, and the difference is who broke the turn: a spent allowance is the
+     * user's own budget, while a restart is usually intentic's OWN doing — the container is recreated on every update,
      * every environment approval and every dev-sandbox.sh swap. Approving the Dockerfile change an agent asked
      * for must not cost the run that asked for it, and a user who just clicked Approve is in the room expecting
      * the work to continue, not a second button.
@@ -774,34 +781,26 @@ export const SandboxSettingsSchema = z.object({
      * OFF still records the interruption: the fleet card reads `interrupted` (see AgentStatusSchema) and an
      * automation's row shows an `interrupted` run — nothing is re-run, but nothing is silently lost either. */
     autoResumeOnRestart: z.boolean().default(true),
-    /* THE LANDING GATE — the check command run over the COMPOSITE of landed work after a landing debounce.
-     * Empty ⇒ no gate at all, which is the default: only the owner knows what verifies this workspace, and a
-     * guessed command that fails on a fresh clone would read as the gate finding a bug on its first run.
+    /* THE PRE-PUSH CHECK — the command run when the user pushes, before anything leaves the machine.
+     * Empty ⇒ no check at all, which is the default: only the owner knows what verifies this workspace, and a
+     * guessed command that fails on a fresh clone would read as the check finding a bug on its first run.
      *
      * Configuring it is the opt-in, which is why there is no separate enable flag to disagree with it. The
-     * command runs in the workspace root through `sh -c`, exactly as a terminal would run it (see gate/gate.ts
-     * for why this is NOT an automation guard: a suite outlives GUARD_TIMEOUT_MS, and a timed-out guard reads
-     * as "skipped" — a silent green over a suite that never finished). */
-    gateCommand: z.string().max(500).default(""),
-    /* How long after a land the gate waits before running. A landing burst is the case this exists for: five
-     * agents finishing within a minute of each other are five lands, and a gate that ran per land would spend
-     * five suites to answer about four trees nobody will ever push. Every land re-arms the timer, so the run
-     * happens once, on the tree the user is about to review.
+     * command runs in the workspace root through `sh -c`, exactly as a terminal would run it. */
+    prepushCommand: z.string().max(500).default(""),
+    // Ceiling on one run, after which the child's whole process group is killed and the result is `failed` with
+    // `timedOut`. Never a pass: a suite that did not finish has said nothing about the tree, and the one thing
+    // this check exists to prevent is a green light nobody earned.
+    prepushTimeoutMs: z.number().min(60_000).max(3_600_000).default(900_000),
+    /* WHAT THE SUGGESTED FIX SESSION RUNS ON when the check fails — `${provider}:${model}` (quickModelKey), and
+     * the reasoning effort beside it. Both empty ⇒ whatever the chat composer would have started with, which is
+     * the right default precisely because it is the model the user already chose to work with.
      *
-     * It counts from the last LAND and nothing else — explicitly not "until the fleet is idle". Agents here run
-     * for hours, so a fleet of twenty with one long runner would never present a quiet moment, and a gate that
-     * waited for one would only ever fire when clicked (gate/gate.ts). */
-    gateQuietMs: z.number().min(0).max(600_000).default(20_000),
-    // Ceiling on one gate run, after which the child is killed and the verdict is `failed` with `timedOut`.
-    // Never a pass: a suite that did not finish has not said anything about the tree, and the one thing this
-    // gate exists to prevent is a green light nobody earned.
-    gateTimeoutMs: z.number().min(60_000).max(3_600_000).default(900_000),
-    /* Wake a fixer automatically when the gate goes red, instead of only lighting the badge. ON with a
-     * configured command, unlike the other unattended-spend toggles (autoResumeOnLimit), and the difference is
-     * that the spend here is the POINT: a red gate whose fix waits for the user to notice has moved the CI
-     * round-trip into the workspace without removing it from the user's day. One attempt per verdict, so a
-     * command that fails for a reason no agent can fix costs one turn, not a loop (gate/gate.ts). */
-    gateAutoFix: z.boolean().default(true),
+     * Pinned here rather than resolved cheapest-first like `quickModel`: this is not a one-click helper, it is a
+     * turn that has to read a failing suite and repair it, so the choice is the user's and worth stating. The
+     * suggestion dialog seeds from these and stays editable — the setting decides where the dialog OPENS. */
+    prepushFixModel: z.string().default(""),
+    prepushFixEffort: z.string().default(""),
 });
 export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
 
@@ -2236,95 +2235,51 @@ export type CiRunParam = z.infer<typeof CiRunParamSchema>;
 export const CiFixResponseSchema = z.object({ conversationId: z.string() });
 export type CiFixResponse = z.infer<typeof CiFixResponseSchema>;
 
-/* ---- the landing gate: the workspace's own verdict on the composite of landed work ----
- *
- * WHERE THIS SITS, and why it is not one of the four other places it could:
- *
- * A fleet of 5-20 agents lands work into the main tree as UNCOMMITTED changes (agents/land.ts), the user
- * reviews and commits it by parts, pushes, and CI answers minutes later. This gate front-runs that answer by
- * asking the same question of the same artifact, before the push.
+/* ---- the pre-push check: the workspace's own answer to "would this push go red" ----
  *
- * NOT inside an agent's turn. An isolated worktree's `node_modules` reads as the MAIN checkout's, so a
- * monorepo's workspace links resolve cross-package imports to /work's sources rather than the worktree's edited
- * ones (agents/worktrees.ts). A suite run in a worktree therefore tests the agent's edits against everyone
- * else's UNEDITED siblings: it invents failures that don't exist and passes changes that break on the
- * composite, and two agents editing one contract each go green alone and red together. The composite is the
- * only honest artifact, and it exists in exactly one place — the main working tree.
+ * WHERE THIS SITS. A fleet of 5-20 agents lands work into the main tree, the user reviews and commits it by
+ * parts, pushes, and CI answers minutes later. The check front-runs that answer at the push itself — the last
+ * moment before the work leaves the machine, and the first moment at which what will be pushed is finally
+ * settled.
  *
- * NOT at commit. The user commits BY PARTS, and a suite reads the worktree, not the index — so a verdict taken
- * at a partial commit describes a tree that never gets pushed as such. Commit is where a verdict is DISPLAYED
- * (ReviewPanel's badge), computed earlier.
+ * WHY THE PUSH AND NOT THE LAND, which is where this used to run. A post-land verdict is about a tree that
+ * keeps moving: the user commits by parts, another agent lands, an edit arrives — so the verdict spent its life
+ * either stale or being recomputed, and needed a content fingerprint, a staleness rule and a badge to say which.
+ * All of that machinery existed to answer a question the push asks for free, because at the push there is
+ * exactly one artifact and the user is standing in front of it waiting.
  *
- * NOT at push. By then HEAD has moved, per-path attribution has expired (agents/origins.ts), and the agents may
- * be archived with their worktrees reclaimed — so the fix starts cold, in the same position `/ci/fix` is in.
- * That saves the CI round-trip and none of the context switch.
- *
- * So: after the land, before the staging — the one window where the artifact is what CI will see, attribution
- * is still live, and nobody is waiting on it. */
+ * SO THERE IS NO STORED VERDICT AND NOTHING IS POLLED AT REST. A run exists while it runs, reports to the
+ * dialog that started it, and is gone. Nothing survives a daemon restart because nothing needs to: the next
+ * push asks again. */
 
-/* What the gate has to say about the tree right now.
+/* Where a run is.
  *
- *   idle      — no command configured, or nothing has run yet.
- *   armed     — work landed; the quiet period is counting down (see gateQuietMs).
+ *   idle      — nothing has run in this daemon's life, or the last run was cleared.
  *   running   — the check is live. `output` grows as it streams.
- *   passed    — exited 0 over `fingerprint`.
- *   failed    — exited non-zero, or was killed by gateTimeoutMs (`timedOut`). The state a fix answers.
- *   error     — the gate itself could not run: the command was not spawnable. NOT a fix-able failure, because
- *               there is nothing wrong with the code — the gate is misconfigured, and saying "tests failed"
+ *   passed    — exited 0. The push goes.
+ *   failed    — exited non-zero, or was killed by prepushTimeoutMs (`timedOut`). The state a fix answers.
+ *   error     — the check could not run at all: the command was not spawnable. NOT a fix-able failure, because
+ *               there is nothing wrong with the code — the command is misconfigured, and saying "tests failed"
  *               would send an agent hunting a bug that isn't there.
- *   cancelled — the user stopped the run, or the tree moved under it.
+ *   cancelled — the user stopped the run.
  */
-export const GateStatusSchema = z.enum(["idle", "armed", "running", "passed", "failed", "error", "cancelled"]);
-export type GateStatus = z.infer<typeof GateStatusSchema>;
-
-// An agent whose landed work the failure implicates. `paths` are its attributed files that the check's own
-// output NAMED — empty when the output named none of them, which is the honest shape for a failure that could
-// not be pinpointed (an integration break between two deltas, a suite that prints no paths at all): the agent
-// is listed because its work is in the tree under test, not because anything accused it.
-export const GateAgentSchema = z.object({
-    agentId: z.string(),
-    title: z.string().optional(),
-    provider: AgentProviderSchema.optional(),
-    paths: z.array(z.string()),
-});
-export type GateAgent = z.infer<typeof GateAgentSchema>;
-
-// The fix turn one red verdict got. It is a workspace conversation because the composite it must reproduce
-// lives as uncommitted content in the main working tree; it still has the same stable registry identity as any
-// other conversation.
-export const GateFixSchema = z.object({
-    startedAt: z.number(),
-    conversationId: z.string(),
-    // `running` while the turn streams; `done` when it ended cleanly, whatever the re-check then said;
-    // `error` when the turn itself failed (a provider outage, no credential), which is worth distinguishing
-    // because it is the one case where re-running the fix could still help.
-    outcome: z.enum(["running", "done", "error"]),
-    detail: z.string().optional(),
-});
-export type GateFix = z.infer<typeof GateFixSchema>;
+export const PrepushStatusSchema = z.enum(["idle", "running", "passed", "failed", "error", "cancelled"]);
+export type PrepushStatus = z.infer<typeof PrepushStatusSchema>;
 
-export const GateVerdictSchema = z.object({
-    status: GateStatusSchema,
-    // The command this verdict ran, echoed rather than read back from settings: a verdict read after the
+export const PrepushRunSchema = z.object({
+    status: PrepushStatusSchema,
+    // The command this run executed, echoed rather than read back from settings: a result read after the
     // setting changed still has to say what produced it.
     command: z.string(),
     startedAt: z.number().optional(),
     finishedAt: z.number().optional(),
     exitCode: z.number().optional(),
     timedOut: z.boolean().optional(),
-    // The check's own output, tail-capped (GATE_OUTPUT_BYTES). The tail, not the head: a suite's verdict and
+    // The check's own output, tail-capped (PREPUSH_OUTPUT_BYTES). The TAIL, not the head: a suite's verdict and
     // its failure summary are at the end, and a head-capped buffer of a chatty build is all progress lines.
     output: z.string(),
-    /* WHICH TREE this verdict is about — HEAD plus the shape of every repo's uncommitted content. Recomputed
-     * on read: when it no longer matches, the verdict is `stale` and the badge says so instead of asserting a
-     * green light over a tree that has since moved. This is what keeps a passed verdict from outliving its
-     * subject when the user edits, discards, or commits half of it. */
-    fingerprint: z.string(),
-    stale: z.boolean(),
-    implicated: z.array(GateAgentSchema),
-    fix: GateFixSchema.optional(),
 });
-export type GateVerdict = z.infer<typeof GateVerdictSchema>;
+export type PrepushRun = z.infer<typeof PrepushRunSchema>;
 
 // ---- drafts: agent-proposed posts awaiting owner approval (.intentic/drafts/<id>.json) ----
 // One JSON file per draft. The AGENT creates drafts with its normal file tools — it can't call daemon routes,
@@ -2507,7 +2462,7 @@ export const BrowserPageSchema = z.object({
     // The page's own title. Absent mid-navigation, which is exactly when a tab still needs to render.
     title: z.string().optional(),
     url: z.string(),
-    // The page the agent last drove. Exactly one page per running session has it.
+    // The page the agent last drove — on a finished session, the one it ended on. Exactly one page has it.
     active: z.boolean(),
 });
 export const BrowserSessionSchema = z.object({
@@ -2521,6 +2476,9 @@ export const BrowserSessionSchema = z.object({
     // still lists for a while, with the pages it had — the record of where the agent went.
     running: z.boolean(),
     activityAt: z.number(),
+    // When that Chromium went away, for the "closed 20m ago" line a finished session leads with. Absent while
+    // running, which is the same fact as `running` — but the view needs the timestamp, not just the flag.
+    finishedAt: z.number().optional(),
     pages: z.array(BrowserPageSchema),
 });
 export type BrowserPage = z.infer<typeof BrowserPageSchema>;
@@ -2529,6 +2487,75 @@ export const BrowsersListSchema = z.object({ sessions: z.array(BrowserSessionSch
 export type BrowsersList = z.infer<typeof BrowsersListSchema>;
 export const BrowserNameParamSchema = z.object({ name: z.string() });
 
+/* ---- subagents: the agents an agent starts ----
+ *
+ * The third thing a turn spawns that the operator can be shown, after its shell and its browser — and the only
+ * one that is itself an agent. Two kinds land in this one list, because from outside they are the same fact
+ * (another agent, working, that you did not start):
+ *   • `subagent` — the SDK's Agent/Task tool. The daemon learns of it from the SubagentStart/SubagentStop hooks
+ *     and the task_* stream messages, joined on `toolUseId`.
+ *   • `codex` / `grok` — a CLI the agent drove from its own Bash (agent/delegation.ts). Detected in the Bash
+ *     PreToolUse hook, bound to its thread/session id from the command's output.
+ *
+ * `id` IS THE SPAWNING TOOL CALL'S id — the Agent card's, or the Bash card's for a delegation. It is the one key
+ * every source already carries (the SDK's subagent meta, its task_* messages, and the `parentToolUseId` the
+ * client nests inner frames under), so nothing has to be correlated: a card links to its subagent with the id it
+ * already has, and the subagent points back at the card the same way. The ids the transcripts are actually READ
+ * with — the SDK's agent id, a Codex thread, an OpenCode session — stay daemon-side, because no surface asks a
+ * question they answer.
+ *
+ * WHAT A KIND CHANGES, and it is only ever the live view: a subagent has no process of its own to look at, so
+ * watching it means reading its transcript. A delegation runs in a tmux window, so it has both — `terminal`
+ * names it, and the card keeps its existing "Watch in terminal" beside the transcript door. */
+export const SubagentKindSchema = z.enum(["subagent", "codex", "grok"]);
+export type SubagentKind = z.infer<typeof SubagentKindSchema>;
+
+// running/pending are live; the rest are terminal. Deliberately the SDK's own task vocabulary
+// (SDKTaskUpdatedMessage.patch.status) rather than AgentStatus: this is not a fleet card's lifecycle (no
+// draft/landed/conflict), and mapping the two would invent states neither side reports.
+export const SubagentStatusSchema = z.enum(["pending", "running", "completed", "failed", "killed", "paused"]);
+export type SubagentStatus = z.infer<typeof SubagentStatusSchema>;
+
+export const SubagentSessionSchema = z.object({
+    id: z.string(),
+    kind: SubagentKindSchema,
+    // The conversation whose turn spawned this — what the area groups its rows by, and the way back to the chat
+    // the card lives in.
+    conversationId: z.string(),
+    // What it is and what it was asked to do: the subagent type (`Explore`, `general-purpose`) or the delegated
+    // provider's model, and the caller's one-line description. The area's row and the card's title read as
+    // `Explore · Locate claimIndexer definition`.
+    agentType: z.string().optional(),
+    description: z.string().optional(),
+    model: z.string().optional(),
+    // How deep in the spawn tree (1 = spawned by the turn itself). From the SDK's meta.json; a subagent may
+    // itself delegate, and a flat list that cannot say so reads as though the turn started all of them.
+    spawnDepth: z.number().optional(),
+    // Backgrounded: the parent went on working instead of waiting for it. This is the whole reason the list
+    // exists — a backgrounded child used to be invisible until its result landed, sometimes minutes later.
+    background: z.boolean().optional(),
+    status: SubagentStatusSchema,
+    startedAt: z.number(),
+    endedAt: z.number().optional(),
+    activityAt: z.number(),
+    // What it has spent and done so far (task_progress). Tokens are the child's own, so a parent's cost line and
+    // the sum of its children's are two different true numbers.
+    tokens: z.number().optional(),
+    toolUses: z.number().optional(),
+    lastTool: z.string().optional(),
+    // Its report — the last assistant message (SubagentStop) or the task summary. The answer to "what did it
+    // conclude?" without opening the transcript, which is the question a finished child is read for.
+    summary: z.string().optional(),
+    error: z.string().optional(),
+    // A delegation's live view: the tmux session its command runs in. Absent for an SDK subagent, which has no
+    // process of its own to attach to.
+    terminal: z.string().optional(),
+});
+export type SubagentSession = z.infer<typeof SubagentSessionSchema>;
+export const SubagentsListSchema = z.object({ sessions: z.array(SubagentSessionSchema) });
+export type SubagentsList = z.infer<typeof SubagentsListSchema>;
+export const SubagentIdParamSchema = z.object({ id: z.string() });
+
 // ---- environment: the overlay Dockerfile extending the sandbox image ----
 // The approved file is DAEMON-COMPOSED: pinned FROM + capability fragments + the owner-approved custom section.
 // The agent writes the proposal file (.intentic/environment.Dockerfile — custom-section content only, no FROM)

package/src/title.ts

@@ -15,8 +15,12 @@
  * names a turn that arrived without one — an automation, a Discord message, a webchat visitor (agents-
  * registry.ts). One rule, because two would let the same prompt open under two different names depending on
  * where it entered. Nothing here calls a model: the title has to exist before the first frame comes back.
- * (A model DOES get its say later — the daemon's title-summary pass renames a still-derived title once the
- * first turn has an answer to read — but that is a promotion over this title, never a replacement for it.) */
+ *
+ * Which is exactly the ceiling on it. Cutting is not naming — what comes out is the user's own sentence,
+ * shortened, and a column of those is scannable only where the users' sentences happened to differ early. The
+ * name a conversation ends up WEARING is written a second or two later by a model that reads the same prompt
+ * and answers in the fleet board's own shape (the daemon's title-namer.ts). This is the title that holds the
+ * tab until that arrives, and the one it keeps if nothing is connected to write a better one. */
 
 // The registry's title budget (agents-registry MAX_TITLE_LENGTH, the rename input's maxlength) — the widest
 // any surface stores. Every surface truncates in CSS to its own width, so the clamp here is a storage cap,

package/src/workspace-state.test.ts

@@ -0,0 +1,129 @@
+import type { FileContribution } from "@intentic/extension-api";
+import { describe, expect, it } from "vitest";
+import { staleQueryKeys, WORKSPACE_STATE_FILES } from "./workspace-state.js";
+
+// What the automations extension declares in its manifest, and what the memory extension WOULD declare if the
+// watcher reported its files. Literals rather than the real manifests: an extension package importing this one is
+// the dependency direction, so reaching back for them here would invert it. The real manifests are checked
+// against this rule where they are loaded — web's fileBindings.test.ts and the daemon's file-bindings.test.ts.
+const AUTOMATIONS: readonly FileContribution[] = [
+    { path: `.intentic/automations.json`, invalidates: [`automations`] },
+    { path: `.intentic/approvals/`, invalidates: [`automation-approvals`] },
+];
+
+describe(`staleQueryKeys`, () => {
+    it(`maps a manifest write to the queries it makes stale`, () => {
+        expect(staleQueryKeys([`.intentic/capabilities.json`], [])).toEqual([`capabilities`, `environment`, `panels`]);
+    });
+
+    it(`matches a name family and a one-file-per-entry directory through one prefix each`, () => {
+        // environment.Dockerfile, environment.custom.Dockerfile, environment.approved.Dockerfile — one entry.
+        expect(staleQueryKeys([`.intentic/environment.custom.Dockerfile`], [])).toEqual([`environment`]);
+        expect(staleQueryKeys([`.intentic/drafts/post-1.json`], [])).toEqual([`drafts`]);
+    });
+
+    it(`refreshes the Drafts view when the AGENT writes a draft`, () => {
+        // The regression this table was reorganized around: the drafts skill writes these files directly, so
+        // there is no browser mutation to hang an invalidate on — the watcher push is the only signal, and it
+        // used to be dropped on the floor.
+        expect(staleQueryKeys([`.intentic/drafts/post-1.json`], [])).toEqual([`drafts`]);
+    });
+
+    it(`ignores unrelated churn under .intentic/`, () => {
+        // The amplification that turned an iq index rebuild into an endless request storm: a prefix test on
+        // `.intentic/` alone would invalidate every one of these queries for each index write.
+        expect(staleQueryKeys([`.intentic/iq/index.db`, `.intentic/claude/projects/p/session.jsonl`], [])).toEqual([]);
+    });
+
+    it(`ignores a store's own temp file while it is mid-swap`, () => {
+        // jsonFile writes `.<name>.<pid>.tmp` beside the target precisely so the atomic rename can't be read as
+        // a write to the target itself. A trailing-tag temp would prefix-match and bill an extra refetch.
+        expect(staleQueryKeys([`.intentic/.settings.json.42.tmp`], [])).toEqual([]);
+        expect(staleQueryKeys([`.intentic/settings.json`], [])).toEqual([`settings`]);
+    });
+
+    it(`ignores ordinary workspace edits`, () => {
+        expect(staleQueryKeys([`src/main.ts`, `README.md`], [])).toEqual([]);
+    });
+
+    it(`dedupes keys across a batch that touches several manifests`, () => {
+        // A capability add recomposes the overlay, so both entries claim `environment` — one refetch, not two.
+        expect(staleQueryKeys([`.intentic/capabilities.json`, `.intentic/environment.Dockerfile`], [])).toEqual([
+            `capabilities`,
+            `environment`,
+            `panels`,
+        ]);
+    });
+
+    it(`invalidates an extension's queries from its own declaration`, () => {
+        expect(staleQueryKeys([`.intentic/automations.json`], AUTOMATIONS)).toEqual([`automations`]);
+        expect(staleQueryKeys([`.intentic/approvals/a1.json`], AUTOMATIONS)).toEqual([`automation-approvals`]);
+    });
+
+    it(`makes nothing stale for an extension that is not running`, () => {
+        // The reason the live set is passed in rather than read off the installed list: `automations` is the
+        // extension's query key, so with the extension gone there is no cache entry for it to be about. The core
+        // table used to carry these two keys itself, and would have kept invalidating them either way.
+        expect(staleQueryKeys([`.intentic/automations.json`, `.intentic/approvals/a1.json`], [])).toEqual([]);
+    });
+
+    it(`lets an extension claim a path the core table deliberately ignores`, () => {
+        // The two lists are unioned flat, not layered: a narrow extension entry under a broad core entry that
+        // invalidates nothing must still fire. Without this, every path beneath one of the daemon's
+        // machine-state prefixes would be unreachable to extensions.
+        const nested: readonly FileContribution[] = [{ path: `.intentic/claude/projects/p/memory/`, invalidates: [`memory`] }];
+        expect(staleQueryKeys([`.intentic/claude/projects/p/memory/note.md`], nested)).toEqual([`memory`]);
+        // …and a sibling under the same core prefix stays ignored.
+        expect(staleQueryKeys([`.intentic/claude/projects/p/session.jsonl`], nested)).toEqual([]);
+    });
+
+    it(`dedupes a key two extensions both claim`, () => {
+        const twice: readonly FileContribution[] = [
+            { path: `.intentic/automations.json`, invalidates: [`automations`] },
+            { path: `.intentic/automations.json`, invalidates: [`automations`] },
+        ];
+        expect(staleQueryKeys([`.intentic/automations.json`], twice)).toEqual([`automations`]);
+    });
+});
+
+describe(`WORKSPACE_STATE_FILES`, () => {
+    it(`declares every entry under .intentic/, root-relative and forward-slash`, () => {
+        for (const file of WORKSPACE_STATE_FILES) {
+            expect(file.path.startsWith(`.intentic/`), file.path).toBe(true);
+            expect(file.path.includes(`\\`), file.path).toBe(false);
+        }
+    });
+
+    it(`states a reason for every entry that invalidates nothing`, () => {
+        // An empty `invalidates` is a real answer (daemon machine state, a deliberately-polled surface, a path
+        // whose query keys belong to an extension), but a SILENT one is indistinguishable from the omission this
+        // table exists to prevent — which is exactly how drafts went missing. Requiring the reason is what makes
+        // the difference visible at review time.
+        for (const file of WORKSPACE_STATE_FILES) {
+            if (file.invalidates.length === 0) {
+                expect(file.why, `${file.path} invalidates nothing and must say why`).toBeTruthy();
+            } else {
+                expect(file.why, `${file.path} invalidates queries, so \`why\` is dead weight`).toBeUndefined();
+            }
+        }
+    });
+
+    it(`keeps directory entries slash-terminated so they cannot swallow a sibling`, () => {
+        // `.intentic/drafts` without the slash would also prefix-match a future `.intentic/drafts-archive.json`.
+        for (const file of WORKSPACE_STATE_FILES.filter((entry) => entry.invalidates.length > 0)) {
+            const isFamilyPrefix = file.path.endsWith(`.`);
+            const isFile = file.path.endsWith(`.json`) || file.path.endsWith(`.Dockerfile`);
+            expect(isFile || isFamilyPrefix || file.path.endsWith(`/`), file.path).toBe(true);
+        }
+    });
+
+    it(`has no entry that prefix-matches another, so one write can't be billed twice`, () => {
+        for (const file of WORKSPACE_STATE_FILES) {
+            const overlapping = WORKSPACE_STATE_FILES.filter((other) => other !== file && other.path.startsWith(file.path));
+            expect(
+                overlapping.map((other) => other.path),
+                `${file.path} is a prefix of another entry`,
+            ).toEqual([]);
+        }
+    });
+});