instar 1.3.491 → 1.3.493

package/dist/core/PostUpdateMigrator.js

@@ -3042,6 +3042,14 @@ setTimeout(() => process.exit(0), 2000);
             patched = true;
             result.upgraded.push('CLAUDE.md: added Cartographer Doc-Freshness section');
         }
+        // Event-loop safety (fix instar#1069) — /health + /stale now serve a cached
+        // snapshot; freshnessSweep.framework is the supported off-Claude routing knob.
+        // Keyed on its OWN marker so it is idempotent and independent of the blocks above.
+        if (!content.includes('serves a cached snapshot')) {
+            content += `\n### Cartographer event-loop safety (fix instar#1069)\n\nThe cartographer never runs a whole-tree walk on the server's event loop: the freshness sweep's "what's stale?" detect runs in a worker thread, and every \`/cartographer/*\` read route **serves a cached snapshot** instead of recomputing live.\n- \`GET /cartographer/health\` + \`GET /cartographer/stale\` carry \`snapshot\` (\`present\`/\`absent\`/\`detect-failing\`), \`generatedAt\`, \`headSha\`, \`snapshotStale\`, and \`lastDetectStatus\`. \`absent\` just means no detect has run yet — not an error. \`/stale\` is a bounded sample with a \`total\` + \`truncated\` flag.\n- The off-Claude model is selected by \`cartographer.freshnessSweep.framework\` (default \`codex-cli\`) — a manual \`sessions.componentFrameworks\` override is no longer required. The boot log line \`Cartographer sweep routing: <fw> (source: …)\` shows what resolved.\n- Rollback knob: \`cartographer.freshnessSweep.detectInWorker: false\` runs the SAME bounded detect synchronously (still never the old full walk).\n`;
+            patched = true;
+            result.upgraded.push('CLAUDE.md: added Cartographer event-loop-safety section');
+        }
         // Standards Enforcement Coverage (cartographer-conformance-audit spec #3) — the
         // registry-wide enforcement-coverage audit. Keyed on this spec's OWN marker
         // ('Standards Enforcement Coverage') so it is independent of specs #1/#2 and
@@ -3821,6 +3829,7 @@ Beyond the one-awake-machine model: with the pool enabled I run conversations ac
 - **Machine nicknames** are the user-facing handle (auto-assigned, editable). Rename via \`PATCH /pool/machines/:machineId\` with \`{"nickname":"the mini"}\`, or inline on the Machines tab.
 - **Which machine + WHY (never guess):** \`GET /pool/placement?topic=N\` → the owning machine + nickname, the **reason** (\`pinned\` = a deliberate move vs \`placed\` = load-balanced vs \`unowned\`), and the lease-holder. Answerable from ANY machine (a standby proxies to the holder). Running ON a machine does NOT mean a topic was deliberately moved there — read this instead of inferring.
 - **Reliable transfer (phrasing-independent):** \`POST /pool/transfer\` with \`{"topic":N,"to":"<nickname|machineId>"}\` runs the same validated planner as "move this to <nickname>" but deterministically. 404 unknown · 409 rate-limited · 409 \`needsConfirmation\` for an offline target (re-send with \`"confirm":true\`). The lever to call directly when a natural-language move didn't catch.
+- **Remote close (any machine, from here):** close a session on ANY machine in the pool from this one — \`POST /sessions/<name>/remote-close\` with \`{"machineId":"<id>","sessionUuid":"<uuid>"}\` (Bearer). Same operator authority as the local close: it WILL close a protected session (the dashboard's confirm dialog is the safety, not a server-side refusal). Outcomes are honest — already-closed comes back calm, and a relay timeout reports outcome-UNKNOWN, never "closed" or "nothing happened". The order is audited on BOTH machines: the relayer appends to \`logs/remote-close-audit.jsonl\`; the owning machine's reap-log entry carries \`viaClaim\`.
 - **Proactive triggers:** when the user says "run this on <nickname>" / "move this to <nickname>" → placement/transfer-by-nickname (the session moves to the named machine, resuming like a session restart). "where is this running / why?" → \`GET /pool/placement?topic=N\`. "move it reliably / it didn't move" → \`POST /pool/transfer\`. Deep mechanics: the Machines tab + \`docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md\`.
 `;
             content += '\n' + section;
@@ -3880,6 +3889,22 @@ Beyond the one-awake-machine model: with the pool enabled I run conversations ac
             patched = true;
             result.upgraded.push('CLAUDE.md: added quota-aware placement line');
         }
+        // Remote session close (REMOTE-SESSION-CLOSE-SPEC §2.4, 2026-06-12): agents
+        // that ALREADY carry the pool section predate the relayed close — the one
+        // agent-facing /sessions/* verb (§2.0 names "the operator's authenticated
+        // agent" as a caller). Without it an agent asked "close the stale Mini
+        // session from here" hand-issues curl against the peer's tunnel URL
+        // (lived 2026-06-11) instead of the audited, allowlisted relay. Byte-
+        // identical to the generateClaudeMd bullet (pinned by
+        // PostUpdateMigrator-remoteCloseAwareness.test.ts). Idempotent via the
+        // unique 'remote-close' marker.
+        if (content.includes('Multi-Machine Session Pool (active-active') && !content.includes('remote-close')) {
+            const remoteClose = `
+- **Remote close (any machine, from here):** close a session on ANY machine in the pool from this one — \`POST /sessions/<name>/remote-close\` with \`{"machineId":"<id>","sessionUuid":"<uuid>"}\` (Bearer). Same operator authority as the local close: it WILL close a protected session (the dashboard's confirm dialog is the safety, not a server-side refusal). Outcomes are honest — already-closed comes back calm, and a relay timeout reports outcome-UNKNOWN, never "closed" or "nothing happened". The order is audited on BOTH machines: the relayer appends to \`logs/remote-close-audit.jsonl\`; the owning machine's reap-log entry carries \`viaClaim\`.`;
+            content += '\n' + remoteClose + '\n';
+            patched = true;
+            result.upgraded.push('CLAUDE.md: added pool remote session close line');
+        }
         // Cross-Machine Secret Sync (spec Phase 4, 2026-06-04): deployed agents don't know
         // a secret can now follow them across machines, nor the two routes. Append the section
         // so an agent surfaces "drop once, usable everywhere" instead of asking the user to
@@ -6243,6 +6268,11 @@ Create worktrees for collaborator repos with \`instar worktree create <branch>\`
         // `git add .` path so contributors can't accidentally commit pr-gate
         // secrets from the project directory.
         this.addGitignoreEntry(projectGitignore, '.instar/secrets/pr-gate/', result, 'project .gitignore');
+        // fix instar#1069: the cartographer index (67MB on a real tree) + the per-host
+        // snapshot are per-machine runtime state, never committable. The header in
+        // cartographer-freshness.mjs historically (wrongly) claimed this was gitignored;
+        // this entry makes it true. Idempotent (addGitignoreEntry no-ops if present).
+        this.addGitignoreEntry(projectGitignore, '.instar/cartographer/', result, 'project .gitignore');
     }
     /**
      * PR-REVIEW-HARDENING Phase A — ensure pr-gate state paths are backed up.