instar 1.3.130 → 1.3.131

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.130",
+  "version": "1.3.131",
   "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-05-31T00:33:26.641Z",
-  "instarVersion": "1.3.130",
+  "generatedAt": "2026-05-31T01:22:54.429Z",
+  "instarVersion": "1.3.131",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "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": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "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": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "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": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "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": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "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": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1129,7 +1129,7 @@
       "type": "template",
       "domain": "operations",
       "sourcePath": "src/templates/scripts/instar-worktree-create.sh",
-      "contentHash": "2e3f78d72a00a56a9bae9dfe0af0ecc48557e5af2cd59fc6435356784c8e6796",
+      "contentHash": "c258707dafb41518f376ffbab4ea3c5a824d6ab7dc9b1df5f8b8a2f7f99fbaee",
       "since": "2025-01-01"
     },
     "template:secret-drop-retrieve.mjs": {
@@ -1489,7 +1489,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "8804d1b46f2b0f32f053b1cc18a42113857fcdd6462d3fe43205aee2452b5a26",
+      "contentHash": "89b3df4de4f24c8825ec19797392f021c54d12a9a18826cb4380ce6986f4558f",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/templates/scripts/instar-worktree-create.sh

@@ -67,6 +67,10 @@ if [[ -e "$WORKTREE_PATH" ]]; then
 fi
 mkdir -p "$WORKTREES_ROOT"
 chmod 0700 "$WORKTREES_ROOT"
+# OS resource hygiene: keep macOS Spotlight/mediaanalysisd from re-indexing every
+# worktree under here (a top OS-level CPU consumer). Honored recursively; no-op
+# elsewhere. The CLI path does the same via ensureWorktreeSpotlightExclusion.
+[[ -f "$WORKTREES_ROOT/.metadata_never_index" ]] || : > "$WORKTREES_ROOT/.metadata_never_index" 2>/dev/null || true
 cd "$INSTAR_REPO"
 if git rev-parse --verify --quiet "$BRANCH" >/dev/null; then
   git worktree add "$WORKTREE_PATH" "$BRANCH"

package/upgrades/1.3.131.md

@@ -0,0 +1,56 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Agent worktrees are now excluded from macOS Spotlight indexing — a top
+OS-level CPU drain on multi-worktree machines.**
+
+Each `instar worktree create` leaves a full source tree on disk under the agent's
+`.worktrees/` directory. macOS Spotlight (mds_stores) and mediaanalysisd treat
+every one of those trees as new content to index and re-index — and on a machine
+that has accumulated dozens of worktrees that becomes one of the single biggest
+CPU consumers on the box (measured: mediaanalysisd pulling ~80% CPU under a
+~120-worktree backlog), entirely separate from anything instar's own code is
+doing.
+
+instar now drops a single `.metadata_never_index` marker at the `.worktrees/`
+container root, which tells Spotlight to skip that whole subtree. New worktrees
+are covered automatically at creation time, and existing agents get the marker
+backfilled on update via a new migration. The marker lives at the container (not
+inside any worktree, so it adds no git noise), is honored recursively for every
+worktree beneath it, is harmless on non-macOS, and is idempotent.
+
+This is the first piece of the **OS resource hygiene** facet of the Responsible
+Resource Usage standard.
+
+## What to Tell Your User
+
+Nothing to configure. On a Mac, the throwaway worktrees instar creates for
+parallel development will no longer be re-indexed by Spotlight — which quietly
+removes a large chunk of background CPU load that had nothing to do with your
+agents actually working. If you have built up a lot of worktrees over time, you
+should feel this as lower idle CPU after the update settles.
+
+## Summary of New Capabilities
+
+- `instar worktree create` (and the convention wrapper's fallback path) drop a
+  `.metadata_never_index` marker at the `.worktrees/` container so Spotlight skips
+  indexing every worktree under it.
+- New exported helper `ensureWorktreeSpotlightExclusion(worktreesDir)` — idempotent,
+  best-effort, never throws, returns whether it created the marker.
+- New `PostUpdateMigrator.migrateWorktreeSpotlightExclusion` backfills the marker
+  into existing agents' `.worktrees/` on update.
+
+## Evidence
+
+- `tests/unit/worktree-spotlight-exclusion.test.ts` — new: the helper (creates the
+  marker, idempotent return, never throws on an unwritable path) and the migration
+  backfill (drops the marker into an existing `.worktrees/`, idempotent on re-run).
+- `tests/unit/InstarWorktreeManager.test.ts` + `migrateWorktreeConvention.test.ts`
+  still green (the `ensureWorktreesDir` hook + always-overwrite wrapper unchanged
+  in behavior).
+- Operationally verified live: dropping the marker on echo's real 121-worktree
+  `.worktrees/` directory; mediaanalysisd dropped from its earlier ~80% spike.
+- Full `npm run lint` clean.

package/upgrades/side-effects/worktree-spotlight-exclusion.md

@@ -0,0 +1,81 @@
+# Side-Effects Review — Worktree Spotlight exclusion
+
+**Version / slug:** `worktree-spotlight-exclusion`
+**Date:** `2026-05-30`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Drop a `.metadata_never_index` marker at the `.worktrees/` container root so macOS
+Spotlight/mediaanalysisd skip indexing every worktree beneath it. Covered at
+creation (`ensureWorktreesDir` → `ensureWorktreeSpotlightExclusion`, plus the
+convention wrapper's fallback path) and backfilled for existing agents via a new
+`PostUpdateMigrator.migrateWorktreeSpotlightExclusion`.
+
+## Decision-point inventory
+
+None. The change adds no decision logic — it writes one inert OS-hint file.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject?** Nothing is rejected. The marker
+only affects Spotlight indexing of throwaway build trees; it does not change git,
+the worktree, the build, or any agent behavior. Source files inside worktrees are
+unaffected (the marker is at the container, not inside a worktree).
+
+## 2. Under-block
+
+**What does this still miss?** It does not reduce indexing of anything outside
+`.worktrees/` (by design), and it does not reclaim the worktrees themselves (the
+sibling reaper work). Spotlight may take time to honor a newly-dropped marker on an
+already-indexed tree, so the relief on existing backlogs is gradual, not instant.
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. The marker-ensure lives in `ensureWorktreesDir`, the single
+chokepoint all CLI create paths run through, and the backfill lives beside the
+existing `migrateWorktreeConvention`. The exported helper keeps the rule in one
+place, reused by the migrator.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No blocking authority added. The helper is best-effort and total: a write failure
+returns false and is swallowed (`@silent-fallback-ok`), never throwing and never
+blocking worktree creation or a migration pass.
+
+## 5. Interactions
+
+Reuses `resolveAgentHomeForWorktree` (same validation as `migrateWorktreeConvention`)
+so non-convention agents are skipped silently. The wrapper fallback change rides the
+existing always-overwrite of `instar-worktree-create.sh`. No interaction with the
+SessionReaper, sentinels, or recovery paths. Idempotent everywhere.
+
+## 6. External surfaces
+
+One new on-disk file per agent (`.worktrees/.metadata_never_index`, empty). No HTTP
+routes, no config, no notifications, no Telegram. Purely a filesystem hint to the OS.
+
+## 7. Rollback cost
+
+Trivial. Delete the marker to restore indexing; revert the PR to remove the
+create-path drop + migration. No state, no schema, no irreversible op.
+
+## Conclusion
+
+Lowest-risk possible change: additive, inert, idempotent, best-effort, reversible,
+no decision logic. Directly targets a measured top OS-level CPU drain (mediaanalysisd
+~80% under a ~120-worktree backlog). Operationally pre-validated by dropping the
+marker on echo's real `.worktrees/` (121 worktrees) live.
+
+## Second-pass review (if required)
+
+Not required — inert additive OS hint, no authority, no decision logic.
+
+## Evidence pointers
+
+- `tests/unit/worktree-spotlight-exclusion.test.ts` — helper + migration backfill.
+- `tests/unit/InstarWorktreeManager.test.ts`, `migrateWorktreeConvention.test.ts` — green.
+- `upgrades/NEXT.md` — upgrade guide.