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

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

@@ -0,0 +1,191 @@
+/** 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.",
+    "max-parallel": "Freeze the Work concurrency limit (external integer 1..256; explicit native 1..15). Omit on replay to retain the original selection; native capacity requires an authorized technical probe and never overrides runtime budgets or Work dependencies.",
+    "delegation": "Select external Work sessions (default) or explicit native children. Native fresh init requires --allow-live-probe; it cannot switch worker profiles.",
+    "allow-live-probe": "Authorize this request's bounded technical native child probe outside the RUN. It can incur provider usage; unknown effects retain exact operation custody and never restart fan-out.",
+    "native-config-home": "Optional absolute provider configuration home for native qualification. Otherwise preserve normal harness authentication and configuration. The CLI never copies or links credentials or rewrites operator configuration.",
+    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.",
+    "registration-sha256": "Exact managed-process registration binding returned by confirmation or renewal. Pins the resource Home and registered owner/PID identity; a changed registration refuses rather than matching a reused process ID.",
+    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."
+};

package/dist/cli/completion-cli.js

@@ -0,0 +1,70 @@
+import { completionCandidates } from "./completion.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { writePreparationError } from "./error-output.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+export function completionScript(shell) {
+    if (shell === "bash")
+        return `# dd-flow completion: bash
+_dd_flow_complete() {
+  local candidate
+  COMPREPLY=()
+  while IFS= read -r candidate; do
+    [ -n "$candidate" ] && COMPREPLY+=("$candidate")
+  done < <("${"$"}{COMP_WORDS[0]}" completion candidates -- "${"$"}{COMP_WORDS[@]:1:COMP_CWORD}")
+}
+complete -o default -F _dd_flow_complete dd-flow
+`;
+    if (shell === "zsh")
+        return `#compdef dd-flow
+_dd_flow_complete() {
+  local -a replies
+  replies=("${"$"}{(@f)$("${"$"}{words[1]}" completion candidates -- "${"$"}{(@)words[2,CURRENT]}")}")
+  if (( ${"$"}{#replies} )) && [[ -n "$replies[1]" ]]; then
+    compadd -a replies
+  else
+    _files
+  fi
+}
+compdef _dd_flow_complete dd-flow
+`;
+    if (shell === "fish")
+        return `function __dd_flow_candidates
+  set -l tokens (commandline -opc)
+  set -l prefix (commandline -ct)
+  set -l arguments
+  if test (count $tokens) -gt 1
+    set arguments $tokens[2..-1]
+  end
+  $tokens[1] completion candidates -- $arguments "$prefix"
+end
+complete -c dd-flow -a '(__dd_flow_candidates)'
+`;
+    throw new AppError("usage", "Supported completion shells: bash, zsh, fish", 2, { effect: "no_effect" });
+}
+/** Completion is grammar-only: never constructs an AppContext or writes a home. */
+export function runCompletionCli(args, io = { stdout: process.stdout, stderr: process.stderr }) {
+    let json = false;
+    try {
+        const output = parseOutputOptions(args);
+        json = output.json;
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const route = prepareCommandRoute(output.args);
+        if (route.key === "completion candidates") {
+            const candidates = completionCandidates(route.parsed.positional);
+            io.stdout.write(json ? `${JSON.stringify(writeResponseFile({ candidates }, output))}\n` : candidates.map(value => `${value}\n`).join(""));
+        }
+        else {
+            const script = completionScript(route.command);
+            io.stdout.write(json ? `${JSON.stringify(writeResponseFile({ shell: route.command, script }, output))}\n` : script);
+        }
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/completion.js

@@ -0,0 +1,57 @@
+import { commandInputs } from "./command-inputs.js";
+import { globalOptionDocumentation, optionsForCommandTree } from "./command-metadata.js";
+const globalSwitches = globalOptionDocumentation.filter(option => option.kind === "switch").map(option => `--${option.name}`);
+const globalValues = globalOptionDocumentation.filter(option => option.kind === "value").map(option => `--${option.name}`);
+/** Read-only completion grammar. Last word is the cursor's unfinished token. */
+export function completionCandidates(words) {
+    const prefix = words.at(-1) ?? "";
+    const completed = words.slice(0, -1);
+    if (completed.includes("--"))
+        return [];
+    const positions = [];
+    let awaiting;
+    let routeKey;
+    const keys = Object.keys(commandInputs).filter(key => !commandInputs[key].retired);
+    const select = () => keys.filter(key => key.split(" ").every((part, index) => positions[index] === part))
+        .sort((left, right) => right.split(" ").length - left.split(" ").length)[0];
+    for (const word of completed) {
+        if (awaiting) {
+            awaiting = undefined;
+            continue;
+        }
+        if (word.startsWith("--")) {
+            const name = word.slice(2).split("=")[0];
+            const input = routeKey ? commandInputs[routeKey] : undefined;
+            const values = input?.values ?? [...new Set(Object.values(commandInputs).flatMap(item => item.values))];
+            if (!word.includes("=") && (values.includes(name) || globalValues.includes(`--${name}`)))
+                awaiting = name;
+            continue;
+        }
+        if (word === "-h")
+            continue;
+        positions.push(word);
+        routeKey = select();
+    }
+    const input = routeKey ? commandInputs[routeKey] : undefined;
+    let candidates;
+    const inline = prefix.match(/^--([^=]+)=(.*)$/);
+    if (awaiting || inline) {
+        const option = awaiting ?? inline[1];
+        candidates = option === "option" ? optionsForCommandTree(routeKey ?? positions.join(" ")).map(item => item.name)
+            : [...(input?.enums[option] ?? [])];
+        if (option === "option" && (inline?.[2] ?? prefix).startsWith("--"))
+            candidates = candidates.map(name => `--${name}`);
+        if (inline)
+            return candidates.filter(value => value.startsWith(inline[2])).map(value => `--${option}=${value}`).sort();
+    }
+    else if (prefix.startsWith("-")) {
+        candidates = [...globalSwitches, ...globalValues, ...(input ? [...input.values, ...input.switches].map(name => `--${name}`) : [])];
+    }
+    else {
+        candidates = keys.filter(key => {
+            const tokens = key.split(" ");
+            return positions.every((part, index) => tokens[index] === part) && tokens.length > positions.length;
+        }).map(key => key.split(" ")[positions.length]);
+    }
+    return [...new Set(candidates)].filter(value => value.startsWith(prefix)).sort();
+}

package/dist/cli/error-output.js

@@ -0,0 +1,52 @@
+import { hasHelpIntent } from "./help.js";
+import { commandHelpTopic } from "./command-metadata.js";
+import { writeJson } from "../shared/json.js";
+export function writePreparationError(io, args, error) {
+    const literal = args.indexOf("--");
+    const options = literal < 0 ? args : args.slice(0, literal);
+    const payload = { ok: false, error };
+    const help = hasHelpIntent(args);
+    let json = false;
+    for (let index = 0; index < options.length; index++) {
+        if (help && options[index] === "--option") {
+            index++;
+            continue;
+        }
+        if (options[index] === "--json")
+            json = true;
+    }
+    // Retain the hook's machine-only contract even when transport validation fails.
+    if (json || args.slice(0, 3).join(" ") === "codex hook handle")
+        writeJson(io.stderr, payload);
+    else
+        io.stderr.write(renderHumanError(payload, args));
+}
+export function renderHumanError(payload, args) {
+    const lines = [`dd-flow: ${payload.error.message}`];
+    const details = recordObject(payload.error.details);
+    const compatibility = recordObject(details?.compatibility);
+    const remediation = recordObject(details?.remediation);
+    if (compatibility) {
+        lines.push(`Compatibility: ${String(compatibility.verdict ?? "unknown")} (${String(compatibility.engine_resolution ?? "unknown")})`);
+        if (compatibility.blocked_operation)
+            lines.push(`Blocked operation: ${String(compatibility.blocked_operation)}`);
+        if (compatibility.install_hint)
+            lines.push(`Install compatible engine: ${String(compatibility.install_hint)}`);
+    }
+    if (remediation?.mb_upgrade_mode)
+        lines.push(`Upgrade mode: ${String(remediation.mb_upgrade_mode)}`);
+    if (details?.preferred_command)
+        lines.push(`Preferred command: ${String(details.preferred_command)}`);
+    const related = Array.isArray(details?.related_commands) ? details.related_commands.map(String) : [];
+    if (related.length > 0) {
+        lines.push("", "Related commands:");
+        for (const command of related)
+            lines.push(`  ${command}`);
+    }
+    const topic = commandHelpTopic(args, "");
+    lines.push(`See: dd-flow${topic ? ` ${topic}` : ""} --help`);
+    return `${lines.join("\n")}\n`;
+}
+function recordObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}

package/dist/cli/executor-onboarding.js

@@ -0,0 +1,76 @@
+import { createInterface } from "node:readline";
+import { AppError } from "../shared/errors.js";
+import { prepareOperatorProfile, prepareProfileCreation, readOperatorProfileInput } from "../services/operator-profiles.js";
+/** One explicit choice; prompts go to stderr so stdout remains machine-readable. */
+export async function askExecutorChoice(settings, io, policy = {}) {
+    const ids = settings.profiles.map(entry => entry.id);
+    io.stderr.write(`Executor profiles: ${ids.length ? ids.join(", ") : "none configured"}\n`);
+    io.stderr.write(`Choose a profile ID/alias, file:/absolute/profile.json, create${policy.allowSkip === false ? "" : ", or skip"}. No model is selected automatically.\n`);
+    const terminal = createInterface({ input: io.stdin, output: io.stderr });
+    const lines = terminal[Symbol.asyncIterator]();
+    const cancelled = () => new AppError("onboarding_cancelled", "Executor onboarding was cancelled", 1, { effect: "no_effect" });
+    terminal.on("SIGINT", () => terminal.close());
+    const ask = async (prompt) => {
+        io.stderr.write(prompt);
+        const line = await lines.next();
+        if (line.done)
+            throw cancelled();
+        const answer = line.value.trim();
+        if (answer.length > 4096)
+            throw new AppError("usage", "Executor choice exceeds the input limit", 2, { effect: "no_effect" });
+        return answer;
+    };
+    try {
+        const answer = await ask("Executor: ");
+        if (answer === "skip") {
+            if (policy.allowSkip === false)
+                throw new AppError("agent_profile_missing", "This flow requires an executor profile", 1, { effect: "no_effect" });
+            return { skip: true };
+        }
+        if (answer === "create") {
+            io.stderr.write("Enter explicit profile settings; this does not probe providers or verify model access. Nothing is saved by this dialog.\n");
+            const input = { schema_id: "dd-flow/agent-profile@1" };
+            for (const [key, prompt] of [
+                ["id", "Profile ID: "], ["harness", "Harness (codex/zcode/agy/opencode/grok/droid): "],
+                ["provider", "Provider ID: "], ["model", "Model ID: "], ["reasoning", "Reasoning setting: "],
+                ["mode", "Mode setting: "], ["permission", "Permission (allow/deny): "]
+            ])
+                input[key] = await ask(prompt);
+            const profile = prepareOperatorProfile(input);
+            if (settings.profiles.some(entry => entry.id === profile.id) || Object.hasOwn(settings.aliases, profile.id)) {
+                throw new AppError("profile_id_conflict", "New profile ID collides with an existing profile or alias", 2, { effect: "no_effect" });
+            }
+            if (await ask("Use this profile for this operation? Type yes: ") !== "yes")
+                throw cancelled();
+            if (policy.allowSave === false)
+                return { profile };
+            const save = await ask("Save this profile globally during installation? Type yes or no: ");
+            if (save !== "yes" && save !== "no")
+                throw cancelled();
+            if (save === "yes") {
+                const defaultChoice = await ask("Set it as global default? Type yes or no: ");
+                if (defaultChoice !== "yes" && defaultChoice !== "no")
+                    throw cancelled();
+                return { profile, profileCreation: prepareProfileCreation(settings, profile, defaultChoice === "yes") };
+            }
+            return { profile };
+        }
+        if (answer.startsWith("file:")) {
+            const file = answer.slice(5);
+            if (!file.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(file))
+                throw new AppError("usage", "Profile file must be an absolute path", 2, { effect: "no_effect" });
+            return { profile: readOperatorProfileInput(file) };
+        }
+        if (!answer)
+            throw new AppError("agent_profile_missing", "An explicit executor choice is required", 1, { effect: "no_effect" });
+        return { profileId: answer };
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        throw cancelled();
+    }
+    finally {
+        terminal.close();
+    }
+}

package/dist/cli/flows.js

@@ -0,0 +1,29 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { listBundledFlows, showBundledFlow } from "../services/flow-catalog.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { writePreparationError } from "./error-output.js";
+/** Catalog inspection never creates an AppContext or executes a flow. */
+export function runFlowCatalogCli(args, io = process) {
+    try {
+        const output = parseOutputOptions(args);
+        const route = prepareCommandRoute(output.args);
+        let result;
+        if (route.key === "flow list")
+            result = { flows: listBundledFlows() };
+        else if (route.key === "flow show")
+            result = { flow: showBundledFlow(route.parsed.positional[0]) };
+        else
+            throw new AppError("usage", "Use dd-flow flow list or flow show <id>", 2, { effect: "no_effect" });
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        io.stdout.write(`${JSON.stringify(writeResponseFile({ ok: true, action: route.key.replaceAll(" ", "_"), ...result }, output), null, output.json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/harnesses.js

@@ -0,0 +1,84 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { writePreparationError } from "./error-output.js";
+import { parseOutputOptions } from "./output-options.js";
+import { optionalOption, optionalPositiveNumber } from "./argument-values.js";
+import { discoverHarnesses, harnessCatalog } from "../services/harness-discovery.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { probeHarnessVersion } from "../services/harness-version-probe.js";
+import { probeHarnessDoctor } from "../services/harness-doctor.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import path from "node:path";
+import { validateModelScope } from "../services/model-discovery.js";
+/** Home-free ingress: process diagnostics require explicit effect admission. */
+export async function runHarnessesCli(args, env, io = { stdout: process.stdout, stderr: process.stderr }) {
+    let json = false;
+    try {
+        const output = parseOutputOptions(args);
+        json = output.json;
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const route = prepareCommandRoute(output.args);
+        const family = route.key === "harnesses show" ? route.parsed.positional[0] : optionalOption(route.parsed, "harness");
+        if (family && !harnessCatalog.entries.some(entry => entry.id === family))
+            throw new AppError("usage", "Unknown harness; see dd-flow harnesses --help", 2, { effect: "no_effect" });
+        const provider = optionalOption(route.parsed, "provider"), account = optionalOption(route.parsed, "account-sha256");
+        const observationFile = optionalOption(route.parsed, "model-observation-file");
+        let modelScope;
+        if (provider !== undefined || account !== undefined || observationFile !== undefined) {
+            if (!provider || !account)
+                throw new AppError("usage", "Doctor model observations require both --provider and --account-sha256", 2, { effect: "no_effect", help: "harnesses doctor" });
+            modelScope = { harness: family, provider, account_sha256: account };
+            validateModelScope(modelScope);
+            if (observationFile) {
+                if (output.responseFile && path.resolve(observationFile) === path.resolve(output.responseFile))
+                    throw new AppError("usage", "Model observation and command response destinations must differ", 2, { effect: "no_effect" });
+                prepareResponseDestination(observationFile);
+            }
+        }
+        const discovery = discoverHarnesses({ env, ...(family ? { harness: family } : {}),
+            ...(optionalOption(route.parsed, "executable") ? { executable: optionalOption(route.parsed, "executable") } : {}) });
+        let probe;
+        let modelObservation;
+        let observationPublication;
+        if (route.key === "harnesses doctor") {
+            const selected = discovery.entries[0]?.candidates.find(candidate => candidate.selected);
+            if (!selected)
+                throw new AppError("harness_selection_required", "Doctor requires one installed executable; use --executable for ambiguous installations", 1, { effect: "no_effect" });
+            const stateDir = optionalOption(route.parsed, "state-dir"), nativeExecutable = optionalOption(route.parsed, "native-executable");
+            const timeoutMs = optionalPositiveNumber(route.parsed, "timeout-ms", true);
+            probe = await probeHarnessDoctor({ harness: family, executable: selected.path, env,
+                ...(stateDir !== undefined ? { stateDir } : {}), ...(nativeExecutable !== undefined ? { nativeExecutable } : {}),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                scope: { processes: route.parsed.options.has("allow-processes"), services: route.parsed.options.has("allow-services"),
+                    credentials: route.parsed.options.has("allow-credentials"), writes: route.parsed.options.has("allow-writes") } });
+            if (modelScope) {
+                modelObservation = { scope: modelScope, observed_at: new Date().toISOString(),
+                    status: probe.reported_models.length ? "listed" : "unavailable", complete: false, models: [...probe.reported_models] };
+                if (observationFile) {
+                    const published = writeResponseFile(modelObservation, { responseFile: observationFile });
+                    observationPublication = { path: observationFile, status: published.response_file_error ? "unknown" : "published",
+                        ...(published.response_file_error ? { error: published.response_file_error } : {}) };
+                }
+            }
+        }
+        else if (route.key === "harnesses probe-version") {
+            const selected = discovery.entries[0]?.candidates.find(candidate => candidate.selected);
+            if (!selected)
+                throw new AppError("harness_selection_required", "Version probe requires one installed executable; use --executable for ambiguous installations", 1, { effect: "no_effect" });
+            probe = await probeHarnessVersion({ harness: family, executable: selected.path, env,
+                ...(optionalPositiveNumber(route.parsed, "timeout-ms", true) === undefined ? {} : { timeoutMs: optionalPositiveNumber(route.parsed, "timeout-ms", true) }),
+                scope: { processes: route.parsed.options.has("allow-processes"), services: false,
+                    credentials: route.parsed.options.has("allow-credentials"), writes: route.parsed.options.has("allow-writes") } });
+        }
+        const result = { ok: true, action: route.key.replaceAll(" ", "_"), catalog: harnessCatalog, discovery, ...(probe ? { probe } : {}),
+            ...(modelObservation ? { model_observation: modelObservation, observation_scope_binding: "operator_declared_unverified" } : {}),
+            ...(observationPublication ? { model_observation_publication: observationPublication } : {}) };
+        io.stdout.write(`${JSON.stringify(writeResponseFile(result, output), null, json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}