knodin 0.6.0 → 0.7.4

package/dist/src/tools/knodin-tools.js

@@ -16,13 +16,15 @@ import { getDocSection, listDocTopics } from "../docs-sections.js";
 import { diagnoseInstallation } from "../doctor.js";
 import { createEngine, REPO_WIDE_QUERY_PATTERNS, } from "../engine/index.js";
 import { measurePerfPhaseSync } from "../engine/perf.js";
+import { runExecutionProfile } from "../execution-profile.js";
 import { diagnoseFailure, } from "../failure-diagnosis.js";
 import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../graph-query-health.js";
 import { inspectRepositoryIntegrationStatus } from "../init.js";
-import { attachLifecycleHealth } from "../lifecycle-health.js";
+import { attachLifecycleHealth, attachRepairLifecycle } from "../lifecycle-health.js";
 import { compressOutput, compressOutputFile, deleteOutputArtifact, readOutputArtifact, } from "../output-compression.js";
 import { appendTelemetryRecord, clearTelemetry, countOutputTokens, exportTelemetry, measureOutput, readTelemetryRecords, telemetryStatus, writeTelemetryReport, } from "../output-telemetry.js";
 import { auditPullRequests, ghUnavailableReason, triagePrDetail } from "../pr-triage.js";
+import { deliverProgressiveEvidence, } from "../progressive-evidence.js";
 import { createRepairPlan } from "../repair-progress.js";
 import { runRepositoryInitializationProcess } from "../repository-init-process.js";
 import { discoverRepositories, initializeRepositories, inventoryRepository, searchRepositories, } from "../repository-management.js";
@@ -31,7 +33,18 @@ import { enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeFor
 import { trustedUpdateStatus } from "../update-policy.js";
 import { waitForFresh } from "../wait-for-fresh.js";
 import { inspectWorktrees, reconcileWorktrees, removeManagedWorktree, } from "../worktree-lifecycle.js";
-const engine = createEngine();
+let initializedEngine = null;
+function gatewayEngine() {
+    initializedEngine ??= createEngine();
+    return initializedEngine;
+}
+/** Lazy engine facade: schema/docs/compression startup does not open graph state. */
+const engine = new Proxy({}, {
+    get(_target, property) {
+        const value = gatewayEngine()[property];
+        return typeof value === "function" ? value.bind(gatewayEngine()) : value;
+    },
+});
 function gatewayCliCommand() {
     const extension = import.meta.url.endsWith(".ts") ? "ts" : "js";
     const entry = nodePath.resolve(nodePath.dirname(fileURLToPath(import.meta.url)), `../../bin/cli.${extension}`);
@@ -44,7 +57,9 @@ function gatewayCliCommand() {
 }
 /** Release the gateway engine's local watcher and database resources. */
 export async function closeKnodinToolEngine() {
-    await engine.close();
+    if (initializedEngine)
+        await initializedEngine.close();
+    initializedEngine = null;
     compactReadyRepos.clear();
 }
 const localTelemetry = [];
@@ -154,7 +169,9 @@ function buildDocumentedKnodinTools() {
                             "docs",
                             "doctor",
                             "pack",
+                            "evidence",
                             "compress",
+                            "execute",
                             "status",
                             "wait",
                             "worktrees",
@@ -163,7 +180,12 @@ function buildDocumentedKnodinTools() {
                             "system",
                             "telemetry",
                         ],
-                        description: "Which knodin capability to run. context: call this FIRST when starting any investigation and unsure which operation to reach for — one ultra-compact orientation (repo stats + top subsystems/hubs/flows + a risk score if there's a diff + a heuristic next-operation suggestion); the suggestion is only a hint and never blocks calling any operation directly. explain: use when orienting on a symbol/file or before editing it — returns edit-ready source + call paths + blast radius. review: use before writing a PR description or approving a diff — risk-scored context (changed symbols, affected flows, test gaps). map: use before a cross-cutting refactor or to understand subsystem boundaries — communities + hub/bridge nodes + confidence-tagged edges. search: use when you don't know the exact symbol name — hybrid semantic + keyword lookup over code symbols. query: use for a structured question about a known symbol — callers_of, tests_for, shortest_path, dead_code, rename_preview, flows, and more (see `pattern`). pack: create deterministic Markdown/JSON/XML source context under hard budgets, or bounded-read/exact-regex-grep a saved artifact. compress: reduce already-produced diagnostic text under exact line/content-byte budgets, preserve exit metadata and detected signals, retain private local drill-down data by default, and never label insufficient-fidelity output complete. prs: use to triage open GitHub PRs (via your local authenticated `gh`) — per-PR status, CI, and blast radius sorted ready-small-impact first; pass `prNumber` for one PR's impacted files + community names. wiki: write a static markdown documentation site for the repository's logical subsystems to `.knodin/wiki/`. Generates an index plus one page per mapped community. Reuses the `map` output. Idempotent: unchanged pages are untouched on disk unless `force` is true. docs: call this to retrieve curated, focused markdown usage guidance directly over MCP.",
+                        description: "Which knodin capability to run. context: call this FIRST when starting any investigation and unsure which operation to reach for — one ultra-compact orientation (repo stats + top subsystems/hubs/flows + a risk score if there's a diff + a heuristic next-operation suggestion); the suggestion is only a hint and never blocks calling any operation directly. explain: use when orienting on a symbol/file or before editing it — returns edit-ready source + call paths + blast radius. review: use before writing a PR description or approving a diff — risk-scored context (changed symbols, affected flows, test gaps). map: use before a cross-cutting refactor or to understand subsystem boundaries — communities + hub/bridge nodes + confidence-tagged edges. search: use when you don't know the exact symbol name — hybrid semantic + keyword lookup over code symbols. query: use for a structured question about a known symbol — callers_of, tests_for, shortest_path, dead_code, rename_preview, flows, and more (see `pattern`). pack: create deterministic Markdown/JSON/XML source context under hard budgets, or bounded-read/exact-regex-grep a saved artifact. compress: reduce already-produced diagnostic text under exact line/content-byte budgets, preserve exit metadata and detected signals, retain private local drill-down data by default, and never label insufficient-fidelity output complete. execute: run one immutable repository-defined profile only when independently enabled globally and locally; no executable or argv is accepted from the caller, unsupported containment fails closed, and output is compressed then diagnosed. prs: use to triage open GitHub PRs (via your local authenticated `gh`) — per-PR status, CI, and blast radius sorted ready-small-impact first; pass `prNumber` for one PR's impacted files + community names. wiki: write a static markdown documentation site for the repository's logical subsystems to `.knodin/wiki/`. Generates an index plus one page per mapped community. Reuses the `map` output. Idempotent: unchanged pages are untouched on disk unless `force` is true. docs: call this to retrieve curated, focused markdown usage guidance directly over MCP.",
+                    },
+                    profile: {
+                        type: "string",
+                        pattern: "^[a-z][a-z0-9_-]{0,63}$",
+                        description: "execute only: immutable repository-defined profile identity. The caller cannot supply executable, argv, cwd, environment, or limits.",
                     },
                     symbol: {
                         type: "string",
@@ -177,6 +199,24 @@ function buildDocumentedKnodinTools() {
                         type: "string",
                         description: "Repo-relative definition file selector.",
                     },
+                    evidenceLevel: {
+                        type: "string",
+                        enum: ["locate", "outline", "evidence", "expand"],
+                        description: "evidence only: deterministic progressive-delivery level.",
+                    },
+                    continuation: {
+                        type: "string",
+                        description: "evidence only: integrity-checked continuation returned by the prior level/page.",
+                    },
+                    baselineHash: {
+                        type: "string",
+                        description: "evidence only: SHA-256 of the complete baseline; omission requires an exact current match.",
+                    },
+                    baselineBytes: {
+                        type: "number",
+                        minimum: 0,
+                        description: "evidence only: complete baseline UTF-8 byte length; required with baselineHash.",
+                    },
                     kind: {
                         type: "string",
                         description: "Definition kind selector (function, class, method, etc.).",
@@ -622,16 +662,16 @@ function buildDocumentedKnodinTools() {
 export function getDocumentedKnodinToolsForSchemaProof() {
     return buildDocumentedKnodinTools();
 }
-const COMPACT_TOOL_DESCRIPTION = "Local code intelligence with freshness evidence. Start with context; use docs for guidance.";
+const COMPACT_TOOL_DESCRIPTION = "Local code intelligence.";
 const COMPACT_PARAMETER_DESCRIPTIONS = {
-    operation: "Capability to run. Use docs for complete operation guidance.",
-    symbol: "Target symbol or file; exact meaning depends on operation.",
-    pattern: "Query pattern; applies only when operation is query.",
-    impactMode: "Impact by stable symbol identity or explicitly labeled files.",
-    apply: "Apply rename_preview edits; false returns a dry-run.",
-    diffScope: "Review scope: unstaged, staged, all, or compare.",
-    section: "Docs section; quickstart includes the complete parameter reference.",
-    persistTelemetry: "Persist metadata-only telemetry locally; never source.",
+    operation: "Capability.",
+    symbol: "Target.",
+    pattern: "Query pattern.",
+    impactMode: "Symbol or file impact.",
+    apply: "Apply verified edits.",
+    diffScope: "Review diff scope.",
+    section: "Documentation section.",
+    persistTelemetry: "Persist metadata telemetry.",
 };
 function compactParameterDescription(name, description) {
     void description;
@@ -881,6 +921,23 @@ function compactExplainSource(result) {
         staleness: result.staleness,
     };
 }
+function handleProgressiveEvidenceOperation(repo, args, observe) {
+    if (!args.file || !args.evidenceLevel)
+        throw new Error("knodin evidence requires `file` and `evidenceLevel`");
+    return observe(deliverProgressiveEvidence({
+        repo,
+        file: args.file,
+        level: args.evidenceLevel,
+        continuation: args.continuation,
+        baselineHash: args.baselineHash,
+        baselineBytes: args.baselineBytes,
+        startLine: args.startLine,
+        endLine: args.endLine,
+        byteLimit: args.byteBudget,
+        tokenLimit: args.tokenBudget,
+        itemLimit: args.itemBudget,
+    }), "evidence");
+}
 function compactCompression(result) {
     return {
         status: result.status,
@@ -958,6 +1015,9 @@ function compactFailureDiagnosis(result) {
         unresolved: result.unresolved,
         context: result.contextBundle,
         freshness: [result.freshness.state, result.freshness.indexedHead, result.freshness.currentHead],
+        confidence: result.confidence,
+        omissions: result.omissions,
+        telemetry: result.telemetry,
         limitations: result.limitations,
     };
 }
@@ -973,6 +1033,7 @@ async function handleCompressionDiagnosis(repo, args, engine, graphRead) {
             artifactId: args.artifactId,
             text: args.text,
             maxDiagnostics: args.limit ?? args.itemBudget,
+            diagnosticOffset: args.startLine,
             contextLines: args.contextLines,
             contextByteBudget: args.compressionByteBudget,
         });
@@ -1042,6 +1103,29 @@ async function handleCompressionOperation(repo, args, engine, observe, bounded,
             throw new Error("knodin compress: invalid compressionAction");
     }
 }
+async function handleExecutionOperation(repo, profile, engine, bounded) {
+    if (!profile)
+        throw new Error("knodin execute requires `profile`");
+    const execution = await runExecutionProfile({ repo, profile });
+    let diagnosis = null;
+    if (execution.output?.artifact.retained && execution.status !== "completed") {
+        try {
+            diagnosis = await diagnoseFailure(engine, repo, {
+                artifactId: execution.output.artifact.id,
+                maxDiagnostics: 10,
+                contextLines: 2,
+                contextByteBudget: 16_384,
+            });
+        }
+        catch (error) {
+            diagnosis = {
+                status: "unavailable",
+                reason: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    return bounded({ execution, diagnosis }, "execute", true);
+}
 async function runCompactExplain(symbol, repo, selector, file, byteBudget) {
     const result = await engine.explain(symbol, repo, "minimal", selector);
     let sourceFile = file;
@@ -1159,6 +1243,9 @@ export async function handleKnodinTool(args) {
                 root.telemetry?.truncated === true,
             schemaTokens: gatewaySchemaTokens(),
         });
+        if (op === "execute" && parsedArgs.profile) {
+            telemetry.executionProfile = parsedArgs.profile;
+        }
         telemetry.temperature = localTelemetry.some(({ operation, repositoryId }) => operation === op && repositoryId === telemetry.repositoryId)
             ? "warm"
             : "cold";
@@ -1237,7 +1324,7 @@ export async function handleKnodinTool(args) {
         case "repair":
             if (repairPlan)
                 return bounded(createRepairPlan(await engine.status(repo, { audit: "deep" })), "repair:plan");
-            return engine.repair(repo).then((result) => bounded(result, "repair"));
+            return bounded(attachRepairLifecycle(repo, await engine.repair(repo)), "repair");
         case "repositories": {
             if (!repositoryAction)
                 throw new Error("knodin repositories requires `repositoryAction`");
@@ -1273,6 +1360,10 @@ export async function handleKnodinTool(args) {
         }
         case "compress":
             return handleCompressionOperation(repo, parsedArgs, engine, observe, bounded, graphRead);
+        case "execute":
+            return handleExecutionOperation(repo, parsedArgs.profile, engine, bounded);
+        case "evidence":
+            return handleProgressiveEvidenceOperation(repo, parsedArgs, observe);
         case "pack": {
             if (packAction !== undefined && !["export", "read", "grep"].includes(packAction))
                 throw new Error("knodin pack: invalid packAction");

package/dist/src/update-ceremony.js

@@ -0,0 +1,158 @@
+import { createHash, createPublicKey } from "node:crypto";
+import { canonicalizeUpdateMetadata, verifyUpdateRootChain, } from "./update-trust.js";
+const SHA256 = /^[0-9a-f]{64}$/;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{2,63}$/;
+function exactKeys(value, expected, label) {
+    const actual = Object.keys(value).sort();
+    const wanted = [...expected].sort();
+    if (actual.join("\0") !== wanted.join("\0"))
+        throw new Error(`${label} contains missing or unknown fields`);
+}
+function rejectPrivateMaterial(value, path = "input") {
+    if (typeof value === "string" && /PRIVATE KEY|recovery secret|seed phrase/i.test(value))
+        throw new Error(`${path} contains private material`);
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (/private|secret|seed|mnemonic|password|token/i.test(key))
+            throw new Error(`${path}.${key} is forbidden`);
+        rejectPrivateMaterial(child, `${path}.${key}`);
+    }
+}
+export function validateRootCeremonyManifest(value) {
+    rejectPrivateMaterial(value);
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("manifest must be an object");
+    const manifest = value;
+    exactKeys(manifest, [
+        "schemaVersion",
+        "ceremonyId",
+        "purpose",
+        "productionActivation",
+        "custodians",
+        "roleKeyIds",
+        "thresholds",
+    ], "manifest");
+    if (manifest.schemaVersion !== 1 ||
+        !ID.test(manifest.ceremonyId) ||
+        !["rehearsal", "production"].includes(manifest.purpose) ||
+        manifest.productionActivation !== false)
+        throw new Error("invalid fail-closed ceremony header");
+    if (!Array.isArray(manifest.custodians) ||
+        manifest.custodians.length < 3 ||
+        new Set(manifest.custodians.map((c) => c.id)).size !== manifest.custodians.length ||
+        manifest.custodians.some((c) => {
+            exactKeys(c, c.role === "root-signer"
+                ? ["id", "role", "publicKeyId"]
+                : ["id", "role", "recoveryKeyIds", "evidenceId"], "custodian");
+            return (!ID.test(c.id) ||
+                !["root-signer", "recovery"].includes(c.role) ||
+                (c.role === "root-signer" && !SHA256.test(c.publicKeyId ?? "")) ||
+                (c.role === "recovery" &&
+                    (!ID.test(c.evidenceId ?? "") ||
+                        !Array.isArray(c.recoveryKeyIds) ||
+                        c.recoveryKeyIds.some((id) => !SHA256.test(id)))));
+        }))
+        throw new Error("at least three distinct named custodians are required");
+    const roles = ["root", "targets", "snapshot", "timestamp"];
+    exactKeys(manifest.roleKeyIds, roles, "roleKeyIds");
+    exactKeys(manifest.thresholds, roles, "thresholds");
+    const all = new Set();
+    for (const role of roles) {
+        const ids = manifest.roleKeyIds?.[role];
+        const threshold = manifest.thresholds?.[role];
+        if (!Array.isArray(ids) ||
+            ids.length === 0 ||
+            ids.some((id) => !SHA256.test(id) || all.has(id)))
+            throw new Error("role keys must be valid and disjoint");
+        for (const id of ids)
+            all.add(id);
+        if (!Number.isInteger(threshold) ||
+            threshold < (role === "root" || role === "targets" ? 2 : 1) ||
+            threshold > ids.length)
+            throw new Error(`invalid ${role} threshold`);
+    }
+    if (manifest.custodians.filter((c) => c.role === "root-signer").length < manifest.thresholds.root ||
+        !manifest.custodians.some((c) => c.role === "recovery"))
+        throw new Error("custodian roles do not satisfy threshold and recovery separation");
+    const assigned = manifest.custodians
+        .filter((c) => c.role === "root-signer")
+        .map((c) => c.publicKeyId)
+        .sort();
+    if (assigned.join("\0") !== [...manifest.roleKeyIds.root].sort().join("\0"))
+        throw new Error("root signer assignments must exactly match root role keys");
+    const recovery = manifest.custodians.filter((c) => c.role === "recovery");
+    if (recovery.length < manifest.thresholds.root ||
+        new Set(recovery.map((c) => c.evidenceId)).size !== recovery.length ||
+        recovery.some((c) => !c.recoveryKeyIds?.length ||
+            new Set(c.recoveryKeyIds).size !== c.recoveryKeyIds.length ||
+            c.recoveryKeyIds.length >= manifest.thresholds.root))
+        throw new Error("recovery sets must preserve root threshold independence");
+    const recovered = new Set(recovery.flatMap((c) => c.recoveryKeyIds ?? []));
+    if (manifest.roleKeyIds.root.some((id) => !recovered.has(id)))
+        throw new Error("recovery assignments must cover every root role key");
+    return manifest;
+}
+export function validateRootPinReviewReceipt(value, manifest) {
+    rejectPrivateMaterial(value);
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("receipt must be an object");
+    const receipt = value;
+    exactKeys(receipt, [
+        "schemaVersion",
+        "ceremonyId",
+        "rootEnvelopeSha256",
+        "reviewerId",
+        "reviewedAt",
+        "decision",
+        "authentication",
+        "productionActivation",
+    ], "receipt");
+    if (receipt.schemaVersion !== 1 ||
+        receipt.ceremonyId !== manifest.ceremonyId ||
+        !SHA256.test(receipt.rootEnvelopeSha256) ||
+        !ID.test(receipt.reviewerId) ||
+        manifest.custodians.some((c) => c.id === receipt.reviewerId) ||
+        receipt.decision !== "approved" ||
+        receipt.authentication !== "rehearsal-unsigned" ||
+        receipt.productionActivation !== false ||
+        !Number.isFinite(Date.parse(receipt.reviewedAt)) ||
+        new Date(receipt.reviewedAt).toISOString() !== receipt.reviewedAt)
+        throw new Error("invalid or non-independent pin-review receipt");
+    return receipt;
+}
+export function preparePublicRootImport(envelope, pin, manifestValue, receiptValue, now = new Date()) {
+    rejectPrivateMaterial(envelope, "rootEnvelope");
+    const manifest = validateRootCeremonyManifest(manifestValue);
+    if (manifest.purpose === "production")
+        throw new Error("production import requires externally authenticated review and remains blocked");
+    const receipt = validateRootPinReviewReceipt(receiptValue, manifest);
+    if (Date.parse(receipt.reviewedAt) > now.getTime())
+        throw new Error("pin-review receipt cannot be future-dated");
+    const roles = ["root", "targets", "snapshot", "timestamp"];
+    for (const role of roles) {
+        const expected = manifest.roleKeyIds[role];
+        const actual = envelope.signed.roles[role];
+        if (actual.threshold !== manifest.thresholds[role] ||
+            [...actual.keyids].sort().join("\0") !== [...expected].sort().join("\0"))
+            throw new Error(`manifest ${role} role does not match root envelope`);
+    }
+    for (const key of Object.values(envelope.signed.keys)) {
+        let canonical = "";
+        try {
+            canonical = createPublicKey(key.keyval.public)
+                .export({ type: "spki", format: "pem" })
+                .toString();
+        }
+        catch {
+            /* fail below */
+        }
+        if (canonical !== key.keyval.public)
+            throw new Error("root envelope keys must use canonical public SPKI PEM only");
+    }
+    const digest = createHash("sha256").update(canonicalizeUpdateMetadata(envelope)).digest("hex");
+    if (pin !== digest || receipt.rootEnvelopeSha256 !== digest)
+        throw new Error("root envelope, pin, and independent review receipt disagree");
+    verifyUpdateRootChain(envelope, pin, [], now);
+    return { rootEnvelope: envelope, rootEnvelopeSha256: digest, productionActivation: false };
+}

package/docs/CLI.md

@@ -32,6 +32,28 @@ example repository existence, mutually exclusive configuration modes, and
 graph-query target rules), but syntax cannot reach a handler unless the shared
 declarative model accepts it first.
 
+For support evidence, `knodin diagnostics enable|status|collect|inspect|clear|disable`
+manages an explicit local failure journal and redacted gzip JSON bundles.
+Collection does not upload data. See `docs/DIAGNOSTICS.md` for retention,
+redaction, inspection, and known bounds.
+
+`knodin index --scip <file>` explicitly imports a bounded local SCIP protobuf
+snapshot. The flag is never implied by `init` or ordinary indexing, and no
+producer, daemon, account, credential, or network service is started. See
+`docs/SCIP-IMPORT.md` for the fact, freshness, path, resource, conflict, and
+known producer/language bounds.
+
+`knodin evidence <locate|outline|evidence|expand> <file>` progressively returns
+exact local source and stable continuations. A returned evidence handle plus
+`--baseline-hash` and `--baseline-bytes` permits omission only on an exact
+current-file match; all other baseline states return the required source. See
+`docs/PROGRESSIVE-EVIDENCE.md` for the protocol and limitations.
+
+`knodin review` returns separately itemized graph impact, test gaps, structural
+centrality, churn, co-change, and coupling evidence. Git history has explicit
+commit/file/time bounds and truthful unavailable or truncation states; see
+`docs/GIT-HISTORY-REVIEW.md`.
+
 `knodin pack grep` evaluates user patterns with exact-pinned RE2 WebAssembly,
 not Node's backtracking regular-expression engine. Backreferences and lookaround
 are rejected because they cannot retain RE2's linear-time guarantee. Route

package/docs/COMMAND-OUTPUT-COMPRESSION.md

@@ -4,8 +4,9 @@ knodin can deterministically compress already-produced build and test output
 without running the command that created it. This capability is available from
 the CLI and the single MCP gateway in post-0.3 development.
 
-knodin deliberately does **not** expose `knodin run`. Portable command
-execution remains excluded until the containment gate below can be proven.
+knodin deliberately does **not** expose `knodin run` or accept command strings.
+The separate `execute` MCP operation is limited to doubly enabled immutable
+profiles and the certified platform boundary documented below.
 
 ## Use it
 
@@ -90,6 +91,7 @@ command:
 ```bash
 knodin compress diagnose <artifact-id> --limit 10 --context 2
 knodin compress diagnose <artifact-id> --max-output-bytes 16384 --json
+knodin compress diagnose <artifact-id> --offset 10 --limit 10 --json
 ```
 
 The same graph read is available through the single MCP gateway:
@@ -100,6 +102,7 @@ The same graph read is available through the single MCP gateway:
   "compressionAction": "diagnose",
   "artifactId": "<sha256>",
   "limit": 10,
+  "startLine": 10,
   "contextLines": 2,
   "compressionByteBudget": 16384,
   "detailLevel": "standard"
@@ -143,8 +146,18 @@ current graph evidence, and an untruncated context bundle. `partial` identifies
 any omitted input, unresolved reference, stale graph, or exhausted context
 budget. `unresolved` means no safe repository location was established.
 
-The relationships are static diagnostic candidates, not proof of runtime
-causality. Package ownership is evidenced by the nearest tracked
+The versioned JSON schema also reports `confidence`, exact `omissions`, and
+`telemetry`. When the diagnostic item cap omits references from a retained
+artifact, `omissions.continuation` identifies the artifact and next diagnostic
+offset for recoverable local drill-down. `telemetry.commandRerun` is always
+false. Outer MCP response budgets add hard byte/token/item accounting without
+changing the diagnosis evidence contract.
+
+For the compact single-tool schema, MCP diagnose continuation uses the existing
+bounded `startLine` integer as its diagnostic offset; CLI uses `--offset`.
+
+The relationships are bounded source-evidenced diagnostic candidates, not
+proof of runtime causality, guaranteed root causes, or automatic fixes. Package ownership is evidenced by the nearest tracked
 `package.json`, `pyproject.toml`, `pom.xml`, `Cargo.toml`, `go.mod`, or
 `.csproj`; malformed or unnamed manifests remain explicit. Dynamic dispatch,
 generated paths, source maps, and framework wiring can require additional
@@ -163,11 +176,15 @@ Oversized input is rejected rather than partially retained. Output artifacts
 are content-addressed, reads are byte-bounded, deletion requires an exact
 artifact identity, and symlinked storage paths are refused.
 
-## Command-execution security gate
+## Profile-based execution boundary
+
+The compressor remains independently usable on already-produced output. The
+optional `execute` operation now accepts only an immutable repository profile
+identity and composes captured output through this compressor. The detailed
+configuration and certified boundary are documented in
+[Profile-based contained execution](CONTAINED-EXECUTION.md).
 
-The safe compressor processes data only; it does not invoke a shell or child
-process. A future runner must address this threat model with executable,
-platform-specific evidence:
+The shipping runner is still held to this threat model:
 
 | Threat | Required proof before shipping a runner |
 |---|---|
@@ -185,10 +202,9 @@ platform-specific evidence:
 | Telemetry leakage | No command text or raw output in default telemetry; redact before opt-in export |
 | Platform differences | Separate verified guarantees and explicit unsupported cases |
 
-Node's cross-platform child-process API alone cannot impose a hard memory limit
-on an arbitrary executable, Windows job-object behavior differs from POSIX
-process groups, and portable network/filesystem containment requires more than
-an output buffer and timeout. Until a reviewed native or operating-system
-containment adapter proves the table above, command execution is an intentional
-safety non-goal. Existing trusted execution tools can write a log and pass that
-artifact to knodin for bounded compression.
+The original C58 prototype remains rejected: cwd/realpath checks and polling
+were not containment. C88 reopens the capability under a narrower contract.
+The certified macOS adapter adds enforceable network/user-data boundaries and
+hard fork denial; Linux and Windows fail closed as unavailable. No portable
+claim is inferred, no unrestricted command surface exists, and repository code
+can still modify the authorized checkout.

package/docs/CONTAINED-EXECUTION.md

@@ -0,0 +1,77 @@
+# Profile-based contained execution
+
+`knodin` can execute one immutable repository-defined profile through the
+single MCP gateway. It never accepts a command string, executable, argv, cwd,
+environment, or limit from an MCP caller.
+
+Execution is disabled by two independent defaults. Enable it globally in
+`$XDG_CONFIG_HOME/knodin/execution.json` (or
+`~/.config/knodin/execution.json`):
+
+```json
+{"execution":{"enabled":true}}
+```
+
+Then define and enable exact profiles in `.knodin/execution.json`:
+
+```json
+{
+  "execution": {
+    "enabled": true,
+    "profiles": {
+      "test": {
+        "executable": "/opt/homebrew/bin/bun",
+        "args": ["run", "test"],
+        "network": "deny",
+        "timeoutMs": 120000,
+        "maxOutputBytes": 2097152,
+        "maxProcesses": 1,
+        "containment": "fully-contained"
+      }
+    }
+  }
+}
+```
+
+An agent may call `{ "operation": "execute", "profile": "test" }`. Profile
+names are bounded identifiers. Shell strings and caller-supplied argument
+suffixes are not part of the schema.
+
+## Containment contract
+
+The initial certified adapter is macOS `sandbox-exec`. It runs with a minimal
+environment (`PATH`, `LANG`, `LC_ALL`, and repository-local `TMPDIR`), closed
+stdin, no shell, repository cwd, a detached process group, hard timeout and
+combined-output caps, and Seatbelt rules that:
+
+- deny all network operations;
+- deny process forks, making `maxProcesses: 1` a hard contract;
+- deny all writes outside the repository;
+- deny reads under user homes, mounted volumes, network mounts, and shared
+  temporary roots outside the repository; and
+- allow repository reads/writes and read-only system runtime paths required to
+  load the approved executable.
+
+Profiles needing child processes are rejected by this first contract. Define
+the profile around a single-process test/lint/typecheck/build executable. The
+macOS adapter reports `fully-contained` only when every configured boundary is
+active. It also reports that `sandbox-exec` is deprecated; this certification
+is tied to the checked-in adversarial tests, not a claim that Seatbelt is a
+supported public Apple API.
+
+Linux and Windows currently report `containment-unavailable` and do not spawn
+the profile. A future Bubblewrap or Windows Job Object/restricted-token adapter
+requires its own native evidence before it can change that result.
+
+## Output, diagnosis, and audit
+
+Captured stdout/stderr goes directly through recoverable compression. Failed,
+timed-out, and output-limited MCP executions then request source-evidenced
+failure diagnosis from the existing graph. Raw command text, argv, environment,
+and output are never written to execution telemetry. The private repository
+audit `.knodin/execution-audit.jsonl` records only timestamp, profile identity,
+status, exit/signal, reported containment, and retained output-artifact identity.
+
+Repository code can still be destructive inside the authorized repository.
+This is a constrained trusted-repository workflow, not a guarantee that an
+approved test/build profile cannot modify its own checkout.

package/docs/DIAGNOSTICS.md

@@ -0,0 +1,45 @@
+# Local troubleshooting diagnostics
+
+knodin can retain a small, local diagnostic journal and build a redacted bundle
+for a user to inspect and share with support. Diagnostics are disabled until the
+user enables them, never upload automatically, and require no account or hosted
+service.
+
+```bash
+knodin diagnostics enable --retention-days 14
+knodin diagnostics status
+knodin diagnostics collect --since 24h
+knodin diagnostics inspect .knodin/diagnostics/knodin-diagnostics-….json.gz
+knodin diagnostics clear
+knodin diagnostics disable
+```
+
+`enable` records bounded failure envelopes from the CLI and MCP gateway. Each
+record contains a timestamp, random correlation ID, surface, operation, phase,
+safe error name/code, a message fingerprint, and sanitized stack shape. It does
+not retain the command arguments, query, error message, source, raw output,
+environment, username, repository path, or source paths. Records are stored in
+`.knodin/diagnostics/events.jsonl`, mode `0600`, capped at 500 events, and
+pruned to the configured 1–365 day retention window.
+
+`collect` runs local installation and deep graph diagnostics and combines their
+redacted results with recent failure envelopes, metadata-only telemetry when
+present, and at most 64 KiB/200 lines from the lifecycle indexer log. The
+default collection window is 24 hours; `--since` accepts hours or days. Bundle
+output must remain inside the repository and cannot traverse a symlink.
+
+The bundle is gzip-compressed JSON, written mode `0600`, and includes a privacy
+manifest, explicit omissions, and a redaction count. `inspect` validates the
+manifest and a 10 MiB compressed-size ceiling before returning its contents.
+Users should inspect the bundle before attaching it to Jira, GitHub, email, or
+another support channel. knodin does not transmit it.
+
+`clear` removes only the event journal. It does not delete previously created
+bundles or ROI telemetry. `disable` stops future failure recording but preserves
+existing events so disabling never silently destroys troubleshooting evidence.
+Run `clear` when deletion is intended.
+
+Diagnostics are evidence, not runtime-causality proof. Message fingerprints can
+group identical sanitized failures but cannot reconstruct the original message.
+Redaction is defense in depth; users remain responsible for inspecting an
+artifact before sharing it outside their organization.

package/docs/DOCTOR-AND-UPDATES.md

@@ -69,8 +69,11 @@ the provenance/SBOM and five-channel attestation machinery; the production
 release must populate it, and C65 must supply compromised-channel and recovery
 evidence before this gate can open.
 
-Run `knodin status --deep` for graph details and `knodin repair` for surgical
-repair. Re-run `knodin init` after changing the executable owner or MCP path.
+Run `knodin status --deep` for graph details and follow its typed repair steps:
+`knodin repair` repairs graph data, while `knodin init` restores lifecycle
+routing. Re-run `knodin init` after changing the executable owner, MCP path, or
+hook-manager installation. The complete refresh-path matrix is in
+[`FRESHNESS-AND-LIFECYCLE.md`](FRESHNESS-AND-LIFECYCLE.md).
 
 ## Query availability