instar 0.28.106 → 0.28.107

package/dist/monitoring/AttributionResolver.d.ts

@@ -0,0 +1,46 @@
+/**
+ * AttributionResolver — read-side resolver for the burn-detection system.
+ *
+ * Phase 2 of docs/specs/token-burn-detection-and-self-heal.md.
+ *
+ * Pure function: given the shape of a TokenLedger event (sessionId, cwd,
+ * prompt text, model) returns an attribution_key suitable for grouping
+ * "calls of the same structural origin." Used by the Phase 3 BurnDetector
+ * to populate attribution_key for events the Phase 1 chokepoint did NOT
+ * write directly — chiefly the dominant Claude-CLI path where the JSONL
+ * trail carries the prompt and cwd but no source-side label.
+ *
+ * Authority shape: this is signal-only. It does not gate, throttle, or
+ * decide anything. It maps event → key. The detector emits, the
+ * Remediator decides. See umbrella spec §"Signal-vs-Authority Decomposition".
+ *
+ * No I/O, no time-dependent behavior — deterministic for tests + reasoning.
+ */
+export interface AttributionEvent {
+    sessionId: string;
+    /** cwd / projectPath field from the JSONL line. */
+    projectPath?: string | null;
+    /** The user prompt that triggered the assistant response. Optional — when missing, resolver falls back to cwd / unknown. */
+    prompt?: string | null;
+    /** Model string from the JSONL line (`message.model`). */
+    model?: string | null;
+}
+/**
+ * Resolve an attribution_key for an event.
+ *
+ * Resolution order:
+ *   1. Manifest entry that matches the prompt (with optional cwd / model
+ *      narrowing) → `<component>::<promptFingerprint>`.
+ *   2. cwd-based scheduled-job inference — if the cwd contains a path
+ *      segment like `.instar/jobs/<name>`, return `user-job:<name>`.
+ *   3. cwd-based user-extension inference — if the cwd contains
+ *      `.claude/hooks/` or `.instar/hooks/`, return the hook filename.
+ *   4. Fallback: `unknown::<sessionId-prefix>`.
+ *
+ * The prompt-based check is intentionally first: it's the most informative
+ * signal for the bleed-detection use case (one prompt shape running tens
+ * of thousands of times). cwd-based inference is the secondary signal for
+ * cases where the prompt is variable but the source is recognisable.
+ */
+export declare function resolveAttribution(event: AttributionEvent): string;
+//# sourceMappingURL=AttributionResolver.d.ts.map

package/dist/monitoring/AttributionResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttributionResolver.d.ts","sourceRoot":"","sources":["../../src/monitoring/AttributionResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4HAA4H;IAC5H,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAgClE"}

package/dist/monitoring/AttributionResolver.js

@@ -0,0 +1,107 @@
+/**
+ * AttributionResolver — read-side resolver for the burn-detection system.
+ *
+ * Phase 2 of docs/specs/token-burn-detection-and-self-heal.md.
+ *
+ * Pure function: given the shape of a TokenLedger event (sessionId, cwd,
+ * prompt text, model) returns an attribution_key suitable for grouping
+ * "calls of the same structural origin." Used by the Phase 3 BurnDetector
+ * to populate attribution_key for events the Phase 1 chokepoint did NOT
+ * write directly — chiefly the dominant Claude-CLI path where the JSONL
+ * trail carries the prompt and cwd but no source-side label.
+ *
+ * Authority shape: this is signal-only. It does not gate, throttle, or
+ * decide anything. It maps event → key. The detector emits, the
+ * Remediator decides. See umbrella spec §"Signal-vs-Authority Decomposition".
+ *
+ * No I/O, no time-dependent behavior — deterministic for tests + reasoning.
+ */
+import { buildAttributionKey } from './attributionKey.js';
+import { ATTRIBUTION_MANIFEST } from './attribution-manifest.js';
+/**
+ * Resolve an attribution_key for an event.
+ *
+ * Resolution order:
+ *   1. Manifest entry that matches the prompt (with optional cwd / model
+ *      narrowing) → `<component>::<promptFingerprint>`.
+ *   2. cwd-based scheduled-job inference — if the cwd contains a path
+ *      segment like `.instar/jobs/<name>`, return `user-job:<name>`.
+ *   3. cwd-based user-extension inference — if the cwd contains
+ *      `.claude/hooks/` or `.instar/hooks/`, return the hook filename.
+ *   4. Fallback: `unknown::<sessionId-prefix>`.
+ *
+ * The prompt-based check is intentionally first: it's the most informative
+ * signal for the bleed-detection use case (one prompt shape running tens
+ * of thousands of times). cwd-based inference is the secondary signal for
+ * cases where the prompt is variable but the source is recognisable.
+ */
+export function resolveAttribution(event) {
+    // 1. Manifest-based prompt match (with optional cwd/model narrowing).
+    if (event.prompt && event.prompt.length > 0) {
+        for (const entry of ATTRIBUTION_MANIFEST) {
+            if (matchesEntry(entry, event)) {
+                return buildAttributionKey(entry.component, event.prompt);
+            }
+        }
+    }
+    // 2. Scheduled-job inference: a path segment of the cwd is the job name.
+    //    e.g. /Users/x/.instar/jobs/daily-summary → user-job:daily-summary
+    if (event.projectPath) {
+        const jobMatch = event.projectPath.match(/[/\\]\.instar[/\\]jobs[/\\]([^/\\]+)/);
+        if (jobMatch && jobMatch[1]) {
+            return `user-job:${jobMatch[1]}::${shortPromptFp(event.prompt)}`;
+        }
+        // 3. Hook / extension inference.
+        const hookMatch = event.projectPath.match(/[/\\](?:\.claude|\.instar)[/\\]hooks[/\\]([^/\\]+)/);
+        if (hookMatch && hookMatch[1]) {
+            return `user-hook:${hookMatch[1]}::${shortPromptFp(event.prompt)}`;
+        }
+    }
+    // 4. Fallback. Use a stable session-id prefix so a single misbehaving
+    //    session shows as one key (and not exploded by per-prompt fingerprint).
+    if (!event.sessionId || event.sessionId.length === 0) {
+        return 'unknown::no-session';
+    }
+    const sidPrefix = event.sessionId.slice(0, 8);
+    return `unknown::${sidPrefix}`;
+}
+function matchesEntry(entry, event) {
+    // Prompt must match if patterns are defined (Phase 2 always defines them).
+    if (entry.promptPatterns && entry.promptPatterns.length > 0) {
+        if (!event.prompt)
+            return false;
+        const hit = entry.promptPatterns.some((re) => re.test(event.prompt));
+        if (!hit)
+            return false;
+    }
+    // Optional cwd narrowing.
+    if (entry.cwdPatterns && entry.cwdPatterns.length > 0) {
+        if (!event.projectPath)
+            return false;
+        const hit = entry.cwdPatterns.some((re) => re.test(event.projectPath));
+        if (!hit)
+            return false;
+    }
+    // Optional model narrowing.
+    if (entry.modelHints && entry.modelHints.length > 0) {
+        if (!event.model)
+            return false;
+        const hit = entry.modelHints.some((m) => event.model.includes(m));
+        if (!hit)
+            return false;
+    }
+    return true;
+}
+function shortPromptFp(prompt) {
+    if (!prompt || prompt.length === 0)
+        return 'nonprompt';
+    // Cheap deterministic fingerprint without importing crypto on every call.
+    // Phase 1's buildAttributionKey covers the cryptographic case; here we
+    // only need to disambiguate prompts at the user-job / user-hook level.
+    let h = 0;
+    const slice = prompt.slice(0, 128);
+    for (let i = 0; i < slice.length; i++)
+        h = ((h << 5) - h + slice.charCodeAt(i)) | 0;
+    return (h >>> 0).toString(16).padStart(8, '0').slice(0, 8);
+}
+//# sourceMappingURL=AttributionResolver.js.map

package/dist/monitoring/AttributionResolver.js.map

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

package/dist/monitoring/attribution-manifest.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Static attribution manifest for the burn-detection-and-self-heal system.
+ *
+ * Phase 2 of docs/specs/token-burn-detection-and-self-heal.md. Maps known
+ * instar-internal LLM call patterns to stable component names so the
+ * BurnDetector (Phase 3) can group calls of the same shape.
+ *
+ * Adding entries does not require a spec change — they are inference rules
+ * for an observation system, not authority. The manifest is a hint store,
+ * not a gate.
+ *
+ * Pattern semantics (per docs/specs/token-burn-detection-and-self-heal.md
+ * §"Attribution key", §"Capture surface"):
+ *   - `promptPatterns`: regex on the user prompt that prompted the
+ *     assistant response. First-match wins. Order matters — list more
+ *     specific patterns first.
+ *   - `cwdPatterns`: optional regex on the `cwd` field of the JSONL line.
+ *     Useful when a component is recognisable by its working directory
+ *     but its prompt varies.
+ *   - `modelHints`: optional list of model substrings; narrows the match
+ *     when the same prompt could come from multiple components but only
+ *     one of them uses a specific model.
+ */
+export interface AttributionPattern {
+    /** Stable component name written into attribution_key. */
+    component: string;
+    /** Regex matched against the user prompt. */
+    promptPatterns?: RegExp[];
+    /** Regex matched against the cwd / projectPath field. */
+    cwdPatterns?: RegExp[];
+    /** Substrings narrowing the match to specific models. */
+    modelHints?: string[];
+}
+/**
+ * The manifest. Order is significant — first-match wins. Add more specific
+ * entries before broader ones.
+ */
+export declare const ATTRIBUTION_MANIFEST: AttributionPattern[];
+//# sourceMappingURL=attribution-manifest.d.ts.map

package/dist/monitoring/attribution-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution-manifest.d.ts","sourceRoot":"","sources":["../../src/monitoring/attribution-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,EAsDpD,CAAC"}

package/dist/monitoring/attribution-manifest.js

@@ -0,0 +1,83 @@
+/**
+ * Static attribution manifest for the burn-detection-and-self-heal system.
+ *
+ * Phase 2 of docs/specs/token-burn-detection-and-self-heal.md. Maps known
+ * instar-internal LLM call patterns to stable component names so the
+ * BurnDetector (Phase 3) can group calls of the same shape.
+ *
+ * Adding entries does not require a spec change — they are inference rules
+ * for an observation system, not authority. The manifest is a hint store,
+ * not a gate.
+ *
+ * Pattern semantics (per docs/specs/token-burn-detection-and-self-heal.md
+ * §"Attribution key", §"Capture surface"):
+ *   - `promptPatterns`: regex on the user prompt that prompted the
+ *     assistant response. First-match wins. Order matters — list more
+ *     specific patterns first.
+ *   - `cwdPatterns`: optional regex on the `cwd` field of the JSONL line.
+ *     Useful when a component is recognisable by its working directory
+ *     but its prompt varies.
+ *   - `modelHints`: optional list of model substrings; narrows the match
+ *     when the same prompt could come from multiple components but only
+ *     one of them uses a specific model.
+ */
+/**
+ * The manifest. Order is significant — first-match wins. Add more specific
+ * entries before broader ones.
+ */
+export const ATTRIBUTION_MANIFEST = [
+    // The 2026-05-15 bleed: the InputDetector's NO_PROMPT classifier asked
+    // the LLM "is this stuck?" every 5s on every idle session, burning
+    // ~3B tokens/day. This pattern catches that exact prompt shape.
+    {
+        component: 'InputDetector',
+        promptPatterns: [/analyzing terminal output/i, /is this stuck/i, /stalled session detection/i],
+    },
+    // MessagingToneGate evaluates outbound user-facing messages for tone +
+    // banned-content compliance (ELI16, no inline code, etc).
+    {
+        component: 'MessagingToneGate',
+        promptPatterns: [/evaluate this outbound message/i, /tone gate/i, /eli16/i],
+    },
+    // CommitmentSentinel watches for commitments the agent made that lack
+    // follow-through.
+    {
+        component: 'CommitmentSentinel',
+        promptPatterns: [/commitment.*follow.through/i, /unfulfilled commitment/i],
+    },
+    // MessageSentinel classifies inbound messages (emergency stop, etc).
+    {
+        component: 'MessageSentinel',
+        promptPatterns: [/classify.*inbound message/i, /emergency stop classifier/i],
+    },
+    // StallTriageNurse — the LLM-powered session-recovery classifier.
+    {
+        component: 'StallTriageNurse',
+        promptPatterns: [/triage.*stalled session/i, /session.*stall.*classifier/i],
+    },
+    // CoherenceReviewer — the deeper "is this agent acting coherently"
+    // check, invoked by the coherence-gate path.
+    {
+        component: 'CoherenceReviewer',
+        promptPatterns: [/coherence review/i, /agent coherence/i],
+    },
+    // ProjectDriftChecker — round-start signal that the project context
+    // has drifted from what was loaded.
+    {
+        component: 'ProjectDriftChecker',
+        promptPatterns: [/project drift/i, /context drift detection/i],
+    },
+    // ResumeValidator — verifies a Claude Code resume payload before
+    // letting a session pick back up.
+    {
+        component: 'ResumeValidator',
+        promptPatterns: [/validate.*resume payload/i, /resume validation/i],
+    },
+    // TopicLinkageHandler — figures out which existing thread a new
+    // Telegram message belongs to.
+    {
+        component: 'TopicLinkageHandler',
+        promptPatterns: [/topic linkage/i, /thread linking/i],
+    },
+];
+//# sourceMappingURL=attribution-manifest.js.map

package/dist/monitoring/attribution-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution-manifest.js","sourceRoot":"","sources":["../../src/monitoring/attribution-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAaH;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAyB;IACxD,uEAAuE;IACvE,mEAAmE;IACnE,gEAAgE;IAChE;QACE,SAAS,EAAE,eAAe;QAC1B,cAAc,EAAE,CAAC,4BAA4B,EAAE,gBAAgB,EAAE,4BAA4B,CAAC;KAC/F;IACD,uEAAuE;IACvE,0DAA0D;IAC1D;QACE,SAAS,EAAE,mBAAmB;QAC9B,cAAc,EAAE,CAAC,iCAAiC,EAAE,YAAY,EAAE,QAAQ,CAAC;KAC5E;IACD,sEAAsE;IACtE,kBAAkB;IAClB;QACE,SAAS,EAAE,oBAAoB;QAC/B,cAAc,EAAE,CAAC,6BAA6B,EAAE,yBAAyB,CAAC;KAC3E;IACD,qEAAqE;IACrE;QACE,SAAS,EAAE,iBAAiB;QAC5B,cAAc,EAAE,CAAC,4BAA4B,EAAE,4BAA4B,CAAC;KAC7E;IACD,kEAAkE;IAClE;QACE,SAAS,EAAE,kBAAkB;QAC7B,cAAc,EAAE,CAAC,0BAA0B,EAAE,6BAA6B,CAAC;KAC5E;IACD,mEAAmE;IACnE,6CAA6C;IAC7C;QACE,SAAS,EAAE,mBAAmB;QAC9B,cAAc,EAAE,CAAC,mBAAmB,EAAE,kBAAkB,CAAC;KAC1D;IACD,oEAAoE;IACpE,oCAAoC;IACpC;QACE,SAAS,EAAE,qBAAqB;QAChC,cAAc,EAAE,CAAC,gBAAgB,EAAE,0BAA0B,CAAC;KAC/D;IACD,iEAAiE;IACjE,kCAAkC;IAClC;QACE,SAAS,EAAE,iBAAiB;QAC5B,cAAc,EAAE,CAAC,2BAA2B,EAAE,oBAAoB,CAAC;KACpE;IACD,gEAAgE;IAChE,+BAA+B;IAC/B;QACE,SAAS,EAAE,qBAAqB;QAChC,cAAc,EAAE,CAAC,gBAAgB,EAAE,iBAAiB,CAAC;KACtD;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.106",
+  "version": "0.28.107",
   "description": "Persistent autonomy infrastructure for AI agents",
   "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-15T21:25:05.645Z",
-  "instarVersion": "0.28.106",
+  "generatedAt": "2026-05-15T21:38:45.342Z",
+  "instarVersion": "0.28.107",
   "entryCount": 188,
   "entries": {
     "hook:session-start": {

package/upgrades/0.28.107.md

@@ -0,0 +1,35 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Phase two of the token-burn-detection-and-self-heal system. Still observation-only — no alerts, no auto-throttling, no new dashboard. This phase adds the piece that figures out which component made each LLM call after the fact.
+
+What lands today:
+
+- A short list of patterns that match the prompt shapes the agent's internal components produce.
+- A pure function that takes a token-ledger event and returns a stable attribution identifier.
+
+The detector in phase three will use this function to group calls by where they came from. Nothing in production calls the new function yet.
+
+## What to Tell Your User
+
+Your agent picked up the second of six pieces of the new self-watch system. Like the first piece, nothing changes about how your agent behaves today. The watcher you approved is being built in stages so each piece can be reviewed on its own.
+
+For now, no action needed. The third piece is the one that will start actually noticing things.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Read-side attribution resolver | Internal — no surface yet. |
+| Static attribution manifest | Internal — covers nine known components. |
+
+## Evidence
+
+Twenty-two new tests in `tests/unit/burn-detection-phase-2.test.ts` all pass. The resolver is a pure function with no I/O and no dependency on time, so the test suite is deterministic. Manifest integrity tests cover uniqueness of component names, non-empty entries, and at-least-one-matcher per entry.
+
+The existing token-ledger and selectIntelligenceProvider unit suites still pass — no regression on the parts not touched by this phase.
+
+Side-effects review for this phase is in `upgrades/side-effects/token-burn-detection-phase-2.md`. The reviewer identified zero blocking concerns; phase two ships pure inference with no runtime decision authority, so second-pass review is not required per the instar-dev skill criteria.

package/upgrades/side-effects/token-burn-detection-phase-2.md

@@ -0,0 +1,44 @@
+# Side-Effects Review — Token-Burn Detection Phase 2
+
+**Spec**: `docs/specs/token-burn-detection-phase-2.md` (parent: `docs/specs/token-burn-detection-and-self-heal.md`, approved by Justin 2026-05-15).
+
+## 1. Over-block
+
+Phase 2 cannot block anything — it's a pure function with no caller in production yet. Worst case "over-block" is a wrong attribution: a prompt that should have been labeled `InputDetector` ends up under `unknown::<sessionPrefix>`. Phase 3's detector treats unknown-keyed spend as alert-only-on-unknown (per umbrella §"Auto-throttle mechanism"), so even a wrong attribution still produces a usable alert — just less informative.
+
+## 2. Under-block
+
+The pattern manifest covers nine known instar-internal components. New components added in unrelated PRs do not appear in the manifest until someone adds them. They fall through to `unknown::<sessionPrefix>` and are still observable — just not labeled by name. Adding manifest entries is the right discipline going forward; the lint from Phase 1 catches new direct-LLM-HTTP callers, but it does not catch new components calling through the chokepoint without a manifest entry. This is a known and accepted gap.
+
+## 3. Level-of-abstraction fit
+
+`AttributionResolver` and the manifest sit in `src/monitoring/`, next to `TokenLedger` and `LlmRateGate`. Correct layer: it's part of the observability surface, not a piece of the core LLM-call path or a decision-maker.
+
+The resolver is a pure function — no I/O, no time-dependent behavior. That's the right abstraction; Phase 3's read path can call it in a tight loop without worrying about side effects.
+
+## 4. Signal-vs-authority compliance
+
+The resolver is signal-only. It produces an attribution key; it does not decide whether anything happens. The umbrella spec's §"Signal-vs-Authority Decomposition" places AttributionResolver in the "no authority" row, and Phase 2 matches that placement.
+
+**Compliant.**
+
+## 5. Interactions
+
+- **TokenLedger.** No interaction in Phase 2 — the resolver does not read or write the ledger. Phase 3 will pair them.
+- **LlmRateGate.** No interaction. The gate enforces decisions; the resolver produces keys those decisions reference.
+- **AnthropicIntelligenceProvider chokepoint path.** No interaction — when the chokepoint writes attribution_key, Phase 3's read path passes it through unchanged and skips the resolver call.
+- **Other manifests.** No other manifest in the tree has overlapping responsibility; this is a new file.
+
+No shadowing, no double-fire, no race.
+
+## 6. External surfaces
+
+No external surface change. Phase 2 is internal pure code with no callers in production.
+
+## 7. Rollback cost
+
+Three new files (`AttributionResolver.ts`, `attribution-manifest.ts`, test). Backout = delete the three files. No persistent state, no schema change, no caller dependency until Phase 3.
+
+## Second-pass review
+
+Phase 2 ships pure observability inference with no runtime decision authority. It does NOT touch any of the high-risk surfaces listed in `/instar-dev` Phase 5 (no block/allow, no session lifecycle, no coherence gate, no sentinel/guard/gate/watchdog with authority). Second-pass review is **not required** per the skill's criteria.