@deksden-com/dd-flow-cli 0.9.0-beta.136 → 0.9.0-beta.137

package/dist/services/vnext-fanout.js

@@ -32,6 +32,62 @@ export function getStageFanoutCapacity(context, input) {
     const available = variables.variables[subagentCapacityKey];
     return { run_key: subagentCapacityKey, available_slots: typeof available === "number" && Number.isInteger(available) && available >= 0 ? available : null, source: "harness_qualification" };
 }
+function nativeFailureController(context, projectId, runId, stage, parent) {
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type='table' AND name='run_controllers'"))
+        return null;
+    const rows = context.db.all("SELECT controller_id,generation,state_json FROM run_controllers WHERE project_id=? AND run_id=? AND status NOT IN ('completed','cancelled','superseded')", [projectId, runId]);
+    const matching = rows.filter(row => {
+        try {
+            const state = JSON.parse(row.state_json);
+            return state.stage === stage && state.sessions?.[state.current_session]?.id === parent;
+        }
+        catch {
+            return false;
+        }
+    });
+    return matching.length === 1 ? matching[0] : null;
+}
+/** Failure metadata authored by a Work is not native evidence. Require the
+ * independently recorded reconciliation and its exact current registry links. */
+export function verifiedNativeWorkFailure(context, input) {
+    const b = input.receipt.native_binding;
+    if (!b || b.schema_id !== "dd-flow/native-work-failure@1")
+        return;
+    const project = requireProjectByRoot(context, input.projectRoot);
+    const scope = stageGraphScope(context, project.id, input.runId, input.stage);
+    const controller = nativeFailureController(context, project.id, input.runId, input.stage, input.parentSessionId);
+    if (!controller || b.controller_id !== controller.controller_id || b.generation !== controller.generation
+        || b.project_id !== project.id || b.run_id !== input.runId || b.stage !== input.stage
+        || b.stage_attempt_id !== scope.attempt || b.stage_cycle !== scope.cycle
+        || b.work_id !== input.workId || b.parent_work_id !== input.parentWorkId
+        || b.parent_provider_session_id !== input.parentSessionId || b.terminal_turn_id !== input.receipt.terminal_turn_id
+        || input.receipt.source !== "native_child_observation" || input.receipt.outcome !== "failed")
+        return;
+    const link = context.db.get(`SELECT ws.id FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id JOIN sessions s ON s.project_id=w.project_id AND s.session_id=ws.session_id
+    WHERE ws.id=? AND w.project_id=? AND w.run_id=? AND w.work_id=? AND w.parent_work_id=? AND ws.status='failed' AND w.status='failed' AND s.parent_session_id=? AND s.provider_session_id=? AND s.harness=?`, [b.work_session_id, project.id, input.runId, input.workId, input.parentWorkId, storageSessionId({ harness_id: b.harness_id, session_id: input.parentSessionId }), b.provider_session_id, b.harness_id]);
+    if (!link)
+        return;
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_id=? AND id=?", [project.id, input.runId]);
+    try {
+        const events = fs.readFileSync(path.join(run.run_root, "timeline.jsonl"), "utf8").trim().split("\n");
+        const proof = events.some(line => {
+            const event = JSON.parse(line);
+            if (event.type !== "native_child_reconciliation" || event.stage !== input.stage)
+                return false;
+            const terminal = event.observations?.children?.find((child) => child.session_id === b.provider_session_id && child.terminal_turn_id === b.terminal_turn_id);
+            if (event.observations?.parent_session_id !== b.parent_provider_session_id || event.observations?.harness_id !== b.harness_id
+                || terminal?.status !== "failed" || terminal.terminal_observed_at !== input.receipt.terminal_observed_at
+                || JSON.stringify(safeNativeFailure(terminal.provider_error)) !== JSON.stringify(safeNativeFailure(input.receipt.provider_error)))
+                return false;
+            return event.reconciled?.some((entry) => entry.outcome === "failed"
+                && entry.native_binding && Object.keys(b).every(key => b[key] === entry.native_binding[key]));
+        });
+        return proof ? b : undefined;
+    }
+    catch {
+        return;
+    }
+}
 export function fanoutState(input) {
     if (!input.hasWork)
         return input.dispatch === "none" ? "coordinator_required" : "dispatch_required";
@@ -177,12 +233,21 @@ export async function reconcileVnextFanout(context, input) {
             continue;
         }
         const providerError = safeNativeFailure(child.provider_error);
+        const controller = nativeFailureController(context, project.id, input.runId, input.stage, value.parent_session_id);
+        const scope = stageGraphScope(context, project.id, input.runId, input.stage);
+        const terminalTime = typeof child.terminal_observed_at === "string" ? Date.parse(child.terminal_observed_at) : NaN;
+        const nativeBinding = child.status === "failed" && controller && typeof child.terminal_turn_id === "string" && child.terminal_turn_id.length > 0 && child.terminal_turn_id.length <= 256 && Number.isFinite(terminalTime)
+            ? { schema_id: "dd-flow/native-work-failure@1", project_id: project.id, run_id: input.runId, stage: input.stage, stage_attempt_id: scope.attempt, stage_cycle: scope.cycle,
+                parent_work_id: status.orchestration.parent_work_id, work_id: link.work_id, work_session_id: link.id, harness_id: value.harness_id,
+                parent_provider_session_id: value.parent_session_id, provider_session_id: String(child.session_id), terminal_turn_id: child.terminal_turn_id,
+                controller_id: controller.controller_id, generation: controller.generation } : undefined;
         const reason = JSON.stringify({ source: "native_child_observation", harness_id: value.harness_id, session_id: child.session_id, work_session_id: link.id, outcome: child.status,
+            ...(nativeBinding ? { native_binding: nativeBinding } : {}),
             ...(typeof child.terminal_turn_id === "string" ? { terminal_turn_id: child.terminal_turn_id } : {}),
             ...(typeof child.terminal_observed_at === "string" ? { terminal_observed_at: child.terminal_observed_at } : {}),
             ...(providerError ? { provider_error: providerError } : {}) });
         const result = await (child.status === "failed" ? failWork : cancelWork)(context, link.work_id, reason);
-        reconciled.push({ work_id: link.work_id, work_session_id: link.id, outcome: child.status, result });
+        reconciled.push({ work_id: link.work_id, work_session_id: link.id, outcome: child.status, ...(nativeBinding ? { native_binding: nativeBinding } : {}), result });
     }
     appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "native_child_reconciliation", stage: input.stage, observations: value, issues, reconciled });
     return { ok: true, issues, reconciled };

package/dist/services/vnext-protocolize.js

@@ -4,6 +4,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { parse as parseYaml } from "yaml";
 import { AppError } from "../shared/errors.js";
 import { projectFeatureWorktreePath, resolveProjectRoot } from "../storage/paths.js";
 import { previewNextEntityId } from "./ids.js";
@@ -189,6 +190,29 @@ export async function finishVnextProtocolize(context, input) {
     const resultFile = prepareProtocolizeResultPath(requireRunHome(run), input.resultFile);
     const result = input.result ?? readResult(resultFile, { projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireRunHome(run) });
     validateSchema({ schemaName: "vnext-protocolize-result", file: resultFile, data: result, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireRunHome(run) });
+    const acceptedIndex = JSON.parse(context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, run.id]).index_json);
+    if (acceptedIndex.stage_runs.some(item => item.stage === stage && item.status === "done")) {
+        publishStageReport(context, project.id, run.id, stage, root);
+        const file = path.join(root, "stage-report.json");
+        if (!fs.existsSync(file))
+            throw new AppError("protocolize_report_missing", "Completed PROTOCOLIZE has no accepted report to replay", 1, { run_id: run.id });
+        const accepted = JSON.parse(fs.readFileSync(file, "utf8"));
+        const authoredSha = accepted.semantic.materialization?.authored_result?.sha256;
+        if (authoredSha && authoredSha !== sha256(fs.readFileSync(resultFile)))
+            throw new AppError("protocolize_intent_conflict", "Completed PROTOCOLIZE result differs from accepted input", 1, { run_id: run.id });
+        const currentStage = acceptedIndex.current_stage ?? [...acceptedIndex.stage_runs].reverse().find(item => item.status === "running" || item.status === "done")?.stage;
+        const activeReplay = currentStage === stage && acceptedIndex.status === "running";
+        const resolvedPolicy = activeReplay ? requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: requireRunHome(run), workspaceRoot: run.workspace_root, stage: "protocolize" }) : accepted.mechanical?.workspace_route;
+        if (activeReplay) {
+            if (acceptedIndex.verdict !== "protocolized")
+                advanceFlowRun(context, { settlementStage: "protocolize", projectRoot, runId: run.id, status: "running", verdict: "protocolized", nextAction: "start_plan" });
+            refreshRunWorkProjection(context, project.id, run.id);
+        }
+        const next = activeReplay ? stageSuccessor(context, { projectRoot, runId: run.id, stage: "plan", command: `${flowCommand(context)} stage start ${run.id} --stage plan --project-root ${JSON.stringify(projectRoot)} --json`, metadata: { cwd: run.workspace_root, session_mode: resolvedPolicy.stage_session_mode } }) : { kind: "complete", outcome: "already_completed" };
+        return { ok: true, outcome: "protocolized", run_id: run.id, protocol_ids: accepted.semantic.acceptance, workspace_root: run.workspace_root, git_policy: resolvedPolicy, next_action: activeReplay ? "await_plan" : acceptedIndex.next_action, ...("command" in next && next.command ? { next_command: next.command } : {}), next,
+            artifacts: { result: resultFile, report_json: file, report_markdown: path.join(root, "stage-report.md"), report_html: path.join(root, "stage-report.html"), protocols: accepted.semantic.acceptance.map(id => path.join(run.workspace_root, ".memory-bank/protocol", id, "summary.md")) } };
+    }
+    const resolvedPolicy = requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: requireRunHome(run), workspaceRoot: run.workspace_root, stage: "protocolize" });
     const acceptedObligations = acceptedSpecifyObligations(context, projectRoot, run.id, path.join(requireRunHome(run), "01-specify", "specify.json"));
     let obligations;
     try {
@@ -202,11 +226,11 @@ export async function finishVnextProtocolize(context, input) {
             throw error;
         throw new AppError(error.code, error.message, error.exitCode, { ...error.details, phase: "prepare", effect: "no_effect", recoverable: true });
     }
-    const resolvedPolicy = requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: requireRunHome(run), workspaceRoot: run.workspace_root, stage: "protocolize" });
     const receipt = readWorkspaceRouteReceipt(root);
     const workspaceRoot = run.workspace_root;
     const intent = await prepareProtocolizeIntent(context, run, resultFile, result, obligations);
     publishProtocolizeIntent(context, project.id, intent);
+    const materialization = verifyProtocolizeMaterialization(intent, result, path.relative(requireRunHome(run), resultFile));
     const protocolIds = intent.protocol_ids;
     const changedFiles = intent.changed_files;
     for (const protocolId of protocolIds)
@@ -216,9 +240,10 @@ export async function finishVnextProtocolize(context, input) {
             ensureManagedWorktreeRecorded(context, { protocolId, projectRoot, branch: requiredPolicyValue(resolvedPolicy.feature_branch, "feature branch"), base: requiredPolicyValue(resolvedPolicy.base_ref, "base ref"), created: receipt.created, bootstrap: receipt.bootstrap });
     }
     const now = context.now();
-    const workSession = completeWorkSession(context, work.work_id, resultFile, now);
+    const workSession = context.db.get("SELECT * FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
     const routedRun = requireRun(context, projectRoot, run.id);
     const report = stageReport(context, routedRun, resultFile, protocolIds, changedFiles, workSession?.session_id ?? null, now, resolvedPolicy);
+    Object.assign(report.semantic, { materialization });
     const reportJson = path.join(root, "stage-report.json");
     const reportMarkdown = path.join(root, "stage-report.md");
     const reportHtml = path.join(root, "stage-report.html");
@@ -235,6 +260,7 @@ export async function finishVnextProtocolize(context, input) {
         const completion = { projectRoot, runId: run.id, stage, status: "done", data: "protocolize-result.json", dataSchemaId: "dd-flow/vnext-protocolize-result@3", report: "stage-report.md", stageReport: "stage-report.html", dataSha256: crypto.createHash("sha256").update(fs.readFileSync(resultFile)).digest("hex") };
         const preparedCompletion = prepareFlowRunStageCompletion(context, completion);
         withStageSettlement(context, () => {
+            completeWorkSession(context, work.work_id, resultFile, now);
             acceptStageReport(context, { projectId: project.id, runId: run.id, stage, root, prepared: preparedReport });
             completeFlowRunStage(context, completion, preparedCompletion);
         });
@@ -367,6 +393,38 @@ function ensureManagedWorktreeRecorded(context, input) {
     recordManagedWorktree(context, input);
 }
 function sha256(bytes) { return crypto.createHash("sha256").update(bytes).digest("hex"); }
+export function verifyProtocolizeMaterialization(intent, result, authoredPath) {
+    const documents = intent.files.map(file => {
+        const target = path.resolve(intent.workspace_root, file.relative);
+        inside(path.join(intent.workspace_root, ".memory-bank"), target);
+        assertNoSymlinkPath(path.join(intent.workspace_root, ".memory-bank"), target);
+        const bytes = fs.readFileSync(target);
+        if (sha256(bytes) !== file.after_sha256)
+            throw new AppError("protocolize_materialization_invalid", "Published document differs from accepted intent", 1, { path: file.relative });
+        return { path: file.relative, sha256: file.after_sha256 };
+    });
+    const featurePaths = intent.changed_files.filter(file => /\/features\/FT-[^/]+\/index\.md$/.test(file));
+    const featurePath = result.feature.action === "not_applicable" ? null : featurePaths.length === 1 ? featurePaths[0] : null;
+    if (result.feature.action !== "not_applicable" && !featurePath)
+        throw new AppError("protocolize_materialization_invalid", "Accepted feature output is ambiguous or missing", 1);
+    const frontmatter = (relative) => {
+        const text = fs.readFileSync(path.join(intent.workspace_root, relative), "utf8");
+        const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+        const value = match ? parseYaml(match[1]) : null;
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new AppError("protocolize_materialization_invalid", "Published document lacks frontmatter", 1, { path: relative });
+        return value;
+    };
+    const edges = featurePath ? intent.protocol_ids.map(protocolId => ({ feature_path: featurePath, protocol_id: protocolId, protocol_path: `.memory-bank/protocol/${protocolId}/summary.md` })) : [];
+    for (const edge of edges) {
+        const protocols = frontmatter(edge.feature_path).related_protocols;
+        const features = frontmatter(edge.protocol_path).related_features;
+        if (!Array.isArray(protocols) || !protocols.includes(edge.protocol_id) || !Array.isArray(features) || !features.includes(edge.feature_path))
+            throw new AppError("protocolize_materialization_invalid", "Owned feature/protocol links are not reciprocal", 1, edge);
+    }
+    return { schema_id: "dd-flow/protocolize-materialization@1", run_id: intent.run_id, stage: "protocolize", action: result.feature.action, feature_path: featurePath,
+        protocol_ids: intent.protocol_ids, authored_result: { role: "authored_input", run_relative_path: authoredPath, sha256: intent.result_sha256 }, documents, owned_links: edges, status: "passed" };
+}
 async function materialize(projectRoot, runId, runHome, result, obligations, ids, psetId) {
     const psetPath = psetId ? path.join(projectRoot, ".memory-bank", "protocol", "_set", `${psetId}.md`) : null;
     const created = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.136",
+  "version": "0.9.0-beta.137",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "packageManager": "pnpm@10.23.0",

package/dist/cli/command-metadata.js

@@ -1,144 +0,0 @@
-import { commandInputs, physicalPathOptions } from "./command-inputs.js";
-import { runtimeOptionDescriptions } from "./command-option-descriptions.js";
-const optionDescriptions = {
-    "harness": "Select one supported harness family. Static discovery checks executable presence, not authentication or model access; diagnostics require separate effect consent.",
-    "provider": "Exact provider namespace for model filtering or doctor observation binding, including namespaced IDs such as builtin:zai-coding-plan. An account binding requires --account-sha256; this selector does not authenticate credentials.",
-    "executable": "Explicit installed harness executable path, including paths with spaces. Resolves ambiguous installations without choosing an arbitrary PATH candidate. Discovery never executes it; probes require explicit effect flags.",
-    "state-dir": "Existing OpenCode server state directory for the selected doctor. Its daemon configuration must bind the selected executable; doctor does not start or stop an unrelated daemon. Not an executor profile or project directory.",
-    "model-observation-file": "Optional destination for a standalone model listing snapshot from the admitted doctor. Requires --provider and --account-sha256; operator scope is unverified. Artifact publication is explicit, separate from provider writes, and never proves account access. Must differ from --response-file.",
-    "save-profile-intent": "Explicit frozen dd-flow/profile-creation-intent@1 JSON file containing before/after settings, profile and default consent. Setup binds it to request identity, saves under revision CAS and reconciles exact replay. Conflicts with --skip-agent-setup; an additional selected profile must match. This file is not provider authorization.",
-    "set-default": "Explicitly select the newly created profile as global default in the same atomic settings write. Omission preserves the existing default. Does not change frozen RUN settings.",
-    "remove": "Remove the positional operator alias binding, not its target profile; conflicts with --target.",
-    "clear": "Clear the operator global default without removing profiles or changing project routing and frozen RUN snapshots.",
-    "allow-processes": "Explicit permission to execute installed diagnostic code. Version/doctor probes are opt-in; static discovery never requires this flag.",
-    "allow-services": "Permit the selected adapter doctor's possible service process effects. Does not authorize model Turns, a flow, or reuse of an unrelated service.",
-    "allow-credentials": "Permit possible credential reads by the installed diagnostic; no credentials or raw adapter output enter this command's result.",
-    "allow-writes": "Permit possible diagnostic temporary/runtime writes by installed code; not permission to modify project packs or RUN settings.",
-    "native-executable": "Absolute native ZCode executable for the selected ZCode ACP doctor; no ambient ZCODE_BIN fallback. Invalid for other families.",
-    "timeout-ms": "Timeout in milliseconds for the selected operation. Harness diagnostics accept 1..60000: version defaults to 3000 and doctor to 30000. Other commands retain their own operation timeout policy; this option is not a productive RUN inactivity policy.",
-    "seed-file": "Optional reviewed dd-flow/model-catalog@1 JSON input; default is the bundled seed. Seed-only entries cannot establish account access or runtime qualification.",
-    "observation-file": "Explicit regular-file model listing snapshot; requires --harness, --provider and --account-sha256. Foreign scopes are ignored; malformed or secret-bearing fields refuse. No live listing is started.",
-    "account-sha256": "Opaque 64-character lowercase SHA-256 account binding, never an account name, token or credential path. Requires --harness and --provider; does not authenticate the account.",
-    "canon-source": "Explicit local signed release bundle or HTTPS envelope URL. Remote archives must use the same origin; trust comes only from --trust-file. Exclusive with --canon-version.",
-    "canon-version": "Exact canon release version in the selected channel of the operator release registry; exclusive with --canon-source. Omission selects the registry's explicit channel default.",
-    "release-registry": "Operator dd-flow/release-registry@1 JSON selector; default is DD_FLOW_RELEASE_REGISTRY or release-registry.json in DD_FLOW_HOME. Registry entries never enroll signing keys.",
-    "trust-file": "Explicit operator dd-flow/release-trust@1 file; release bytes cannot enroll their own signing key.",
-    "channel": "Selected release channel; preview and development must be requested explicitly.",
-    "skip-agent-setup": "Install without selecting or configuring an executor; conflicts with --profile.",
-    "non-interactive": "Never request interactive input; a missing executor selection fails unless agent setup is explicitly skipped.",
-    "project-root": "Stable repository identity; not the assigned feature workspace.",
-    "workspace-root": "Concrete assigned checkout used for this operation.",
-    "workspace-path": "Concrete assigned checkout; does not change project identity.",
-    "root": "Explicit root for the selected command; prevents implicit root discovery.",
-    "run": "Exact retained RUN identity; its frozen execution settings remain authoritative.",
-    "reason": "Operator explanation retained with the requested change.",
-    "request-id": "Stable request identity for reconciliation and idempotent retry.",
-    "expected-revision": "Required current revision; stale changes are rejected instead of overwriting concurrent edits.",
-    "profile": "Explicit configured profile identifier; credentials are not stored in profiles.",
-    "profile-file": "Complete validated executor profile; exclusive with --profile and --skip-agent-setup. Does not change operator defaults.",
-    "agent-profile": "Explicit configured executor profile; no automatic model selection.",
-    "force": "Explicit force request; does not bypass ownership, compatibility or authorization gates.",
-    "offline": "Explicit drained/offline operation; does not establish physical settlement by itself."
-};
-/** Option names alone are insufficient when different commands own different inputs. */
-const commandOptionDescriptions = {
-    "profiles create": { file: "Regular UTF-8 JSON file containing one complete validated agent profile. The ID must be unused. Credentials and unknown fields are refused; creation uses --expected-revision and never starts a model Turn." },
-    "profiles edit": { file: "Regular UTF-8 JSON file containing the complete replacement agent profile, not a patch. Its ID must already exist. Revision conflicts refuse the edit; retained RUN snapshots are unchanged." },
-    "profiles alias": {
-        target: "Existing canonical profile ID for the positional alias. Aliases cannot chain or collide with profile IDs. Supply exactly one of --target or --remove, plus --expected-revision.",
-        remove: "Remove the positional alias, not its target profile. Exclusive with --target. The revision-checked change does not rewrite retained RUN settings."
-    },
-    "profiles set-default": { clear: "Clear only the operator global default. Exclusive with a positional profile ID or alias; existing profiles, project routing and frozen RUN settings remain unchanged." },
-    "work add-batch": { file: "Validated Work batch JSON file declaring children of --parent, including their task and dependency inputs. Adding logical Work does not launch physical Sessions." },
-    "schema validate": { file: "JSON document to validate against --schema in the selected schema directory. Validation does not execute a flow or accept semantic completion." },
-    "migration verify": { file: "Existing dd-flow/mb-upgrade-migration-report@1 JSON report to verify against migration evidence; verification does not apply a storage migration." },
-    "migration apply": { file: "Explicit migration report JSON file used for admission to the requested apply operation; backup and ownership gates remain mandatory." },
-    "prompt render": { profile: "Prompt profile name required by the assigned Work execution context; not an operator executor profile ID or a Codex home profile." },
-    "runtime process register": { harness: "Harness family associated with the registered process/budget; registration is not a discovery or doctor probe.", "state-dir": "Adapter runtime state directory retained with the physical process for later ownership/admission checks." },
-    "runtime process admission": { "state-dir": "Exact adapter runtime state directory matching the confirmed process record; mismatched ownership refuses provider admission." },
-    "runtime process release-turn": { "observation-file": "Provider turn release observation file for the selected daemon/operation budget. This is not a model inventory snapshot or account listing." },
-    "runtime scope control": { mode: "Recoverable scope control intent: pause or stop. Drain/settlement remains pending until owned physical evidence is confirmed." },
-    "merge request route": { mode: "Route this MERGE request through same_session or server; selected execution policy and workspace admission still apply." },
-    "worktree close": { mode: "keep retains the feature checkout; remove requests its guarded removal. Dirty or foreign worktrees must not be silently discarded." },
-    "codex home remove": { mode: "keep-shared preserves shared state; remove-owned removes only the verified project-owned home entries.", profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
-    "codex home plan": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
-    "codex home init": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
-    "codex home status": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
-    "codex home print-env": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
-    "codex hooks print": { target: "Hook installation target: isolated (default) or default Codex home. Printing does not install hooks.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
-    "codex hooks status": { target: "Hook installation target: isolated (default) or default Codex home. Status does not install hooks.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
-    "codex hooks install": { target: "Hook installation target: isolated (default) or default Codex home; mutation also requires explicit confirmation.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
-    "codex hooks remove": { target: "Hook installation target: isolated (default) or default Codex home; removal also requires explicit confirmation.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
-    "protocol sync-from-run": { target: "Protocol state target derived from the selected RUN; auto uses the command's supported state mapping." },
-    "run fork": { from: "Existing retained snapshot path to fork into a new RUN with the explicitly selected engine; not a control request identity." },
-    "run control resume": { from: "Exact retained pause/stop control ID whose captured state authorizes this resume request; not a snapshot path." },
-    "stage block": { kind: "Blocker category: engine, harness or environment; code and summary identify the actionable cause." },
-    "migration impact": { mode: "Optional full_migration request forces the strict full-migration assessment; otherwise impact evidence determines patch, targeted_minor or full_migration." },
-    "memory permissions preflight": { mode: "Permission contour to check: read, write, repair or report_only; write checks may create temporary permission probes.", flow: "Workflow permission contour: mb-init, mb-upgrade, mb-audit, mb-fix, mb-upgrade-review or custom. Not a filesystem path." }
-};
-export const globalOptionDocumentation = [
-    { name: "help", description: "Show help before command preparation or resource access; -h is equivalent.", kind: "switch", required: false, repeatable: false, choices: [], physical_path: false },
-    { name: "option", description: "Help-only selector for one option; accepts name or --name.", kind: "value", required: false, repeatable: false, choices: [], physical_path: false },
-    { name: "json", description: "Emit structured JSON rather than human text.", kind: "switch", required: false, repeatable: false, choices: [], physical_path: false },
-    { name: "progress-jsonl", description: "Emit machine-readable progress events during command execution.", kind: "switch", required: false, repeatable: false, choices: [], physical_path: false },
-    { name: "response-file", description: "Execution-only response destination; help never opens or writes it.", kind: "value", required: false, repeatable: false, choices: [], physical_path: true }
-];
-export function optionsForCommand(input, command) {
-    return [...new Set([...input.values, ...input.switches])].map(name => ({
-        name,
-        description: optionDescription(name, command),
-        kind: input.switches.includes(name) ? "switch" : "value",
-        required: input.required.includes(name), repeatable: input.repeatable.includes(name),
-        choices: input.enums[name] ?? [], physical_path: physicalPathOptions.has(name) && name !== "flow" && name !== "stage"
-    }));
-}
-function optionDescription(name, command) {
-    const description = (command ? commandOptionDescriptions[command]?.[name] : undefined) ?? optionDescriptions[name] ?? runtimeOptionDescriptions[name];
-    if (!description)
-        throw new Error(`Missing CLI option documentation: ${command ?? "inventory"} --${name}`);
-    return description;
-}
-/** Shared help/completion option set for a route, family or root catalog. */
-export function optionsForCommandTree(command) {
-    const options = new Map(globalOptionDocumentation.map(option => [option.name, option]));
-    for (const [key, input] of Object.entries(commandInputs)) {
-        if (!command || key === command || key.startsWith(`${command} `)) {
-            for (const option of optionsForCommand(input, key))
-                options.set(option.name, option);
-        }
-    }
-    return [...options.values()].sort((left, right) => left.name.localeCompare(right.name, "en"));
-}
-/** One exact native routing classification shared by router and compatibility admission. */
-export function routerNativeRoute(key) {
-    return key === "version" || key === "run reconcile" || key.startsWith("engine ") || key === "schema validate"
-        || key.startsWith("profiles ") || key.startsWith("models ") || key.startsWith("harnesses ") || key.startsWith("completion ") || key === "setup" || key.startsWith("setup ")
-        || key === "storage migrate-writer" || key === "codex hook handle"
-        || key === "zcode hook handle" || key === "zcode invocation prepare"
-        || /^(zcode|grok|droid|opencode|agy) (event handle|usage ingest)$/.test(key);
-}
-export function commandKeyForPositions(positions) {
-    return Object.keys(commandInputs).filter(key => key.split(" ").every((part, index) => positions[index] === part))
-        .sort((a, b) => b.split(" ").length - a.split(" ").length)[0];
-}
-/** Best matching help topic for rejected argv; never validates or executes it.
- * Option values and literal passthrough cannot impersonate a command path.
- */
-export function commandHelpTopic(args, fallback) {
-    const switches = new Set([...globalOptionDocumentation.filter(option => option.kind === "switch").map(option => option.name),
-        ...Object.values(commandInputs).flatMap(input => input.switches)]);
-    const positions = [];
-    for (let index = 0; index < args.length; index++) {
-        const arg = args[index];
-        if (arg === "--")
-            break;
-        if (arg.startsWith("--")) {
-            const name = arg.slice(2).split("=", 1)[0];
-            if (!arg.includes("=") && !switches.has(name) && args[index + 1] && !args[index + 1].startsWith("-"))
-                index++;
-        }
-        else if (!arg.startsWith("-"))
-            positions.push(arg);
-    }
-    return commandKeyForPositions(positions) ?? fallback;
-}

package/dist/cli/command-option-descriptions.js

@@ -1,186 +0,0 @@
-/** Reviewed meanings for existing runtime options. Grammar owns requiredness,
- * repetition and enumerations; these descriptions do not grant effect authority.
- */
-export const runtimeOptionDescriptions = {
-    "acquire-lock": "Boolean: acquire the workspace lane lock when claiming the next merge job; waiting alone does not grant ownership.",
-    "adapter-executable": "Executable path retained with the registered adapter process for ownership and later reconciliation.",
-    after: "Timeline cursor for controller status; return observations after this sequence number.",
-    alias: "Additional report alias to retain with the completed stage; repeat for multiple aliases.",
-    all: "Refresh dashboards for all selected projects rather than only the current project.",
-    "allow-downgrade": "Explicitly permit lowering flow flags during a revision-checked change; other admission gates still apply.",
-    "answer-file": "File containing the user's answer for the selected paused stage or drive request; not a replacement task or execution policy.",
-    "answer-stdin": "Read the stage answer from standard input instead of --answer-file.",
-    apply: "Apply the proposed project-ID migration; without this switch the command remains a preview.",
-    "available-slots": "Record available native delegation capacity as an integer from 0 through 15; capacity is not proof of child settlement.",
-    backup: "New absolute backup destination for the explicitly drained database; an existing backup is never overwritten.",
-    "backup-created-at": "Timestamp of the retained backup used as migration evidence; must agree with the selected migration inputs.",
-    "backup-path": "Path to the retained backup bound into migration planning, reporting or application evidence.",
-    base: "Git base reference from which the requested feature worktree is created.",
-    bootstrap: "Request the supported initial stage bootstrap rather than starting a stage on an existing RUN; still requires declared intake and admission.",
-    branch: "Git branch assigned to the selected workspace or worker; a branch name does not itself authorize creation or merge.",
-    "budget-json": "Inline JSON declaration of runtime process budget; validated by the process owner before registration.",
-    "cancel-queue": "Boolean: cancel protocol queue entries as part of cancellation; does not silently settle running workers.",
-    candidate: "Mark the created snapshot as a recovery candidate rather than claiming accepted restoration.",
-    "capture-key": "Exact retained capture digest selecting the recovery state for the requested scope generation.",
-    "capture-path": "Destination for the selected RUN recovery capture; capture is distinct from accepting recovery.",
-    "capture-root": "Root directory for controller recovery captures associated with this drive request.",
-    check: "Check identity associated with a registered runtime process, preserving its ownership scope.",
-    "check-ref": "Retained check evidence reference motivating repair Work; repeat to bind multiple checks.",
-    "check-registry": "Include project registry consistency diagnostics in status; does not repair the registry.",
-    "close-sessions": "Boolean: request closing protocol Sessions during cancellation; physical completion requires separate evidence.",
-    code: "Stable diagnostic code for the engine, harness or environment blocker being recorded.",
-    command: "Command to launch as the owned runtime service, with declared ports and readiness checks.",
-    "context-file": "Prepared context file for the selected stage/controller request; its bytes must match --context-sha256.",
-    "context-sha256": "SHA-256 of the exact --context-file bytes, preventing substitution of prepared context.",
-    "control-id": "Retained RUN control request identity used by its owner or reconciliation command.",
-    "controller-id": "Retained drive controller identity; does not create an unrelated controller or bypass ownership.",
-    "daemon-id": "Selected provider daemon identity for scoped admission or recovery; not a request to start an arbitrary daemon.",
-    dashboard: "Dashboard artifact path associated with the completed stage.",
-    data: "Stage data artifact path supplied for validation and completion; its applicable schema is independently selected.",
-    "data-schema-id": "Registered schema identity for the stage data artifact; selecting a schema is not semantic acceptance.",
-    database: "Existing absolute SQLite database path to migrate; the command does not initialize a missing runtime database.",
-    "decision-file": "Retained stage decision artifact required by the selected finish contract.",
-    dir: "Stage artifact directory selected for attachment or lifecycle processing; must satisfy the selected stage's layout contract.",
-    "dispatch-barrier": "Retained dispatch barrier associated with the registered runtime process; not proof of productive admission.",
-    "engine-version": "Exact installed engine version selected for legacy binding recovery or a requested RUN fork.",
-    escalate: "Escalation policy for an owned pause/stop operation; does not authorize stopping unrelated processes.",
-    event: "Hook event name identifying the Codex event being handled; hook payload is validated separately.",
-    evidence: "Evidence reference supporting a completed plan item; repeat to retain multiple references.",
-    "execution-routing-file": "Validated execution routing JSON file used for the selected RUN creation or restoration; retained RUN profiles remain frozen.",
-    file: "JSON input file consumed by this command's declared validator; see the exact command topic for its contract.",
-    flag: "Explicit flow flag assignment for creation or revision; repeat for multiple assignments. Revision and policy gates still apply.",
-    flow: "Memory workflow whose permissions are checked; preflight does not execute that workflow.",
-    "flow-kind": "Flow kind recorded when creating the RUN; a label alone cannot register handlers or admit execution.",
-    format: "Dashboard output format; rendering and opening follow the selected command's supported formats.",
-    from: "Retained source identity for a fork or resume; its meaning is specified by the exact command topic.",
-    "from-check": "Check identity causing the repair Work, preserving traceability to the failed check.",
-    "from-finding": "Review finding identity motivating repair Work; repeat for multiple findings.",
-    "from-unresolved": "Unresolved issue identity motivating repair Work; repeat for multiple issues.",
-    generation: "Exact runtime scope generation; stale generations cannot admit recovery or new dispatch.",
-    global: "Read global dashboard data rather than one project dashboard.",
-    "grace-ms": "Grace period in milliseconds for an owned process or control stop before reconciliation/escalation.",
-    "group-by": "Usage aggregation dimension; grouping does not change source-backed usage evidence.",
-    hide: "Timeline event category to hide from the displayed view; repeat for multiple categories. Retained events are not deleted.",
-    "hook-event-id": "Trusted hook event identity binding this lifecycle invocation to its physical event.",
-    id: "Exact runtime process registry identity targeted by registration, lease operations or admission.",
-    "idempotency-key": "Stable flow-flag revision request key; retry the exact same change rather than applying it twice.",
-    "include-results": "Include retained Work result projections in the listing; listing remains an observation, not acceptance.",
-    incomplete: "Permit creation of an explicitly incomplete recovery snapshot; does not qualify it as a restorable complete snapshot.",
-    "intake-file": "File containing the raw user intake for initial stage bootstrap; do not replace it with an inferred solution.",
-    "intake-stdin": "Read raw bootstrap intake from standard input instead of --intake-file.",
-    "integrity-checksum": "Expected retained engine integrity checksum, checked independently of its version label.",
-    "interruption-json": "Inline JSON interruption evidence opening the selected RUN recovery attempt.",
-    "invocation-id": "Exact retained lifecycle invocation identity; syntax alone does not establish generation, ownership or authorization.",
-    "json-file": "JSON transition payload file; an alternative to the transition payload-file input.",
-    key: "Configuration or RUN variable key selected for reading or writing; supported configuration keys are validated by the owner.",
-    kind: "Classification of the recorded blocker or process; the exact command determines supported kinds.",
-    lane: "Named project workspace lane whose workspace, waiters or lock are being inspected or changed.",
-    "lease-ms": "Runtime process lease duration in milliseconds; renewal requires the current lease token.",
-    "lease-token": "Current owned lease token for the exact process or lane; not an executor credential or an ownership override.",
-    limit: "Maximum number of Work entries returned by the listing; must be a positive integer.",
-    "manifest-json": "Inline runtime-scope manifest declaration binding the selected source manifest and executions; changed declarations refuse.",
-    "max-parallel-projects": "Maximum projects processed concurrently by the merge server; does not widen per-project merge authority.",
-    "memory-bank": "Memory Bank path whose access is checked by permission preflight; no installation or workflow is started.",
-    mode: "Operation mode accepted by this exact command; consult its allowed values and mode-specific effects.",
-    "native-session-id": "Existing physical provider Session identity for scoped recovery/admission; logical Work ancestry is separate.",
-    "next-action": "Explicit next-action projection stored with RUN creation or an operator override; it is not automatic dispatch.",
-    "observations-file": "Bounded observations JSON file for the selected fan-out/native scope; observations must satisfy ownership and settlement contracts.",
-    on: "Dependency Work identity to add or remove; repeat for multiple dependencies. Dependencies are not physical Session parentage.",
-    once: "Process one merge-server iteration instead of polling continuously.",
-    open: "Open the refreshed dashboard after rendering; does not alter RUN control state.",
-    operation: "Named operation associated with a registered process or provider admission request.",
-    "operation-id": "Exact retained provider operation identity bound to turn admission or release.",
-    "operational-decision-file": "Validated operational decision artifact authorizing the applicable snapshot restoration or fork route; not a release or arbitrary mutation permit.",
-    "origin-work": "Origin Work identity motivating repair; repeat to preserve multiple origins.",
-    outcome: "Outcome declared for the selected stage result; finish still validates its contract and evidence before transition.",
-    output: "Destination for a created snapshot, fork artifact or rendered dashboard; see the command's artifact contract.",
-    owner: "Runtime resource owner identity used for registration, admission or reconciliation; ownership is independently checked.",
-    "owner-pid": "Operating-system PID of the registered process owner, used for scoped liveness and reconciliation.",
-    package: "Engine package name used to locate the requested installed snapshot.",
-    parent: "Logical parent Work identity for batch creation or listing; does not make children physical subagents automatically.",
-    path: "Concrete workspace path used by lane, merge or worktree operations; not the stable project identity.",
-    "pause-id": "Exact retained user-interaction pause identity answered by this drive request.",
-    "payload-base64": "Base64-encoded Session registration payload; use only one payload transport.",
-    "payload-file": "File containing the selected transition or Session registration payload; validated before registration or transition.",
-    "payload-json": "Inline JSON Session registration payload; use only one payload transport.",
-    pid: "Operating-system PID of the registered physical process; a PID alone does not prove ownership or completion.",
-    "plan-file": "Previously generated cleanup plan file; application still checks its scope and explicit reason.",
-    "plan-item": "Plan item identity selected for the bounded worker prompt.",
-    "poll-interval": "Polling interval in seconds for lane/merge waiting; must be positive.",
-    "poll-seconds": "Merge server polling interval in seconds; must be positive.",
-    ports: "Comma-separated port declarations for the owned runtime service.",
-    preset: "Named flow-flag preset for creation or revision; explicit flag assignments and policy admission remain separate.",
-    "process-group-id": "Operating-system process-group identity retained for owned-tree cleanup; not a permit to kill unrelated groups.",
-    project: "Project selector for dashboard data, rendering or opening.",
-    "project-id": "Registered project identity associated with the physical runtime process.",
-    "prompt-sha256": "Digest of exact provider prompt bytes associated with operation admission.",
-    protocol: "Protocol selector limiting dashboard output to the requested protocol.",
-    "protocol-id": "Existing protocol identity whose feature worktree is planned, created, inspected or closed.",
-    "protocol-override-file": "Validated protocol override JSON input supplied at RUN creation; does not overwrite an existing frozen RUN.",
-    "question-file": "File containing the user question that pauses this stage/Work under the selected interaction contract.",
-    "question-stdin": "Read the stage question from standard input instead of --question-file.",
-    ready: "List dependency-ready Work entries rather than all entries; readiness does not launch them.",
-    "ready-path": "HTTP path used for the runtime service readiness check.",
-    "ready-port": "Declared service port used for the runtime readiness check.",
-    "ready-timeout-ms": "Maximum service readiness wait in milliseconds; must be a positive integer.",
-    "reason-file": "File containing the reason artifact required by the selected lifecycle finish contract.",
-    "recovery-id": "Exact retained RUN recovery attempt identity; recovery acceptance and physical settlement remain separate gates.",
-    "release-locks": "Boolean: request protocol lock release during cancellation; ownership checks still apply.",
-    report: "Report artifact path associated with the completed stage.",
-    request: "Retained request reference supplied to the selected stage finish contract; not a new setup request ID.",
-    requeue: "Boolean: put the failed merge job or bundle back in the queue; a failure is not converted into accepted merge evidence.",
-    "require-session-binding": "Require trusted physical Session binding before starting the stage; do not synthesize one from a RUN ID.",
-    "result-file": "Validated result JSON artifact for this stage or Work; process exit success is not a substitute for accepted result evidence.",
-    "result-stdin": "Read result JSON from standard input instead of --result-file.",
-    "retry-check": "Check identity requested for the selected bounded retry path; prior results cannot be reused without matching evidence.",
-    retryable: "Mark the recorded blocker as retryable; does not launch a retry or bypass the blocker.",
-    role: "Role metadata retained with the registered runtime process.",
-    schema: "Registered JSON schema name against which the supplied file is validated.",
-    "schema-dir": "Explicit schema directory for validation; not a workflow handler registry or permission to execute code.",
-    "scope-id": "Exact retained runtime/EVAL scope identity; operations must not affect neighboring scopes.",
-    "semantic-file": "Stage semantic result artifact; applicable schema and finish checks are selected independently.",
-    session: "Physical Session selector for source-backed usage aggregation.",
-    "session-id": "Exact retained physical Session identity for registration, status, stop or usage synchronization.",
-    "settlement-json": "Inline JSON physical settlement evidence sealing a recovery attempt; logical inactivity alone is insufficient.",
-    slug: "Safe human-readable slug used for the new typed identifier or RUN.",
-    snapshot: "Existing snapshot artifact selected for bootstrap or RUN restoration; restored execution requires independent admission.",
-    "source-home": "Source Codex home used to plan or initialize the isolated project home; credentials remain operator-owned.",
-    "source-version": "Source Memory Bank version whose migration impact and evidence are being assessed.",
-    stage: "Stage identity within the selected flow/RUN; a name alone cannot admit a foreign stage.",
-    "stage-entry": "Stage entry selected for snapshot capture.",
-    "stage-report": "Stage report artifact path supplied for completion and retained observation.",
-    state: "Terminal state reported for the owned runtime process; supported values are shown below.",
-    status: "Work filter or declared stage/RUN state, depending on the exact command; lifecycle admission remains authoritative.",
-    stderr: "Retained standard-error log path associated with the registered process.",
-    stdout: "Retained standard-output log path associated with the registered process.",
-    "stop-after": "Stage boundary at which the drive controller should stop advancing; not proof of physical child settlement.",
-    subject: "Safe subject text for the bootstrap RUN; raw user intake is supplied separately.",
-    "subject-id": "Identity of the protocol or other subject associated with the new RUN.",
-    "subject-type": "Type of subject associated with RUN creation; it does not select an executor.",
-    summary: "Human summary retained with plan-item or merge completion/note evidence.",
-    "summary-file": "File containing the diagnostic summary for a stage blocker.",
-    "summary-stdin": "Read the blocker summary from standard input instead of --summary-file.",
-    target: "Destination selector for protocol synchronization or hook management; see the exact command topic.",
-    "target-home": "Destination isolated Codex home used by the project home plan/init operation.",
-    "target-version": "Target Memory Bank version selected for migration impact, planning or application.",
-    "task-file": "Bounded worker task artifact used for prompt rendering or repair Work creation.",
-    "task-profile-file": "Validated task-profile JSON input used when freezing a new RUN's task policy.",
-    "task-stdin": "Read repair task content from standard input instead of --task-file.",
-    tasks: "Task directory whose access is checked by Memory Bank permission preflight.",
-    timeout: "Maximum lane/merge waiting duration in seconds; not a provider model timeout.",
-    to: "Requested protocol lifecycle target; transition requirements are validated before changing state.",
-    ttl: "Lane lease lifetime in seconds; expiry does not by itself prove physical process settlement.",
-    type: "Typed identifier family whose next identifier is being previewed.",
-    "user-required": "Boolean indicating that the blocked plan item requires a user decision.",
-    value: "Configuration or RUN variable value to store under --key; configuration-specific validation still applies.",
-    verdict: "Operator override verdict projection; cannot turn an override into ordinary semantic acceptance.",
-    "verification-file": "Verification evidence artifact required by the selected stage finish or repair provenance contract.",
-    version: "Exact engine package version to inspect; omitted selection follows the engine-info command's existing resolver.",
-    viewer: "Viewer requested for opening the rendered dashboard.",
-    "wait-ms": "Maximum observation wait in milliseconds for the requested RUN control operation; timeout is not terminal settlement.",
-    work: "Exact Work identity within the selected RUN/stage or associated with a registered process/merge request.",
-    "worker-id": "Worker identity bound to the selected Session, lane lease or merge claim; not a model/profile selector.",
-    worktree: "Worktree handling policy requested during protocol cancellation; project ownership and cleanup guards still apply.",
-    write: "Boolean: publish the project summary instead of only returning its current projection.",
-    yes: "Explicit confirmation for hook installation/removal; does not bypass project access or target validation."
-};