@maintainabilityai/research-runner 0.1.35 → 0.1.41

package/dist/runner/skills.js

@@ -1337,8 +1337,19 @@ const ProviderResultSchema = zod_1.z.object({
     publishedDate: zod_1.z.string().optional(),
     authors: zod_1.z.array(zod_1.z.string()).optional(),
 });
+// Cert-run-2 bug D fix (Task #56) — schema now accepts BOTH the
+// canonical grouped shape (`ProviderResult[][]`, one inner array per
+// provider) AND the agent's intuitive flat shape (`ProviderResult[]`).
+// Cert run #2 chain showed the agent attempting flat-input dedupe-and-
+// rank TWICE in a row (events 10+11) before figuring out grouped on
+// attempt 3 — burning Zod-error feedback to converge. Lenient schema
+// removes the trial-and-error: either shape works, handler normalizes
+// internally before calling the pure dedupeAndRank function.
 const DedupeAndRankInput = zod_1.z.object({
-    results: zod_1.z.array(zod_1.z.array(ProviderResultSchema)),
+    results: zod_1.z.union([
+        zod_1.z.array(zod_1.z.array(ProviderResultSchema)), // canonical: grouped by provider
+        zod_1.z.array(ProviderResultSchema), // lenient: flat list across providers
+    ]),
     topN: zod_1.z.number().int().positive().optional(),
 });
 const handleDedupeAndRank = async (input) => {
@@ -1346,11 +1357,17 @@ const handleDedupeAndRank = async (input) => {
     if (!parsed.success) {
         return { ok: false, reason: `bad-input: ${parsed.error.message}` };
     }
-    const flat = parsed.data.results.flat();
+    // Discriminate via first element: if it's an array → grouped (flatten);
+    // else flat → use directly. Empty array → treat as empty flat (no-op).
+    const r = parsed.data.results;
+    const grouped = r.length > 0 && Array.isArray(r[0]);
+    const flat = grouped
+        ? parsed.data.results.flat()
+        : parsed.data.results;
     const ranked = (0, dedupe_and_rank_1.dedupeAndRank)({ results: flat, topN: parsed.data.topN ?? 50 });
     const providerCounts = {};
-    for (const r of ranked) {
-        providerCounts[r.provider] = (providerCounts[r.provider] ?? 0) + 1;
+    for (const result of ranked) {
+        providerCounts[result.provider] = (providerCounts[result.provider] ?? 0) + 1;
     }
     return { ok: true, rankedSources: ranked, providerCounts };
 };
@@ -1430,7 +1447,19 @@ const handleFormatResearchIssueUpdate = async (input) => {
 const AuditEmitInput = zod_1.z.object({
     okrId: zod_1.z.string().min(1),
     runId: zod_1.z.string().min(1),
-    eventKind: zod_1.z.enum(['skill_call', 'llm_call', 'artifact_written', 'review_received', 'state_transition', 'human_gate']),
+    // Bug K (cert-run-5) — added `self_review` and `self_review_exhausted`
+    // to the enum. The HOW + WHAT workflows' review-emit step calls
+    // `audit-emit-event` with `eventKind: 'self_review'` to write per-
+    // persona-per-round events into the chain (parsed from PR-body /
+    // artifact-md / artifact-frontmatter sources). Previously the enum
+    // rejected the kind with bad-input; the workflow logged a warning
+    // and moved on; the chain never got the synthetic event; the UI
+    // had to rely on its artifact-fallback. Now the emit succeeds.
+    eventKind: zod_1.z.enum([
+        'skill_call', 'llm_call', 'artifact_written', 'review_received',
+        'self_review', 'self_review_exhausted',
+        'state_transition', 'human_gate',
+    ]),
     payload: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
     phase: zod_1.z.enum(['why', 'how', 'what']),
     intentThreadUuid: zod_1.z.string().min(1),
@@ -1493,29 +1522,125 @@ async function sleep(ms) {
 // `sealed: false, sealVerified: false` but still passes if hashes are
 // intact. A chain with PARTIAL signatures is treated as tampering.
 // ─────────────────────────────────────────────────────────────────────
-function knightSealPubKeyPath(okrId, runId) {
+// ─────────────────────────────────────────────────────────────────────
+// Bug O (Task #72) — Per-epoch Ed25519 signing.
+//
+// Each agent session = one "signer epoch":
+//   - Original agent invocation → epoch 1
+//   - First revise-agent invocation (different runner machine) → epoch 2
+//   - Second revise → epoch 3
+//   - ... etc
+//
+// Each epoch persists its OWN keypair:
+//   <runId>.epoch-N.pub.pem    (mesh, committed)
+//   <runId>--<runId>.epoch-N.priv.pem  (tmpdir, ephemeral)
+//
+// Events carry `signer_epoch: N` so chain-verify can look up the right
+// pub key per event. Workflow-emitted events (`emitted_by: 'workflow'`)
+// stay unsigned-by-design — those are CI infrastructure, not an agent.
+//
+// Backward compat:
+//   - Legacy chains used <runId>.pub.pem with no epoch suffix. Verifiers
+//     treat that as the epoch-1 pub key if no epoch-suffixed files exist.
+//   - Events without `signer_epoch` field default to epoch 1.
+// ─────────────────────────────────────────────────────────────────────
+function knightSealLegacyPubKeyPath(okrId, runId) {
     return path.join(meshPath(), 'okrs', okrId, 'audit', 'keys', `${runId}.pub.pem`);
 }
-function knightSealPrivKeyPath(okrId, runId) {
+function knightSealEpochPubKeyPath(okrId, runId, epoch) {
+    return path.join(meshPath(), 'okrs', okrId, 'audit', 'keys', `${runId}.epoch-${epoch}.pub.pem`);
+}
+function knightSealEpochPrivKeyPath(okrId, runId, epoch) {
     // Tmpdir-scoped to avoid any chance of `git add`-ing a private key.
-    // Filename collision-resistant via okrId+runId.
-    return path.join(os.tmpdir(), '.research-runner-keys', `${okrId.replace(/[^A-Za-z0-9_-]/g, '_')}--${runId.replace(/[^A-Za-z0-9_-]/g, '_')}.priv.pem`);
+    return path.join(os.tmpdir(), '.research-runner-keys', `${okrId.replace(/[^A-Za-z0-9_-]/g, '_')}--${runId.replace(/[^A-Za-z0-9_-]/g, '_')}.epoch-${epoch}.priv.pem`);
 }
 /**
- * Load the run's private key from tmp, or generate + persist a fresh
- * keypair if this is the first event for the run. Returns both KeyObjects.
+ * Find the active signer epoch for this run.
+ *
+ * Returns the epoch number AND whether the caller should generate a
+ * fresh keypair (isNewSession=true) or load the existing one (false).
+ *
+ * Logic:
+ *   1. Scan `audit/keys/<runId>.epoch-N.pub.pem` files → find max N.
+ *   2. Legacy compat: if no epoch files but `<runId>.pub.pem` exists,
+ *      treat it as the epoch-1 pub (max=1).
+ *   3. If max=0 (no keys at all) → genesis, return { epoch: 1, isNew: true }.
+ *   4. If max>0 and `<okrId>--<runId>.epoch-N.priv.pem` exists in tmp →
+ *      same session, return { epoch: max, isNew: false }.
+ *   5. If max>0 and priv missing → new session (revise pass / different
+ *      runner machine), return { epoch: max+1, isNew: true }.
  */
-function loadOrCreateRunKeypair(okrId, runId) {
-    const privPath = knightSealPrivKeyPath(okrId, runId);
-    const pubPath = knightSealPubKeyPath(okrId, runId);
-    if (fs.existsSync(privPath) && fs.existsSync(pubPath)) {
-        const privPem = fs.readFileSync(privPath, 'utf8');
-        const pubPem = fs.readFileSync(pubPath, 'utf8');
+function findActiveEpoch(okrId, runId) {
+    const keysDir = path.join(meshPath(), 'okrs', okrId, 'audit', 'keys');
+    let maxEpoch = 0;
+    if (fs.existsSync(keysDir)) {
+        const escaped = runId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const epochRe = new RegExp(`^${escaped}\\.epoch-(\\d+)\\.pub\\.pem$`);
+        for (const f of fs.readdirSync(keysDir)) {
+            const m = f.match(epochRe);
+            if (m) {
+                maxEpoch = Math.max(maxEpoch, parseInt(m[1], 10));
+            }
+        }
+        // Legacy fallback: bare `<runId>.pub.pem` counts as epoch 1.
+        if (maxEpoch === 0 && fs.existsSync(knightSealLegacyPubKeyPath(okrId, runId))) {
+            maxEpoch = 1;
+        }
+    }
+    if (maxEpoch === 0) {
+        return { epoch: 1, isNewSession: true };
+    }
+    // Check if the max-epoch's private key still exists in tmp.
+    const privPath = knightSealEpochPrivKeyPath(okrId, runId, maxEpoch);
+    // For legacy compat: epoch 1 priv key might be at the legacy path.
+    const legacyPrivPath = path.join(os.tmpdir(), '.research-runner-keys', `${okrId.replace(/[^A-Za-z0-9_-]/g, '_')}--${runId.replace(/[^A-Za-z0-9_-]/g, '_')}.priv.pem`);
+    if (fs.existsSync(privPath) || (maxEpoch === 1 && fs.existsSync(legacyPrivPath))) {
+        return { epoch: maxEpoch, isNewSession: false };
+    }
+    // Priv gone → new session, advance to the next epoch.
+    return { epoch: maxEpoch + 1, isNewSession: true };
+}
+/**
+ * Load OR create the keypair for a specific (run, epoch). When
+ * isNewSession is true, generates a fresh Ed25519 keypair and persists
+ * BOTH the pub key (mesh) and priv key (tmpdir, mode 0600). When
+ * isNewSession is false, loads the existing pair from disk.
+ *
+ * Bug O (Task #72) — replaces the old single-key `loadOrCreateRunKeypair`.
+ * Per-epoch model means every agent session signs with its own identity,
+ * closing the cryptographic gap that revise-agent events previously had.
+ *
+ * Backward compat: for epoch 1 only, if no `<runId>.epoch-1.pub.pem`
+ * exists but the legacy `<runId>.pub.pem` does, load from the legacy
+ * path (existing chains keep verifying without renaming files).
+ */
+function loadOrCreateEpochKeypair(okrId, runId, epoch, isNewSession) {
+    const privPath = knightSealEpochPrivKeyPath(okrId, runId, epoch);
+    const pubPath = knightSealEpochPubKeyPath(okrId, runId, epoch);
+    const legacyPubPath = knightSealLegacyPubKeyPath(okrId, runId);
+    const legacyPrivPath = path.join(os.tmpdir(), '.research-runner-keys', `${okrId.replace(/[^A-Za-z0-9_-]/g, '_')}--${runId.replace(/[^A-Za-z0-9_-]/g, '_')}.priv.pem`);
+    if (!isNewSession) {
+        // Load existing keypair. For epoch 1, try the epoch-suffixed path
+        // first; fall back to legacy paths if those are what's on disk.
+        let privPem;
+        let pubPem;
+        if (fs.existsSync(privPath) && fs.existsSync(pubPath)) {
+            privPem = fs.readFileSync(privPath, 'utf8');
+            pubPem = fs.readFileSync(pubPath, 'utf8');
+        }
+        else if (epoch === 1 && fs.existsSync(legacyPrivPath) && fs.existsSync(legacyPubPath)) {
+            privPem = fs.readFileSync(legacyPrivPath, 'utf8');
+            pubPem = fs.readFileSync(legacyPubPath, 'utf8');
+        }
+        else {
+            throw new Error(`epoch-keypair-load-failed: epoch=${epoch} privPath=${privPath} pubPath=${pubPath}`);
+        }
         return {
             privKey: (0, node_crypto_1.createPrivateKey)({ key: privPem, format: 'pem' }),
             pubKey: (0, node_crypto_1.createPublicKey)({ key: pubPem, format: 'pem' }),
         };
     }
+    // Generate + persist fresh keypair for this epoch.
     const { privateKey, publicKey } = (0, node_crypto_1.generateKeyPairSync)('ed25519');
     const privPem = privateKey.export({ type: 'pkcs8', format: 'pem' });
     const pubPem = publicKey.export({ type: 'spki', format: 'pem' });
@@ -1525,19 +1650,47 @@ function loadOrCreateRunKeypair(okrId, runId) {
     fs.writeFileSync(pubPath, pubPem, 'utf8');
     return { privKey: privateKey, pubKey: publicKey };
 }
-/** Returns null if no public key has been persisted for this run yet. */
-function tryLoadRunPublicKey(okrId, runId) {
-    const pubPath = knightSealPubKeyPath(okrId, runId);
-    if (!fs.existsSync(pubPath)) {
-        return null;
+/**
+ * Load every epoch's public key for this run into a Map<epoch, KeyObject>.
+ * Used by audit-verify-chain. Includes the legacy `<runId>.pub.pem` as
+ * epoch 1 when present (so old chains verify without renaming).
+ */
+function loadAllEpochPubKeys(okrId, runId) {
+    const keysDir = path.join(meshPath(), 'okrs', okrId, 'audit', 'keys');
+    const result = new Map();
+    if (!fs.existsSync(keysDir)) {
+        return result;
     }
-    try {
-        return (0, node_crypto_1.createPublicKey)({ key: fs.readFileSync(pubPath, 'utf8'), format: 'pem' });
+    const escaped = runId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const epochRe = new RegExp(`^${escaped}\\.epoch-(\\d+)\\.pub\\.pem$`);
+    for (const f of fs.readdirSync(keysDir)) {
+        const m = f.match(epochRe);
+        if (!m) {
+            continue;
+        }
+        const epoch = parseInt(m[1], 10);
+        try {
+            const pem = fs.readFileSync(path.join(keysDir, f), 'utf8');
+            result.set(epoch, (0, node_crypto_1.createPublicKey)({ key: pem, format: 'pem' }));
+        }
+        catch { /* skip unreadable */ }
     }
-    catch {
-        return null;
+    // Legacy fallback: bare `<runId>.pub.pem` populates epoch 1 if not
+    // already set by an epoch-suffixed file.
+    if (!result.has(1)) {
+        const legacyPath = knightSealLegacyPubKeyPath(okrId, runId);
+        if (fs.existsSync(legacyPath)) {
+            try {
+                result.set(1, (0, node_crypto_1.createPublicKey)({ key: fs.readFileSync(legacyPath, 'utf8'), format: 'pem' }));
+            }
+            catch { /* skip */ }
+        }
     }
+    return result;
 }
+// tryLoadRunPublicKey removed in Bug O (Task #72) — the per-epoch
+// model uses loadAllEpochPubKeys() to load every signer's key.
+// Legacy callers should switch to the multi-key flow.
 function signEventHash(privKey, eventHashHex) {
     // Ed25519 signs raw bytes — we sign the UTF-8 bytes of the hex digest,
     // which is the canonical chain anchor. Output: 64-byte signature, hex.
@@ -1600,8 +1753,48 @@ const handleAuditEmitEvent = async (input) => {
                     nextEventId = last.event_id + 1;
                 }
             }
-            const { privKey, pubKey } = loadOrCreateRunKeypair(okrId, runId);
-            const publicKeyPem = pubKey.export({ type: 'spki', format: 'pem' });
+            // Bug O (Task #72) — per-epoch signing.
+            //
+            // Workflow-emitted events stay unsigned-by-design (CI infrastructure,
+            // not an agent). Everything else (original agent + revise agent)
+            // gets a per-epoch signature; each agent session = one signer epoch.
+            //
+            // Backward compat: legacy chains with emitted_by:'revise-agent' +
+            // unsigned events still verify (chain-verify accepts the legacy
+            // attribution). New chains sign all agent events.
+            const emittedBy = payload?.emitted_by;
+            const isWorkflowEmit = emittedBy === 'workflow';
+            let privKey = null;
+            let publicKeyPem = null;
+            let signerEpoch = null;
+            let isFirstEventOfEpoch = false;
+            if (!isWorkflowEmit) {
+                // Agent context (original OR revise). Determine the current
+                // epoch + load-or-generate its keypair.
+                const { epoch, isNewSession } = findActiveEpoch(okrId, runId);
+                signerEpoch = epoch;
+                const keypair = loadOrCreateEpochKeypair(okrId, runId, epoch, isNewSession);
+                privKey = keypair.privKey;
+                publicKeyPem = keypair.pubKey.export({ type: 'spki', format: 'pem' });
+                // First event of each epoch embeds the pub key inline so a
+                // single-line audit excerpt names its signer.
+                if (fs.existsSync(filePath)) {
+                    const existing = fs.readFileSync(filePath, 'utf8').split('\n').filter(l => l.trim().length > 0);
+                    isFirstEventOfEpoch = !existing.some(line => {
+                        try {
+                            const e = JSON.parse(line);
+                            const eEpoch = typeof e.signer_epoch === 'number' ? e.signer_epoch : 1;
+                            return eEpoch === epoch;
+                        }
+                        catch {
+                            return false;
+                        }
+                    });
+                }
+                else {
+                    isFirstEventOfEpoch = true;
+                }
+            }
             const draft = {
                 event_id: nextEventId,
                 ts: new Date().toISOString(),
@@ -1612,19 +1805,23 @@ const handleAuditEmitEvent = async (input) => {
                 event_kind: eventKind,
                 payload,
                 prev_event_hash: prevHash,
-                // Embed public key on event 1 so a single-line audit excerpt
-                // still names its signer. Subsequent events reference the same
-                // committed key on disk; embedding on every line would balloon
-                // the JSONL with no integrity gain.
-                public_key: nextEventId === 1 ? publicKeyPem : null,
+                // Embed pub key on first event of each epoch (agent only).
+                // Workflow events carry no public_key — they're system-trusted.
+                public_key: isFirstEventOfEpoch ? publicKeyPem : null,
                 event_hash: '',
                 signature: '',
             };
+            // signer_epoch present on all agent-signed events; absent on
+            // workflow events. Older chains without this field default to
+            // epoch 1 in chain-verify (backward compat).
+            if (signerEpoch !== null) {
+                draft.signer_epoch = signerEpoch;
+            }
             const hash = sha256(canonicalStringify(draft));
-            const signature = signEventHash(privKey, hash);
+            const signature = privKey ? signEventHash(privKey, hash) : '';
             const finalEvent = { ...draft, event_hash: hash, signature };
             fs.appendFileSync(filePath, JSON.stringify(finalEvent) + '\n', 'utf8');
-            return { ok: true, chainHead: hash, eventId: nextEventId, sealed: true };
+            return { ok: true, chainHead: hash, eventId: nextEventId, sealed: signature !== '' };
         }
         finally {
             if (lockFd !== null) {
@@ -1677,11 +1874,13 @@ const handleAuditVerifyChain = async (input) => {
     catch (err) {
         return { ok: false, reason: `read-failed: ${err.message}` };
     }
-    const pubKey = tryLoadRunPublicKey(okrId, runId);
-    // Track signature state across the whole chain. v1 contract: either
-    // EVERY event is signed (sealed=true) or NO event is signed (legacy
-    // pre-B27 chain, sealed=false). Partial signatures = tampering.
+    // Bug O (Task #72) — load ALL epoch pub keys (epoch-1, epoch-2, ...).
+    // Each agent session signs with its own epoch key. Includes legacy
+    // <runId>.pub.pem as epoch-1 if no epoch-suffixed files exist.
+    const epochPubKeys = loadAllEpochPubKeys(okrId, runId);
+    // Track signature state across the whole chain.
     let signedCount = 0;
+    let workflowUnsignedCount = 0; // post-agent workflow-emitted events, unsigned by-design
     let prev = null;
     for (let i = 0; i < lines.length; i++) {
         let event;
@@ -1712,25 +1911,54 @@ const handleAuditVerifyChain = async (input) => {
         if (recordedHash !== recomputed) {
             return { ok: false, reason: `forged-hash-line-${i + 1}: recorded=${recordedHash.slice(0, 16)}… recomputed=${recomputed.slice(0, 16)}…` };
         }
-        if (recordedSignature !== null) {
+        // Bug K + N (cert-run-5): post-agent events (payload.emitted_by in
+        // {'workflow', 'revise-agent'}) carry signature: '' by design — the
+        // post-agent context can't sign because the ephemeral private key is
+        // gone. Count them separately so they don't trip partial-tampering
+        // detection or signature verification. Both attributions are
+        // legitimate-unsigned.
+        const eventPayload = event.payload;
+        const emittedBy = eventPayload?.emitted_by;
+        const isUnsignedByDesign = emittedBy === 'workflow' || emittedBy === 'revise-agent';
+        if (recordedSignature !== null && recordedSignature !== '') {
             signedCount++;
         }
+        else if (isUnsignedByDesign) {
+            workflowUnsignedCount++;
+        }
         prev = recordedHash;
     }
-    // Knight's Seal verification: enforce all-or-nothing.
+    // Knight's Seal verification: every AGENT-emitted event must be signed
+    // by its declared signer_epoch's pub key. Workflow-unsigned events are
+    // excluded from the denominator (their emitted_by: 'workflow' marker
+    // proves they're legitimate-unsigned).
     const sealed = signedCount > 0;
+    const agentEventCount = lines.length - workflowUnsignedCount;
     let sealVerified = false;
     if (sealed) {
-        if (signedCount !== lines.length) {
-            return { ok: false, reason: `partial-signatures: ${signedCount}/${lines.length} events signed (chain tampered)` };
+        if (signedCount !== agentEventCount) {
+            return { ok: false, reason: `partial-signatures: ${signedCount}/${agentEventCount} agent-emitted events signed (chain tampered; ${workflowUnsignedCount} workflow-emitted unsigned by-design)` };
         }
-        if (!pubKey) {
-            return { ok: false, reason: `public-key-missing: events are signed but no <runId>.pub.pem found in audit/keys/` };
+        if (epochPubKeys.size === 0) {
+            return { ok: false, reason: `public-key-missing: events are signed but no <runId>.epoch-*.pub.pem (or legacy <runId>.pub.pem) found in audit/keys/` };
         }
         for (let i = 0; i < lines.length; i++) {
             const event = JSON.parse(lines[i]);
+            const emittedBy = event.payload?.emitted_by;
+            const isLegacyUnsigned = (emittedBy === 'workflow' || emittedBy === 'revise-agent')
+                && (!event.signature || event.signature === '');
+            if (isLegacyUnsigned) {
+                continue;
+            }
+            // Bug O (Task #72) — per-epoch verification. Events default to
+            // epoch 1 if signer_epoch absent (legacy chains).
+            const epoch = typeof event.signer_epoch === 'number' ? event.signer_epoch : 1;
+            const pubKey = epochPubKeys.get(epoch);
+            if (!pubKey) {
+                return { ok: false, reason: `pub-key-missing-for-epoch-${epoch}-line-${i + 1}: chain references epoch ${epoch} but no <runId>.epoch-${epoch}.pub.pem on disk` };
+            }
             if (!verifyEventSignature(pubKey, event.event_hash, event.signature)) {
-                return { ok: false, reason: `signature-mismatch-line-${i + 1}: Ed25519 verify failed` };
+                return { ok: false, reason: `signature-mismatch-line-${i + 1}: Ed25519 verify failed against epoch-${epoch} pub key` };
             }
         }
         sealVerified = true;
@@ -1810,6 +2038,15 @@ async function runSkill(name, input) {
             if (!result.ok) {
                 payload.reason = result.reason;
             }
+            // Bug O (Task #72) — per-epoch signing now handles revise-agent
+            // context natively. handleAuditEmitEvent's findActiveEpoch()
+            // detects revise-context from filesystem state and advances to
+            // a fresh epoch with its own keypair. No payload tagging needed
+            // here — every agent-emitted event gets a real signature
+            // attributable to a specific signer_epoch. The legacy
+            // emitted_by:'revise-agent' attribution (Bug N) is still
+            // accepted by chain-verify for backward compat with chains
+            // created before this commit, but new code doesn't emit it.
             // Best-effort: an audit-write failure must not shadow the real
             // skill result. But we MUST surface the failure to stderr — pre-
             // B28a.v1.1 these were silently swallowed and PR #108 dropped 3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maintainabilityai/research-runner",
-  "version": "0.1.35",
+  "version": "0.1.41",
   "description": "Research + PRD agent runner — orchestrates the Archeologist and PRD pipelines for the MaintainabilityAI governance mesh",
   "license": "MIT",
   "author": "MaintainabilityAI",