@intentic/sandbox-contract 1.170.0 → 1.171.0

package/src/index.ts

@@ -5,6 +5,7 @@ import { agentContract } from "./contracts/agent.contract.js";
 import { agentsContract } from "./contracts/agents.contract.js";
 import { automationsContract } from "./contracts/automations.contract.js";
 import { capabilitiesContract } from "./contracts/capabilities.contract.js";
+import { choresContract } from "./contracts/chores.contract.js";
 import { ciContract } from "./contracts/ci.contract.js";
 import { claudeContract } from "./contracts/claude.contract.js";
 import { codexContract } from "./contracts/codex.contract.js";
@@ -37,6 +38,7 @@ export { agentContract } from "./contracts/agent.contract.js";
 export { agentsContract } from "./contracts/agents.contract.js";
 export { automationsContract } from "./contracts/automations.contract.js";
 export { capabilitiesContract } from "./contracts/capabilities.contract.js";
+export { choresContract } from "./contracts/chores.contract.js";
 export { ciContract } from "./contracts/ci.contract.js";
 export { claudeContract } from "./contracts/claude.contract.js";
 export { codexContract } from "./contracts/codex.contract.js";
@@ -86,6 +88,7 @@ export const sandboxContract = {
     agents: agentsContract,
     automations: automationsContract,
     capabilities: capabilitiesContract,
+    chores: choresContract,
     ci: ciContract,
     claude: claudeContract,
     codex: codexContract,

package/src/schemas.ts

@@ -122,6 +122,12 @@ export const AgentTurnSchema = z
         // 'acceptEdits' auto-accepts file edits; 'bypassPermissions' runs everything. The agent can move
         // itself between modes mid-turn (EnterPlanMode/ExitPlanMode), which rides back as a `mode` frame.
         permissionMode: PermissionModeSchema.optional(),
+        /* Narrows the turn to these tool names (the SDK option of the same name — not to be confused with the
+         * daemon's MCP `tools`, which are servers). Absent ⇒ every tool the runtime has, which is what an
+         * owner-driven chat wants. Set by the automation dispatchers from Automation.allowedTools: a wake driven
+         * by an OUTSIDE message runs bypassPermissions like any other automation turn, so for a public Doorbell
+         * this list is the actual boundary — prompt wording is advice, an empty toolbox is not. */
+        allowedTools: z.array(z.string().min(1)).optional(),
         effort: z.string().optional(),
         thinking: z.boolean().optional(),
         // The opt-in editor context chip: what the user is looking at, folded into the prompt daemon-side.
@@ -286,6 +292,7 @@ export type AgentSummary = z.infer<typeof AgentSummarySchema>;
 // mutated agents back. The browser drops any roster older than the newest it has applied, and holds its own
 // pending change until a roster at or past the revision that applied it arrives. See useAgents.ts.
 export const AgentsListSchema = z.object({ agents: z.array(AgentSummarySchema), rev: z.number() });
+export type AgentsList = z.infer<typeof AgentsListSchema>;
 export const AgentIdSchema = z.object({ id: z.string().min(1) });
 // archive's input: the agents to take off the board. Absent `ids` ⇒ every finished agent that is archivable
 // right now (the lane header's "Clear"); unarchive always names its ids (a restore, or a bulk archive's undo).
@@ -353,6 +360,11 @@ export const LandConflictSchema = z.object({
     repo: z.string(),
     paths: z.array(LandConflictPathSchema),
     clean: z.number(),
+    // The branch the user's checkout is on — the thing the agent has to rebase onto. Carried because only the
+    // daemon can see it: an isolated turn's worktree is mounted over the agent's whole view, so the resolution
+    // errand could otherwise only tell it to go and read the name off `git worktree list`. Absent on a detached
+    // HEAD or a vanished checkout, where there is no name to give.
+    mainBranch: z.string().optional(),
 });
 export type LandConflict = z.infer<typeof LandConflictSchema>;
 
@@ -584,6 +596,7 @@ export const OauthAccountSchema = z.object({
 });
 export type OauthAccount = z.infer<typeof OauthAccountSchema>;
 export const OauthAccountListSchema = z.object({ accounts: z.array(OauthAccountSchema) });
+export type OauthAccountList = z.infer<typeof OauthAccountListSchema>;
 // Address one account of a provider (disconnect, and the turn's `account`).
 export const AccountIdSchema = z.object({ id: z.string().min(1) });
 // Rename one account of a provider whose credential the sandbox owns (Claude, Kimi). Blank ⇒ the daemon falls
@@ -663,6 +676,7 @@ export const SessionSummarySchema = z.object({
     // own heading is noise, not evidence. See AgentMatchSchema for the same field on the fleet's side.
     snippet: z.string().optional(),
 });
+export type SessionSummary = z.infer<typeof SessionSummarySchema>;
 export const SessionsListSchema = z.object({ sessions: z.array(SessionSummarySchema) });
 
 // ---- settings: per-sandbox agent settings (.intentic/settings.json) ----
@@ -1254,24 +1268,37 @@ export type FileDiff = z.infer<typeof FileDiffSchema>;
 
 // ---- workspace tree + files ----
 
-// One node of the full /work filesystem tree the agent sees (untracked + generated files included), distinct
-// from the git-tracked listing. `path` is root-relative with forward slashes so it feeds straight back to the
-// file route. Recursive via zod's getter form (so the type is inferred, not hand-annotated).
-export const WorkspaceTreeEntrySchema = z.object({
+/* One node of the full /work filesystem tree the agent sees (untracked + generated files included), distinct
+ * from the git-tracked listing. `path` is root-relative with forward slashes so it feeds straight back to the
+ * file route.
+ *
+ * Recursive, and the type is declared rather than inferred. Zod's getter form does infer one, but it collapses
+ * to `{}` below the first level of nesting — so `entry.children[0].name` type-checked as an index-signature
+ * read on both sides of the wire, and the tree walker's own suite was reading a `hidden` field off entries
+ * that has never existed there without the compiler minding. The interface is the contract; the schema
+ * validates against it, and z.ZodType makes a divergence between the two an error here. */
+export interface WorkspaceTreeEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly type: "file" | "dir";
+    readonly size?: number | undefined;
+    // Ignored-by-tooling (node_modules, .git, .gitignore'd paths, browser profiles): the client grays the row.
+    readonly ignored?: boolean | undefined;
+    // A DIR without `children` was listed but not descended into — because it's ignored, or because the walk's
+    // breadth-first budget stopped above it. Either way the client lazy-loads it via /workspace/children on
+    // expand, so "not loaded yet" and "empty directory" (`children: []`) stay distinguishable.
+    readonly children?: readonly WorkspaceTreeEntry[] | undefined;
+}
+export const WorkspaceTreeEntrySchema: z.ZodType<WorkspaceTreeEntry> = z.object({
     name: z.string(),
     path: z.string(),
     type: z.enum(["file", "dir"]),
     size: z.number().optional(),
-    // Ignored-by-tooling (node_modules, .git, .gitignore'd paths, browser profiles): the client grays the row.
     ignored: z.boolean().optional(),
-    // A DIR without `children` was listed but not descended into — because it's ignored, or because the walk's
-    // breadth-first budget stopped above it. Either way the client lazy-loads it via /workspace/children on
-    // expand, so "not loaded yet" and "empty directory" (`children: []`) stay distinguishable.
     get children() {
         return z.array(WorkspaceTreeEntrySchema).optional();
     },
 });
-export type WorkspaceTreeEntry = z.infer<typeof WorkspaceTreeEntrySchema>;
 export const WorkspaceTreeSchema = z.object({
     root: z.string(),
     tree: z.array(WorkspaceTreeEntrySchema),
@@ -1332,14 +1359,20 @@ export type WorkspaceClassification = z.infer<typeof WorkspaceClassificationSche
 // The workspace-search wire shape — shared by the daemon's /workspace/search route and the web client.
 // (Implementation detail, not part of the contract: the daemon backs this route with a resident in-process iq
 // engine; the engine is interchangeable behind this shape.) Groups are relevance-ranked (best first, never path
-// order); each hit carries the match-reason tags the fused engines contributed. `start`/`end` are char offsets
-// within `text` so clients highlight without re-finding the needle.
+// order); each hit carries the match-reason tags the fused engines contributed, and the char spans within `text`
+// that matched, so clients highlight without re-finding the needle.
 export const WorkspaceSearchQuerySchema = z.object({
     query: z.string().min(2).max(512),
     // Search verbs only — anchor/git verbs (outline, context, log, who, …) are CLI-only surface. Natural language
     // has no verb of its own: `q` classifies the query and answers it semantically when the words call for it.
     mode: z.enum(["q", "find", "files", "def", "refs", "sym", "ast"]).optional(),
     includeIgnored: z.stringbool().optional(),
+    // How `find` reads the query — the three switches every editor's search box has (VSCode: Aa, ab, .*).
+    // `literal` treats it as fixed text instead of a regex; `caseSensitive` off means case-INSENSITIVE, not
+    // ripgrep's smart case.
+    literal: z.stringbool().optional(),
+    word: z.stringbool().optional(),
+    caseSensitive: z.stringbool().optional(),
     limit: z.coerce.number().int().positive().optional(),
     after: z.string().optional(),
 });
@@ -1348,11 +1381,14 @@ export const WorkspaceSearchTagSchema = z.object({
     score: z.number().optional(),
 });
 export type WorkspaceSearchTag = z.infer<typeof WorkspaceSearchTagSchema>;
+export const WorkspaceSearchSpanSchema = z.object({ start: z.number(), end: z.number() });
+export type WorkspaceSearchSpan = z.infer<typeof WorkspaceSearchSpanSchema>;
 export const WorkspaceSearchHitSchema = z.object({
     line: z.number(),
     text: z.string(),
-    start: z.number().optional(),
-    end: z.number().optional(),
+    // Every matched span in `text`, in order — a text search marks all of them, the way an editor does. Empty
+    // where the LINE is the match and no span of it is (a semantic or definition hit reports none).
+    spans: z.array(WorkspaceSearchSpanSchema),
     tags: z.array(WorkspaceSearchTagSchema),
     // Enclosing symbol ("createWidget (fn)") — parent-document context so the reader often needs no follow-up.
     context: z.string().optional(),
@@ -1374,12 +1410,19 @@ export type WorkspaceSearchFreshness = z.infer<typeof WorkspaceSearchFreshnessSc
 export const WorkspaceSearchResultSchema = z.object({
     mode: z.string(),
     total: z.number(),
+    // Files the query matched in total, which `groups` reports only for the page it carries — the count a
+    // results panel puts beside the hit total ("218 results in 61 files").
+    files: z.number(),
     shown: z.number(),
     groups: z.array(WorkspaceSearchGroupSchema),
     freshness: WorkspaceSearchFreshnessSchema,
     truncated: z.boolean(),
     cursor: z.string().optional(),
     hint: z.string().optional(),
+    // What the engine did with the query that the query did not ask for — a pattern rerun as literal text
+    // because it is not valid regex, grep-style escapes rewritten, a language filter that matched no files. The
+    // text surface has always printed this above the results; a JSON caller could not see it at all.
+    note: z.string().optional(),
     // Code-graph neighbors of the top hits (definition anchors + the strongest caller of each).
     related: z.array(z.string()).optional(),
     // Ranked `path:line` anchors that placed but were NOT shown, best first — the answer often sits at rank 5–13,
@@ -2103,12 +2146,130 @@ export const TriggerSchema = z.discriminatedUnion("kind", [
 ]);
 export type Trigger = z.infer<typeof TriggerSchema>;
 
+/* The Doorbell widget's settings — everything about the embeddable chat that isn't the automation's prompt.
+ * Present only on `webchat` listener automations; the trigger keeps `allowedOrigins` because that one is the
+ * admission gate the message route reads, not a rendering choice.
+ *
+ * Split deliberately into what the WIDGET may read (title/greeting/accent/position/access/googleClientId/
+ * turnstileSiteKey — all public by construction, they ship to a stranger's browser) and what only the daemon
+ * may read (turnstileSecret). GET /webchat/<id>/config serves the first group by naming it, never by omitting
+ * the second: a field added here is invisible to the widget until it is listed there. */
+export const WebchatConfigSchema = z.object({
+    // `public` admits anyone; `google` refuses a message that carries no verifiable Google ID token. Absent ⇒
+    // public — a Doorbell with no access setting is the anonymous support box it looks like.
+    access: z.enum(["public", "google"]).optional(),
+    // Ask an anonymous visitor for a display name before the first message. Cosmetic: the name is typed, so it
+    // reaches the model as untrusted `displayName`, never as identity.
+    requireName: z.boolean().optional(),
+    /* The bot ceiling. `turnstile` is Cloudflare's (invisible, needs the site's own keys); `pow` is a
+     * hashcash-style challenge the daemon issues and the widget solves in a worker, so a site with no
+     * Cloudflare account still has something. Absent ⇒ off: the origin allowlist and the rate limit are then
+     * the whole boundary, which is the right default for an internal or invite-only page. */
+    antiBot: z.enum(["turnstile", "pow"]).optional(),
+    turnstileSiteKey: z.string().optional(),
+    turnstileSecret: z.string().optional(),
+    // The site's OWN Google OAuth web client id. It cannot be intentic's: Google Identity Services only issues
+    // a token to an authorized JavaScript origin, and intentic's client can't list every customer domain.
+    googleClientId: z.string().optional(),
+    // Widget chrome. `accent` is any CSS colour the host page can render; `position` picks the launcher corner.
+    title: z.string().max(80).optional(),
+    greeting: z.string().max(500).optional(),
+    accent: z.string().max(40).optional(),
+    position: z.enum(["top-right", "top-left", "bottom-right", "bottom-left"]).optional(),
+    /* Two ceilings on top of the route's fixed per-minute window, because a public endpoint's real exposure is
+     * cost, not request rate: `dailyMessageMax` caps the whole automation per UTC day, `conversationMessageMax`
+     * caps one visitor thread for its lifetime.
+     *
+     * `dailyMessageMax` absent ⇒ WEBCHAT_DAILY_MAX_DEFAULT, not uncapped. Every message here is an agent turn
+     * billed to the owner, and the per-minute window bounds the RATE without bounding the DAY — twenty a minute,
+     * sustained, is tens of thousands of turns before anyone notices. A Doorbell nobody configured should not be
+     * able to spend that, so the safe number is the one you get for free and the owner raises it deliberately.
+     * `conversationMessageMax` stays optional-means-uncapped: it is per visitor thread, which the daily ceiling
+     * already bounds in aggregate. */
+    dailyMessageMax: z.number().int().positive().optional(),
+    conversationMessageMax: z.number().int().positive().optional(),
+    // (WEBCHAT_DAILY_MAX_DEFAULT, below the schema, is the number `dailyMessageMax` falls back to.)
+    // How long a visitor thread keeps resuming the same conversation before the next message starts a fresh
+    // one. Absent ⇒ WEBCHAT_SESSION_TTL_MS (the daemon's default).
+    sessionTtlMinutes: z.number().int().positive().optional(),
+});
+export type WebchatConfig = z.infer<typeof WebchatConfigSchema>;
+
+/* The daily agent-turn ceiling a Doorbell gets when its owner sets none. Lives here rather than beside the
+ * route that enforces it because both ends need the number: the daemon to apply it, and the automation editor
+ * to show the owner what they are already protected by (an invisible limit is one people hit and file as a bug).
+ *
+ * 200 is chosen to be irrelevant to real support traffic and decisive against a script. A Doorbell answering
+ * two hundred questions in one UTC day is a busy one; a scripted flood reaches that in ten seconds and then
+ * stops costing anything. */
+export const WEBCHAT_DAILY_MAX_DEFAULT = 200;
+
+/* ---- the widget wire: three shapes GET /webchat/<id>/config, GET …/challenge and POST …/message speak ----
+ *
+ * They live here, beside the stored config they derive from, because the Doorbell widget is a SECOND client of
+ * this daemon — a bundle running on a stranger's page — and the reason this package exists is that both ends of
+ * a wire read one definition. The widget imports these as types only (`import type`), so zod never reaches a
+ * visitor's browser. */
+
+// What the widget is told about itself. Fully RESOLVED — every default is applied daemon-side, so the widget
+// carries no fallback logic and one place decides what an unset field means. Everything here is public by
+// construction: it ships to any browser that can reach the endpoint from an allowed origin.
+export const WebchatPublicConfigSchema = z.object({
+    automationId: z.string(),
+    title: z.string(),
+    greeting: z.string(),
+    accent: z.string(),
+    position: z.enum(["top-right", "top-left", "bottom-right", "bottom-left"]),
+    access: z.enum(["public", "google"]),
+    requireName: z.boolean(),
+    // "off" is spelled out rather than left absent: the widget branches on this, and a missing field that means
+    // "no challenge" is the kind of default that turns one serialization bug into an open door.
+    antiBot: z.enum(["turnstile", "pow", "off"]),
+    turnstileSiteKey: z.string().optional(),
+    googleClientId: z.string().optional(),
+});
+export type WebchatPublicConfig = z.infer<typeof WebchatPublicConfigSchema>;
+
+// A proof-of-work challenge: find a nonce whose SHA-256 of `${salt}:${nonce}` starts with `difficulty` zero
+// bits. Issued per visitor conversation, spent on its first message.
+export const WebchatChallengeSchema = z.object({ salt: z.string(), difficulty: z.number().int().positive() });
+export type WebchatChallenge = z.infer<typeof WebchatChallengeSchema>;
+
+// One visitor message. `conversationId` is the widget's own localStorage id — it threads the visitor's messages
+// into ONE sandbox conversation, so it is the thread key, not a secret (anyone can mint one; the origin
+// allowlist, the challenge and the rate limit are the gate).
+export const WebchatMessageSchema = z.object({
+    conversationId: z.string().min(1).max(200),
+    content: z.string().min(1),
+    // What the visitor TYPED as their name. Never identity — it reaches the model tagged as unverified, and a
+    // signed-in visitor's verified name comes from the ID token instead.
+    displayName: z.string().max(200).optional(),
+    // A Google ID token from the site's own client id, verified daemon-side against Google's JWKS.
+    idToken: z.string().optional(),
+    // The anti-bot answer, whichever kind the config asked for. Checked once per conversation, not per message.
+    turnstileToken: z.string().optional(),
+    powNonce: z.string().optional(),
+    // The widget's own transcript, sent ONLY on the first message of a thread — after that the sandbox
+    // conversation resumes and carries its own context.
+    history: z
+        .array(z.object({ author: z.string().optional(), content: z.string() }))
+        .max(50)
+        .optional(),
+});
+export type WebchatMessage = z.infer<typeof WebchatMessageSchema>;
+
 export const AutomationSchema = z.object({
     id: entryId,
     trigger: TriggerSchema,
     // Shell command run in the workspace root before waking; exit 0 ⇒ wake, non-zero ⇒ the run is "skipped".
     guard: z.string().min(1).optional(),
     prompt: z.string().min(1),
+    // The Doorbell widget's settings — `webchat` listener automations only, ignored on every other trigger.
+    webchat: WebchatConfigSchema.optional(),
+    // The tool names this automation's wake may call (AgentTurnSchema.allowedTools). The reason it exists: a
+    // webchat automation is driven by strangers, and an automation turn runs bypassPermissions by default — so
+    // the allowlist, not the prompt's wording, is what bounds what an injected instruction can reach.
+    allowedTools: z.array(z.string().min(1)).optional(),
     // Which provider adapter serves the wake; absent ⇒ claude. Same dispatch as a chat turn (AgentTurnSchema.agent).
     agent: AgentProviderSchema.optional(),
     // Which harness (agentic loop) runs the wake; absent ⇒ native. Same semantics as AgentTurnSchema.harness.
@@ -2664,6 +2825,7 @@ export const InfoSchema = z.object({
     latest: z.string().optional(),
     updateAvailable: z.boolean().optional(),
 });
+export type Info = z.infer<typeof InfoSchema>;
 
 // A daemon-minted session (system.session): the steady-state browser credential, exchanged for a verified
 // Google ID token so Google UI is a sign-in moment instead of an hourly renewal. `expiresAt` is epoch ms —
@@ -2970,3 +3132,211 @@ export const PushConfigQuerySchema = z.object({ endpoint: z.string().url().optio
 // the question being asked. A count separates "your OS swallowed it" from "nothing was sent at all".
 export const PushTestSchema = z.object({ delivered: z.number().int().nonnegative() });
 export type PushTest = z.infer<typeof PushTestSchema>;
+
+// ---- maintenance: the standing evidence a chore is decided from ----
+
+/* THE DAEMON SERVES FACTS; THE BROWSER DECIDES. Everything below is measurement — what a tool reported, what the
+ * manifests say, when a chore last ran. Not one field here says "you should do something", and that is the whole
+ * boundary: which chore is DUE is computed by @intentic/sandbox-contract/chores, which both the Maintenance view and its rail
+ * badge run, so the number on the tile and the reason in the panel can never disagree. Put the verdict on the wire
+ * instead and a daemon one image behind would be quietly arguing with the browser about what needs doing.
+ *
+ * The split inside the evidence is by COST, not by subject:
+ *   probes   subprocesses (pnpm outdated, pnpm audit, knip, jscpd) — minutes, so they are cached on disk with a
+ *            TTL and refreshed by a background runner. A route hit never waits on one.
+ *   signals  things the daemon already knows — the resident iq index's health ranking, the package manifests it
+ *            reads for the dependency graph, its own node version. Recomputed per request; all of it is cheap. */
+
+export const PROBE_IDS = ["outdated", "audit", "knip", "jscpd"] as const;
+export const ProbeIdSchema = z.enum(PROBE_IDS);
+export type ProbeId = z.infer<typeof ProbeIdSchema>;
+
+// One dependency the registry has moved past. `kind` is the SEMVER distance, which is the whole reason this is
+// not one number: forty patch releases behind is a morning's work and one major is a project.
+export const OutdatedPackageSchema = z.object({
+    name: z.string(),
+    current: z.string(),
+    latest: z.string(),
+    kind: z.enum(["major", "minor", "patch"]),
+    // "dependencies" / "devDependencies" / "optionalDependencies" — a dev-only major is a different risk.
+    section: z.string(),
+});
+export type OutdatedPackage = z.infer<typeof OutdatedPackageSchema>;
+
+// One advisory, reduced to what a decision needs. No CVSS vector and no reference list: those are for reading on
+// the advisory page, and carrying them would put a kilobyte of prose per finding on every poll of this route.
+export const AdvisorySchema = z.object({
+    name: z.string(),
+    severity: z.enum(["critical", "high", "moderate", "low", "info"]),
+    title: z.string(),
+    // The range that fixes it, when the advisory names one. Absent ⇒ no patch published yet, which is the case
+    // where a chore must NOT offer to bump and say so instead.
+    patched: z.string().optional(),
+    // Whether it reaches a production dependency path. A build-time-only tool's transitive CVE is a different
+    // problem, and the chore's prompt says so rather than treating every advisory alike.
+    dev: z.boolean(),
+});
+export type Advisory = z.infer<typeof AdvisorySchema>;
+
+// knip's counts, by the kind of thing it found unreachable. Counts plus a sample rather than the full list: the
+// agent re-runs knip itself against the live tree (a list from a probe hours old would send it at files that are
+// already gone), so what travels here only has to be enough to decide whether the turn is worth starting.
+export const DeadCodeSchema = z.object({
+    files: z.number().int().nonnegative(),
+    exports: z.number().int().nonnegative(),
+    types: z.number().int().nonnegative(),
+    dependencies: z.number().int().nonnegative(),
+    devDependencies: z.number().int().nonnegative(),
+    // A handful of the unreferenced files, for the panel to show instead of asking the reader to take "31" on faith.
+    sample: z.array(z.string()),
+});
+export type DeadCode = z.infer<typeof DeadCodeSchema>;
+
+// jscpd's headline plus the biggest clones. `percentage` is of scanned lines, which is the figure a threshold is
+// worth setting against — a clone COUNT grows with the repo and would mean something different every quarter.
+export const DuplicationSchema = z.object({
+    percentage: z.number(),
+    clones: z.number().int().nonnegative(),
+    top: z.array(z.object({ lines: z.number().int().nonnegative(), first: z.string(), second: z.string() })),
+});
+export type Duplication = z.infer<typeof DuplicationSchema>;
+
+/* One probe's cached result. The three states are deliberately distinct, because a panel that collapses them
+ * lies about the most important case:
+ *   ok           the tool ran and reported. `facts` carries its findings — including "nothing found", which is
+ *                a real answer and the one that keeps a chore quiet.
+ *   unavailable  the tool is not part of this repo (knip is not a devDependency, there is no lockfile to audit).
+ *                Not a failure and not evidence of health: the chore renders as unmeasured, and can never badge.
+ *   failed       the tool ran and broke — a network-less audit, a jscpd that ran out of memory. Says so, with
+ *                the tail of what it printed, rather than reading as "clean".
+ * Merging `unavailable` into `ok`-with-zeros is how a maintenance surface ends up reporting a green repository
+ * it has never actually measured. */
+export const ProbeStateSchema = z.enum(["ok", "unavailable", "failed"]);
+export type ProbeState = z.infer<typeof ProbeStateSchema>;
+
+// The findings, discriminated by which probe produced them. Absent while the probe has never completed, and on
+// `unavailable`/`failed` — a reader must go through `state` to reach facts, so there is no shape in which a
+// missing measurement can be mistaken for a zero.
+export const ProbeFactsSchema = z.discriminatedUnion("id", [
+    z.object({ id: z.literal("outdated"), packages: z.array(OutdatedPackageSchema) }),
+    z.object({ id: z.literal("audit"), advisories: z.array(AdvisorySchema) }),
+    z.object({ id: z.literal("knip"), deadCode: DeadCodeSchema }),
+    z.object({ id: z.literal("jscpd"), duplication: DuplicationSchema }),
+]);
+export type ProbeFacts = z.infer<typeof ProbeFactsSchema>;
+
+export const ProbeResultSchema = z.object({
+    id: ProbeIdSchema,
+    state: ProbeStateSchema,
+    // When the probe last COMPLETED — the age the panel shows, and what the runner's TTL is measured from.
+    ranAt: z.number(),
+    // How long it took. Shown because a seven-minute jscpd is why the tier-2 refresh is weekly, and a reader
+    // deciding whether to force a refresh deserves to know what they are asking for.
+    tookMs: z.number().int().nonnegative(),
+    facts: ProbeFactsSchema.optional(),
+    // Why it is unavailable, or how it failed — the tail of the tool's own output. Never invented here.
+    reason: z.string().optional(),
+});
+export type ProbeResult = z.infer<typeof ProbeResultSchema>;
+
+// One workspace package as its manifest declares it — what the daemon already reads to build the dependency
+// graph, carried through so chores can reason about the repo's own shape without a probe. `documented` is the
+// one derived field: whether docs/architecture/<dir>/doc.md exists, a stat per package.
+export const ChorePackageSchema = z.object({
+    dir: z.string(),
+    name: z.string(),
+    // The manifest's `engines` map, verbatim — the runtime chore compares it against what the daemon is running.
+    engines: z.record(z.string(), z.string()).optional(),
+    dependencies: z.array(z.string()),
+    devDependencies: z.array(z.string()),
+    documented: z.boolean(),
+});
+export type ChorePackage = z.infer<typeof ChorePackageSchema>;
+
+/* The cheap half of the evidence: what the daemon knows without starting anything. `hotspots` and `keyModules`
+ * are the same rankings GET /workspace/health serves, capped tighter — a chore only ever asks whether a file has
+ * ENTERED the top of the ranking, so a leaderboard is enough and a full report per repo per poll is not. */
+/* WHAT THIS REPOSITORY IS MADE OF — the facts that decide whether a chore is a QUESTION worth asking of it at
+ * all, as opposed to whether the answer happens to be yes.
+ *
+ * The distinction is the difference between a maintenance surface that reads as attentive and one that reads as
+ * generic. "Re-read the documentation against the code" in a repository with no documentation is not a chore
+ * that is currently clear — it is a chore that will never make sense here, and showing it teaches the owner that
+ * this list was written by someone who had not looked. Same for a Docker chore with no Dockerfile, or a CI chore
+ * with no pipeline.
+ *
+ * These are all paths, deliberately: presence of a FILE is checkable, cheap, and cannot be argued with, which is
+ * the same evidence-over-identity rule the extension activation facts follow. Every field is a list rather than a
+ * boolean where the paths themselves are worth showing — a chore that says "not applicable: no Dockerfile" is
+ * useful, and one that says "3 Dockerfiles: ./Dockerfile, _apps/web/Dockerfile, …" is more so. */
+export const ChoreShapeSchema = z.object({
+    // Architecture documents that actually exist (docs/architecture/**/doc.md), capped — the count is what
+    // matters, and the drift survey needs to know there is something to re-read.
+    docs: z.array(z.string()),
+    dockerfiles: z.array(z.string()),
+    // CI pipeline definitions: .github/workflows/*.yml, .gitlab-ci.yml, and the other single-file conventions.
+    ci: z.array(z.string()),
+    // Whether dependencies are resolved to a lockfile — what makes an audit mean anything.
+    lockfile: z.boolean(),
+    // A package.json at the repo root. The gate for every chore whose subject is the JavaScript dependency tree:
+    // a Rust or Go repository has no majors to be behind on and no engines field to be pinned by, and offering it
+    // those chores would be this surface guessing at what it is looking at.
+    packageManifest: z.boolean(),
+});
+export type ChoreShape = z.infer<typeof ChoreShapeSchema>;
+
+export const ChoreSignalsSchema = z.object({
+    packages: z.array(ChorePackageSchema),
+    shape: ChoreShapeSchema,
+    hotspots: z.array(WorkspaceHotspotSchema),
+    keyModules: z.array(WorkspaceKeyModuleSchema),
+    totals: z.object({ files: z.number(), symbols: z.number(), complexity: z.number(), hotspots: z.number() }),
+    // Whether the index these rankings came from is current. A chore must not fire on a half-built index, and
+    // this is how the browser knows to hold its verdict rather than act on a partial ranking.
+    indexed: z.boolean(),
+});
+export type ChoreSignals = z.infer<typeof ChoreSignalsSchema>;
+
+// What a finished chore turn left behind — written by the agent, read back to decide whether the chore is still
+// due. `clean` is the load-bearing one: an agent that looked and found the tool's findings to be false positives
+// must be able to say so, or the next poll starts the same turn again forever.
+export const ChoreOutcomeSchema = z.enum(["acted", "reported", "clean"]);
+export type ChoreOutcome = z.infer<typeof ChoreOutcomeSchema>;
+
+/* One chore's history in one repo. The DIGEST is what makes this a debounce rather than a suppression: it is a
+ * hash of the evidence that was standing when the turn ran, so a chore whose evidence has since changed is due
+ * again on its own merits while one whose evidence is unchanged stays quiet — with the run still visible in the
+ * panel, saying when it ran and what it concluded. Nothing here can hide a chore from the view; it only decides
+ * whether the rail is allowed to speak. */
+export const ChoreLedgerEntrySchema = z.object({
+    repo: z.string(),
+    chore: z.string(),
+    ranAt: z.number(),
+    runId: z.string(),
+    outcome: ChoreOutcomeSchema,
+    digest: z.string(),
+    // Set by the owner from the panel — the chore stays visible and stays out of the badge until this passes.
+    // Distinct from opting out, which is the absence of the chore from `enabled` in the sandbox's settings.
+    snoozedUntil: z.number().optional(),
+});
+export type ChoreLedgerEntry = z.infer<typeof ChoreLedgerEntrySchema>;
+
+// GET /chores — every discovered repo's standing evidence, plus the ledger, in one read. One route rather than
+// one per repo because the rail badge scans ALL of them on a timer, and N requests a minute to answer "is
+// anything due" is the kind of poll that shows up in a battery graph.
+export const ChoresReportSchema = z.object({
+    repos: z.array(z.object({ repo: z.string(), probes: z.array(ProbeResultSchema), signals: ChoreSignalsSchema })),
+    ledger: z.array(ChoreLedgerEntrySchema),
+    // The daemon's own runtime, for the chore that asks whether this sandbox is running something end-of-life.
+    // Read off the process rather than a manifest: what is INSTALLED is the fact that matters, and an `engines`
+    // range is a wish.
+    node: z.string(),
+});
+export type ChoresReport = z.infer<typeof ChoresReportSchema>;
+
+// POST /chores/probe — force one probe to re-run now, ahead of its TTL. Returns immediately; the runner does the
+// work and the next GET /chores carries the result, the same shape the panel already polls.
+export const ChoreProbeRequestSchema = z.object({ repo: z.string().min(1), id: ProbeIdSchema });
+// POST /chores/ledger — record a run, or snooze. Written daemon-side rather than by the browser so a chore turn
+// started from anywhere (the panel, an automation, the agent itself) lands in one ledger.
+export const ChoreLedgerWriteSchema = ChoreLedgerEntrySchema;

package/src/tunnel-ids.test.ts

@@ -0,0 +1,49 @@
+import { expect, test } from "vitest";
+import { hostSshIdFromToken, PORT_SLOT_COUNT, portSlotsFromToken, sandboxIdFromToken } from "./tunnel-ids.js";
+
+const TOKEN = "connect-token-one";
+const OTHER = "connect-token-two";
+
+test("the sandbox id is a stable 12-hex digest of the connect token, and absent without one", () => {
+    expect(sandboxIdFromToken(TOKEN)).toMatch(/^[0-9a-f]{12}$/);
+    expect(sandboxIdFromToken(TOKEN)).toBe(sandboxIdFromToken(TOKEN));
+    expect(sandboxIdFromToken(OTHER)).not.toBe(sandboxIdFromToken(TOKEN));
+    expect(sandboxIdFromToken("")).toBeUndefined();
+});
+
+test("a host ssh id is salted per host, so two deploy targets never collide", () => {
+    expect(hostSshIdFromToken(TOKEN, "web-1")).toMatch(/^[0-9a-f]{12}$/);
+    expect(hostSshIdFromToken(TOKEN, "web-1")).not.toBe(hostSshIdFromToken(TOKEN, "web-2"));
+});
+
+test("port slots are a fixed-size pool of DNS-safe labels, stable per token", () => {
+    const slots = portSlotsFromToken(TOKEN);
+    // Fixed size: the pool is the cap on preview DNS records a sandbox costs the shared zone.
+    expect(slots).toHaveLength(PORT_SLOT_COUNT);
+    // Every label must survive as one DNS label AND pass the platform's mint filter
+    // (/^(preview|port)-[a-z0-9][a-z0-9-]*$/, ≤50 chars), which `port-<slot>` has to satisfy.
+    for (const slot of slots) {
+        expect(slot).toMatch(/^[0-9a-f]{12}$/);
+        expect(`port-${slot}`).toMatch(/^port-[a-z0-9][a-z0-9-]*$/);
+        expect(`port-${slot}`.length).toBeLessThanOrEqual(50);
+    }
+    // Distinct, or two forwards would fight over one hostname.
+    expect(new Set(slots).size).toBe(PORT_SLOT_COUNT);
+    // Stable: the daemon and the platform derive these independently and must agree, and a restart has to
+    // land on the records already minted rather than orphaning them.
+    expect(portSlotsFromToken(TOKEN)).toEqual(slots);
+});
+
+/* The whole point of the salt. The sandbox id is public — it is the leading label of the sandbox's own URL and
+ * of every preview link its owner has shared — so anything derived from the id ALONE is derivable by whoever
+ * holds one of those links. Slots must not be: knowing a sandbox's id must not tell you where its forwarded
+ * ports live. */
+test("slots are not derivable from the sandbox id — only from the token behind it", () => {
+    expect(portSlotsFromToken(OTHER)).not.toEqual(portSlotsFromToken(TOKEN));
+    // No slot leaks the id it will be paired with in `port-<slot>-<sandboxId>`.
+    const id = sandboxIdFromToken(TOKEN);
+    expect(id).toBeDefined();
+    expect(portSlotsFromToken(TOKEN)).not.toContain(id);
+    // And none of them is the old fixed alphabet, which is what made the hostnames guessable.
+    expect(portSlotsFromToken(TOKEN).some((slot) => slot.length === 1)).toBe(false);
+});

package/src/tunnel-ids.ts

@@ -17,3 +17,27 @@ export const sandboxIdFromToken = (connectToken: string): string | undefined =>
 // own ssh-<id>.<zone> (no collision across hosts). Shared by the CLI (createHostSshTunnel) and the platform API
 // (provisionHostSshTunnel), which MUST derive the identical id.
 export const hostSshIdFromToken = (connectToken: string, hostName: string): string => sha256Hex(`${connectToken}:${hostName}`).slice(0, 12);
+
+/* How many port-forward slots a sandbox has. Eight is enough for a monorepo's worth of concurrent dev servers,
+ * and it is the hard cap on preview DNS records a sandbox can ever cost the shared intentic zone. */
+export const PORT_SLOT_COUNT = 8;
+
+/* THE PORT-FORWARD SLOT LABELS — the `port-<slot>` half of `port-<slot>-<sandboxId>.<zone>`.
+ *
+ * These were the letters a…h, and that was the hole: a forwarded port's hostname was then a pure function of the
+ * sandbox id, and the sandbox id is not a secret — it is the leading label of the URL the owner uses daily and
+ * of every preview link they have ever shared. So anyone who had seen ONE preview link could poll eight fixed
+ * names forever and catch whatever the owner forwarded, at any point in the future. The Ports view says a
+ * forwarded port is public, and it is; what it could not say was that "public" meant eight guessable URLs.
+ *
+ * Salting with the connect token fixes that without costing anything the letters bought. Still exactly eight
+ * records (the reason slots exist at all — the intentic-provided zone mints per label, and dev servers churn
+ * ephemeral ports far faster than DNS should), still stable across restarts so a slot's record stays warm, and
+ * still derivable with no coordination by every party that already holds the token: the daemon that forwards,
+ * and the platform that mints the DNS. A party without the token has no business predicting these names.
+ *
+ * The browser is deliberately NOT one of those parties — it never derives a port hostname, it reads `previewUrl`
+ * off the daemon's response — which is why this can live here, in the node-only half of the contract, next to
+ * the digest it shares with sandboxIdFromToken. */
+export const portSlotsFromToken = (connectToken: string): readonly string[] =>
+    Array.from({ length: PORT_SLOT_COUNT }, (_, index) => sha256Hex(`${connectToken}:port:${index}`).slice(0, 12));

package/src/workspace-state.ts

@@ -77,6 +77,11 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
      * Both entries below are outside that by design, so an empty set is the honest record — naming a key no
      * query uses would put the drift this table exists to remove straight back into it. Each says which
      * constraint would have to move first, so the next reader doesn't re-derive it. */
+    {
+        path: ".intentic/webchat-sessions.json",
+        invalidates: [],
+        why: "Doorbell thread bookkeeping (visitor thread → sandbox conversation + provider session), written on EVERY visitor message. Nothing in the browser reads it: what a visitor's chat produces is a conversation, and the fleet board already learns about that from the agent registry's own push. Naming a key here would bill every connected browser a refetch per inbound message — the request storm this table's own note warns about — to refresh nothing it can see.",
+    },
     {
         path: ".intentic/extension-settings.json",
         invalidates: [],