instar 1.3.350 → 1.3.351

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.350",
+  "version": "1.3.351",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-06T06:52:19.246Z",
-  "instarVersion": "1.3.350",
+  "generatedAt": "2026-06-06T06:55:18.419Z",
+  "instarVersion": "1.3.351",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1538,7 +1538,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "2562b5b7c37deb568e00eefebc9acc07571a5e5ccc251f6e424e7e63039ee297",
+      "contentHash": "523899adda3f26a840f9559afd1b79fdc6088ebeaffe1e07d142fdb8133bc5b7",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/{1.3.350.md → 1.3.351.md}

@@ -23,6 +23,16 @@ The route now injects both as read-only helpers (`gh pr view` and
 project's target repo. A wiring-integrity test asserts the helper-absent
 error can never recur.
 
+macOS Spotlight (`mds_stores`) was a top constant CPU consumer on busy fleet
+boxes because it re-indexed the Claude Code session transcripts on every turn —
+~18 GB of JSONL that grows with every message. Instar already excluded
+`.worktrees/` and `node_modules/` from Spotlight; this extends the same
+`.metadata_never_index` exclusion to the agent's Claude transcript directory
+(`~/.claude/projects/<encoded-agent-home>`), the largest churning set.
+
+New `ensureClaudeTranscriptSpotlightExclusion()` helper + a `PostUpdateMigrator`
+backfill so existing agents get the relief on their next update.
+
 ## What to Tell Your User
 
 Nothing user-facing changes. This is foundation code (experimental) for the
@@ -35,6 +45,10 @@ work's pull request really merged (merge state, commit reachable on the
 main branch, CI green) instead of always erroring out. Project status
 finally tracks reality through the whole pipeline.
 
+Nothing required — this is silent OS-level resource hygiene. If they've noticed
+the Mac running hot, part of the cause was Spotlight endlessly re-indexing
+session transcripts; this stops that going forward.
+
 ## Summary of New Capabilities
 
 - `PrincipalGuard` (experimental, no runtime consumers yet): `establishOperator`,
@@ -45,6 +59,13 @@ finally tracks reality through the whole pipeline.
   confirms the merge commit is reachable on `origin/main` before recording
   the item as merged.
 
+- `ensureClaudeTranscriptSpotlightExclusion()` — drops a `.metadata_never_index`
+  marker at the agent's Claude transcript dir so macOS Spotlight stops
+  re-indexing the constantly-appended JSONL session transcripts (~18GB churn).
+- `PostUpdateMigrator` backfill — existing agents get the exclusion on their next
+  update; new agents get it once they have transcripts. Internal OS hygiene; no
+  agent-facing API or config surface.
+
 ## Evidence
 
 Net-new capability. Verified by 13 unit tests including the incident-replay
@@ -56,3 +77,15 @@ clean `tsc --noEmit`.
   GH_PR_VIEW_FAILED (not UNAVAILABLE), deterministic regardless of whether
   gh is installed/authed. Full projects-api (45) + StageTransitionValidator
   (26) green; tsc + destructive lint clean.
+
+Unit + migration tests (both sides of every boundary: marker dropped when
+transcripts exist, correct encoding, graceful no-op for a new agent, idempotent;
+migration backfills/skips/idempotent). 15/15 green. `tsc --noEmit` clean.
+Mirrors the existing node_modules/worktree exclusion pattern.
+
+## Scope (honest)
+
+This prevents FUTURE re-indexing. It does not instantly drop `mds_stores` —
+Spotlight releases already-indexed content on its own schedule; forcing
+immediate eviction needs a one-time `sudo mdutil -E ~/.claude/projects` the
+operator runs. One of several resource-efficiency fixes (2026-06-06).

package/upgrades/side-effects/spotlight-resource-hygiene.md

@@ -0,0 +1,45 @@
+# Side-Effects Review - Spotlight resource hygiene (Claude transcript exclusion)
+
+**Version / slug:** `spotlight-resource-hygiene`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (Tier 1)`
+
+## Summary of the change
+
+Extends Instar's existing macOS Spotlight exclusion (currently covers `.worktrees/` + `node_modules/`) to the agent's Claude Code transcript directory (`~/.claude/projects/<encoded-agent-home>`). The JSONL session transcripts grow on every turn and a busy fleet box accumulates ~18 GB of them — measured as the single largest `mds_stores` (Spotlight) CPU consumer (60-90% of a core, constantly), because Spotlight re-indexes each file on every append. Adds `ensureClaudeTranscriptSpotlightExclusion()` (reuses the generic marker-dropper) + a `PostUpdateMigrator` backfill.
+
+## Decision-point inventory
+
+- `ensureClaudeTranscriptSpotlightExclusion(agentHome, claudeHome?)` (new, exported) — pure-ish: computes the encoded transcript dir, drops `.metadata_never_index` if the dir exists. Reuses `ensureWorktreeSpotlightExclusion` (the dir-agnostic dropper).
+- `PostUpdateMigrator.migrateClaudeTranscriptSpotlightExclusion` (new, private) — runs the helper on every update, pushes an `upgraded`/`errors` entry.
+- Wired into the migrate() sequence right after `migrateNodeModulesSpotlightExclusion`.
+
+## 1. Behavior change / gating
+
+NONE that affects message flow, sessions, or any gate. The only effect is writing one empty marker file into the agent's Claude transcript dir, which tells macOS Spotlight to stop indexing that subtree. No runtime behavior of the agent changes; instar's own transcript reads (TokenLedger) are unaffected (Spotlight indexing is orthogonal to file reads).
+
+## 2. Over/under-signal
+
+N/A — not a signal/gate. The only "decision" is whether the transcript dir exists (drop the marker) or not (skip). Both branches are covered.
+
+## 3. Blast radius
+
+Filesystem only, additive: writes `~/.claude/projects/<encoded>/.metadata_never_index`. This reaches OUTSIDE the agent home (into `~/.claude`), which is deliberate and bounded: (a) instar already READS that exact directory (TokenLedger/CompactionSentinel), so it is not new territory; (b) the path is scoped to THIS agent's own transcript dir via the home-path encoding, never all of `~/.claude/projects`; (c) the write is a single empty marker, idempotent, reversible. No state, no migration of data, no config. On a non-macOS host the marker is inert.
+
+## 4. Failure modes
+
+The underlying `ensureWorktreeSpotlightExclusion` swallows write errors (`@silent-fallback-ok`) and returns false — a failed marker write just means Spotlight keeps indexing (status quo), and can never block the migration or an update. `existsSync` guards the absent-dir case (brand-new agent, no sessions). The encoding is a pure string transform with no throw path.
+
+## 5. Migration parity
+
+Covered: the `PostUpdateMigrator` backfill means existing agents get the marker on their next update (the fast release cadence drops it within minutes once transcripts exist). New agents get it on their first post-session update. No agent-installed config/hooks/skills/CLAUDE.md change — this is internal OS hygiene with no agent-facing surface (consistent with the precedent: the node_modules + worktree exclusions also have no CLAUDE.md template line, as they are not capabilities the agent surfaces to a user). No init-path call is needed because the transcript dir does not exist at init time (no sessions yet) — it would no-op; the migration is the correct single mechanism.
+
+## 6. Scope honesty (what this is NOT)
+
+- This is fix 1 of 4 in the resource-efficiency initiative (Justin, 2026-06-06). It is the biggest single lever (the 18 GB transcript churn) but does NOT instantly drop `mds_stores`: the marker prevents FUTURE re-indexing; Spotlight releases already-indexed content on its own schedule, and forcing immediate eviction needs a one-time `sudo mdutil -E` the operator runs (instar cannot run sudo). The durable guarantee is that no agent keeps feeding the churn.
+- `mediaanalysisd` (macOS media/photo analysis) is a separate high-CPU process NOT addressed here and likely not Instar-triggered.
+
+## 7. Causal autopsy
+
+Origin: **latent** (not a prior-PR regression). The transcript-indexing cost has existed since Claude Code began writing JSONL transcripts; the recent node_modules/worktree exclusion PRs addressed the static trees but never extended to the constantly-churning transcript set, which grounding showed is the larger consumer. This PR closes that gap by reusing the same marker mechanism. No behavior was broken by a prior change; an existing cost was simply never excluded.