open-multi-agent-kit 0.78.0 → 0.78.2

package/dist/goal/interview-scoring.js

@@ -0,0 +1,187 @@
+// Module: src/goal/interview-scoring.ts
+// OMK Deep Interview — pure deterministic scoring/ranking.
+//
+// 100% deterministic: no I/O, no Date.now, no randomness, no network/LLM calls.
+// All 0..1 outputs are clamped to [0,1] and scores rounded to 2 decimals.
+const clamp01 = (x) => Math.min(1, Math.max(0, x));
+const round2 = (x) => Math.round(x * 100) / 100;
+/** Max questions surfaced per interview depth. */
+export const DEPTH_LIMITS = {
+    light: 5,
+    standard: 10,
+    deep: 18,
+};
+/**
+ * Derive the ranking score for a candidate question.
+ * score = informationGain*0.35 + riskReduction*0.25 + dagImpact*0.20
+ *       + evidenceImpact*0.15 - userCost*0.05, clamped to [0,1].
+ */
+export function scoreInterviewQuestion(input) {
+    const raw = input.informationGain * 0.35 +
+        input.riskReduction * 0.25 +
+        input.dagImpact * 0.2 +
+        input.evidenceImpact * 0.15 -
+        input.userCost * 0.05;
+    const score = round2(clamp01(raw));
+    return { ...input, score };
+}
+/**
+ * Select the highest-value questions for a depth, dropping questions whose
+ * target field is already answered by the goal (unless marked required).
+ */
+export function selectInterviewQuestions(goal, candidates, depth, maxQuestions) {
+    const limit = maxQuestions != null ? Math.min(maxQuestions, DEPTH_LIMITS[depth]) : DEPTH_LIMITS[depth];
+    const answeredTargets = new Set();
+    if (goal) {
+        if (goal.objective?.trim())
+            answeredTargets.add("objective");
+        if (goal.successCriteria.length > 0)
+            answeredTargets.add("successCriteria");
+        if (goal.expectedArtifacts.length > 0)
+            answeredTargets.add("expectedArtifacts");
+        if (goal.constraints.length > 0)
+            answeredTargets.add("constraints");
+        if (goal.nonGoals.length > 0)
+            answeredTargets.add("nonGoals");
+        if (goal.risks.length > 0)
+            answeredTargets.add("risks");
+    }
+    const filtered = candidates.filter((q) => q.required || !answeredTargets.has(q.targetField));
+    const byScoreThenRequired = (a, b) => {
+        const byScore = b.score - a.score;
+        if (byScore !== 0)
+            return byScore;
+        return Number(b.required) - Number(a.required);
+    };
+    // Pin required questions so a small --max-questions/limit can never drop a
+    // required axis; optional questions fill the remaining slots by score.
+    const required = filtered.filter((q) => q.required).sort(byScoreThenRequired);
+    const optional = filtered.filter((q) => !q.required).sort(byScoreThenRequired);
+    const remaining = Math.max(0, limit - required.length);
+    return [...required, ...optional.slice(0, remaining)].sort(byScoreThenRequired);
+}
+/** Keyword/regex heuristics describing one ambiguity axis. */
+const AMBIGUITY_AXES = [
+    {
+        weight: 0.18,
+        pattern: /\b(objective|goal|implement|build|create|add|fix|refactor|design|develop|generate|support|enable)\b/,
+        goalPresent: (s) => !!s.goal?.objective?.trim(),
+    },
+    {
+        weight: 0.18,
+        pattern: /\b(acceptance|success criteria|criteria|criterion|definition of done|done when|must pass|requirement|expected result|should)\b/,
+        goalPresent: (s) => (s.goal?.successCriteria.length ?? 0) > 0,
+    },
+    {
+        weight: 0.13,
+        pattern: /\b(test|verify|verification|check|lint|typecheck|build|coverage|assert|validate)\b/,
+        goalPresent: (s) => (s.goal?.expectedArtifacts.some((a) => a.gate === "command-pass") ?? false),
+    },
+    {
+        weight: 0.12,
+        pattern: /(\.[a-z]{2,4}\b|\bfile\b|\bpath\b|\bmodule\b|\bcomponent\b|\bdirectory\b|\bartifact\b|\boutput\b)/,
+        goalPresent: (s) => (s.goal?.expectedArtifacts.length ?? 0) > 0,
+    },
+    {
+        weight: 0.1,
+        pattern: /\b(constraint|must not|only|do not|don't|limit|restrict|without|avoid|never|forbidden)\b/,
+        goalPresent: (s) => (s.goal?.constraints.length ?? 0) > 0,
+    },
+    {
+        weight: 0.08,
+        pattern: /\b(risk|danger|safe|safety|destructive|irreversible|production|rollback|backup|prod)\b/,
+        goalPresent: (s) => (s.goal?.risks.length ?? 0) > 0 || s.riskLevel != null,
+    },
+    {
+        weight: 0.08,
+        pattern: /\b(write|edit|modify|delete|shell|command|merge|commit|push|deploy|permission|read.only|authority|scope)\b/,
+        goalPresent: (s) => !!s.goal?.intentFrame?.directives?.some((d) => d.kind === "read-only" || d.kind === "no-edits" || d.kind === "scope"),
+    },
+    {
+        weight: 0.07,
+        pattern: /\b(non-goal|out of scope|exclude|except|not (include|touch|modify|change|do)|do not (edit|modify|change|touch))\b/,
+        goalPresent: (s) => (s.goal?.nonGoals.length ?? 0) > 0,
+    },
+    {
+        weight: 0.06,
+        pattern: /\b(depend|dependenc|requires|require|prerequisite|blocked by|relies on|integrat|import)\b/,
+        goalPresent: () => false,
+    },
+];
+/**
+ * Ambiguity 0..1 — higher means more interview is needed. Computed as the
+ * weighted sum of axes that are neither described in the prompt nor present on
+ * the goal. Axis weights sum to 1.
+ */
+export function computeAmbiguity(seed) {
+    const prompt = (seed.rawPrompt ?? "").toLowerCase();
+    let missing = 0;
+    for (const axis of AMBIGUITY_AXES) {
+        const present = axis.pattern.test(prompt) || axis.goalPresent(seed);
+        if (!present)
+            missing += axis.weight;
+    }
+    return round2(clamp01(missing));
+}
+/**
+ * Map an ambiguity score to a recommended depth.
+ * <0.25 light (caller may skip) · <0.50 light · <0.75 standard · else deep.
+ */
+export function recommendDepth(ambiguity) {
+    if (ambiguity < 0.5)
+        return "light";
+    if (ambiguity < 0.75)
+        return "standard";
+    return "deep";
+}
+/** Per-axis completeness: 0.6 if goal field populated, +0.4 if a finding matches. */
+function axisScore(goalPopulated, fields, findings) {
+    const hasFinding = findings.some((f) => fields.includes(String(f.field)));
+    let score = 0;
+    if (goalPopulated)
+        score += 0.6;
+    if (hasFinding)
+        score += 0.4;
+    return round2(clamp01(score));
+}
+/**
+ * Completeness across required and supporting axes, blending populated goal
+ * fields with assimilated interview findings.
+ */
+export function computeCompleteness(goal, findings) {
+    const objective = axisScore(!!goal?.objective?.trim(), ["objective"], findings);
+    const successCriteria = axisScore((goal?.successCriteria.length ?? 0) > 0, ["successCriteria"], findings);
+    const evidence = axisScore((goal?.expectedArtifacts.some((a) => !!a.gate) ?? false) ||
+        (goal?.successCriteria.some((c) => c.requirement === "required") ?? false), ["evidence"], findings);
+    const artifacts = axisScore((goal?.expectedArtifacts.length ?? 0) > 0, ["expectedArtifacts", "artifact", "artifacts"], findings);
+    const constraints = axisScore((goal?.constraints.length ?? 0) > 0, ["constraints"], findings);
+    const risks = axisScore((goal?.risks.length ?? 0) > 0, ["risks", "riskLevel"], findings);
+    const authority = axisScore(!!goal?.intentFrame?.directives?.some((d) => d.kind === "read-only" || d.kind === "no-edits" || d.kind === "scope"), ["authority", "intentFrame"], findings);
+    const overall = round2(clamp01(objective * 0.15 +
+        successCriteria * 0.25 +
+        evidence * 0.2 +
+        artifacts * 0.15 +
+        constraints * 0.1 +
+        risks * 0.1 +
+        authority * 0.05));
+    const criticalMissing = [];
+    if (objective < 0.5)
+        criticalMissing.push("objective");
+    if (successCriteria < 0.5)
+        criticalMissing.push("successCriteria");
+    if (evidence < 0.5)
+        criticalMissing.push("evidence");
+    const contradictions = findings.filter((f) => f.conflict).map((f) => String(f.field));
+    return {
+        overall,
+        objective,
+        successCriteria,
+        evidence,
+        artifacts,
+        constraints,
+        risks,
+        authority,
+        criticalMissing,
+        contradictions,
+    };
+}

package/dist/goal/interview-session.d.ts

@@ -0,0 +1,25 @@
+import type { InterviewAnswer, InterviewDepth, InterviewMode, InterviewSeed, InterviewSession } from "../contracts/interview.js";
+/** Completeness threshold above which the interview is considered done. */
+export declare const COMPLETENESS_THRESHOLD = 0.82;
+export interface BuildInterviewSessionInput {
+    seed: InterviewSeed;
+    mode: InterviewMode;
+    depth?: InterviewDepth;
+    maxQuestions?: number;
+    sessionId?: string;
+    goalId?: string;
+}
+/**
+ * Build a fresh interview session: score ambiguity, rank deterministic
+ * questions, and emit an empty spec delta. No answers are applied yet.
+ */
+export declare function buildInterviewSession(input: BuildInterviewSessionInput): InterviewSession;
+/**
+ * Apply a batch of answers to an open session: assimilate into findings and a
+ * spec delta, recompute completeness, and decide the terminal status.
+ *
+ * Termination (spec): complete when completeness >= 0.82 AND no critical
+ * missing field AND no unresolved contradiction. Contradictions => blocked.
+ */
+export declare function ingestAnswers(session: InterviewSession, seed: InterviewSeed, newAnswers: InterviewAnswer[]): InterviewSession;
+export declare function decideStatus(completeness: InterviewSession["completeness"]): InterviewSession["status"];

package/dist/goal/interview-session.js

@@ -0,0 +1,116 @@
+// src/goal/interview-session.ts
+// OMK Deep Interview — session orchestrator.
+//
+// Composes the three deterministic modules (question-bank, scoring,
+// assimilation) into an InterviewSession lifecycle:
+//   seed -> ambiguity -> question ranking -> answers -> findings
+//        -> spec delta -> completeness -> status
+//
+// This module owns the critical integration path and is intentionally
+// deterministic except for timestamps and the session id.
+import { INTERVIEW_SCHEMA_VERSION, INTERVIEW_DELTA_SCHEMA_VERSION } from "../contracts/interview.js";
+import { computeAmbiguity, computeCompleteness, recommendDepth, scoreInterviewQuestion, selectInterviewQuestions, } from "./interview-scoring.js";
+import { buildInterviewQuestionBank } from "./interview-question-bank.js";
+import { assimilateAnswers, applyInterviewDelta } from "./interview-assimilation.js";
+import { createGoalSpec } from "./intake.js";
+import { redactSecretText } from "./intent-frame.js";
+/** Completeness threshold above which the interview is considered done. */
+export const COMPLETENESS_THRESHOLD = 0.82;
+function generateSessionId() {
+    return `iv-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+}
+/**
+ * Build a fresh interview session: score ambiguity, rank deterministic
+ * questions, and emit an empty spec delta. No answers are applied yet.
+ */
+export function buildInterviewSession(input) {
+    const now = new Date().toISOString();
+    const ambiguity = computeAmbiguity(input.seed);
+    const depth = input.depth ?? recommendDepth(ambiguity);
+    const candidates = buildInterviewQuestionBank(input.seed);
+    const scored = candidates.map((candidate) => scoreInterviewQuestion(candidate));
+    const questions = selectInterviewQuestions(input.seed.goal, scored, depth, input.maxQuestions);
+    const completeness = computeCompleteness(input.seed.goal, []);
+    return {
+        schemaVersion: INTERVIEW_SCHEMA_VERSION,
+        sessionId: input.sessionId ?? generateSessionId(),
+        goalId: input.goalId ?? input.seed.goal?.goalId,
+        mode: input.mode,
+        depth,
+        createdAt: now,
+        updatedAt: now,
+        rawPrompt: redactSecretText(input.seed.rawPrompt),
+        ambiguity,
+        questions,
+        answers: [],
+        findings: [],
+        completeness,
+        specDelta: {
+            schemaVersion: INTERVIEW_DELTA_SCHEMA_VERSION,
+            goalId: input.goalId ?? input.seed.goal?.goalId,
+            changes: [],
+        },
+        status: "open",
+    };
+}
+/**
+ * Apply a batch of answers to an open session: assimilate into findings and a
+ * spec delta, recompute completeness, and decide the terminal status.
+ *
+ * Termination (spec): complete when completeness >= 0.82 AND no critical
+ * missing field AND no unresolved contradiction. Contradictions => blocked.
+ */
+export function ingestAnswers(session, seed, newAnswers) {
+    // Redact secrets from answers before they are assimilated, persisted, or
+    // echoed so tokens never reach interview artifacts or the GoalSpec.
+    const redactedAnswers = newAnswers.map((answer) => ({
+        ...answer,
+        answer: redactSecretText(answer.answer),
+    }));
+    const mergedAnswers = mergeAnswers(session.answers, redactedAnswers);
+    const { findings, specDelta, contradictions } = assimilateAnswers({
+        seed,
+        questions: session.questions,
+        answers: mergedAnswers,
+        goal: seed.goal,
+    });
+    // Completeness is measured against the PROJECTED goal (base + delta) so the
+    // score reflects what the answers actually contribute to the GoalSpec, not
+    // the empty seed goal. This makes the 0.82 termination threshold meaningful.
+    const baseGoal = seed.goal ?? createGoalSpec(seed.rawPrompt);
+    const projected = applyInterviewDelta(baseGoal, specDelta).goal;
+    const completeness = computeCompleteness(projected, findings);
+    completeness.contradictions = uniqueStrings([...completeness.contradictions, ...contradictions]);
+    const status = decideStatus(completeness);
+    return {
+        ...session,
+        updatedAt: new Date().toISOString(),
+        answers: mergedAnswers,
+        findings,
+        completeness,
+        specDelta: {
+            ...specDelta,
+            goalId: session.goalId ?? specDelta.goalId,
+        },
+        status,
+    };
+}
+export function decideStatus(completeness) {
+    if (completeness.contradictions.length > 0)
+        return "blocked";
+    if (completeness.overall >= COMPLETENESS_THRESHOLD && completeness.criticalMissing.length === 0) {
+        return "complete";
+    }
+    return "open";
+}
+function mergeAnswers(existing, incoming) {
+    const byId = new Map();
+    for (const answer of existing)
+        byId.set(answer.questionId, answer);
+    for (const answer of incoming)
+        byId.set(answer.questionId, answer);
+    return [...byId.values()];
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter((value) => value.length > 0))];
+}

package/dist/input/input-envelope.d.ts

@@ -1,4 +1,23 @@
 export type InputKind = "plain-prompt" | "slash-command" | "goal-form" | "resume" | "verify" | "replan";
+/**
+ * Image or file attached to a prompt (clipboard paste, --image flag, drag).
+ * Carries both the on-disk path and the base64 data URI for multimodal
+ * wire protocol use (image_url parts).
+ */
+export interface InputAttachment {
+    /** Original file name or "clipboard-image.png". */
+    name: string;
+    /** Absolute or project-relative path to the saved file. */
+    path: string;
+    /** MIME type: image/png, image/jpeg, image/webp, image/gif. */
+    mimeType: string;
+    /** Base64 data URI (data:image/png;base64,...) for wire protocol. */
+    dataUri: string;
+    /** Detected extension: png, jpg, webp, gif. */
+    ext: string;
+    /** Source of the attachment. */
+    source: "clipboard" | "file" | "drag";
+}
 export type InputSource = "chat" | "parallel" | "run" | "goal" | "api";
 export type InputMcpScope = "all" | "project" | "none";
 export interface InputRequestedArtifact {
@@ -32,6 +51,8 @@ export interface InputEnvelope {
     theme?: string;
     constraints: string[];
     requestedArtifacts: InputRequestedArtifact[];
+    /** Images/files attached to this input (clipboard paste, --image, drag). */
+    attachments: InputAttachment[];
     slashCommand?: InputSlashCommandEnvelope;
     createdAt: string;
 }
@@ -52,6 +73,7 @@ export interface BuildInputEnvelopeInput {
     theme?: string;
     constraints?: readonly string[];
     requestedArtifacts?: readonly InputRequestedArtifact[];
+    attachments?: readonly InputAttachment[];
     slashCommand?: InputSlashCommandEnvelope;
     now?: () => Date;
 }

package/dist/input/input-envelope.js

@@ -60,6 +60,7 @@ export function buildInputEnvelope(input) {
         theme: input.theme,
         constraints: [...(input.constraints ?? [])],
         requestedArtifacts: input.requestedArtifacts?.map((artifact) => ({ ...artifact })) ?? [],
+        attachments: input.attachments?.map((a) => ({ ...a })) ?? [],
         slashCommand: input.slashCommand
             ? cloneSlashCommand(input.slashCommand)
             : undefined,

package/dist/memory/local-graph-memory-store.d.ts

@@ -1,4 +1,5 @@
 import { type MemorySettings, type MemoryStatus } from "./memory-config.js";
+import type { RunManifest } from "../contracts/run.js";
 export interface MemorySearchResult {
     path: string;
     content: string;
@@ -114,6 +115,20 @@ export declare class LocalGraphMemoryStore {
     search(query: string, limit?: number): Promise<MemorySearchResult[]>;
     ontology(): Promise<MemoryOntology>;
     mindmap(query?: string, limit?: number): Promise<MemoryMindmap>;
+    /**
+     * Idempotent finalizer that links a finalized run manifest into the local
+     * graph. Emits run -> providerRoute -> provider, run -> evidence,
+     * run -> decision, and run -> artifact nodes/edges.
+     *
+     * Privacy: only ids, status, paths, sha256, and aggregate counts are stored.
+     * Raw evidence/decision message bodies and secrets are never persisted.
+     *
+     * Idempotency: node/edge ids are deterministic and prior run-generated
+     * nodes/edges (tagged `generatedFromRun`) are pruned before re-inserting, so
+     * re-running with the same (or a changed) manifest never duplicates state.
+     */
+    linkRun(runId: string, manifest: RunManifest): Promise<void>;
+    private applyRunManifest;
     graphQuery(query: string): Promise<GraphQueryResult>;
     private loadState;
     private emptyState;

package/dist/memory/local-graph-memory-store.js

@@ -339,6 +339,182 @@ export class LocalGraphMemoryStore {
         const root = this.buildMindmapTree(rootNode, state, includedIds, new Set());
         return { root, nodes: flatNodes, edges, ontology: ONTOLOGY };
     }
+    /**
+     * Idempotent finalizer that links a finalized run manifest into the local
+     * graph. Emits run -> providerRoute -> provider, run -> evidence,
+     * run -> decision, and run -> artifact nodes/edges.
+     *
+     * Privacy: only ids, status, paths, sha256, and aggregate counts are stored.
+     * Raw evidence/decision message bodies and secrets are never persisted.
+     *
+     * Idempotency: node/edge ids are deterministic and prior run-generated
+     * nodes/edges (tagged `generatedFromRun`) are pruned before re-inserting, so
+     * re-running with the same (or a changed) manifest never duplicates state.
+     */
+    async linkRun(runId, manifest) {
+        const canonicalRunId = manifest.runId || runId;
+        if (runId && manifest.runId && runId !== manifest.runId) {
+            throw new Error(`linkRun: runId mismatch (param=${runId}, manifest=${manifest.runId})`);
+        }
+        await this.mutateState((state, now) => {
+            this.applyRunManifest(state, canonicalRunId, manifest, now);
+        });
+    }
+    applyRunManifest(state, runId, manifest, now) {
+        state.updatedAt = now;
+        state.project = { ...this.settings.project };
+        state.ontology = ONTOLOGY;
+        // Prune prior run-generated child nodes/edges for idempotent re-runs. The
+        // Run node and shared Provider nodes are intentionally not pruned (the Run
+        // node is re-upserted preserving createdAt; Providers are shared by runs).
+        const staleNodeIds = new Set(state.nodes.filter((node) => node.properties.generatedFromRun === runId).map((node) => node.id));
+        state.nodes = state.nodes.filter((node) => !staleNodeIds.has(node.id));
+        state.edges = state.edges.filter((edge) => edge.properties.generatedFromRun !== runId && !staleNodeIds.has(edge.from) && !staleNodeIds.has(edge.to));
+        const tag = { generatedFromRun: runId };
+        const projectId = this.nodeId("Project", this.settings.project.key);
+        this.upsertNode(state, {
+            id: projectId,
+            type: "Project",
+            labels: ["OmkProject", "Project"],
+            label: this.settings.project.name,
+            summary: this.settings.project.root,
+            tags: ["project"],
+            properties: { key: this.settings.project.key, root: this.settings.project.root },
+            createdAt: now,
+            updatedAt: now,
+        });
+        const runNodeId = this.nodeId("Run", runId);
+        this.upsertNode(state, {
+            id: runNodeId,
+            type: "Run",
+            labels: ["OmkRun", "Run"],
+            label: runId,
+            summary: `Run ${runId} (${manifest.status})`,
+            tags: ["run", manifest.status],
+            properties: {
+                runId,
+                status: manifest.status,
+                schemaVersion: manifest.schemaVersion,
+                createdAt: manifest.createdAt,
+                completedAt: manifest.completedAt ?? null,
+                promptHash: manifest.promptHash ?? null,
+                decisionTracePath: manifest.decisionTracePath ?? null,
+                evidenceRequired: manifest.evidenceSummary.required,
+                evidencePassed: manifest.evidenceSummary.passed,
+                evidenceFailed: manifest.evidenceSummary.failed,
+                evidenceMissing: manifest.evidenceSummary.missing,
+                nodeCount: manifest.nodes.length,
+                artifactCount: manifest.artifacts.length,
+                projectKey: this.settings.project.key,
+                source: this.source,
+            },
+            createdAt: now,
+            updatedAt: now,
+        });
+        this.upsertEdge(state, projectId, runNodeId, "HAS_RUN", now, tag);
+        // Provider route -> provider.
+        const provider = manifest.providerPolicy.provider;
+        const mode = manifest.providerPolicy.mode ?? "auto";
+        const routeNodeId = this.nodeId("ProviderRoute", `${runId}:${provider}:${mode}`);
+        this.upsertNode(state, {
+            id: routeNodeId,
+            type: "ProviderRoute",
+            labels: ["OmkProviderRoute", "ProviderRoute"],
+            label: `${provider} (${mode})`,
+            summary: `Provider route for run ${runId}`,
+            tags: ["provider-route", provider, mode],
+            properties: { runId, provider, mode, projectKey: this.settings.project.key, generatedFromRun: runId },
+            createdAt: now,
+            updatedAt: now,
+        });
+        this.upsertEdge(state, runNodeId, routeNodeId, "HAS_PROVIDER_ROUTE", now, tag);
+        const providerNodeId = this.nodeId("Provider", provider);
+        this.upsertNode(state, {
+            id: providerNodeId,
+            type: "Provider",
+            labels: ["OmkProvider", "Provider"],
+            label: provider,
+            summary: `Provider ${provider}`,
+            tags: ["provider", provider],
+            properties: { provider, projectKey: this.settings.project.key },
+            createdAt: now,
+            updatedAt: now,
+        });
+        this.upsertEdge(state, routeNodeId, providerNodeId, "ROUTES_TO", now, tag);
+        // Evidence summary node (counts/paths/sha only — never raw bodies).
+        const evidenceArtifact = manifest.artifacts.find((artifact) => artifact.kind === "evidence" || /(^|\/)evidence\.jsonl$/i.test(artifact.path));
+        const evidenceNodeId = this.nodeId("Evidence", `${runId}:evidence`);
+        this.upsertNode(state, {
+            id: evidenceNodeId,
+            type: "Evidence",
+            labels: ["OmkEvidence", "Evidence"],
+            label: `evidence:${runId}`,
+            summary: `Evidence ${manifest.evidenceSummary.passed}/${manifest.evidenceSummary.required} passed`,
+            tags: ["evidence", manifest.status],
+            properties: {
+                runId,
+                required: manifest.evidenceSummary.required,
+                passed: manifest.evidenceSummary.passed,
+                failed: manifest.evidenceSummary.failed,
+                missing: manifest.evidenceSummary.missing,
+                path: evidenceArtifact?.path ?? null,
+                sha256: evidenceArtifact?.sha256 ?? null,
+                projectKey: this.settings.project.key,
+                generatedFromRun: runId,
+            },
+            createdAt: now,
+            updatedAt: now,
+        });
+        this.upsertEdge(state, runNodeId, evidenceNodeId, "HAS_EVIDENCE", now, tag);
+        // Decision trace node (path/sha only — never raw bodies).
+        const decisionArtifact = manifest.artifacts.find((artifact) => artifact.kind === "decision" ||
+            artifact.kind === "decisions" ||
+            /(^|\/)decisions\.jsonl$/i.test(artifact.path));
+        const decisionPath = manifest.decisionTracePath ?? decisionArtifact?.path ?? null;
+        const decisionNodeId = this.nodeId("Decision", `${runId}:decision`);
+        this.upsertNode(state, {
+            id: decisionNodeId,
+            type: "Decision",
+            labels: ["OmkDecision", "Decision"],
+            label: `decisions:${runId}`,
+            summary: `Decision trace for run ${runId}`,
+            tags: ["decision", manifest.status],
+            properties: {
+                runId,
+                path: decisionPath,
+                sha256: decisionArtifact?.sha256 ?? null,
+                projectKey: this.settings.project.key,
+                generatedFromRun: runId,
+            },
+            createdAt: now,
+            updatedAt: now,
+        });
+        this.upsertEdge(state, runNodeId, decisionNodeId, "HAS_DECISION", now, tag);
+        // Artifacts -> File/Artifact nodes (id/kind/path/sha only).
+        for (const artifact of manifest.artifacts) {
+            const artifactNodeId = this.nodeId("Artifact", `${runId}:${artifact.kind}:${artifact.path}`);
+            this.upsertNode(state, {
+                id: artifactNodeId,
+                type: "Artifact",
+                labels: ["OmkArtifact", "Artifact", "File"],
+                label: artifact.path,
+                path: artifact.path,
+                summary: `${artifact.kind} artifact`,
+                tags: ["artifact", artifact.kind, ...pathTags(artifact.path)],
+                properties: {
+                    runId,
+                    kind: artifact.kind,
+                    path: artifact.path,
+                    sha256: artifact.sha256 ?? null,
+                    projectKey: this.settings.project.key,
+                    generatedFromRun: runId,
+                },
+                createdAt: now,
+                updatedAt: now,
+            });
+            this.upsertEdge(state, runNodeId, artifactNodeId, "TOUCHES_FILE", now, tag);
+        }
+    }
     async graphQuery(query) {
         const normalized = query.replace(/\s+/g, " ").trim();
         const data = {};

package/dist/memory/memory-store.d.ts

@@ -1,6 +1,7 @@
 import { type MemoryStatus } from "./memory-config.js";
 import type { GraphQueryResult, MemoryMindmap, MemoryOntology, MemorySearchResult } from "./local-graph-memory-store.js";
 import type { MemoryBackend } from "./memory-config.js";
+import type { RunManifest } from "../contracts/run.js";
 export interface MemoryStoreOptions {
     projectRoot?: string;
     sessionId?: string;
@@ -19,7 +20,24 @@ export interface UnifiedMemoryStore {
     ontology?: () => Promise<MemoryOntology | null>;
     mindmap?: (query?: string, limit?: number) => Promise<MemoryMindmap | null>;
     graphQuery?: (query: string) => Promise<GraphQueryResult>;
+    linkRun?: (runId: string, manifest: RunManifest) => Promise<void>;
 }
+export interface LinkRunToGraphOptions {
+    projectRoot?: string;
+    sessionId?: string;
+    source?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Idempotent, non-fatal finalizer: links a finalized run manifest into the
+ * local graph memory backend. Returns true when the active backend linked the
+ * run, false when no graph backend is available (e.g. file-only backend).
+ *
+ * Only ids/status/paths/sha256/counts are persisted — never raw evidence or
+ * decision bodies, and never secrets. Callers should still wrap this in their
+ * own try/catch so a graph write failure can never fail a run.
+ */
+export declare function linkRunToGraph(runId: string, manifest: RunManifest, options?: LinkRunToGraphOptions): Promise<boolean>;
 export declare function createMemoryStore(backend: MemoryBackend, options?: MemoryStoreOptions): Promise<UnifiedMemoryStore | null>;
 export declare class MemoryStore {
     private readonly options;

package/dist/memory/memory-store.js

@@ -2,6 +2,24 @@ import { readFile, writeFile, mkdir } from "fs/promises";
 import { join, dirname, resolve, relative, isAbsolute } from "path";
 import { getProjectRoot } from "../util/fs.js";
 import { loadMemorySettings, summarizeMemorySettings, } from "./memory-config.js";
+import { loadMemorySettings as loadMemorySettingsForLink } from "./memory-config.js";
+/**
+ * Idempotent, non-fatal finalizer: links a finalized run manifest into the
+ * local graph memory backend. Returns true when the active backend linked the
+ * run, false when no graph backend is available (e.g. file-only backend).
+ *
+ * Only ids/status/paths/sha256/counts are persisted — never raw evidence or
+ * decision bodies, and never secrets. Callers should still wrap this in their
+ * own try/catch so a graph write failure can never fail a run.
+ */
+export async function linkRunToGraph(runId, manifest, options = {}) {
+    const settings = await loadMemorySettingsForLink(options.projectRoot, options.env);
+    const store = await createMemoryStore(settings.backend, options);
+    if (!store || typeof store.linkRun !== "function")
+        return false;
+    await store.linkRun(runId, manifest);
+    return true;
+}
 export async function createMemoryStore(backend, options = {}) {
     if (backend === "local_graph") {
         const { LocalGraphMemoryStore } = await import("./local-graph-memory-store.js");