@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.151

package/dist/cli/memory-storage-qualification.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Writable } from "node:stream";
+import { DatabaseSync } from "node:sqlite";
+import { getDatabase, getResourceDatabase } from "../storage/database.js";
+import { canonicalPath } from "../storage/paths.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { runMemoryStorageAdmissionCli } from "./memory-storage-admission.js";
+import { writePreparationError } from "./error-output.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { captureStoreMigrationState } from "../storage/writer-migration.js";
+import { PreparedPairedWriterMigration, observeDrainedMigrationStores } from "../storage/paired-writer-migration.js";
+import { assertImportAdmission } from "../storage/import-guard.js";
+/** Capability only. Exercise the actual target migration/admission on private
+ * WAL-aware copies before paying for a native probe. Never grants real-store
+ * write admission, productive migration proof or a runtime permit. */
+export function runMemoryStorageQualificationCli(args, env = process.env, io = process) {
+    let temporary;
+    try {
+        const output = parseOutputOptions(args), route = prepareCommandRoute(output.args);
+        if (route.key !== "runtime storage qualify" || output.responseFile || output.progressJsonl)
+            throw new AppError("usage", "Storage qualification accepts stdout output only", 2, { effect: "no_effect" });
+        const home = env.DD_FLOW_HOME, resource = env.DD_FLOW_RESOURCE_HOME;
+        for (const root of [home, resource])
+            if (!root || !path.isAbsolute(root) || canonicalPath(root, false) !== root)
+                throw new AppError("usage", "Qualification requires both explicit canonical storage Homes", 2, { effect: "no_effect" });
+        for (const root of new Set([home, resource]))
+            assertImportAdmission(root);
+        const stores = [{ database: path.join(home, "db.sqlite") }, { database: path.join(resource, "runtime.sqlite") }];
+        const admit = (selected) => {
+            let stdout = "", stderr = "";
+            const collect = (write) => new Writable({ write(chunk, _encoding, done) { write(chunk.toString()); done(); } });
+            const code = runMemoryStorageAdmissionCli(["runtime", "storage", "admit", "--operation", "memory-upgrade", "--json"], selected, { stdout: collect(chunk => { stdout += chunk; }), stderr: collect(chunk => { stderr += chunk; }) });
+            return { code, stdout, stderr };
+        };
+        const current = admit(env);
+        let selectedRoute = "verified-no-op";
+        if (current.code !== 0) {
+            // No simulation of a live runtime: the normal admission above remains
+            // sufficient for compatible stores; changed stores must already drain.
+            temporary = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "dd-upgrade-capability-")));
+            const runHome = path.join(temporary, "run"), resourceHome = path.join(temporary, "resource");
+            fs.mkdirSync(runHome);
+            fs.mkdirSync(resourceHome);
+            const copies = [path.join(runHome, "db.sqlite"), path.join(resourceHome, "runtime.sqlite")];
+            stores.forEach((store, index) => {
+                if (!fs.existsSync(store.database)) {
+                    if (["-wal", "-shm", "-journal"].some(suffix => fs.existsSync(store.database + suffix)))
+                        throw new AppError("storage_capability_invalid", "Missing source store retains sidecars", 1, { effect: "no_effect" });
+                    const fresh = index === 0 ? getDatabase(runHome, "create_new") : getResourceDatabase(resourceHome, "create_new");
+                    fresh.close?.();
+                    return;
+                }
+                const owner = fs.lstatSync(store.database);
+                if (!owner.isFile() || owner.nlink !== 1)
+                    throw new AppError("storage_capability_invalid", "Source store must have one regular physical owner", 1, { effect: "no_effect" });
+                const reader = new DatabaseSync(store.database, { readOnly: true });
+                try {
+                    reader.exec(`VACUUM INTO '${copies[index].replaceAll("'", "''")}'`);
+                    const copy = new DatabaseSync(copies[index], { readOnly: true });
+                    try {
+                        if (hybridDigest(captureStoreMigrationState(reader)) !== hybridDigest(captureStoreMigrationState(copy)))
+                            throw new AppError("storage_capability_invalid", "Source changed during private qualification", 1, { effect: "no_effect" });
+                    }
+                    finally {
+                        copy.close();
+                    }
+                    const after = fs.lstatSync(store.database);
+                    if (after.dev !== owner.dev || after.ino !== owner.ino || after.nlink !== 1)
+                        throw new AppError("storage_capability_invalid", "Source store owner changed", 1, { effect: "no_effect" });
+                }
+                finally {
+                    reader.close();
+                }
+            });
+            let checked = admit({ ...env, DD_FLOW_HOME: runHome, DD_FLOW_RESOURCE_HOME: resourceHome });
+            if (checked.code !== 0) {
+                observeDrainedMigrationStores(stores.filter(store => fs.existsSync(store.database)));
+                PreparedPairedWriterMigration.prepare({ requestId: "capability-only", requestFile: path.join(temporary, "plan.json"), projectRoot: temporary,
+                    workspaceRoot: temporary, runHome, resourceHome, selectionSha256: hybridDigest(stores), bootstrapSchema: "memory-upgrade@1" }).apply();
+                checked = admit({ ...env, DD_FLOW_HOME: runHome, DD_FLOW_RESOURCE_HOME: resourceHome });
+                selectedRoute = "migration";
+            }
+            if (checked.code !== 0)
+                throw new AppError("storage_capability_invalid", "Target cannot admit its privately migrated copies", 1, { effect: "no_effect", admission: JSON.parse(checked.stderr) });
+        }
+        const facts = { schema_id: "dd-flow/memory-upgrade-storage-capability@1", operation: "memory-upgrade", route: selectedRoute,
+            source_stores: stores.map(store => store.database), productive_admission: false };
+        io.stdout.write(`${JSON.stringify({ ok: true, action: "runtime_storage_qualify", facts, sha256: hybridDigest(facts) })}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        record.details = { ...record.details, effect: "no_effect" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+    finally {
+        if (temporary)
+            fs.rmSync(temporary, { recursive: true, force: true });
+    }
+}

package/dist/cli/memory-storage-transition.js

@@ -0,0 +1,123 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { writePreparationError } from "./error-output.js";
+import { restoreMemoryUpgradeSelection } from "../services/memory-upgrade-selection.js";
+import { assertMemoryUpgradeProjectCurrent } from "../services/memory-upgrade-storage-readiness.js";
+import { PreparedPairedWriterMigration, PreparedPairedWriterRecovery } from "../storage/paired-writer-migration.js";
+import { readBoundedReleaseFile } from "../services/release-source.js";
+import { shellArgument } from "../services/runtime-command.js";
+function refuse(reason) { throw new AppError("memory_storage_transition_invalid", "Storage transition requires the original upgrade and its selected immutable engine", 1, { reason, effect: "no_effect" }); }
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** Pre-context transport: no initialize/prepared-existing database connection,
+ * router fallback, provider or RUN creation. Executed by the selected engine. */
+export function runMemoryStorageTransitionCli(args, env = process.env, io = process) {
+    let effects = false;
+    try {
+        const output = parseOutputOptions(args), route = prepareCommandRoute(output.args);
+        if (route.key !== "runtime storage transition" || output.responseFile || output.progressJsonl)
+            throw new AppError("usage", "Storage transition accepts stdout output only", 2, { effect: "no_effect" });
+        const option = (key) => route.parsed.options.get(key)?.[0];
+        const action = option("action"), expected = option("expected-sha256"), recoveryId = option("recovery-id");
+        if (env.DD_FLOW_INVOCATION_READONLY === "1" && !["status", "recovery-status"].includes(action))
+            refuse("readonly_invocation");
+        if (action !== "plan" && (!expected || !/^[a-f0-9]{64}$/.test(expected)))
+            throw new AppError("usage", "This action requires --expected-sha256 from its retained request", 2, { effect: "no_effect" });
+        if ((action === "recovery-plan") !== Boolean(recoveryId))
+            throw new AppError("usage", "--recovery-id is required only for recovery-plan", 2, { effect: "no_effect" });
+        if (["apply", "recovery-plan", "recover"].includes(action) && !route.parsed.options.has("offline"))
+            throw new AppError("usage", "Storage mutation requires --offline after draining all runtime owners", 2, { effect: "no_effect" });
+        const home = env.DD_FLOW_HOME, resource = env.DD_FLOW_RESOURCE_HOME;
+        for (const root of [home, resource])
+            if (!root || !path.isAbsolute(root) || fs.realpathSync(root) !== root)
+                refuse("explicit_canonical_homes_required");
+        const scope = { requestId: option("request-id"), projectRoot: option("project-root"), workspaceRoot: option("workspace-root") };
+        const selected = restoreMemoryUpgradeSelection(home, scope), engine = selected.engine;
+        if (option("selection-sha256") !== selected.sha256)
+            refuse("original_selection_changed");
+        if (!process.argv[1] || fs.realpathSync(process.argv[1]) !== engine.entrypoint)
+            refuse("selected_engine_entrypoint_required");
+        const file = path.join(path.dirname(selected.original.candidate.retain().file), "storage-migration.json");
+        const pairedId = `upgrade-${selected.sha256.slice(0, 32)}`;
+        const assertProjectCurrent = () => {
+            if (!selected.payload.git || !selected.oldTree)
+                refuse("productive_upgrade_selection_required");
+            assertMemoryUpgradeProjectCurrent(selected, scope, env);
+        };
+        const restorePair = (sha) => {
+            const pair = PreparedPairedWriterMigration.restore(file, sha), material = pair.recoveryMaterial();
+            if (material.intent.selection_sha256 !== selected.sha256 || material.intent.request_id !== pairedId
+                || material.intent.project_root !== scope.projectRoot || material.intent.workspace_root !== scope.workspaceRoot
+                || material.intent.stores[0]?.home !== home || material.intent.stores[1]?.home !== resource)
+                refuse("retained_pair_scope_changed");
+            return pair;
+        };
+        const command = (next, sha) => `DD_FLOW_RESOURCE_HOME=${shellArgument(resource)} ${engine.command(home, [
+            "runtime", "storage", "transition", "--action", next, "--project-root", scope.projectRoot, "--workspace-root", scope.workspaceRoot,
+            "--request-id", scope.requestId, "--selection-sha256", selected.sha256, "--expected-sha256", sha, ...(["apply", "recover"].includes(next) ? ["--offline"] : []), "--json"
+        ])}`;
+        let result;
+        if (action === "plan") {
+            let pair;
+            if (fs.existsSync(file))
+                pair = restorePair(expected ?? hash(readBoundedReleaseFile(file, 16 * 1024 * 1024)));
+            else {
+                if (expected)
+                    refuse("original_pair_missing");
+                assertProjectCurrent();
+                pair = PreparedPairedWriterMigration.prepare({ requestId: pairedId, requestFile: file, projectRoot: scope.projectRoot, workspaceRoot: scope.workspaceRoot,
+                    runHome: home, resourceHome: resource, selectionSha256: selected.sha256, bootstrapSchema: "memory-upgrade@1" });
+            }
+            effects = true;
+            const request = pair.retain();
+            result = { request, apply_command: command("apply", pair.sha256), status_command: command("status", pair.sha256) };
+        }
+        else if (action === "recover" || action === "recovery-status") {
+            const recovery = PreparedPairedWriterRecovery.restore(file + ".recovery.json", expected), reference = recovery.migrationReference();
+            if (reference.path !== file)
+                refuse("recovery_migration_scope_changed");
+            restorePair(reference.sha256);
+            if (action === "recover") {
+                effects = true;
+                result = recovery.apply();
+            }
+            else
+                result = recovery.reconcile();
+        }
+        else {
+            const pair = restorePair(expected);
+            if (action === "status") {
+                const observed = pair.reconcile();
+                result = { status: observed.status,
+                    proof: fs.existsSync(file + ".result.json") ? pair.readEvidence() : null,
+                    outcomes: observed.outcomes.map(outcome => ({ status: outcome.status, ...(outcome.reason ? { reason: outcome.reason } : {}) })) };
+            }
+            else if (action === "apply") {
+                if (pair.reconcile().status === "not_applied")
+                    assertProjectCurrent();
+                effects = true;
+                pair.apply();
+                result = { status: "applied", proof: pair.readEvidence() };
+            }
+            else {
+                const recovery = PreparedPairedWriterRecovery.prepare(pair, recoveryId);
+                effects = true;
+                const request = recovery.retain();
+                result = { request, recover_command: command("recover", request.sha256), status_command: command("recovery-status", request.sha256) };
+            }
+        }
+        io.stdout.write(`${JSON.stringify({ ok: true, action: "runtime_storage_transition", operation: action, scope, selection_sha256: selected.sha256,
+            engine: { manifest_sha256: engine.manifestSha256, sha256: engine.manifest().integrity.checksum }, result }, null, output.json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        if (effects)
+            record.details = { ...record.details, effect: "unknown", next_action: "reconcile_exact_request" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/memory-upgrade.js

@@ -0,0 +1,189 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { createContext } from "../runtime/context.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { resolveDdFlowHome } from "../storage/paths.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { readSetupStatus } from "../services/setup.js";
+import { readOperatorProfiles, readOperatorProfileInput } from "../services/operator-profiles.js";
+import { onboardExecutor } from "../services/executor-onboarding.js";
+import { readMemoryUpgradeRequestCandidate, prepareMemoryUpgradeRequestCandidate } from "../services/memory-init-request-candidate.js";
+import { readMemoryUpgradeRequestInput } from "../services/memory-init-request-input.js";
+import { PreparedMemoryUpgradeSelection, readMemoryUpgradeSelection, restoreMemoryUpgradeSelection } from "../services/memory-upgrade-selection.js";
+import { PreparedUpgradeStorageReadiness, readUpgradeStorageReadiness, assertMemoryUpgradeProjectCurrent } from "../services/memory-upgrade-storage-readiness.js";
+import { startMemoryUpgradeRun, registerMemoryUpgradeProject } from "../services/memory-upgrade-start.js";
+import { openMemoryInitStores, assertMemoryInitStorePrerequisites } from "../services/memory-init-stores.js";
+import { PreparedInstalledFlowSource } from "../services/installed-flow-source.js";
+import { selectMemoryInitInstalledEngine } from "../services/memory-init-engine-release.js";
+import { FrozenGenericExecution } from "../services/generic-execution.js";
+import { prepareMemoryInitHarnessCommands } from "../services/memory-init-project-bootstrap.js";
+import { produceMemoryInitNativeCapacity, restoreCompletedMemoryNativeCapacity } from "../services/memory-init-native-capacity.js";
+import { inspectMemoryLintExecutable, inspectMemoryGitExecutable } from "../services/memory-init-preflight.js";
+import { PreparedMemoryInitLintCapability } from "../services/memory-init-lint-capability.js";
+import { observeMemoryGitPolicySelection } from "../services/memory-init-git-policy.js";
+import { parseRuntimeBudget } from "../services/runtime-budget.js";
+import { launchAndObserveMemoryFlow } from "./memory-init.js";
+import { prepareMemoryUpgradeInvocation, assertMemoryInitInvocationReplay } from "./memory-init-invocation.js";
+import { askExecutorChoice } from "./executor-onboarding.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination } from "./response-file.js";
+import { prepareFileBytes } from "./input-preparation.js";
+import { writePreparationError } from "./error-output.js";
+/** Upgrade never enters init's project publication path. Read-only original
+ * request lookup precedes ambient selection; writable stores are opened only
+ * after retaining the target/current selection, without initializing existing
+ * stores. Pristine stores use shared pair publication, never init documents.
+ * Storage-changing transitions must first settle their explicit migration.
+ */
+export async function runMemoryUpgradeCli(args, env = process.env, io = process) {
+    let context, effects = false;
+    try {
+        const output = parseOutputOptions(args), invocation = prepareMemoryUpgradeInvocation(output.args);
+        parseRuntimeBudget(env.DD_FLOW_RUNTIME_BUDGET);
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const home = resolveDdFlowHome(env), scope = invocation.scope;
+        const reader = createContext(env, "read_existing");
+        let storage;
+        try {
+            storage = readUpgradeStorageReadiness(reader, scope);
+        }
+        finally {
+            reader.db.close?.();
+        }
+        const candidate = storage ? null : readMemoryUpgradeRequestCandidate(home, scope);
+        const original = storage?.receipt.selection?.request_input ?? candidate?.input;
+        if (storage && !original)
+            throw new AppError("memory_upgrade_original_request_required", "Historical storage metadata cannot select a fresh upgrade", 1, { effect: "no_effect" });
+        if (original) {
+            const objective = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.from(original.intake_base64, "base64"));
+            const raw = readMemoryUpgradeRequestInput(original, scope, objective);
+            if (invocation.profileFile)
+                invocation.execution.rootProfile = readOperatorProfileInput(invocation.profileFile);
+            assertMemoryInitInvocationReplay(invocation, raw.selection, original.intake_sha256);
+            if (invocation.nativeConfigHome) {
+                const selected = storage?.selection?.payload.execution ?? readMemoryUpgradeSelection(home, scope)?.payload.execution;
+                const reference = selected?.snapshot.settings.delegation.native_capacity_receipt;
+                const encoded = selected?.receipt_blobs?.find(([sha]) => sha === reference?.sha256)?.[1];
+                if (!encoded || JSON.parse(Buffer.from(encoded, "base64").toString("utf8")).input.native_config_home !== invocation.nativeConfigHome)
+                    throw new AppError("memory_upgrade_request_conflict", "Original native configuration selection changed", 1, { effect: "no_effect" });
+            }
+            if (!storage && !readMemoryUpgradeSelection(home, scope)) {
+                // A raw candidate is not resolved selection authority. Resume only its
+                // original target/profile request; never replace it with new CLI input.
+                effects = true;
+                const native = raw.selection.execution.delegation?.mode === "native"
+                    ? await restoreCompletedMemoryNativeCapacity({ home, scope, env }) : undefined;
+                if (native && hybridDigest(native.reference) !== hybridDigest(raw.selection.execution.delegation?.nativeCapacityReceipt))
+                    throw new AppError("memory_upgrade_request_conflict", "Completed probe differs from the original request", 1, { effect: "unknown" });
+                PreparedMemoryUpgradeSelection.prepare(home, scope, candidate.candidate, { env, now: new Date().toISOString(),
+                    ...(native ? { receipts: native.receipts, receiptBytes: native.receiptBytes } : {}) }).retain();
+            }
+        }
+        else {
+            if (!invocation.intakeFile || !invocation.intakeSha256 || !invocation.gitPolicy)
+                throw new AppError("usage", "Fresh upgrade requires original intake file/hash and explicit Git policy", 2, { effect: "no_effect" });
+            const intake = prepareFileBytes(invocation.intakeFile, "original upgrade intake", 64 * 1024).bytes;
+            if (createHash("sha256").update(intake).digest("hex") !== invocation.intakeSha256)
+                throw new AppError("memory_upgrade_intake_changed", "Original intake differs from its declared hash", 2, { effect: "no_effect" });
+            let objective;
+            try {
+                objective = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(intake);
+            }
+            catch {
+                throw new AppError("usage", "Original upgrade intake must be UTF-8", 2, { effect: "no_effect" });
+            }
+            const setup = readSetupStatus(home), installation = setup.installation;
+            if (!installation || setup.installation_readiness !== "installed")
+                throw new AppError("memory_upgrade_setup_required", "Install the target release with setup before project upgrade", 1, { effect: "no_effect" });
+            const stdin = io.stdin ?? process.stdin;
+            const selected = await onboardExecutor({
+                ...(typeof invocation.execution.rootProfile === "string" ? { profileId: invocation.execution.rootProfile } : {}),
+                ...(invocation.profileFile ? { profileFile: invocation.profileFile } : {})
+            }, () => readOperatorProfiles(home), { allowSkip: false, nonInteractive: invocation.nonInteractive || output.json || output.progressJsonl
+                    || !stdin.isTTY || !io.stderr.isTTY }, settings => askExecutorChoice(settings, { stdin, stderr: io.stderr }, { allowSave: false, allowSkip: false }));
+            if (selected.source === "explicit-file" || selected.source === "explicit-profile")
+                invocation.execution.rootProfile = selected.profile;
+            else if (invocation.execution.rootProfile === undefined && selected.source === "explicit-id")
+                invocation.execution.rootProfile = selected.profile.id;
+            let native;
+            if (invocation.execution.delegation?.mode === "native") {
+                if (!invocation.allowLiveProbe)
+                    throw new AppError("usage", "Fresh native upgrade requires --allow-live-probe", 2, { effect: "no_effect" });
+                const source = PreparedInstalledFlowSource.fromInstalledRelease(home, installation.manifest_sha256, "mb-upgrade");
+                const engine = selectMemoryInitInstalledEngine(home, installation.manifest_sha256);
+                engine.admitMemoryUpgradeFlow(source);
+                if (!fs.existsSync(path.join(home, "db.sqlite")))
+                    assertMemoryInitStorePrerequisites(env, scope);
+                engine.qualifyMemoryUpgradeStorage(home, env.DD_FLOW_RESOURCE_HOME ?? home);
+                observeMemoryGitPolicySelection(env, { scope, gitExecutable: inspectMemoryGitExecutable(env).executable, selection: invocation.gitPolicy });
+                const lint = inspectMemoryLintExecutable(env);
+                PreparedMemoryInitLintCapability.prepareExecutable(lint.executable, lint.probe, env, { temporaryConfiguration: true });
+                const execution = FrozenGenericExecution.prepare(source.resolveRegisteredFlow(), readOperatorProfiles(home), {
+                    ...invocation.execution, delegation: { mode: "external", max_parallel: invocation.execution.delegation.max_parallel ?? 1 }
+                }, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspace: scope.workspaceRoot });
+                prepareMemoryInitHarnessCommands({ ddFlowHome: home }, execution);
+                const snapshot = execution.snapshot(), profile = snapshot.profiles.find(entry => entry.id === snapshot.settings.root_profile).profile;
+                if (snapshot.profiles.some(entry => hybridDigest({ ...entry.profile, id: profile.id }) !== hybridDigest(profile)))
+                    throw new AppError("generic_execution_invalid", "Native delegation cannot change execution profiles", 2, { effect: "no_effect" });
+                effects = true;
+                native = await produceMemoryInitNativeCapacity({ home, scope, profile, maximum: invocation.execution.delegation.max_parallel ?? 1,
+                    ...(invocation.nativeConfigHome ? { nativeConfigHome: invocation.nativeConfigHome } : {}), allowLiveProbe: true, env,
+                    requestSha256: hybridDigest({ flow: "mb-upgrade", scope, execution: invocation.execution, gitPolicy: invocation.gitPolicy,
+                        objective, intake: invocation.intakeSha256, target: installation.manifest_sha256 }) });
+                invocation.execution.delegation.nativeCapacityReceipt = native.reference;
+            }
+            const raw = { schema_id: "dd-flow/memory-upgrade-request-selection@1", scope,
+                execution: invocation.execution, git_policy: invocation.gitPolicy, objective, engine_checksum: null,
+                receipts: [...native?.receipts ?? []], target_installation_sha256: installation.manifest_sha256 };
+            const prepared = prepareMemoryUpgradeRequestCandidate(home, scope, Buffer.from(JSON.stringify(raw)), intake);
+            effects = true;
+            prepared.retain();
+            PreparedMemoryUpgradeSelection.prepare(home, scope, prepared, { env, now: new Date().toISOString(),
+                ...(native ? { receipts: native.receipts, receiptBytes: native.receiptBytes } : {}) }).retain();
+        }
+        if (!storage) {
+            const selected = restoreMemoryUpgradeSelection(home, scope);
+            if (!fs.existsSync(path.join(home, "db.sqlite"))) {
+                assertMemoryUpgradeProjectCurrent(selected, scope, env);
+                effects = true;
+                // Shared store creation owns pristine/replay checks and never writes
+                // project documents. Existing stores still take explicit migration.
+                const fresh = openMemoryInitStores(env, { scope, selectionSha256: selected.sha256 });
+                fresh.context.db.close?.();
+            }
+            try {
+                selected.engine.admitMemoryUpgradeStorage(home, env.DD_FLOW_RESOURCE_HOME ?? home);
+            }
+            catch (error) {
+                if (!(error instanceof AppError) || error.code !== "frozen_engine_storage_incompatible")
+                    throw error;
+                // Retain only the selected engine's explicit plan. Never apply it as a
+                // side effect of starting upgrade or open the old stores for writes.
+                effects = true;
+                const planned = selected.engine.transitionMemoryUpgradeStorage({ home, resourceHome: env.DD_FLOW_RESOURCE_HOME ?? home,
+                    scope, selectionSha256: selected.sha256, action: "plan" });
+                throw new AppError("memory_upgrade_storage_transition_required", "Drain runtime owners, apply the retained storage plan, then repeat this exact upgrade request", 1, { effect: "partial", storage_effect: "no_effect", migration: planned.result });
+            }
+        }
+        context = createContext(env, "prepared_existing", undefined, { resourceDatabaseMode: "prepared_existing" });
+        effects = true;
+        if (!storage) {
+            registerMemoryUpgradeProject(context, scope);
+            PreparedUpgradeStorageReadiness.prepareFromSelection(context, scope).apply(context);
+        }
+        const started = startMemoryUpgradeRun(context, scope);
+        return await launchAndObserveMemoryFlow(context, invocation, started, "mb-upgrade", output, env, io);
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        if (effects)
+            record.details = { ...record.details, effect: record.details.effect === "partial" ? "partial" : "unknown", next_action: "observe_or_reconcile_exact_request" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+    finally {
+        context?.db.close?.();
+    }
+}

package/dist/cli/models.js

@@ -0,0 +1,39 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { optionalOption } from "./argument-values.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { listOperatorModels } from "../services/model-catalog.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { writePreparationError } from "./error-output.js";
+/** Model listing never opens an AppContext, starts a probe or reads credentials. */
+export function runModelsCli(args, io = process) {
+    let json = false;
+    try {
+        const output = parseOutputOptions(args);
+        json = output.json;
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const route = prepareCommandRoute(output.args);
+        if (!["models list", "models show"].includes(route.key))
+            throw new AppError("usage", "Unknown models command; see dd-flow models --help", 2, { effect: "no_effect" });
+        const input = {};
+        for (const [option, field] of [["harness", "harness"], ["provider", "provider"], ["account-sha256", "accountSha256"],
+            ["seed-file", "seedFile"], ["observation-file", "observationFile"]]) {
+            const value = optionalOption(route.parsed, option);
+            if (value !== undefined)
+                input[field] = value;
+        }
+        if (route.key === "models show")
+            input.model = route.parsed.positional[0];
+        const models = listOperatorModels(input);
+        if (route.key === "models show" && models.entries.length === 0)
+            throw new AppError("model_not_found", "Model is absent from the selected seed and scoped observation", 1, { effect: "no_effect", help: "models" });
+        io.stdout.write(`${JSON.stringify(writeResponseFile({ ok: true, action: route.key.replaceAll(" ", "_"), ...models }, output), null, json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/native-hook-ingress.js

@@ -0,0 +1,90 @@
+import { AppError, errorRecord } from "../shared/errors.js";
+import { parseCommandArgs } from "../services/lifecycle-command.js";
+import { channel } from "node:diagnostics_channel";
+import { nativeHookNonParticipation } from "./native-hook-preparation.js";
+/** These ingress commands consume a prepared store; they never prepare it. */
+export function isNativeHookIngress(args) {
+    return args[2] === "handle" && ((args[1] === "event" && ["agy", "grok", "droid", "opencode", "zcode"].includes(args[0] ?? ""))
+        || args[0] === "zcode" && args[1] === "hook");
+}
+export async function dispatchNativeHook(args, stdin, env) {
+    const started = performance.now();
+    const deadline = env.DD_FLOW_HOOK_DEADLINE_AT ? Number(env.DD_FLOW_HOOK_DEADLINE_AT) : Date.now() + 25_000;
+    env = { ...env, DD_FLOW_HOOK_DEADLINE_AT: String(deadline) };
+    if (deadline !== undefined && !Number.isSafeInteger(deadline))
+        throw new AppError("hook_deadline_invalid", "Native hook deadline must be an absolute millisecond timestamp", 1, { effect: "unknown" });
+    const phase = (name) => {
+        if (deadline !== undefined && deadline <= Date.now())
+            throw new AppError("native_hook_timeout", "Native hook deadline expired", 1, { phase: name, effect: "unknown" });
+        process.stderr.write(`${JSON.stringify({ kind: "native_hook_phase", phase: name, elapsed_ms: Math.round(performance.now() - started), ...(deadline !== undefined ? { remaining_ms: Math.max(0, deadline - Date.now()) } : {}) })}\n`);
+    };
+    phase("import");
+    const parsed = parseCommandArgs(args.slice(3));
+    const projectRoot = parsed.options.get("project-root")?.[0];
+    if (!isNativeHookIngress(args) || parsed.positional.length || !projectRoot || projectRoot === "__dd_flow_flag__")
+        throw new AppError("usage", "Native hook requires --project-root", 2);
+    for (const [name, values] of parsed.options)
+        if (!["project-root", "json"].includes(name) || values.length !== 1 || name === "json" && values[0] !== "__dd_flow_flag__")
+            throw new AppError("usage", `Invalid native hook option: ${name}`, 2);
+    const unrelated = nativeHookNonParticipation(args, stdin);
+    if (unrelated) {
+        phase("ack");
+        return unrelated;
+    }
+    const [hooks, { createContext }, { resolveDdFlowHome }] = await Promise.all([
+        import("../services/hooks.js"), import("../runtime/context.js"), import("../storage/paths.js")
+    ]);
+    phase("imported");
+    let opened;
+    // Reuse the actual envelope validators and shell parser. They return for
+    // unrelated tools before their first DB access, without duplicating policy.
+    const context = {
+        env, ddFlowHome: resolveDdFlowHome(env), now: () => new Date().toISOString(),
+        get db() {
+            if (!opened) {
+                phase("store_open");
+                opened = createContext(env, "hook");
+                phase("store_opened");
+            }
+            return opened.db;
+        }
+    };
+    const handler = args[0] === "agy" ? hooks.handleAgyEvent : args[0] === "grok" ? hooks.handleGrokEvent
+        : args[0] === "droid" ? hooks.handleDroidEvent : args[0] === "opencode" ? hooks.handleOpenCodeEvent
+            : args[1] === "hook" ? hooks.handleZcodeHook : hooks.handleZcodeEvent;
+    const timing = channel("dd-flow.sqlite.ingress");
+    // This command owns one synchronous store; there is no concurrent handler here.
+    let previousPhase;
+    const log = (value) => {
+        const record = value;
+        if (record.phase === previousPhase)
+            return;
+        previousPhase = record.phase;
+        process.stderr.write(`${JSON.stringify({ kind: "native_hook_phase", phase: record.phase, elapsed_ms: Math.round(performance.now() - started), ...(record.remaining_ms !== undefined ? { remaining_ms: record.remaining_ms } : {}) })}\n`);
+    };
+    timing.subscribe(log);
+    try {
+        phase("receipt");
+        const result = await handler(context, { projectRoot, stdin });
+        phase("ack");
+        return result;
+    }
+    finally {
+        timing.unsubscribe(log);
+        opened?.db.close?.();
+    }
+}
+export async function runNativeHookIngress(args) {
+    try {
+        const { readNativeHookInput, hookBudget } = await import("../harness-runtime/lib/native-hook-command.mjs");
+        const budget = hookBudget(25_000, process.env.DD_FLOW_HOOK_DEADLINE_AT ? Number(process.env.DD_FLOW_HOOK_DEADLINE_AT) : null);
+        const stdin = await readNativeHookInput(process.stdin, budget);
+        process.stdout.write(`${JSON.stringify(await dispatchNativeHook(args, stdin, { ...process.env, DD_FLOW_HOOK_DEADLINE_AT: String(budget.deadlineAt) }))}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        process.stderr.write(`${JSON.stringify({ ok: false, error: record })}\n`);
+        return record.exitCode;
+    }
+}

package/dist/cli/native-hook-preparation.js

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { parseJsonObject } from "../shared/json.js";
+import { continuationCommand, parseLifecycleCommand } from "../services/lifecycle-command.js";
+const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+const text = (value) => typeof value === "string" && value.length > 0 ? value : undefined;
+/** Only a validated, ordinary before-tool command can skip the stateful handler.
+ * In particular after-tool, Stop, malformed and ambiguous events remain owned
+ * by their existing handler; this gate does not invent an admission policy. */
+export function nativeHookNonParticipation(args, stdin) {
+    const payload = parseJsonObject(stdin || "{}", "native hook stdin");
+    let command;
+    if (args[0] === "zcode" && args[1] === "event") {
+        const update = object(object(payload.params).update);
+        if (payload.method !== "session/update" || update.sessionUpdate !== "tool_call")
+            return null;
+        const tool = text(object(object(update._meta).claudeCode).toolName);
+        if (!tool || !["Bash", "bash", "execute"].includes(tool))
+            return null;
+        const input = object(update.rawInput);
+        command = text(input.command) ?? text(input.cmd);
+    }
+    else if (args[0] === "grok" || args[0] === "zcode") {
+        const event = text(payload.hook_event_name) ?? text(payload.hookEventName);
+        if (event && !["PreToolUse", "pre_tool_use"].includes(event))
+            return null;
+        const tool = text(payload.tool_name) ?? text(payload.toolName);
+        if (tool && !(args[0] === "grok" ? ["Bash", "bash", "run_terminal_command", "RunTerminalCommand"] : ["Bash", "bash", "execute"]).includes(tool))
+            return null;
+        const input = object(payload.tool_input ?? payload.toolInput);
+        command = text(input.command) ?? text(input.cmd) ?? text(payload.command);
+    }
+    else {
+        const family = args[0];
+        if (payload.schema_id !== `dd-flow/${family}-tool-event@1` || payload.phase !== "before")
+            return null;
+        const session = object(payload.session), tool = text(payload.tool);
+        const directory = family === "agy" ? text(payload.launch_cwd) : text(session.directory);
+        const id = family === "agy" ? text(payload.conversation_id) : text(session.provider_session_id);
+        if (!directory || !path.isAbsolute(directory) || !id || !text(payload.daemon_id) || !text(payload.event_id)
+            || family === "opencode" && !text(payload.tool_call_id) || !tool
+            || !(family === "droid" ? ["Execute"] : ["bash", "Bash", "shell", "run_command", "run_terminal_command", "RunTerminalCommand"]).includes(tool)
+            || family === "droid" && session.parent_provider_session_id === id)
+            return null;
+        if (family === "agy" && Array.isArray(payload.workspace_paths)
+            && payload.workspace_paths.length && !payload.workspace_paths.some(value => typeof value === "string" && path.resolve(value) === path.resolve(directory)))
+            return null;
+        const input = object(payload.input);
+        command = text(input.command) ?? text(input.cmd) ?? text(input.CommandLine);
+    }
+    if (!command)
+        return null;
+    const parsed = parseLifecycleCommand(command);
+    return parsed.participation === "none" && !continuationCommand(command)
+        ? { ok: true, observed: false, reason: args[0] === "zcode" && args[1] === "event" ? "acp_evidence_only" : "event_not_participating" } : null;
+}