@intentic/sandbox-contract 1.231.0 → 1.233.0

package/src/workspace-state.ts

@@ -187,7 +187,7 @@ const STATE_FILES = [
     },
 
     /* 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
+     * what a session wearing it may do, where it works (PersonaSchema, schemas/personas.ts). 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.
      *
@@ -221,6 +221,18 @@ const STATE_FILES = [
     },
 
     { path: ".intentic/config/settings.json", invalidates: ["settings", "manifests"], portability: "carry", versioned: true },
+    /* Which agent commands are heavy enough to take turns, and how many may run at once (the daemon reads it
+     * per Bash command: platform/heavy-commands.ts).
+     *
+     * `carry`, because the answer is a property of the WORKSPACE rather than of this machine: `pnpm test` fans
+     * out to the same 74 packages wherever the repo is cloned, so a fresh sandbox should arrive already knowing
+     * which commands to queue rather than rediscovering it by freezing once.
+     *
+     * `versioned` for the reason the config slice generally is (personas.json's entry argues it): the file
+     * changes at human speed, it holds no secret, and a change to it is exactly the kind a reviewer should see
+     * — raising the limit is a decision about everyone's sessions on that box, and `git log` is the only thing
+     * that answers "since when have we allowed four of these at once". */
+    { path: ".intentic/config/heavy-commands.json", invalidates: ["settings"], 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.
@@ -230,6 +242,13 @@ const STATE_FILES = [
         portability: "derived",
         note: "Stamps of when each rule last did something; the new sandbox starts its own record.",
     },
+    /* The runtime-install ledger: which tools sessions installed into the container at runtime, how often, and
+     * the last drift snapshot (environment/runtime-installs.ts). `carry` where rule-firings chose `derived`,
+     * because the two record different subjects: a firing is about what THIS machine did, while the ledger is
+     * about what this WORKSPACE's tasks keep needing — a workspace moved to a fresh sandbox will hit the same
+     * missing tools, and arriving with the recurrence memory is the whole reason it is kept. The drift snapshot
+     * inside is machine-scoped, and self-expires on the move: its bornAt can never match the new container. */
+    { path: ".intentic/records/runtime-installs.json", invalidates: ["environment"], portability: "carry" },
     /* 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. `authored`:
      * a draft is text somebody wrote, and "find the reddit draft about X" is an ordinary search.
@@ -457,20 +476,15 @@ const STATE_FILES = [
         portability: "secret",
         note: "Sign the agent's AI accounts in again on the Agent tab, then re-enter each connection's credential on Capabilities and each extension's secret settings on Extensions, both arrived listed but unauthenticated.",
     },
-    /* 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/records/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. */
+    /* Agent session transcripts, rewritten on every streamed token: nothing renders them off disk, so nothing
+     * under here is watched. The exclusion is a DESCENT filter, which is what makes it cheap: the watcher never
+     * walks `projects` and its per-slug subtrees at all. Measured on the live workspace, descending would add
+     * +119 watched directories against ~593 (a fifth more), with 314 continuously-rewritten transcripts inside
+     * the newly-watched set. If a surface here ever needs to be live, weigh that 20% against a poll first. */
     {
         path: ".intentic/records/sessions/claude/",
         invalidates: [],
-        why: "Agent session transcripts, see the note above on why the memory notes under it stay polled.",
+        why: "Agent session transcripts; nothing derives from watching them, and descending into them would cost a fifth of the watcher.",
         portability: "carry",
     },
     {
@@ -482,7 +496,7 @@ const STATE_FILES = [
     {
         path: ".intentic/local/cache/",
         invalidates: [],
-        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.",
+        why: "Rebuildable indexes and caches, the iq index and its vector sidecar, the whisper model, fileq's derived/ markdown shadows of binary files; ignored by the watcher and recreated from carried workspace content.",
         portability: "derived",
     },
     /* Connector and extension scratch, one directory per extension under runtime/extensions/<id>