@intentic/sandbox-contract 1.176.3 → 1.209.0

package/src/workspace-state.ts

@@ -1,4 +1,5 @@
-import type { FileContribution } from "@intentic/extension-api";
+import { STATE_DIR } from "@intentic/constants";
+import type { FileContribution } from "@intentic/extension-manifest";
 import type { StateFile } from "./state-portability.js";
 
 /* WHICH WORKSPACE FILE BACKS WHICH CORE VIEW — one declaration, read by both sides of the wire.
@@ -49,9 +50,48 @@ export interface WorkspaceStateFile extends StateFile {
     readonly invalidates: readonly string[];
     // Why this file has no invalidations, for the entries that declare none. Absent when it has some.
     readonly why?: string;
+    /* Whether this entry is TRACKED by the root repo — the third thing an entry declares, and the one an owner
+     * sees most directly: a tracked entry gets a diff in the Changes review and a line in `git log`, so a change
+     * to how this sandbox behaves can be read, reverted, and attributed.
+     *
+     * ABSENT IS THE ANSWER FOR ALMOST EVERYTHING, and deliberately so. The root repo excludes `.intentic`
+     * wholesale and this flag is the only thing that carves an entry back out, so a store added later is
+     * untracked until someone says otherwise — the same default-deny the `portability` classes are built on, for
+     * the same reason. An ignore-pattern list would invert it: a credential store added next month would be
+     * committed on its first write, and nothing would have had to change for that to happen.
+     *
+     * Only CONFIGURATION belongs here — the small, slow-moving files that decide how this sandbox behaves. Two
+     * kinds of entry are excluded on purpose even though they are `carry` and hold no secret:
+     *   - LEDGERS (workflow runs, loop iterations, thread bookkeeping, permission-usage batches), which are
+     *     rewritten on a timer or several times per step. Tracking them buries the owner's code review under
+     *     machine noise — one of them is written every few seconds while a browser has the app open.
+     *   - BULK (session transcripts, artifacts), which are hundreds of megabytes of constantly-rewritten
+     *     content. They travel in a bundle; they do not belong in a diff.
+     * `versioned` is therefore NARROWER than `carry`, and the two answer different questions: carry is "does it
+     * move to a new sandbox", this is "should a human review it changing". */
+    readonly versioned?: true;
+    /* AUTHORED but not configuration — the fourth question an entry can answer, and the narrowest: is this
+     * human- or agent-written TEXT that a workspace search should surface? Every `versioned` entry already is
+     * (a setting, a persona, a skill — things the agent is asked to find and edit), so this flag exists only
+     * for the entries that are authored content without being config: a draft awaiting approval, a staged
+     * README, an extension the agent wrote in place. Everything else under `.intentic` is machine state, and
+     * `SEARCHABLE_STATE_PATHS` below is what lets the search engine deny the rest BY DEFAULT instead of
+     * hand-keeping a deny list that goes stale the day a store is added (which is how a 98 kB loop ledger and
+     * whole third-party extension checkouts ended up ranking in code search). */
+    readonly authored?: true;
+    /* WHO BUILDS THIS TREE, when it is not the daemon — an extension, pnpm, another process entirely. Declared
+     * on the entry because the coverage guard's second direction ("every declared entry is built somewhere in
+     * the daemon") is only meaningful for entries the daemon owns: one it can never build must say who does, or
+     * the guard would read the entry as dead. Absent for everything the daemon writes itself. */
+    readonly outsideWriter?: string;
 }
 
-export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
+/* Declared `as const` so the paths survive as literal types (see WorkspaceStatePath below), then published under
+ * the interface. Both bindings are needed and neither is redundant: the const is the only thing that can produce
+ * the path union, and every consumer reads entries as `WorkspaceStateFile` — an exact-literal tuple loses the
+ * optional members (`note`, `why`) on the entries that omit them, which is a worse type for reading than the
+ * interface it satisfies. One list, two views of it. */
+const STATE_FILES = [
     /* A capability add/remove recomposes the environment overlay and can add or drop a repo's panel.
      *
      * Each entry's `config` carries that capability's credential (an mcp server's token, a Komodo key, an ssh
@@ -59,7 +99,35 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
      * fragments from, which makes this the entry where the owner's export choice has the most visible
      * consequence: a bundle exported WITHOUT secrets rebuilds a stock overlay, and the import report has to
      * name every capability the target needs re-added before its environment matches again. */
-    { path: ".intentic/capabilities.json", invalidates: ["capabilities", "environment", "panels"], portability: "secret" },
+    { path: ".intentic/capabilities.json", invalidates: ["capabilities", "environment", "panels", "manifests"], portability: "secret" },
+
+    /* Which workspace-derived recommendations the owner has said "not needed" to, and the evidence each was
+     * declined against. It rides the `capabilities` key because the catalog is what changes when one lands, and
+     * it travels because a decision about what this workspace does NOT need is as much the owner's as the
+     * connections themselves — an export that dropped it would greet them on the target with the same
+     * suggestions they had already dismissed. Holds no credential: it is a card name and a file path. */
+    { path: ".intentic/capability-dismissals.json", invalidates: ["capabilities"], portability: "carry", versioned: true },
+
+    /* The secret use ledger — one row per moment the agent's exits spent a stored secret (a `{{secret:name}}`
+     * reference resolved into a shell command, a value typed into a browser field), joined onto the secrets
+     * inventory as each entry's "last used" (sandbox's secrets/secret-uses.ts). Holds names and destinations,
+     * never values — which is why it may `carry`: like the automations' run ledger, a use history is about the
+     * secrets, and an export that dropped it would arrive claiming none had ever been touched. */
+    { path: ".intentic/secret-uses.json", invalidates: ["secrets"], portability: "carry" },
+
+    /* The named personas this sandbox shows the outside world — which connected accounts each one speaks for,
+     * what a session wearing it may do, where it works (schemas.ts PersonaSchema). It invalidates `capabilities` as well as
+     * its own key because a card and the accounts it names are read together everywhere they are shown: connect
+     * a second Reddit and the persona list has a new candidate; remove one and a card points at nothing.
+     *
+     * It is `carry`, and that is the whole design rather than an oversight — a card is a NAME and a list of ids,
+     * never a credential, so it travels to a new sandbox in full while the logins it refers to stay behind. What
+     * arrives is a workspace that already knows it has a work-reddit and a studio-x, both visibly unconnected,
+     * each waiting for one sign-in. It was also the FIRST file under .intentic the root repo tracked, and the
+     * argument it was carved out on — a card is configuration, holds no secret, and belongs in review — is the
+     * one `versioned` now generalises to the rest of the config slice (personas/personas-store.ts argues it at
+     * length, and its reasoning is why the flag exists rather than a second hand-kept list). */
+    { path: ".intentic/personas.json", invalidates: ["personas", "capabilities", "manifests"], portability: "carry", versioned: true },
 
     /* The overlay Dockerfile, four files that a single `.intentic/environment.` prefix used to cover. They are
      * split here because they answer PORTABILITY differently while answering invalidation identically, and the
@@ -71,9 +139,9 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
      *     not be on (see composeEnvironment's baseImageOf);
      *   - the proposal and the per-tool drafts under environment.d/ are the agent's pending requests, which the
      *     owner has not answered yet; they travel so the question survives the move. */
-    { path: ".intentic/environment.custom.Dockerfile", invalidates: ["environment"], portability: "carry" },
-    { path: ".intentic/environment.Dockerfile", invalidates: ["environment"], portability: "carry" },
-    { path: ".intentic/environment.d/", invalidates: ["environment"], portability: "carry" },
+    { path: ".intentic/environment.custom.Dockerfile", invalidates: ["environment"], portability: "carry", versioned: true },
+    { path: ".intentic/environment.Dockerfile", invalidates: ["environment"], portability: "carry", versioned: true },
+    { path: ".intentic/environment.d/", invalidates: ["environment"], portability: "carry", versioned: true },
     {
         path: ".intentic/environment.approved.Dockerfile",
         invalidates: ["environment"],
@@ -81,10 +149,20 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
         note: "The target composes its own overlay on first boot; rebuild it there to install the tools it names.",
     },
 
-    { path: ".intentic/settings.json", invalidates: ["settings"], portability: "carry" },
+    { path: ".intentic/settings.json", invalidates: ["settings", "manifests"], portability: "carry", versioned: true },
+    // The rule table's last-fired stamps, beside the rules themselves. `derived` rather than `carry`: it is a
+    // record of what happened in THIS sandbox, and carrying it to a fresh one would date every rule to work
+    // that machine never did.
+    {
+        path: ".intentic/rule-firings.json",
+        invalidates: ["rule-firings"],
+        portability: "derived",
+        note: "Stamps of when each rule last did something; the new sandbox starts its own record.",
+    },
     // Written by the AGENT's file tools (the drafts skill), read by the owner's approval inbox — the one entry
-    // here whose whole point is that a change arrives from outside the browser that renders it.
-    { path: ".intentic/drafts/", invalidates: ["drafts"], portability: "carry" },
+    // here whose whole point is that a change arrives from outside the browser that renders it. `authored`:
+    // a draft is text somebody wrote, and "find the reddit draft about X" is an ordinary search.
+    { path: ".intentic/drafts/", invalidates: ["drafts"], portability: "carry", authored: true },
     // ---- declared by the extension that renders them (contributes.files), not here ----
     // The path is the DAEMON's (automations-store writes both), the query keys are the intentic.automations
     // extension's. It declares them in its own manifest and the browser unions the two lists, so uninstalling
@@ -94,6 +172,26 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
         invalidates: [],
         why: "Declared by the intentic.automations extension's contributes.files — `automations` is its query key, not core's.",
         portability: "carry",
+        versioned: true,
+    },
+    /* The run history, keyed by automation id — the LEDGER half of what automations.json used to be, and split
+     * out of it for the one reason this table's `versioned` note already gives: a tracked file must be worth
+     * reviewing. A scheduled automation records a run every time it fires, so every fire dirtied the manifest
+     * the owner reviews, and the run records went into `git log` with it — timestamps and conversation ids
+     * committed beside the prompt they belong to, burying an actual edit to the automation's config under
+     * machine noise. Config is now the only thing in the tracked file, and a fire touches nothing tracked.
+     *
+     * It is `carry` for the same reason the workflow ledger is: a run history is about the automation, not about
+     * the machine, and an export that dropped it would arrive claiming every automation had never run.
+     *
+     * Its invalidation is the extension's, exactly like the manifest above — and it has to be DECLARED there
+     * rather than inherited, because the row renders its run history from this file now: without its own entry
+     * a completed run would stop refreshing the view the moment it stopped living in automations.json. */
+    {
+        path: ".intentic/automation-runs.json",
+        invalidates: [],
+        why: "Declared by the intentic.automations extension's contributes.files — `automations` is its query key, not core's.",
+        portability: "carry",
     },
     {
         path: ".intentic/approvals/",
@@ -101,6 +199,58 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
         why: "Declared by the intentic.automations extension's contributes.files — `automation-approvals` is its query key, not core's.",
         portability: "carry",
     },
+    {
+        path: ".intentic/automations.seeded.json",
+        invalidates: [],
+        why: "Which default automations this workspace has been offered (default-automations.ts); nothing renders it — it exists so deleting a seeded automation is final.",
+        portability: "carry",
+        versioned: true,
+    },
+    /* The maintenance ledger and probe evidence, written by the daemon's chores-store and rendered by the
+     * intentic.maintenance extension — the automations shape exactly: the path is the daemon's, the query keys
+     * (`maintenance-report`, `maintenance-runs`) are the extension's own contributes.files. Point-in-time
+     * evidence about this workspace, so `carry` like the run ledgers: an export that dropped it would arrive
+     * claiming no chore had ever been checked. */
+    {
+        path: ".intentic/chores/",
+        invalidates: [],
+        why: "Declared by the intentic.maintenance extension's contributes.files — `maintenance-report`/`maintenance-runs` are its query keys, not core's.",
+        portability: "carry",
+    },
+    /* The documentation STAGING tree (documentation extension's paths.ts): generation writes here, the owner
+     * reads and approves here, publishing copies into the repo. `authored` is the whole nature of the entry —
+     * these are draft READMEs, drafts-shaped in every way that matters, and "find the staged page about X" is
+     * as ordinary a search as finding a post draft. */
+    {
+        path: ".intentic/docs/",
+        invalidates: [],
+        why: "Declared by the intentic.documentation extension's contributes.files — `documentation`/`documentation-runs` are its query keys, not core's.",
+        portability: "carry",
+        authored: true,
+        outsideWriter: "the intentic.documentation extension's staging writes (its paths.ts)",
+    },
+    /* The workflow designs and their run ledger became CORE keys the day runs got cards on the fleet board and
+     * a mode of the chat panel (web's useWorkflowRuns): those surfaces exist whether or not the workflows
+     * extension is enabled, so their freshness cannot ride an extension's contributes.files — an owner turning
+     * the extension off would have frozen the board's run cards mid-run. This push is the ONLY live feed the
+     * run surfaces have: the scheduler writes the ledger several times per step and nothing polls for it.
+     * The runs file invalidates `workflows` too, because GET /workflows embeds each design's runs
+     * (WorkflowSummary) — a settled step changes that answer as surely as an edited design does. */
+    { path: ".intentic/workflows.json", invalidates: ["workflows"], portability: "carry", versioned: true },
+    { path: ".intentic/workflow-runs.json", invalidates: ["workflows", "workflow-runs"], portability: "carry" },
+    /* The SAVED loops, which are a manifest and so the opposite of the ledger below them: a handful of entries
+     * a person authors, read by two surfaces at once — the workflows page that owns them, and every chat
+     * composer's loop picker. Those two are in different windows as often as not (a popped-out chat is its own
+     * window), so an edit made on the page has to reach a picker nobody is going to think to reopen. A CORE key
+     * rather than the workflows extension's, for the reason the workflow designs beside it are: the composer
+     * lists saved loops whether or not that extension is switched on. */
+    { path: ".intentic/loop-designs.json", invalidates: ["loop-designs"], portability: "carry", versioned: true },
+    {
+        path: ".intentic/loops.json",
+        invalidates: [],
+        why: "Ralph loops and their iteration history. Nothing observes it: where a RUNNING loop stands rides on the fleet roster (AgentSummary.loop), which the /events stream already pushes about once a second, and a second source invalidating on this file could only ever disagree with the card beside it. The iteration list of an ENDED loop is an on-demand read — nothing renders it until someone opens it (web's useLoops, which holds no query for exactly this reason).",
+        portability: "carry",
+    },
 
     /* ---- reached by no query, for reasons that are not oversights ----
      *
@@ -139,6 +289,29 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
         path: ".intentic/extension-enablement.json",
         invalidates: ["extensions"],
         portability: "carry",
+        versioned: true,
+    },
+    /* Workspace extensions: one directory per extension, consumed straight from the workspace — no clone, no
+     * install moment. Written like drafts, by the agent's own file tools (which is the point: an agent authors
+     * an extension and it is live for the daemon and every session at once, since .intentic is shared), so this
+     * push is what makes one appearing or changing show up on the Extensions tab while the owner watches.
+     * `authored` for the same reason as drafts: this is source the agent wrote and will be asked to find —
+     * unlike `.intentic/extensions/` below, which is CLONES of source that lives elsewhere. */
+    { path: ".intentic/workspace-extensions/", invalidates: ["extensions"], portability: "carry", authored: true },
+    /* What the registry comparison found per installed extension (update available / advisory / post-update
+     * health), written by the periodic check and by the update/revert transactions — pushed to the tab because
+     * an advisory that auto-disabled something must not wait for a reload to be seen. */
+    { path: ".intentic/extension-updates.json", invalidates: ["extensions"], portability: "carry" },
+    /* The owner's per-extension update posture (notify / agent / auto, and the advisory opt-out). Carried:
+     * it is a decision about the extension, not about this machine. */
+    { path: ".intentic/extension-update-policy.json", invalidates: ["extensions"], portability: "carry", versioned: true },
+    /* Carried, because the evidence is about the extension rather than about the machine: an export that dropped
+     * it would arrive claiming every permission was unused, which is worse than arriving with no figures at all. */
+    {
+        path: ".intentic/extension-usage.json",
+        invalidates: [],
+        why: "Which of the routes each extension DECLARED it has actually called — the evidence behind the permissions list on its row. The one entry here whose empty set is a RATE decision rather than an architectural one: every browser with the app open reports its batch on a timer, so wiring this to the `extensions` query would refetch the whole list every few seconds for a figure nobody is watching change. The tab reads it when it loads, which is when anyone is reading it.",
+        portability: "carry",
     },
     {
         path: ".intentic/members.json",
@@ -149,52 +322,107 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
     },
 
     // ---- daemon-owned, nothing derives from watching them ----
+    /* Keep credentials and conversation state in disjoint top-level trees. Provider homes are intentionally
+     * classified as a single secret unit: several CLIs mix OAuth, config, and provider-native thread metadata,
+     * and no generic export can safely distinguish those files. The broad root also makes a newly-added provider
+     * secret by construction instead of relying on another hand-maintained provider-name list. */
+    {
+        path: ".intentic/auth/",
+        invalidates: [],
+        why: "AI-provider credentials and runtime homes; each account is rendered through owner-gated provider routes.",
+        portability: "secret",
+        note: "Sign the agent's AI accounts in again on the Agent tab.",
+    },
     /* Agent session transcripts, rewritten on every streamed token.
      *
      * The memory notes under it (`projects/<slug>/memory/**`) ARE user-facing and the /memory view polls them
      * every 30s, which is the one place in this table where a poll survives a real change feed being available.
      * It stays a poll deliberately: the watcher's exclusion is a DESCENT filter, so reaching those notes means
-     * letting it walk `.intentic/claude` → `projects` → every project slug. Measured on the live workspace that
-     * is +119 watched directories against ~593 today (a fifth more), with 314 continuously-rewritten transcripts
-     * inside the newly-watched set, to make ONE memory directory live. Notes change at agent-turn cadence, so the
-     * poll costs a request a minute and the alternative costs a permanent 20% on the watcher. */
-    /* THE STORE THAT IS TWO THINGS, hence two entries — this is the case stateFileFor's longest-match rule
-     * exists for. `.intentic/claude/` is where linkClaudeState parks the Claude CLI's per-conversation state,
-     * and (when AGENT_AUTH_DIR is unset, which is the production layout) it is ALSO the provider credential
-     * root. The subtree under `projects/` is the half a bundle exists to carry — the agent's memory notes and
-     * every conversation's transcript — while its siblings hold the OAuth that must not leave the sandbox. */
-    {
-        path: ".intentic/claude/",
+     * letting it walk `.intentic/sessions/claude` → `projects` → every project slug. Measured on the live
+     * workspace that is +119 watched directories against ~593 today (a fifth more), with 314 continuously-
+     * rewritten transcripts inside the newly-watched set, to make ONE memory directory live. Notes change at
+     * agent-turn cadence, so the poll costs a request a minute and the alternative costs a permanent 20% on the
+     * watcher. */
+    {
+        path: ".intentic/sessions/claude/",
         invalidates: [],
         why: "Agent session transcripts — see the note above on why the memory notes under it stay polled.",
-        portability: "secret",
-        note: "Sign the agent's AI accounts in again on the Agent tab.",
+        portability: "carry",
     },
     {
-        path: ".intentic/claude/projects/",
+        path: ".intentic/artifacts/",
         invalidates: [],
-        why: "Same store as the entry above; split from it for portability, not for invalidation.",
+        why: "Durable outputs owned by conversations and extension runs: attachments, browser captures, generated images, acceptance reports, workflow step reports, voice transcripts, and loop ledgers.",
         portability: "carry",
     },
     {
-        path: ".intentic/ci.json",
+        path: ".intentic/cache/",
         invalidates: [],
-        why: "Webhook secret + conclusion memory; the Pipelines view reads it through /ci/runs, not off disk.",
-        portability: "secret",
-        note: "Re-add the CI webhook on the Pipelines view — its secret is per-sandbox.",
+        why: "Rebuildable indexes and caches — the iq index and its vector sidecar, the whisper model; ignored by the watcher and recreated from carried workspace content.",
+        portability: "derived",
+    },
+    /* Connector and extension scratch, one directory per extension under runtime/extensions/<id>
+     * (extensionRuntimeDir below — the ONLY way an extension names a home here, so a new one lands under its
+     * own id by construction instead of minting a file at the .intentic root). Resume watermarks, cached
+     * hour-tokens, gateway discovery state: all of it either expires or re-establishes itself, and classifying
+     * the root once is what keeps a token an extension caches tomorrow out of bundles without a second edit. */
+    {
+        path: ".intentic/runtime/",
+        invalidates: [],
+        why: "Extension runtime scratch (watermarks, cached short-lived tokens); nothing renders it and gateways re-derive it.",
+        portability: "derived",
+        outsideWriter: "extensions, through extensionRuntimeDir below",
     },
     {
-        path: ".intentic/komodo.json",
+        path: ".intentic/tmp/",
         invalidates: [],
-        why: "Per-connection 'when the owner last looked at Deployments'; the view reads it through /komodo/{capability}/overview, not off disk — and it is written BY that view being opened, so invalidating on it would refetch the board in answer to the browser's own click.",
+        why: "Scratch that agents and tools leave behind (build logs, demo checkouts); nothing reads it after the turn that wrote it. The state janitor empties it at boot.",
+        portability: "derived",
+    },
+    /* Not written by the daemon at all: pnpm auto-creates its content-addressable store at the project's
+     * mountpoint, and `.intentic` is its own mount in an isolated turn — so an install run from under it mints
+     * this. Declared anyway, because the table's job is to say what everything under `.intentic` IS: hardlink
+     * sources a fresh install rebuilds, which an export must not ship (it reached 1.3 GB on the workspace this
+     * entry was written against). */
+    {
+        path: ".intentic/.pnpm-store/",
+        invalidates: [],
+        why: "pnpm's content-addressable store, auto-created by installs run from under .intentic; the next install rebuilds it.",
+        portability: "derived",
+        outsideWriter: "pnpm itself, when an install runs from under .intentic",
+    },
+    {
+        path: ".intentic/newest-run.json",
+        invalidates: [],
+        why: "The newest daemon version that ever ran this workspace (store/newest-run.ts) — a downgrade tripwire, about THIS sandbox the way rule-firings is.",
+        portability: "derived",
+        note: "The target stamps its own daemon version on first boot.",
+    },
+    {
+        path: ".intentic/verify.json",
+        invalidates: [],
+        why: "The dependency verifier's verdict memory; nothing renders it directly — outcomes reach the owner as activity entries and workspace events.",
         portability: "carry",
     },
     {
-        path: ".intentic/bridge-tokens.json",
+        path: ".intentic/verify/",
         invalidates: [],
-        why: "Hashed ACP bridge tokens, listed on demand by the owner.",
+        why: "A running check's wrapper artifacts (log + exit status), read once by the daemon when the panel finishes.",
+        portability: "derived",
+    },
+    {
+        path: ".intentic/ci.json",
+        invalidates: [],
+        why: "Webhook secret + conclusion memory; the Pipelines view reads it through /ci/runs, not off disk.",
+        portability: "secret",
+        note: "Re-add the CI webhook on the Pipelines view — its secret is per-sandbox.",
+    },
+    {
+        path: ".intentic/control-tokens.json",
+        invalidates: [],
+        why: "Hashed control tokens (the ACP editor bridge, and anything else driving this sandbox from outside), listed on demand by the owner.",
         portability: "identity",
-        note: "Mint fresh ACP bridge tokens — the old ones authenticate against the source sandbox.",
+        note: "Mint fresh control tokens — the old ones authenticate against the source sandbox.",
     },
     {
         path: ".intentic/owner.json",
@@ -208,7 +436,13 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
         why: "The workspace identity, read from the /events hello frame rather than as a file.",
         portability: "identity",
     },
-    { path: ".intentic/templates.json", invalidates: [], why: "Scaffold templates, read when the scaffold dialog opens.", portability: "carry" },
+    {
+        path: ".intentic/templates.json",
+        invalidates: [],
+        why: "Scaffold templates, read when the scaffold dialog opens.",
+        portability: "carry",
+        versioned: true,
+    },
     /* Classed `derived` for size rather than for safety, and it is the one entry where that costs the owner
      * something real: the profiles ARE logged-in sessions. They are also gigabytes of a store Chromium rewrites
      * constantly and versions against its own build, so carrying them ships bulk that the target's Chromium may
@@ -228,7 +462,156 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
         note: "Extensions re-clone from the capability manifest on the target's next reconcile.",
     },
     { path: ".intentic/plugins/", invalidates: [], why: "Agent plugin dirs, read by the SDK's loader each turn.", portability: "carry" },
-];
+    /* THE SKILLS THE OWNER WROTE THEMSELVES, one directory per skill — the source of truth the reconciler copies
+     * into `.agents/skills` for the ones currently switched on (settings.json's `skills` list). It is here rather
+     * than in the loaded folder for the reason the plugin dirs are: that tree holds only what is currently ON,
+     * and a skill switched off has to keep its text somewhere the loaders will not read it from.
+     *
+     * `versioned`, like the rest of the config slice: a skill changes how the agent behaves, so it earns a diff
+     * in the Changes review and a line in `git log` the same way a rule or a persona does. `carry` for the same
+     * reason — it is text the owner wrote, with no credential in it and nothing about this machine. */
+    { path: ".intentic/skills/", invalidates: ["skills"], portability: "carry", versioned: true },
+    /* ONE FOLDER PER PERSONA — what a session wearing that card is told, and the skills and tools only it gets.
+     * Laid out as a Claude Code plugin (`.claude-plugin/plugin.json`, `skills/`, `agents/`, `commands/`,
+     * `hooks/`, `.mcp.json`) so the runtime's own loader reads it and this daemon parses none of it, exactly as
+     * the plugin checkouts above are read (personas/persona-kit.ts).
+     *
+     * A SECOND ENTRY BESIDE `personas.json` RATHER THAN A FIELD INSIDE IT, because the two are different kinds
+     * of thing to review. The card is a name, some ids and some switches — a few lines that diff cleanly. This
+     * is prose and files: a system prompt, a skill, a subagent. Folding a 20k prompt into the JSON would make
+     * every persona edit an unreadable diff and put text somebody wrote inside a record nobody writes by hand.
+     *
+     * `versioned` and `carry` for the same reasons the card and the skills above are: it changes how the agent
+     * behaves, it holds no credential, and it belongs in a pull request — which is also what makes it
+     * searchable, since every versioned entry already is. */
+    { path: ".intentic/personas/", invalidates: ["personas"], portability: "carry", versioned: true },
+] as const satisfies readonly WorkspaceStateFile[];
+
+export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = STATE_FILES;
+
+/* The entries the root repo tracks, workspace-root-relative and in declaration order — what history.ts turns
+ * into the negations that carve them back out of the wholesale `.intentic` exclusion.
+ *
+ * Derived rather than written down beside the exclude rule, for the reason this whole file exists: the git rule
+ * lives in the daemon and the classification lives here, and a second hand-kept copy of "which config is
+ * reviewable" is a copy that goes stale the first time someone adds a store. Marking an entry `versioned` is now
+ * the entire change — the exclude list follows on the next boot, in both places it is written. */
+export const VERSIONED_STATE_PATHS: readonly string[] = WORKSPACE_STATE_FILES.filter((file) => file.versioned).map((file) => file.path);
+
+/* The `.intentic` slice a workspace SEARCH may surface: configuration a person reviews (`versioned`) plus the
+ * authored-content dirs (`authored`) — drafts, staged docs, workspace extensions. Everything else under
+ * `.intentic` is machine state, and the search engine (iq's floor) denies it BY DEFAULT off this list, the
+ * same default-deny the portability classes are built on and for the same reason: a deny list is a list a new
+ * ledger is forgotten from, and the forgetting is silent — it ranked loop iteration history and cloned
+ * third-party extension source against the user's own code for months before this derivation existed.
+ *
+ * Note what falls out without a special case: `capabilities.json` is `secret` and unversioned, so the index
+ * stops copying capability tokens into search text — the exact boundary the floor already drew for `auth/`. */
+export const SEARCHABLE_STATE_PATHS: readonly string[] = WORKSPACE_STATE_FILES.filter((file) => file.versioned || file.authored).map(
+    (file) => file.path,
+);
+
+/* THE ONE WAY AN EXTENSION NAMES ITS SCRATCH HOME — `.intentic/runtime/extensions/<id>`, workspace-relative
+ * and forward-slash so the browser bundle can hold it too; callers join it onto whatever root is in force.
+ *
+ * It exists for the reason statePath does one table over: before it, every gateway spelled the layout itself
+ * and one extension (deployments) simply didn't, minting `komodo.json` at the `.intentic` root where nothing
+ * classified it. An extension that composes through this helper cannot land outside its own directory, so the
+ * runtime/ entry's `derived` covers whatever it writes tomorrow. Extension ids are validated slugs already;
+ * the replace is defence in depth against a path ever being built from something else. */
+export const extensionRuntimeDir = (extension: string): string => `${STATE_DIR}/runtime/extensions/${extension.replaceAll(/[^a-zA-Z0-9._-]/g, "_")}`;
+
+/* The manifests whose problems the unreadable-manifest notice SHOWS — the handful a person hand-edits — and the
+ * one fact that decides it is already in the table above.
+ *
+ * Every store reads through the same `jsonFile`, so every store reports what it could not make sense of, and for
+ * a long time the notice showed all of them. That is wrong twice over. Its advice — fix the file and this clears
+ * on its own — is addressed to somebody holding an editor, which is true of `settings.json` and false of a
+ * daemon-written LEDGER nobody opens: a run history that stopped matching a schema the build tightened is not a
+ * mistake the owner made, and the card asked them to repair sixty kilobytes of machine JSON by hand. Worse, a
+ * file that reports into the notice without feeding the notice's QUERY leaves a complaint no write can refresh,
+ * so it sits on screen until the daemon restarts — which is exactly how the workflow ledger's entry became
+ * permanent furniture.
+ *
+ * Both follow from one rule, which is why this derives rather than lists: a file's problems are shown IFF a write
+ * to that file refreshes the notice. Declaring `manifests` in `invalidates` is the entire opt-in, so the edit
+ * that puts a file on the card is the same edit that keeps it current, and neither can be done without the
+ * other. A ledger that breaks still falls back and still sets its unreadable bytes aside on the next write
+ * (store/json-file.ts) — it just stops asking the owner to fix it. */
+export const REPORTED_MANIFEST_PATHS: readonly string[] = WORKSPACE_STATE_FILES.filter((file) => file.invalidates.includes("manifests")).map(
+    (file) => file.path,
+);
+
+// Accepts either separator, like isLockedWorkspacePath below: the daemon holds these as platform paths and makes
+// them relative at the last moment, and normalizing at each call site is the one that eventually gets forgotten.
+export const isReportedManifest = (relPath: string): boolean => REPORTED_MANIFEST_PATHS.includes(relPath.replaceAll("\\", "/"));
+
+/* Old directory names are never read or migrated. Keep that finite set in one quarantine record so access,
+ * export, and search cannot reinterpret abandoned machine state as ordinary workspace content after a rename.
+ * `artifacts` still carry; the distinction here tells portability only which retired roots are secrets or
+ * derived — and tells the state janitor which it may DELETE: a retired `derived` root is a rebuildable cache
+ * by its own classification, so leaving 466 MB of abandoned model where only a manual `rm` reaches it was
+ * quarantine doing half its job. Secret and artifact roots stay until an owner removes them by hand: deleting
+ * content is not the janitor's call, only deleting what the class already says is disposable. */
+export const RETIRED_WORKSPACE_STATE_DIRS = {
+    secret: ["claude", "codex", "kimi", "opencode", "cliproxy"],
+    derived: ["iq", "extensions-runtime", "whisper", "browser/output"],
+    artifacts: ["attachments", "acceptance", "loops", "workflow-runs", "transcripts"],
+} as const;
+
+/* THE DAEMON'S OWN CONTROL PLANE — the entries directly under the workspace root's `.intentic/` that the file
+ * API refuses to read, write, move or delete for anyone, the owner included (workspace/workspace-files.ts holds
+ * the enforcement and the full reasoning for each name).
+ *
+ * The list lives HERE, in the package both sides import, because the browser has to draw the same rule the
+ * daemon enforces. It didn't, and the gap was a small piece of theatre: the explorer listed `capabilities.json`
+ * like any other file, opening it flashed a tab, the read came back with nothing there, and the tab closed
+ * itself — a refusal acted out as a glitch. A file the app will not open should say so before it is clicked,
+ * which takes a rule the explorer can consult, not a status code it can only react to.
+ *
+ * Naming these to the browser gives nothing away that the tree did not already publish — it listed them, sizes
+ * and all. What stays behind the guard is the only thing that ever mattered: the bytes. */
+const LOCKED_STATE_ENTRIES: ReadonlySet<string> = new Set([
+    "owner.json",
+    "members.json",
+    "capabilities.json",
+    "ci.json",
+    "claude.json",
+    "auth",
+    "sessions",
+    "browser",
+    ...RETIRED_WORKSPACE_STATE_DIRS.secret,
+]);
+
+/* Whether a workspace-root-relative path lands in that control plane — and so is shown locked rather than
+ * opened. Scoped deliberately tight, matching the guard: only the ROOT `.intentic` counts (a repo's own nested
+ * one is ordinary content) and only these entries within it, subtrees included, so a new provider dropped under
+ * `auth/` is covered without a second edit.
+ *
+ * The ROOT's own `.git` joins them. It is the pointer to the shadow history repo kept off the workspace so the
+ * agent cannot rewrite its own past; a NESTED repo's `.git` is ordinary content and stays browsable.
+ *
+ * Accepts either slash so a caller holding a platform path doesn't have to normalize first. */
+export const isLockedWorkspacePath = (relPath: string): boolean => {
+    const segments = relPath.split(/[\\/]/).filter((segment) => segment !== "" && segment !== ".");
+    if (segments[0] === ".git") {
+        return true;
+    }
+    return segments.length >= 2 && segments[0] === STATE_DIR && LOCKED_STATE_ENTRIES.has(segments[1] ?? "");
+};
+
+/* Every path this table declares, as a type. `as const` above is what makes it one, and it is what finally makes
+ * the first sentence of this file's header TRUE rather than aspirational.
+ *
+ * "The daemon builds its store paths from `path`" was the design; the code did not. `composition.ts` and twenty
+ * files beside it spelled the same layout a SECOND way — `join(root, ".intentic", "settings.json")` — with
+ * nothing tying the two spellings together. Rename a store's file and this table keeps declaring the old name:
+ * no error, no failing test, just a view that quietly stops refreshing, which is the exact failure the table was
+ * written to end and the exact way drafts went missing.
+ *
+ * So the daemon joins through `statePath` (workspace/state-paths.ts), which takes one of THESE and nothing else.
+ * A rename is now a compile error at every site that names the file, in both packages, or it is not a rename. */
+export type WorkspaceStatePath = (typeof STATE_FILES)[number]["path"];
 
 /* The query keys a batch of changed paths makes stale, deduped and stable. The browser's `/events` handler calls
  * this; keeping it here rather than in the web means the rule is unit-testable without a query client, and the
@@ -249,3 +632,12 @@ export const staleQueryKeys = (paths: readonly string[], contributed: readonly F
             .flatMap((file) => file.invalidates),
     ),
 ];
+
+/* Every query key any watched file feeds — what a NEW /events connection invalidates wholesale (core's table
+ * plus the running extensions'). The file push is these keys' ONLY live feed, and a `workspaceChanged` frame
+ * produced while the stream was down is a frame nobody will ever resend — so each key's view would sit stale
+ * until the file's NEXT write, indefinitely for anything that settled while the browser was away. Re-asking on
+ * connect bounds the damage at one cheap read per key, which is what lets those views go entirely unpolled. */
+export const fileBoundQueryKeys = (contributed: readonly FileContribution[]): readonly string[] => [
+    ...new Set([...WORKSPACE_STATE_FILES, ...contributed].flatMap((file) => file.invalidates)),
+];

package/dist/contracts/codex.contract.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"codex.contract.d.ts","sourceRoot":"","sources":["../../src/contracts/codex.contract.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,aAAa;IAEtB,MAAM;;;;;;;;;;;;;CACT,CAAC"}

package/dist/contracts/codex.contract.js

@@ -1,6 +0,0 @@
-import { oc } from "@orpc/contract";
-import { ModelsSchema } from "../schemas.js";
-export const codexContract = {
-    models: oc.route({ method: "GET", path: "/codex/models" }).output(ModelsSchema),
-};
-//# sourceMappingURL=codex.contract.js.map

package/dist/contracts/codex.contract.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"codex.contract.js","sourceRoot":"","sources":["../../src/contracts/codex.contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAK7C,MAAM,CAAC,MAAM,aAAa,GAAG;IAEzB,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;CAClF,CAAC"}

package/dist/contracts/gemini.contract.d.ts

@@ -1,16 +0,0 @@
-export declare const geminiContract: {
-    models: import("@orpc/contract").ContractProcedureBuilderWithOutput<import("@orpc/contract").Schema<unknown, unknown>, import("zod").ZodObject<{
-        models: import("zod").ZodArray<import("zod").ZodObject<{
-            id: import("zod").ZodString;
-            label: import("zod").ZodString;
-            efforts: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
-            description: import("zod").ZodOptional<import("zod").ZodString>;
-            badges: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodEnum<{
-                fast: "fast";
-                reasoning: "reasoning";
-            }>>>;
-        }, import("zod/v4/core").$strip>>;
-        default: import("zod").ZodString;
-    }, import("zod/v4/core").$strip>, Record<never, never>, Record<never, never>>;
-};
-//# sourceMappingURL=gemini.contract.d.ts.map

package/dist/contracts/gemini.contract.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"gemini.contract.d.ts","sourceRoot":"","sources":["../../src/contracts/gemini.contract.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,cAAc;IAEvB,MAAM;;;;;;;;;;;;;CACT,CAAC"}

package/dist/contracts/gemini.contract.js

@@ -1,6 +0,0 @@
-import { oc } from "@orpc/contract";
-import { ModelsSchema } from "../schemas.js";
-export const geminiContract = {
-    models: oc.route({ method: "GET", path: "/gemini/models" }).output(ModelsSchema),
-};
-//# sourceMappingURL=gemini.contract.js.map

package/dist/contracts/gemini.contract.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"gemini.contract.js","sourceRoot":"","sources":["../../src/contracts/gemini.contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAM7C,MAAM,CAAC,MAAM,cAAc,GAAG;IAE1B,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;CACnF,CAAC"}