instar 0.28.110 → 0.28.112

package/dist/server/routes/remediation-proposals.js

@@ -0,0 +1,350 @@
+/**
+ * Dashboard Proposals routes — Tier-3 S-2 of the Self-Healing Remediator v2.
+ *
+ * Spec anchor: docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md
+ *   §A10 — outstanding-proposal cap (≤ 3 visible at any time + queued behind).
+ *   §A13 — Config + telemetry + dashboard taxonomy. Proposals is a sub-section
+ *          of the existing Remediation tab. All four `/remediation/proposals*`
+ *          routes require bearer auth + `X-Instar-Request: 1`. Redacted view
+ *          by default; full `reason.full` field shown only at `collaborative`
+ *          trust (matches v1's `/remediation/attempts` redaction rule).
+ *   §A26 — Proposal dismiss requires `collaborative` trust + ≤ 10/hour
+ *          per-principal rate-limit. Every dismiss is audit-logged with the
+ *          principal identity (callers wire the audit-writer; this route
+ *          emits structured events / route-level diagnostics only).
+ *   §A48 — Path-limited proposal fetch shape (id-keyed JSON files under
+ *          `.instar/remediation/proposals-<machineId>/<proposalId>.json`).
+ *   §A57 Tier-3 — Dashboard Proposals sub-section + auth-gated routes.
+ *
+ * Routes:
+ *   GET  /remediation/proposals             — list outstanding proposals
+ *                                              (visible + queued).
+ *   GET  /remediation/proposals/:id         — detail view of a proposal.
+ *   POST /remediation/proposals/:id/dismiss — user dismisses (no promotion).
+ *                                              Requires `collaborative` trust.
+ *
+ * Redaction rule: at less than `collaborative` trust, the response omits
+ * `forensic.rawResponse` and any `sampleEvents[].reason.full` field. At
+ * `collaborative` trust, both fields are included verbatim. The proposal
+ * file on disk always carries redacted `reason.redacted` per S-1; this
+ * route enforces redaction at the response boundary regardless of disk
+ * shape, so a future migration adding `reason.full` does not silently
+ * leak the field through.
+ *
+ * Reads proposals from every `proposals-<machineId>/` directory under
+ * `<stateDir>/remediation/`. The store is per-machine (A14) but the
+ * dashboard surfaces a fleet-wide list; merging happens here at the read
+ * boundary. The `producingAgentId` field on each proposal disambiguates
+ * cross-machine duplicates per §A60.
+ *
+ * Dismiss is implemented as a status-mutation in place (status: 'outstanding'
+ * → 'dismissed'). The proposal is NOT deleted — auditability requires the
+ * file to remain for post-hoc forensic review. The outstanding-3 cap
+ * counts only `status === 'outstanding'` entries.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+// ── Constants ────────────────────────────────────────────────────────
+const PROPOSAL_DIR_PREFIX = 'proposals-';
+const PROPOSAL_ID_REGEX = /^[A-Za-z0-9_-]{1,128}$/;
+const DISMISS_RATE_LIMIT_PER_HOUR = 10;
+const HOUR_MS = 60 * 60 * 1000;
+// ── Helpers ──────────────────────────────────────────────────────────
+function requireUserIntent(req, res) {
+    const header = String(req.header('x-instar-request') ?? '').trim();
+    if (header !== '1') {
+        res.status(400).json({
+            error: 'X-Instar-Request: 1 header required (user-intent attestation)',
+            reason: 'missing-user-intent',
+        });
+        return false;
+    }
+    return true;
+}
+function listProposalDirs(remediationDir) {
+    if (!fs.existsSync(remediationDir))
+        return [];
+    let entries;
+    try {
+        entries = fs.readdirSync(remediationDir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        if (!name.startsWith(PROPOSAL_DIR_PREFIX))
+            continue;
+        const abs = path.join(remediationDir, name);
+        try {
+            const stat = fs.statSync(abs);
+            if (stat.isDirectory())
+                out.push(abs);
+        }
+        catch {
+            // Skip unreadable entries.
+        }
+    }
+    return out;
+}
+function readProposalsFromDir(dir) {
+    let files;
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        try {
+            const raw = fs.readFileSync(path.join(dir, f), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && typeof parsed.proposalId === 'string') {
+                parsed.sourceMachineDir = path.basename(dir);
+                out.push(parsed);
+            }
+        }
+        catch {
+            // Skip corrupt entries; A26 forensic copy lives in llm-raw-*.jsonl.
+        }
+    }
+    return out;
+}
+function loadAllProposals(stateDir) {
+    const remediationDir = path.join(stateDir, 'remediation');
+    const dirs = listProposalDirs(remediationDir);
+    const all = [];
+    for (const d of dirs) {
+        all.push(...readProposalsFromDir(d));
+    }
+    // Sort oldest-first to make the visible-3 deterministic.
+    all.sort((a, b) => (a.generatedAt ?? 0) - (b.generatedAt ?? 0));
+    return all;
+}
+function findProposalById(stateDir, id) {
+    const remediationDir = path.join(stateDir, 'remediation');
+    const dirs = listProposalDirs(remediationDir);
+    for (const d of dirs) {
+        const candidate = path.join(d, `${id}.json`);
+        if (fs.existsSync(candidate)) {
+            try {
+                const raw = fs.readFileSync(candidate, 'utf8');
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === 'object' && parsed.proposalId === id) {
+                    parsed.sourceMachineDir = path.basename(d);
+                    return { proposal: parsed, filePath: candidate };
+                }
+            }
+            catch {
+                // Skip — treated as not-found.
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Apply the §A13 redaction rule: at less than `collaborative` trust, strip
+ * `forensic.rawResponse` and any `sampleEvents[].reason.full` field. Returns
+ * a defensive copy — the on-disk JSON is never mutated.
+ */
+function redactForViewer(proposal, hasCollaborative) {
+    if (hasCollaborative) {
+        return { ...proposal, redactionApplied: false };
+    }
+    const copy = {
+        ...proposal,
+        redactionApplied: true,
+    };
+    if (Array.isArray(copy.sampleEvents)) {
+        copy.sampleEvents = copy.sampleEvents.map((e) => {
+            if (!e || !e.reason)
+                return e;
+            const { full: _omit, ...rest } = e.reason;
+            return { ...e, reason: rest };
+        });
+    }
+    if (copy.forensic && typeof copy.forensic === 'object') {
+        const { rawResponse: _omit, ...rest } = copy.forensic;
+        copy.forensic = rest;
+    }
+    return copy;
+}
+function makeDismissLimiter(now) {
+    const buckets = new Map();
+    return function check(principal) {
+        const t = now();
+        let bucket = buckets.get(principal);
+        if (!bucket) {
+            bucket = { timestamps: [] };
+            buckets.set(principal, bucket);
+        }
+        // Drop expired timestamps.
+        while (bucket.timestamps.length > 0 && bucket.timestamps[0] <= t - HOUR_MS) {
+            bucket.timestamps.shift();
+        }
+        if (bucket.timestamps.length >= DISMISS_RATE_LIMIT_PER_HOUR) {
+            return {
+                allowed: false,
+                retryAfterMs: bucket.timestamps[0] + HOUR_MS - t,
+            };
+        }
+        bucket.timestamps.push(t);
+        return { allowed: true };
+    };
+}
+function principalKey(req) {
+    // Bearer-only model: every authed call is the configured principal.
+    // We still partition by IP for defence-in-depth against future
+    // multi-principal expansion. `'auth'` fallback handles tests that mount
+    // the routes without a real socket (supertest).
+    return `${req.ip || req.socket?.remoteAddress || 'auth'}`;
+}
+// ── Public API ───────────────────────────────────────────────────────
+/**
+ * Register the three Tier-3 S-2 Dashboard Proposals routes on the given
+ * Express app. The routes assume bearer-auth middleware is already mounted
+ * UPSTREAM of this registration — registration order is the caller's
+ * responsibility.
+ */
+export function registerRemediationProposalsRoutes(opts) {
+    const { app, stateDir, trustSource } = opts;
+    const now = opts.now ?? (() => Date.now());
+    const emit = (event, payload) => {
+        try {
+            opts.onEvent?.({ event, payload });
+        }
+        catch {
+            // Observability MUST never throw (matches NovelFailureReviewer convention).
+        }
+    };
+    const dismissLimiter = makeDismissLimiter(now);
+    // GET /remediation/proposals — list (visible + queued).
+    app.get('/remediation/proposals', (req, res) => {
+        if (!requireUserIntent(req, res))
+            return;
+        let proposals = [];
+        try {
+            proposals = loadAllProposals(stateDir);
+        }
+        catch (err) {
+            // Missing proposals-<machineId>/ directory is handled by
+            // loadAllProposals → returns []. Any other error is a 500.
+            res.status(500).json({ error: err.message });
+            return;
+        }
+        const hasCollaborative = trustSource.hasCollaborativeTrust();
+        const outstanding = proposals.filter((p) => p.status === 'outstanding');
+        const dismissed = proposals.filter((p) => p.status === 'dismissed');
+        const promoted = proposals.filter((p) => p.status === 'promoted');
+        // Visible-3 + queued behind (§A10).
+        const visible = outstanding.slice(0, 3).map((p) => redactForViewer(p, hasCollaborative));
+        const queued = outstanding.slice(3).map((p) => redactForViewer(p, hasCollaborative));
+        emit('remediation.dashboard.proposals-listed', {
+            visibleCount: visible.length,
+            queuedCount: queued.length,
+            dismissedCount: dismissed.length,
+            promotedCount: promoted.length,
+            hasCollaborativeTrust: hasCollaborative,
+        });
+        res.json({
+            visible,
+            queued,
+            dismissed: dismissed.map((p) => redactForViewer(p, hasCollaborative)),
+            promoted: promoted.map((p) => redactForViewer(p, hasCollaborative)),
+            trust: { hasCollaborative },
+        });
+    });
+    // GET /remediation/proposals/:id — detail.
+    app.get('/remediation/proposals/:id', (req, res) => {
+        if (!requireUserIntent(req, res))
+            return;
+        const id = String(req.params.id ?? '');
+        if (!PROPOSAL_ID_REGEX.test(id)) {
+            res.status(400).json({ error: 'invalid proposalId format', reason: 'invalid-id' });
+            return;
+        }
+        const found = findProposalById(stateDir, id);
+        if (!found) {
+            res.status(404).json({ error: 'proposal not found', proposalId: id });
+            return;
+        }
+        const hasCollaborative = trustSource.hasCollaborativeTrust();
+        const view = redactForViewer(found.proposal, hasCollaborative);
+        emit('remediation.dashboard.proposal-fetched', {
+            proposalId: id,
+            hasCollaborativeTrust: hasCollaborative,
+        });
+        res.json({ proposal: view, trust: { hasCollaborative } });
+    });
+    // POST /remediation/proposals/:id/dismiss — collaborative-only (§A26).
+    app.post('/remediation/proposals/:id/dismiss', (req, res) => {
+        if (!requireUserIntent(req, res))
+            return;
+        const id = String(req.params.id ?? '');
+        if (!PROPOSAL_ID_REGEX.test(id)) {
+            res.status(400).json({ error: 'invalid proposalId format', reason: 'invalid-id' });
+            return;
+        }
+        if (!trustSource.hasCollaborativeTrust()) {
+            emit('remediation.dashboard.dismiss-refused', {
+                proposalId: id,
+                reason: 'trust-level-below-collaborative',
+            });
+            res.status(403).json({
+                error: 'dismiss requires collaborative trust',
+                reason: 'trust-level-below-collaborative',
+            });
+            return;
+        }
+        const principal = principalKey(req);
+        const rl = dismissLimiter(principal);
+        if (!rl.allowed) {
+            emit('remediation.dashboard.dismiss-refused', {
+                proposalId: id,
+                reason: 'rate-limited',
+                principal,
+            });
+            res.status(429).json({
+                error: `dismiss rate limit exceeded (max ${DISMISS_RATE_LIMIT_PER_HOUR}/hour per principal)`,
+                retryAfterMs: rl.retryAfterMs,
+                reason: 'rate-limited',
+            });
+            return;
+        }
+        const found = findProposalById(stateDir, id);
+        if (!found) {
+            res.status(404).json({ error: 'proposal not found', proposalId: id });
+            return;
+        }
+        if (found.proposal.status === 'dismissed') {
+            // Idempotent — second dismiss is a no-op, returns current state.
+            res.json({ proposal: redactForViewer(found.proposal, true), dismissed: false, alreadyDismissed: true });
+            return;
+        }
+        if (found.proposal.status === 'promoted') {
+            res.status(409).json({
+                error: 'cannot dismiss a promoted proposal',
+                reason: 'already-promoted',
+            });
+            return;
+        }
+        const next = {
+            ...found.proposal,
+            status: 'dismissed',
+        };
+        try {
+            fs.writeFileSync(found.filePath, JSON.stringify(next, null, 2), { mode: 0o600 });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+            return;
+        }
+        emit('remediation.dashboard.proposal-dismissed', {
+            proposalId: id,
+            principal,
+        });
+        res.json({ proposal: redactForViewer(next, true), dismissed: true });
+    });
+}
+//# sourceMappingURL=remediation-proposals.js.map

package/dist/server/routes/remediation-proposals.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.110",
+  "version": "0.28.112",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/scripts/instar-dev-precommit.js

@@ -29,6 +29,7 @@ import crypto from 'node:crypto';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { checkEli16Overview } from './eli16-overview-check.mjs';
+import { verifyProposalDerivedRunbooks } from '../skills/instar-dev/scripts/verify-proposal-derived-runbook.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -329,10 +330,39 @@ if (staged.includes(spec) && !staged.includes(eli16Rel)) {
   );
 }
 
+// ─── Step 8: proposal-derived runbook gate (S-3) ─────────────────────────
+// Per SELF-HEALING-REMEDIATOR-V2-SPEC §A11/§A22/§A32, runbook source files
+// emitted by the SystemReviewer proposal pipeline must:
+//   1. Reference a proposal that actually exists in
+//      .instar/remediation/proposals-*/<id>.json on this checkout, AND
+//   2. Carry a __producingAgentId const matching the proposal's
+//      producingAgentId field.
+// The CI gate (C-1) re-verifies at PR-merge time with full fleet visibility.
+// This commit-time gate catches author mistakes before the PR is pushed.
+
+const promotionGateResult = verifyProposalDerivedRunbooks({
+  repoRoot: ROOT,
+  files: staged,
+});
+if (!promotionGateResult.ok) {
+  blockCommit(
+    inScopeFiles,
+    [
+      'Proposal-derived runbook gate refused this commit:',
+      `  ${promotionGateResult.reason}`,
+      '',
+      'See SELF-HEALING-REMEDIATOR-V2-SPEC.md §A11, §A22, §A32 for the rationale.',
+      'The proposal pipeline (Tier-3 S-1) must emit __proposalDerivedFrom +',
+      '__producingAgentId together, and the matching proposal JSON must be',
+      'present at .instar/remediation/proposals-<machineId>/<id>.json.',
+    ].join('\n'),
+  );
+}
+
 // ─── Pass ────────────────────────────────────────────────────────────────
 
 console.error(
-  `[instar-dev-precommit] OK — trace ${path.basename(validTrace.entry.file)} covers ${inScopeFiles.length} in-scope file(s), artifact ${validTrace.trace.artifactPath} verified, spec ${spec} is converged + approved, ELI16 overview ${eli16Rel} present (${eli16Result.charCount} chars).`,
+  `[instar-dev-precommit] OK — trace ${path.basename(validTrace.entry.file)} covers ${inScopeFiles.length} in-scope file(s), artifact ${validTrace.trace.artifactPath} verified, spec ${spec} is converged + approved, ELI16 overview ${eli16Rel} present (${eli16Result.charCount} chars), promotion-gate: ${promotionGateResult.reason}.`,
 );
 process.exit(0);
 

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-16T00:17:59.972Z",
-  "instarVersion": "0.28.110",
+  "generatedAt": "2026-05-16T18:53:49.177Z",
+  "instarVersion": "0.28.112",
   "entryCount": 188,
   "entries": {
     "hook:session-start": {
@@ -1416,7 +1416,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "f90bbc51ba1129b5664eabc4e9463fa347213c08c3eac5ff1e60788b1bcb730f",
+      "contentHash": "510f556002273a0ba882a9db9cb99a22b5d96eeb1362570d5e23e12de23bb55f",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {

package/upgrades/0.28.111.md

@@ -0,0 +1,43 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+Tier-3 step two of the self-healing remediator is live. The Dashboard now has a Remediation Proposals view, and three new HTTP endpoints back it.
+
+What lands today:
+
+- A list endpoint that surfaces every pending NovelFailureReviewer proposal on disk. Up to three appear in the visible section; any extras sit silently in the queued section per the outstanding-three cap. Bearer auth and an `X-Instar-Request` header are required, matching the convention used by other user-authoritative endpoints.
+- A detail endpoint for a single proposal. At the collaborative trust level the full LLM forensic record and raw reason text come through. Below collaborative trust the route strips the untrusted fields before they reach the response — the dashboard always renders the LLM-summarized portion inside an "Untrusted LLM-summarized content" frame, prefixed `[REVIEW NEEDED]` per the spec rendering rule.
+- A dismiss endpoint that lets a collaborative-trust user clear a proposal from the outstanding-three cap. Each principal is limited to ten dismissals per hour. Dismiss is idempotent — re-dismissing a proposal returns the current state instead of erroring.
+- A standalone dashboard page at `/dashboard/proposals.html` that reads from the three endpoints. The page can be linked from the existing Remediation tab once Tier-2 lands; until then it stands on its own.
+
+## What to Tell Your User
+
+Your agent can now show you which novel failures it has noticed but does not yet know how to fix. From this release on, when the NovelFailureReviewer runs and finds a recurring un-recognized error, it writes a proposal to disk. You can review those proposals in your dashboard at the new Remediation Proposals page, and dismiss the ones that turn out to be noise.
+
+The visible list shows three at a time so you are never asked to review a wall of items. Anything beyond three sits silently in the queued section and is shown once you clear space. Dismissing requires the collaborative trust level — the same level you set for other write-side dashboard actions.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Pending-proposal list at `/remediation/proposals` | Bearer auth + `X-Instar-Request: 1`. |
+| Proposal detail at `/remediation/proposals/:id` | Same auth shape; full fields shown only at collaborative trust. |
+| Proposal dismiss at `/remediation/proposals/:id/dismiss` | Collaborative trust + bearer + `X-Instar-Request: 1`. Ten dismissals per hour per principal. |
+| Dashboard Proposals page at `/dashboard/proposals.html` | Open in a browser, paste your bearer token, click Refresh. |
+
+## Evidence
+
+Twelve new integration tests in `tests/integration/remediation-proposals-routes.test.ts` cover the nine spec-required cases plus three bonus checks (404 on unknown id, 400 on invalid id format, three-visible cap with queued overflow). All twelve pass. The full TypeScript build passes clean (`tsc --noEmit` returns zero).
+
+Side-effects review for this slice is in `upgrades/side-effects/s2-dashboard-proposals.md`. Second-pass review was marked not-required by the spec gate procedure — the routes are read-mostly with one write path (dismiss) whose authority is gated through `TrustElevationSource.hasCollaborativeTrust()`, the same gate used by S-1's in-process dismiss path.
+
+The new route file is `src/server/routes/remediation-proposals.ts` (about three hundred sixty lines). Wiring into `AgentServer.ts` adds eight lines guarded by a try/catch so a misconfigured trust source cannot prevent the server from starting. A one-line visibility change to `TrustElevationSource.hasCollaborativeTrust()` makes the existing private method public so route handlers can consult it directly — this is the same change S-1 makes on its branch, deliberately duplicated so either order of merge produces a clean rebase.
+
+## What is outstanding
+
+The Remediation tab itself is not yet on main — it ships with a separate Tier-2 slice. Until then the proposals page lives at its own URL rather than nested inside the tab. The dashboard navigation will gain a Remediation entry pointing at this page once the parent tab lands.
+
+The route file mounts the trust source from `config.autonomyProfile` directly. Once the Remediator bootstrap is wired into `AgentServer`, the routes should consume that shared instance instead, so config-flip events take effect without a server restart. That swap is mechanical and tracked in the same Tier-3 follow-up that wires the rest of the Remediator into the server lifecycle.

package/upgrades/0.28.112.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Ships S-3 of Tier-3 from the self-healing remediator spec — the **commit-time** half of the promotion gate that pairs with the **PR-merge-time** half shipped in C-1 (PR #204).
+
+A "proposal-derived runbook" is a runbook source file that the SystemReviewer's clustering pipeline (Tier-3 S-1, not yet shipped) emits when it spots a repeating failure pattern that warrants a new automated remediation. Those files carry two special markers: `__proposalDerivedFrom = '<proposalId>'` and `__producingAgentId = '<agentId>'`. Before this release, nothing checked those markers locally — the only enforcement happened in CI at PR review.
+
+This release adds a second check at commit time, inside the `/instar-dev` skill's pre-commit hook:
+
+- If you stage a runbook source under `src/remediation/runbooks/` that carries `__proposalDerivedFrom`, the hook reads the proposal JSON at `.instar/remediation/proposals-<machineId>/<proposalId>.json`, verifies the agent IDs match, and (if a signature and pubkey are present) verifies the Ed25519 signature.
+- If anything is missing or mismatched, the commit is refused with a structured message pointing at the proposal pipeline as the responsible surface.
+- Runbooks without the markers — every runbook on main today — pass through with no work.
+
+This catches author mistakes before a PR is pushed. The CI gate (C-1) remains the authoritative check at PR-merge time because only CI can verify signing identity for the different-principal rule.
+
+## What to Tell Your User
+
+No behavior change for users. This is a developer-side guardrail that prevents a malformed runbook from being committed in the first place. The user-visible promotion flow (proposal review and approval via the dashboard or Telegram) still works the same way.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Commit-time promotion gate for proposal-derived runbooks | Automatic; runs inside `/instar-dev` pre-commit |
+| `verify-proposal-derived-runbook.mjs` CLI | `node skills/instar-dev/scripts/verify-proposal-derived-runbook.mjs --files <csv>` |

package/upgrades/side-effects/s1-novel-failure-reviewer.md

@@ -0,0 +1,79 @@
+# Side-Effects Review — S-1 NovelFailureReviewer
+
+**Version / slug:** `s1-novel-failure-reviewer`
+**Date:** 2026-05-16
+**Author:** echo
+**Second-pass reviewer:** not required (Tier-3 LLM-driven module; proposes only, cannot promote)
+
+## Summary of the change
+
+Adds `src/remediation/NovelFailureReviewer.ts` — the bottom-up signature-discovery module per spec §A18, §A10, §A26, §A57 Tier-3. Watches the audit projection for `no-matching-runbook` entries, clusters by signature, summarizes recurring patterns via a Haiku-class LLM, and emits proposals for human approval. Cannot author runbooks itself — proposals require an `/instar-dev` commit + spec-converge approval to become runbooks. 17 unit tests cover all behaviors. Small extensions to `Remediator.ts`, `TrustElevationSource.ts`, `audit/AuditProjection.ts`, and `audit/AuditWriter.ts` expose the read-only APIs the reviewer needs.
+
+## Decision-point inventory
+
+- `src/remediation/NovelFailureReviewer.ts` (new) — **add** — clustering + LLM summarization + proposal generation. Propose-only authority.
+- `src/remediation/TrustElevationSource.ts` (modified) — **modify** — adds a `dismissProposal` predicate path requiring `collaborative` trust per §A26.
+- `src/remediation/audit/AuditProjection.ts` (modified) — **modify** — exposes `readUnmatchedSince(cursor)` for the reviewer's tick loop.
+- `src/remediation/audit/AuditWriter.ts` (modified) — **modify** — emits `remediation.novel-failure-reviewer.*` events through the same writer.
+- `src/remediation/Remediator.ts` (modified) — **modify** — one-line API surface for cluster-counter introspection.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- LLM output that's schema-valid but conservative (e.g., suggests `UNKNOWN_NETWORK_FAILURE`) is accepted regardless of whether it's the *best* code — the gate is structural, not quality. This is intentional.
+- Collisions with existing runbook prefilters are auto-rejected (no slot consumed per §A26 R3). False-positive collisions on common substrings would mean a legitimate proposal is suppressed; mitigated by the strict prefilter-equality check (not substring match).
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- An LLM that returns schema-valid output containing injected misleading text past the URL/code-fence/imperative-verb filter. The 200/400 char limits + tier-3 human-review boundary contain damage; rendering is in a clearly-marked "Untrusted LLM-summarized content" frame.
+- Coordinated audit-log pollution: if an attacker can inject enough no-matching-runbook entries to cross the 3-occurrence × 2-lifetime × 14-day threshold for a chosen signature, they can shape a proposal. Mitigated by §A12 audit-token enforcement (forged entries route to `audit-rejected.jsonl`, not `audit-projection`); the reviewer reads only verified entries.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The reviewer reads audit projection (read-only signal) and emits proposals (writes to a per-machine proposals directory). It cannot mutate the runbook registry, cannot dispatch attempts, cannot suppress alerts. The line between "execute" and "propose" is structural — the reviewer's only write surface is `proposals-<machineId>/` and the cluster-counters file. Promotion requires crossing a different authority boundary (`/instar-dev` commit + spec-converge).
+
+## 4. Signal vs authority compliance
+
+**Does this hold blocking authority with brittle logic, or does it produce a signal?**
+
+Pure signal-producer. LLM-summarized proposals are explicitly marked as untrusted human-review artifacts. The runbook registry validator (in F-8) is the authority; the reviewer feeds candidate signatures into a human-gated approval path. Compliant with `docs/signal-vs-authority.md`.
+
+## 5. Interactions
+
+**Does it shadow another check, get shadowed, double-fire, race?**
+
+- **Cluster threshold + per-signature persistence (§A47):** counters live at `.instar/remediation/cluster-counters-<machineId>.json`. LRU-capped at 500 distinct signatures. 1k-entry tail kept for forensic display. No race with the audit writer (read-only consumer; writes its own state file).
+- **Outstanding-proposal cap (≤3, §A10):** queue overflow is silent. New proposals beyond the cap are tracked in counters but not LLM-summarized until a slot frees.
+- **LLM monthly budget (§A65):** pauses LLM calls when cumulative spend ≥ budget. Backoff on LLM failure: 1h → 6h → 24h.
+
+## 6. External surfaces
+
+**Does it change anything visible to other agents, other users, other systems?**
+
+- New state files under `.instar/remediation/`: `cluster-counters-<machineId>.json`, `proposals-<machineId>/<proposalId>.json`, `llm-raw-<machineId>.jsonl` (30-day TTL per §A26 R4).
+- Per §A14 backup/sync taxonomy: cluster-counters and llm-raw are per-machine, NOT git-synced. proposals are git-synced read-only history (Dashboard S-2 surfaces them).
+- LLM call: outbound to the configured `llmModel` (default haiku-class). Subject to §A65 monthly budget cap.
+
+## 7. Rollback cost
+
+**If this turns out wrong, what's the back-out?**
+
+- Delete `src/remediation/NovelFailureReviewer.ts` + tests.
+- Revert the small API additions in `TrustElevationSource.ts`, `AuditProjection.ts`, `AuditWriter.ts`, `Remediator.ts` (each <15 lines).
+- The Tier-3 dashboard sub-section (S-2, future PR) is the only consumer. No runtime path depends on this module yet.
+- State files at `.instar/remediation/cluster-counters-*` and `proposals-*/` are forensic-only; safe to delete.
+
+## Trust elevation
+
+`dismissProposal` requires `collaborative` trust + audit-logged principal identity. Per-agent dismiss rate-limit: 10/hour (enforced in the reviewer module).
+
+## Side-effects on adjacent systems
+
+- No HTTP routes, no Telegram surfaces, no dashboard wiring yet (S-2 is the consumer).
+- Audit projection: read-only consumer; reviewer's own writes go to `audit-projection` via the standard AuditWriter path (verified-append per §A12).
+- Backup/sync: A14 paths honored. F-7's `addGitignoreEntry` step already includes `cluster-counters-*` and `llm-raw-*`.