instar 1.3.349 → 1.3.350

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.350",
   "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:52:19.246Z",
+  "instarVersion": "1.3.350",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {

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

@@ -5,6 +5,15 @@
 
 ## 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
@@ -16,6 +25,10 @@ error can never recur.
 
 ## 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
@@ -24,6 +37,9 @@ finally tracks reality through the whole pipeline.
 
 ## 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
@@ -31,6 +47,11 @@ finally tracks reality through the whole pipeline.
 
 ## 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

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).