instar 1.3.349 → 1.3.351

package/dist/core/PrincipalGuard.d.ts

@@ -0,0 +1,64 @@
+/**
+ * PrincipalGuard — cross-principal attribution detector (EXO 3.0 / "Know Your
+ * Principal" standard, Phase 1 brain).
+ *
+ * The "Caroline" incident (2026-06-05, topic 19437): an autonomous session
+ * silently adopted a real OTHER principal as its operator and credited the
+ * actual operator's decisions to her across three docs — and no gate watched,
+ * because the contamination was in the agent's OWN output, not an inbound
+ * message. This module is the pure-logic detector for that failure: given a
+ * piece of agent-authored text, it finds operator-ROLE-decision attributions
+ * ("X approved", "locked with X", "mandate (X)", "X dropped a token") and
+ * flags any whose attributed principal is NOT the topic's bound operator and
+ * does NOT resolve to a known user.
+ *
+ * Pure + deterministic so it is unit-testable in isolation; it performs no I/O
+ * and is not wired into the live request path here (that is a later increment).
+ * The constitution standard it enforces: "Know Your Principal — An Unverified
+ * Identity Is a Guess" (docs/STANDARDS-REGISTRY.md). Spec:
+ * docs/specs/OPERATOR-IDENTITY-BINDING-SPEC.md.
+ */
+/** A verified operator, established ONLY from an authenticated channel — never
+ *  from a name read in content (that is the whole point). */
+export interface VerifiedOperator {
+    /** The platform-verified sender id (e.g. Telegram uid). */
+    uid: string;
+    /** Display name(s) the operator is known by, lowercased for matching. */
+    names: string[];
+}
+/**
+ * Establish a topic's operator from the AUTHENTICATED sender — never from a
+ * content name. The uid is the authority; names are only for matching the
+ * agent's prose against the verified principal. A blank uid yields no operator
+ * (an unbound topic), which the guard treats as "everything is unverified".
+ */
+export declare function establishOperator(authenticatedUid: string, displayName?: string): VerifiedOperator | null;
+/** The kind of operator-role decision an attribution carries — drives warn vs block. */
+export type AttributionKind = 'approval' | 'mandate' | 'credential' | 'lock' | 'acting-for';
+export interface Attribution {
+    /** The principal name the decision was attributed to (lowercased). */
+    principal: string;
+    kind: AttributionKind;
+    /** The matched snippet, for the audit trail. */
+    snippet: string;
+}
+/** Find every operator-role-decision attribution in agent-authored text. */
+export declare function detectAttributions(text: string): Attribution[];
+export type Verdict = 'ok' | 'warn' | 'block';
+export interface PrincipalFinding {
+    attribution: Attribution;
+    verdict: Verdict;
+    reason: string;
+}
+/**
+ * Evaluate a piece of agent-authored text against the topic's verified
+ * operator and the known-user registry. An attribution to the bound operator
+ * (or any known user) is fine; an attribution to anyone else is the Caroline
+ * failure — warn for prose, block for authority/credential decisions.
+ *
+ * `knownUserNames` are lowercased display names from UserManager (the
+ * authoritative registry). Resolution against it is what the "Know Your
+ * Principal" standard requires before any principal is accepted.
+ */
+export declare function evaluatePrincipalCoherence(text: string, operator: VerifiedOperator | null, knownUserNames?: string[]): PrincipalFinding[];
+//# sourceMappingURL=PrincipalGuard.d.ts.map

package/dist/core/PrincipalGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrincipalGuard.d.ts","sourceRoot":"","sources":["../../src/core/PrincipalGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;6DAC6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,gBAAgB,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAKzG;AAED,wFAAwF;AACxF,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,SAAS,GACT,YAAY,GACZ,MAAM,GACN,YAAY,CAAC;AAEjB,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,eAAe,CAAC;IACtB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;CACjB;AA0CD,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAgB9D;AAED,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAKD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,cAAc,GAAE,MAAM,EAAO,GAC5B,gBAAgB,EAAE,CAqBpB"}

package/dist/core/PrincipalGuard.js

@@ -0,0 +1,125 @@
+/**
+ * PrincipalGuard — cross-principal attribution detector (EXO 3.0 / "Know Your
+ * Principal" standard, Phase 1 brain).
+ *
+ * The "Caroline" incident (2026-06-05, topic 19437): an autonomous session
+ * silently adopted a real OTHER principal as its operator and credited the
+ * actual operator's decisions to her across three docs — and no gate watched,
+ * because the contamination was in the agent's OWN output, not an inbound
+ * message. This module is the pure-logic detector for that failure: given a
+ * piece of agent-authored text, it finds operator-ROLE-decision attributions
+ * ("X approved", "locked with X", "mandate (X)", "X dropped a token") and
+ * flags any whose attributed principal is NOT the topic's bound operator and
+ * does NOT resolve to a known user.
+ *
+ * Pure + deterministic so it is unit-testable in isolation; it performs no I/O
+ * and is not wired into the live request path here (that is a later increment).
+ * The constitution standard it enforces: "Know Your Principal — An Unverified
+ * Identity Is a Guess" (docs/STANDARDS-REGISTRY.md). Spec:
+ * docs/specs/OPERATOR-IDENTITY-BINDING-SPEC.md.
+ */
+/**
+ * Establish a topic's operator from the AUTHENTICATED sender — never from a
+ * content name. The uid is the authority; names are only for matching the
+ * agent's prose against the verified principal. A blank uid yields no operator
+ * (an unbound topic), which the guard treats as "everything is unverified".
+ */
+export function establishOperator(authenticatedUid, displayName) {
+    const uid = String(authenticatedUid ?? '').trim();
+    if (!uid)
+        return null;
+    const names = (displayName ?? '').trim() ? [displayName.trim().toLowerCase()] : [];
+    return { uid, names };
+}
+// ── Detection patterns ───────────────────────────────────────────────
+// Each captures a person-like principal NAME in group 1. Kept conservative:
+// a name is 1-3 capitalized-ish words (so "the team" / "prod" don't match).
+// NAME requires a real capital first letter (case-SENSITIVE — no `i` flag — so
+// "have"/"production" can never be captured as a principal). Only the keyword
+// LEADS are made case-flexible ([Mm]andate, [Ll]ock…) so a sentence-initial
+// "Mandate" matches as well as a mid-sentence "mandate".
+const NAME = String.raw `([A-Z][a-zA-Z]+(?:\s+[A-Z][a-zA-Z]+){0,2})`;
+// Bounded gap that lets a date/short clause sit between a keyword and the name
+// ("Locked 2026-06-04 with Caroline") without swallowing a sentence.
+const GAP = String.raw `[^.\n]{0,40}?`;
+const PATTERNS = [
+    { re: new RegExp(String.raw `\b[Mm]andate\s*\(\s*${NAME}\s*\)`, 'g'), kind: 'mandate' },
+    { re: new RegExp(String.raw `\b${NAME}\s+[Aa]uthoriz(?:ed|es)\b`, 'g'), kind: 'mandate' },
+    { re: new RegExp(String.raw `\b${NAME}\s+[Aa]pprov(?:ed|es)\b`, 'g'), kind: 'approval' },
+    { re: new RegExp(String.raw `\b(?:[Bb]lessed|[Ss]igned[- ]off)\s+by\s+${NAME}`, 'g'), kind: 'approval' },
+    { re: new RegExp(String.raw `\b[Ll]ock(?:ed)?\b${GAP}\b(?:with|by)\s+${NAME}`, 'g'), kind: 'lock' },
+    { re: new RegExp(String.raw `\b[Ss]tanding requirement from\s+${NAME}`, 'g'), kind: 'lock' },
+    { re: new RegExp(String.raw `\b${NAME}\s+(?:dropped|drop)\s+(?:a|the)\s+(?:token|credential|secret|key)`, 'g'), kind: 'credential' },
+    { re: new RegExp(String.raw `\b${NAME}['’]s\s+(?:credential|token|git\s+cred)`, 'g'), kind: 'credential' },
+    { re: new RegExp(String.raw `\b[Oo]n\s+behalf\s+of\s+${NAME}`, 'g'), kind: 'acting-for' },
+    { re: new RegExp(String.raw `\b[Oo]n\s+${NAME}['’]s\s+(?:say-so|behalf|authority)`, 'g'), kind: 'acting-for' },
+];
+// Words that look capitalized but are never principals (sentence-start nouns,
+// product/role terms). Keeps the detector from flagging "Production approved".
+const NON_PRINCIPALS = new Set([
+    'the', 'a', 'an', 'prod', 'production', 'ci', 'team', 'board', 'ops', 'staging',
+    'github', 'telegram', 'slack', 'dawn', 'echo', 'i', 'we', 'you', 'they', 'it',
+    'have', 'has', 'this', 'that', 'every', 'all',
+]);
+function isPersonLike(name) {
+    const firstWord = name.split(/\s+/)[0];
+    // The `i` flag lets [A-Z] match lowercase too, so require an actual capital
+    // first letter here — a real person name is capitalized; "production" is not.
+    const startsCapital = /^[A-Z]/.test(firstWord);
+    return startsCapital && !NON_PRINCIPALS.has(firstWord.toLowerCase());
+}
+/** Find every operator-role-decision attribution in agent-authored text. */
+export function detectAttributions(text) {
+    const out = [];
+    const seen = new Set();
+    for (const { re, kind } of PATTERNS) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            const principal = (m[1] ?? '').trim();
+            if (!principal || !isPersonLike(principal))
+                continue;
+            const key = `${kind}:${principal.toLowerCase()}:${m.index}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ principal: principal.toLowerCase(), kind, snippet: m[0] });
+        }
+    }
+    return out;
+}
+/** Credential/authority-bearing kinds BLOCK when misattributed; the rest WARN. */
+const BLOCK_KINDS = new Set(['mandate', 'credential']);
+/**
+ * Evaluate a piece of agent-authored text against the topic's verified
+ * operator and the known-user registry. An attribution to the bound operator
+ * (or any known user) is fine; an attribution to anyone else is the Caroline
+ * failure — warn for prose, block for authority/credential decisions.
+ *
+ * `knownUserNames` are lowercased display names from UserManager (the
+ * authoritative registry). Resolution against it is what the "Know Your
+ * Principal" standard requires before any principal is accepted.
+ */
+export function evaluatePrincipalCoherence(text, operator, knownUserNames = []) {
+    const known = new Set([
+        ...(operator?.names ?? []),
+        ...knownUserNames.map((n) => n.trim().toLowerCase()).filter(Boolean),
+    ]);
+    const findings = [];
+    for (const attribution of detectAttributions(text)) {
+        if (known.has(attribution.principal))
+            continue; // resolves to a verified principal — fine
+        const verdict = BLOCK_KINDS.has(attribution.kind) ? 'block' : 'warn';
+        findings.push({
+            attribution,
+            verdict,
+            reason: `Operator-role ${attribution.kind} attributed to "${attribution.principal}", who is ` +
+                (operator
+                    ? `not this topic's bound operator and does not resolve to a known user`
+                    : `unverifiable — this topic has no bound operator`) +
+                `. Know Your Principal: an unrecognized party in a decision role is a question to resolve, not a fact to accept.`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=PrincipalGuard.js.map

package/dist/core/PrincipalGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrincipalGuard.js","sourceRoot":"","sources":["../../src/core/PrincipalGuard.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.349",
+  "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:49:15.721Z",
-  "instarVersion": "1.3.349",
+  "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.351.md

@@ -0,0 +1,91 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added `src/core/PrincipalGuard.ts` — the pure-logic brain of the "Know Your
+Principal" cross-principal coherence guard (constitution standard ratified in
+#898). It establishes a topic's operator only from the authenticated sender,
+detects operator-role-decision attributions in agent-authored text ("X
+approved", "Mandate (X)", "locked with X", "X dropped a token"), and flags any
+credited to a principal who is neither the bound operator nor a known user —
+blocking authority/credential misattributions, warning on prose. No runtime
+consumers yet (the wiring is a later increment).
+
+Fixes #866: `POST /projects/:id/advance` building→merged always failed
+`GH_PR_VIEW_UNAVAILABLE` because `StageTransitionValidator` has no internal
+default for `ghPrView`/`gitMergeBaseIsAncestor` and the route never injected
+them — so no project item could ever reach `merged` through the live API.
+The route now injects both as read-only helpers (`gh pr view` and
+`merge-base --is-ancestor` via SafeGitExecutor.readSync) against the
+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
+security fix behind the Caroline identity-bleed incident — it does not alter any
+current behavior.
+
+If you drive a multi-spec initiative through the projects pipeline, its
+items can now actually reach the "merged" stage — the system verifies the
+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`,
+  `detectAttributions`, `evaluatePrincipalCoherence`.
+
+- `POST /projects/:id/advance` with `targetStage: "merged"` now works end to
+  end (was structurally impossible): it verifies the PR via `gh pr view` and
+  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
+regression test (the three real Caroline doc lines all caught with the topic
+bound to the operator; the same lines crediting the operator all pass) and a
+clean `tsc --noEmit`.
+
+- tests/integration/projects-api.test.ts: building→merged now returns
+  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/principal-guard-phase1.md

@@ -0,0 +1,39 @@
+# Side-effects review — PrincipalGuard (Phase 1 brain)
+
+## What this change is
+A new pure-logic module `src/core/PrincipalGuard.ts` (operator establishment +
+cross-principal attribution detector + warn/block evaluator) and its unit test.
+Implements the detector half of the just-ratified "Know Your Principal" standard
+(the cross-principal coherence guard from OPERATOR-IDENTITY-BINDING-SPEC.md §2).
+
+## Blast radius
+- **Runtime impact: none.** Nothing imports `PrincipalGuard` at boot or in any
+  route/job/sentinel yet. Adding the file cannot change live behavior. It is the
+  testable brain; wiring it into the topic-operator binding, session-start
+  injection, and the outbound/at-rest review path are explicit later increments.
+- **No I/O, no network, no new config/route/migration surface.** Pure functions
+  over strings + a `VerifiedOperator` value object.
+- **Establishment is uid-only by construction:** `establishOperator` takes the
+  authenticated sender uid; there is NO code path that accepts a name from
+  content as the operator (the Caroline failure mode is impossible by type).
+
+## Security review
+- The detector is conservative: a name must be capitalized (case-sensitive,
+  not the `i` flag) and not in a non-principal stop-set, so "Production
+  approved" / "The Board approved" do not flag. False positives warn (prose) or
+  block (authority/credential) — they never silently pass a misattribution.
+- No payload/secret handling; operates only on already-authored text.
+
+## Framework generality
+Pure logic, no session-launch/inject/message-delivery surface — framework-agnostic.
+
+## Test coverage
+13 unit tests covering both sides of every boundary: uid-only establishment
+(incl. blank → null), each detection shape, non-principal rejection,
+bound-operator pass, known-user pass, unknown-principal flag with block-vs-warn
+tiering, no-operator case, and the **incident-replay regression test** — the
+three real Caroline doc lines all caught (block for mandate/credential), and the
+same lines crediting the bound operator all pass. `tsc --noEmit` clean.
+
+## Rollback
+Delete the module + test; zero runtime consequence (no consumers).

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.

package/upgrades/1.3.349.md

@@ -1,37 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: patch -->
-
-## What Changed
-
-Fixes #866: `POST /projects/:id/advance` building→merged always failed
-`GH_PR_VIEW_UNAVAILABLE` because `StageTransitionValidator` has no internal
-default for `ghPrView`/`gitMergeBaseIsAncestor` and the route never injected
-them — so no project item could ever reach `merged` through the live API.
-The route now injects both as read-only helpers (`gh pr view` and
-`merge-base --is-ancestor` via SafeGitExecutor.readSync) against the
-project's target repo. A wiring-integrity test asserts the helper-absent
-error can never recur.
-
-## What to Tell Your User
-
-If you drive a multi-spec initiative through the projects pipeline, its
-items can now actually reach the "merged" stage — the system verifies the
-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.
-
-## Summary of New Capabilities
-
-- `POST /projects/:id/advance` with `targetStage: "merged"` now works end to
-  end (was structurally impossible): it verifies the PR via `gh pr view` and
-  confirms the merge commit is reachable on `origin/main` before recording
-  the item as merged.
-
-## Evidence
-
-- tests/integration/projects-api.test.ts: building→merged now returns
-  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.