@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.160

package/README.md

@@ -1,5 +1,71 @@
 # dd-flow-cli
 
+See [dd-zcode integration](src/harness-runtime/DD-ZCODE.md) for native transport,
+adapter ownership and the versioned bridge contract.
+
+## OpenCode v2
+
+`dd-opencode` supports OpenCode v2 only; the final v1 source is tagged
+`archive/opencode-v1-final-beta134`. Client/plugin build inputs are pinned to
+2.0.28; build copies the unmodified self-contained upstream Promise assets.
+Optional AI/Effect/TUI dependency graphs are not production engine dependencies.
+Select the native executable with `--opencode-bin`, portable JSON/JSONC provider
+config with `--config-path` and selected credentials with `--auth-path` (legacy
+provider auth map or native v2 credential-list JSON). Credentials are loaded and
+verified in the owned private DB, never copied from the user's Session DB.
+
+The adapter owns an unregistered loopback `serve` instance, private XDG paths,
+DB and launch-bound dd-flow plugin. It does not install a global user plugin or
+load third-party plugins. `doctor` checks the native instance and productive
+plugin separately from model qualification. No-flow probes load only the owned
+secret-stripping security definition, without lifecycle admission. V1 states/archives are rejected
+without migration; use a fresh v2 state directory.
+
+Prompt acknowledgement means inbox admission, not success. Lost replies are
+reconciled read-only against the same message ID; `session resume` never wakes
+execution. Native projected user/idle records prove delivery/outcome because
+CLI v2 does not persist full event payloads by default. Model/tool deltas and
+new owned shell output sustain the shared sliding observer. Proven terminal
+overload uses the shared continuation policy; quota/auth and unknown effects
+do not authorize a prompt replay. `session fork --message-id` means **before**
+that message, recorded in the native boundary receipt.
+
+Technical native probes use a local stub, not scored EVALs:
+`DD_TEST_OPENCODE_V2=<absolute-v2-binary> node --test test/fixtures/opencode-v2-native.mjs test/fixtures/opencode-v2-plugin-native.mjs`.
+Add `DD_TEST_OPENCODE_LONG=1` to prove shell progress beyond the old 120s cutoff.
+
+## Native daemon shutdown
+
+Managed native shells use the launch-bound `DD_FLOW_DAEMON_ID`, `DD_FLOW_HOME`,
+`DD_FLOW_BIN` and resource path. Inherited invocation/control authority is
+cleared; security-only launches do not borrow a previous RUN's identity.
+Compact lifecycle commands resolve private arguments from the issued assignment
+and its native receipt, not from a model-supplied ID or the latest matching row.
+A lost managed binding is a tooling failure, not permission to replay a short
+command. Corrective retries are scoped to the action, Session and Stage attempt;
+exact native event re-delivery returns the retained outcome.
+
+`daemon.stop` fences productive dispatch before awaiting settlement. A successful
+durable stop receipt follows native tree settlement, physical provider exit,
+journal drain and required resource/auth finalization. The endpoint then retires
+before ACK; clients also verify the retained daemon PID has exited. A missing
+socket alone is not physical shutdown proof.
+
+Partial cleanup preserves the same incarnation's completed phases in
+`daemon.json` (`dd-flow/daemon-shutdown@1`). A fresh control operation can finish
+remaining cleanup without replaying agent work or inspecting a closed pipe.
+Failed operation IDs remain immutable. Unknown ownership and persistent EPERM
+remain failures; never remove sockets or repair runtime databases manually to
+make an outcome look clean.
+
+Shutdown proof records `required_phases`; every recorded phase must be complete,
+including native tree and daemon resource settlement. A `clean` label without
+this proof cannot authorize retained restart. `stopping`, `cleanup_failed` and
+`unclean` cannot start a replacement native bridge. Forced AGY termination
+without a current native terminal receipt is unclean, even after a previous
+successful Turn. Mandatory stream-journal failures remain failures after
+physical cleanup. Listener retirement must not unlink a replacement endpoint.
+
 ## Managed temporary HTTP services
 
 For an interactive scenario, `runtime process start --run <RUN-ID>
@@ -17,6 +83,36 @@ Never use a broad `pkill`/`killall`. A failed owned stop retains resources.
 
 It does not replace Memory Bank prompts and does not make product, design, merge, or verification judgments. Prompts own intent, route selection, planning depth, evidence meaning, and semantic readiness. The CLI owns explicit local state: projects, protocols, Codex session bindings, transitions, worktree records, lanes, locks, merge queue jobs, hook records, and audit events.
 
+## Factory Droid harness
+
+Configure `droid-cli` in `~/.dd-flow/harnesses.json` with absolute
+`adapter_command` (`dd-droid`) and `runtime_command` (`droid`) paths. Agent
+profiles use the `droid` alias; the adapter receives `--droid-bin`.
+
+The controlled adapter sends `dd-flow/droid-tool-event@1` JSON to
+`dd-flow droid event handle --project-root <root> --json`. Events include a
+stable `event_id`, `daemon_id`, `phase` (`before` or `after`), native Session
+identity and parent, absolute Session directory, `Execute` input, observed
+profile and transcript path. Before a lifecycle invocation, the returned
+`hookSpecificOutput.updatedInput` adds its one-use `--hook-event-id` receipt.
+The event ID belongs to the native hook invocation and is reused only for
+transport retries. Session success is established by the Work contract.
+
+`dd-flow droid usage ingest --project-root <root> --json` accepts cumulative
+per-Session counters with explicit `usage_scope: physical_session` and
+`completeness: complete|partial`. Inclusive root counters are rejected;
+partial windows remain unavailable in RUN totals until complete evidence
+arrives. Keep inclusive provider totals in adapter evidence for reconciliation.
+
+## Check evidence
+
+Checks write evidence into their invocation's `DD_FLOW_EVIDENCE_DIR`. Receipts
+retain and hash every regular file in that directory, including nested files.
+`required_artifacts` specifies the minimum files needed to pass, so an empty
+list still permits supplemental screenshots or reports. Missing required files
+fail the check. Symlinks are not followed or registered. The same collection
+rules apply when recovering a detached check from its completion marker.
+
 ## Runtime Model
 
 Root local database:
@@ -65,6 +161,8 @@ dd-flow canon status --json
 
 `canon resolve` checks explicit `--root`, then `DD_MEMORYBANK`, then the globally registered value in `DD_FLOW_HOME`, then known nearby `dd-memorybank` checkouts from the current working directory. If two different valid canonical roots are discovered, it fails closed with structured blockers and bootstrap hints. Use `DD_MEMORYBANK` for the local canonical `dd-memorybank` checkout.
 
+With no explicit, environment or registered source, the release installed by `setup` in `DD_FLOW_HOME` takes precedence over nearby checkouts. Archive provenance comes from its retained release manifest. A degraded installation does not silently fall back to a local checkout. Discovery remains read-only and does not open SQLite before runtime context admission.
+
 Register a project:
 
 ```bash
@@ -412,13 +510,44 @@ remain invalid and receive a standalone retry.
 
 ## Verification
 
-Local verification for this repository:
-
-```bash
-pnpm test
-pnpm typecheck
-pnpm lint
-pnpm build
-```
-
-Manual smoke checks should use a temporary `DD_FLOW_HOME` when they do not intentionally inspect the operator's real local state.
+Checks follow changed contracts, not a merge/release/EVAL event. Inspect
+`pnpm verify:plan`, then run `pnpm test` (or `pnpm gate:merge`) for only missing
+affected contracts. `scripts/verification-policy.mjs` owns impact selection;
+existing Node/Vitest runners retain complete selected-file/case evidence.
+Unknown impact requires an explicit policy mapping, never a full-suite fallback.
+
+There is no mandatory full release gate. Freeze source/canon, build and pack the
+exact artifact, then accept with `DD_FLOW_VERIFICATION_RECEIPT` pointing to the
+scoped verification receipt. Preserve receipts outside the checkout. Unchanged
+contract inputs reuse intact reports; commit/version/build time alone do not
+invalidate behavior evidence. Failed/unknown attempts require investigation,
+not automatic retries. Package identity and registry readback remain mandatory.
+GitHub CI is disabled. Publication does not repeat the accepted package's smoke
+after identical registry tar readback. EVAL preparation is resource readiness,
+not another engine or product test suite.
+The [verification runbook](https://github.com/deksden-com/dd-eval/blob/main/runbooks/flow-test-suite-verification.md)
+owns the local procedure. A scoped PASS is not a claim that every test ran.
+
+### RUN status during recovery
+
+A controller failure pauses the logical RUN without rewriting its Stage/Work
+outcomes. Accepted pause/stop or recovery intent immediately persists `paused` in the RUN row,
+`index_json`, and `run.json`. A trusted recovery acknowledgement restores the
+operational status; an existing Stage/Work pause remains paused. Terminal RUNs
+are never reopened. Physical tree settlement remains a separate control receipt.
+
+Legacy stores with a fenced recovery may still contain `running`. After building,
+inspect one exact RUN with:
+
+```sh
+node tools/repair-paused-run-status.mjs --home /path/to/dd-flow-home --project PRJ-001-project --run RUN-001-eval-subject
+```
+
+Add `--apply` to repair it. This requires the latest recovery to be draining, sealed or resuming, saves the original row and runtime JSON
+beside `run.json`, and changes no schema, engine binding or recovery capture.
+It does not claim physical settlement or alter its receipts. `--cancel-abandoned`
+explicitly cancels an abandoned fixture only when the project directory is absent
+and it has no Work, Session, controller or recovery history. Historical experiment
+engine snapshots remain pinned; rebuild/release the engine for future executions.
+
+`dd-flow run reconcile [RUN] --json` проверяет сохранённые статусы без dispatch; `--apply` сохраняет согласованную health-проекцию. Возраст записи даёт предупреждение, а не доказательство ошибки. Ожидания и потеря владельца различаются; обслуживание не сигналит процессам и не перехватывает leases.

package/dist/build-info.json

@@ -1,15 +1,15 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.16",
-  "cli_commit": "8de503c90a952a8b56300a0c0367dd89be5c2436",
-  "built_at": "2026-09-05T22:05:40.605Z",
+  "cli_version": "0.9.0-beta.160",
+  "cli_commit": "3d065fa9b570fdb25570e4c47d7c99a5d50d5574",
+  "built_at": "2026-10-29T15:12:42.101Z",
   "built_with_canon": {
-    "version": "4.0.4",
-    "commit": "8e572d151c7f9d22c2b60122c87d9febcbfbde69",
+    "version": "4.1.4",
+    "commit": "7cc415b3ef3ce37c9624c7cee51023e66f67cd57",
     "flow_contract": "dd-flow-canonical-2026-08",
-    "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
-    "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",
-    "flow_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank/dd-flow",
+    "repo_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-canon-cp263",
+    "memorybank_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-canon-cp263/.memory-bank",
+    "flow_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-canon-cp263/.memory-bank/dd-flow",
     "layout": "dot_memory_bank"
   }
 }

package/dist/cli/argument-values.js

@@ -0,0 +1,38 @@
+import { AppError } from "../shared/errors.js";
+const flagValue = "__dd_flow_flag__";
+export function optionalOption(parsed, key) {
+    const values = parsed.options.get(key);
+    const value = values?.[values.length - 1];
+    if (value === flagValue)
+        throw new AppError("usage", `--${key} requires a value`, 2, { parameter: key, reason: "missing_option_value" });
+    if (value !== undefined && !value.trim())
+        throw new AppError("usage", `--${key} requires a non-empty value`, 2, { parameter: key, reason: "empty_option_value" });
+    return value;
+}
+export function requiredOption(parsed, key) {
+    const value = optionalOption(parsed, key);
+    if (!value) {
+        throw new AppError("usage", `Missing required option: --${key}`, 2, { parameter: key, reason: "missing_required_option" });
+    }
+    return value;
+}
+export function optionalNumber(parsed, key) {
+    const value = optionalOption(parsed, key);
+    if (typeof value === "undefined") {
+        return undefined;
+    }
+    const parsedNumber = Number(value);
+    if (!Number.isFinite(parsedNumber)) {
+        throw new AppError("validation", `--${key} must be a number`, 2, { parameter: key, reason: "invalid_number" });
+    }
+    return parsedNumber;
+}
+export function optionalPositiveNumber(parsed, key, integer = false) {
+    const value = optionalNumber(parsed, key);
+    if (typeof value === "undefined")
+        return undefined;
+    if (value <= 0 || (integer && !Number.isInteger(value))) {
+        throw new AppError("validation", `--${key} must be a positive${integer ? " integer" : ""} number`, 2, { parameter: key, reason: "invalid_number" });
+    }
+    return value;
+}