@deksden-com/dd-flow-cli 0.9.0-beta.143 → 0.9.0-beta.145

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

@@ -1,6 +1,7 @@
 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] ?? ""))
@@ -8,7 +9,8 @@ export function isNativeHookIngress(args) {
 }
 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) : undefined;
+    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) => {
@@ -24,6 +26,11 @@ export async function dispatchNativeHook(args, stdin, env) {
     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")
     ]);
@@ -58,7 +65,9 @@ export async function dispatchNativeHook(args, stdin, env) {
     timing.subscribe(log);
     try {
         phase("receipt");
-        return await handler(context, { projectRoot, stdin });
+        const result = await handler(context, { projectRoot, stdin });
+        phase("ack");
+        return result;
     }
     finally {
         timing.unsubscribe(log);
@@ -68,8 +77,9 @@ export async function dispatchNativeHook(args, stdin, env) {
 export async function runNativeHookIngress(args) {
     try {
         const { readNativeHookInput, hookBudget } = await import("../harness-runtime/lib/native-hook-command.mjs");
-        const stdin = await readNativeHookInput(process.stdin, hookBudget(25_000, process.env.DD_FLOW_HOOK_DEADLINE_AT ? Number(process.env.DD_FLOW_HOOK_DEADLINE_AT) : null));
-        process.stdout.write(`${JSON.stringify(await dispatchNativeHook(args, stdin, process.env))}\n`);
+        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) {

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;
+}

package/dist/cli/response-file.js

@@ -40,7 +40,8 @@ export function writeResponseFile(payload, output) {
     if (!output.responseFile)
         return payload;
     const file = path.resolve(output.responseFile), temporary = `${file}.tmp-${randomUUID()}`;
-    const visible = payload && typeof payload === "object" && !Array.isArray(payload) ? { ...payload } : { ok: true, result: payload };
+    const record = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : null;
+    const visible = record ? { ...(record.prompt_delivery ? { prompt_delivery: record.prompt_delivery } : {}), ...record } : { ok: true, result: payload };
     let ownsTemporary = false;
     try {
         prepareResponseDestination(file);

package/dist/cli/run-cli.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { preparePromptDelivery, publishPromptDelivery } from "../services/prompt-delivery.js";
 import { requiredOption, optionalOption, optionalNumber, optionalPositiveNumber } from "./argument-values.js";
 import { resolveCommandPaths, resolveCommandProjectRoot } from "../services/command-context.js";
 import { assertAuxiliaryCommandScope, cliManagedInvocationScope, manualRecoveryInvocationScope, assertManualRecoveryInvocationTarget } from "../services/lifecycle-invocations.js";
@@ -49,6 +50,7 @@ import { validateSchema } from "../services/schema-validation.js";
 import { preflightMemoryPermissions } from "../services/memory-permissions.js";
 import { ingestDroidUsage, ingestAgyUsage, ingestGrokUsage, ingestOpenCodeUsage, ingestZcodeUsage } from "../services/usage.js";
 import { applyMigration, assessMigrationImpact, assertUpgradeRunStorageReady, planMigration, prepareMigrationApply, verifyMigrationReport } from "../services/migrations.js";
+import { PreparedUpgradeStorageReadiness } from "../services/memory-upgrade-storage-readiness.js";
 import { publishProjectSummary } from "../services/project-summary.js";
 import { requireProjectByRoot } from "../services/projects.js";
 import { resolveProjectRoot, resolveDdFlowHome } from "../storage/paths.js";
@@ -62,9 +64,9 @@ import { addVnextCodeRepair, prepareVnextCodeRepair, prepareVnextCodeStart } fro
 import { isVnextCodeReviewRun, prepareCodeReviewDecision, prepareVnextCodeReviewRepair, prepareVnextCodeReviewStart } from "../services/vnext-code-review.js";
 import { applyVnextMerge, getVnextMergeRequest, isVnextMergeRun, prepareVnextMergeFinish, prepareVnextMergeStart, repairVnextMerge, routeVnextMergeRequest } from "../services/vnext-merge.js";
 import { sdlcStageHandlers } from "../services/stage-handlers.js";
-import { startMemoryStage, finishMemoryStage } from "../services/memory-stage-dispatch.js";
+import { startMemoryStage, finishMemoryStage, startMemoryUpgradeStage, finishMemoryUpgradeStage } from "../services/memory-stage-dispatch.js";
 import { bindStageCoordinatorWork } from "../services/work-registry.js";
-import { registerMemoryCompositionFromStage } from "../services/memory-compose-handler.js";
+import { registerMemoryCompositionFromStage, publishMemoryUpgradeFromStage } from "../services/memory-compose-handler.js";
 import { runMemoryVerificationChecks } from "../services/memory-verify-handler.js";
 import { registerMemoryReviewFromStage, collectMemoryInitialReviewFromStage } from "../services/memory-review-handler.js";
 import { PreparedRetainedMemoryReviewAuthority } from "../services/memory-retained-review-authority.js";
@@ -81,7 +83,7 @@ import { blockStageForRuntime, unblockStageAfterRuntimeRepair, prepareStageRunti
 import { classifyCliOperation, requiresExplicitUpgradeAuthorization } from "../services/cli-operation-classifier.js";
 import { prepareWorkerPrompt, renderWorkerPrompt } from "../services/prompts.js";
 import { finishStage, prepareStageFinish, startStage, prepareLegacyStageStart } from "../services/stage-lifecycle.js";
-import { addWorkBatch, prepareWorkBatch, prepareWorkDeps, prepareWorkDelete, prepareWorkSettlement, prepareWorkRetry, assertStageLifecycleOwner, assertWorkLifecycleOwner, cancelWork, deleteWork, failWork, finishWork, listWorks, mutateWorkDeps, prepareWorkResult, workResultByteLimit, retryWork, showWork, startWork } from "../services/work-registry.js";
+import { addWorkBatch, assertGenericWorkBatchAllowed, prepareWorkBatch, prepareWorkDeps, prepareWorkDelete, prepareWorkSettlement, prepareWorkRetry, assertStageLifecycleOwner, assertWorkLifecycleOwner, cancelWork, deleteWork, failWork, finishWork, listWorks, mutateWorkDeps, prepareWorkResult, workResultByteLimit, retryWork, showWork, startWork } from "../services/work-registry.js";
 import { launchExternalWork } from "../services/external-work-launch.js";
 import { createEvalBootstrapSnapshot, prepareEvalBootstrapSnapshot, createEvalRunSnapshot, prepareEvalRunSnapshotCreation, prepareVnextSpecifyRun, prepareEvalRunRestore, prepareEvalBootstrapRestore, restoreEvalBootstrapSnapshot, restoreEvalRunSnapshot } from "../services/eval-snapshots.js";
 import { forkRunFromSnapshot, prepareRunFork } from "../services/run-fork.js";
@@ -328,7 +330,7 @@ async function runCliRequest(args, io, env) {
         if (!invocationId) {
             const preparationContext = createContext({ ...env }, "read_existing", undefined, maintenanceOptions);
             try {
-                preparedInput = await prepareCliInput(invocationArgs, preparationContext, io, scopeProjectRoot, output.responseFile);
+                preparedInput = await prepareCliInput(invocationArgs, preparationContext, io, scopeProjectRoot, output.responseFile, undefined, commandProgress(io, output));
             }
             finally {
                 preparationContext.db.close?.();
@@ -357,8 +359,8 @@ async function runCliRequest(args, io, env) {
                         throw error;
                     }
                 },
-                prepare: async () => { preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile, preparedRoute); },
-                assertCurrent: scope => assertLifecycleInvocationCurrent(dispatchContext, scope, command) });
+                prepare: async () => { preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile, preparedRoute, commandProgress(io, output)); },
+                assertCurrent: scope => assertLifecycleInvocationCurrent(dispatchContext, scope, command), progress: commandProgress(io, output) });
             if (admission.replay) {
                 retainedOutcome = admission.outcome;
                 settleHook = undefined;
@@ -386,7 +388,7 @@ async function runCliRequest(args, io, env) {
             throw new AppError(error.code, error.message, error.exitCode, error.details);
         }
         if (!retainedOutcome && !preparedInput)
-            preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile);
+            preparedInput = await prepareCliInput(invocationArgs, dispatchContext, io, scopeProjectRoot, output.responseFile, undefined, commandProgress(io, output));
         if (!retainedOutcome)
             await preflightCliCompatibility(dispatchContext, invocationArgs, env, scopeProjectRoot);
         if (!retainedOutcome) {
@@ -394,11 +396,10 @@ async function runCliRequest(args, io, env) {
             const event = !invocationId ? nativeEvent : null;
             settleHook = observeLifecycleCommand(dispatchContext, command, event ?? undefined);
         }
-        const result = retainedOutcome ? retainedOutcome.result : await dispatch(dispatchArgs, dispatchContext, io, scopeProjectRoot, classification, output, preparedInput);
-        if (!retainedOutcome && invocationArgs[0] === "stage" && invocationArgs[1] === "start"
-            && result && typeof result === "object" && "prompt_path" in result && typeof result.prompt_path === "string") {
+        const result = preparePromptDelivery(retainedOutcome ? retainedOutcome.result : await dispatch(dispatchArgs, dispatchContext, io, scopeProjectRoot, classification, output, preparedInput));
+        if (!retainedOutcome && result && typeof result === "object" && "worker_prompt_markdown" in result && typeof result.worker_prompt_markdown === "string") {
             try {
-                bindLifecyclePublishedPacket(dispatchContext, fs.readFileSync(result.prompt_path, "utf8"));
+                bindLifecyclePublishedPacket(dispatchContext, result.worker_prompt_markdown);
             }
             catch (cause) {
                 throw new AppError("invocation_packet_binding_failed", "Stage started but its published lifecycle assignments could not be retained", 1, { effect: "committed", cause: String(cause) });
@@ -422,6 +423,7 @@ async function runCliRequest(args, io, env) {
             writeProgressJsonl(io, "done", "Command finished");
         emitHumanProgress(io, output, progress, "done");
         const payload = attachProgress(resultWithWarnings, progress, output);
+        publishPromptDelivery(payload);
         const visible = writeResponseFile(payload, output);
         const maintenanceReceipt = payload;
         const maintenanceExpiry = maintenanceReceipt?.lease_expires_at ?? maintenanceReceipt?.process?.lease_expires_at;
@@ -436,7 +438,7 @@ async function runCliRequest(args, io, env) {
         const record = errorRecord(caught);
         maintenanceDiagnostics?.failure(caught);
         const error = isAppError(caught) ? caught : Object.assign(new AppError(record.code, record.message, record.exitCode, { effect: "unknown", ...record.details, ...(caught?.errcode !== undefined ? { sqlite_extended_code: caught.errcode } : {}) }), { ...(record.cause ? { cause: record.cause } : {}), ...(record.cleanup_error ? { cleanup_error: record.cleanup_error } : {}), ...(record.retryable !== undefined ? { retryable: record.retryable } : {}) });
-        if (!settleHook && !invocationSettlement) {
+        if (!settleHook && !invocationSettlement && error.code !== "prompt_delivery_pending") {
             let earlyContext;
             try {
                 const command = quote(["dd-flow", ...args]);
@@ -558,6 +560,8 @@ function databaseModeForCommand(args, classification) {
     if (isRuntimeMaintenance(args))
         return "read_existing";
     const [family, command] = args;
+    if (family === "migration" && command === "readiness")
+        return "prepared_existing";
     // Managed attempts are issued only from a prepared store. Opening that
     // existing writer must not run migrations before their input is admitted.
     if (parseArgs(args.slice(2)).options.has("invocation-id"))
@@ -635,7 +639,12 @@ function writeProgressJsonl(io, phase, message, detail) {
     io.stderr.write(`${JSON.stringify({ schema_id: "dd-flow/progress@1", phase, message, at: new Date().toISOString(), ...(detail ? { detail } : {}) })}\n`);
 }
 function commandProgress(io, output) {
-    return (message) => output.progressJsonl ? writeProgressJsonl(io, "running", message) : io.stderr.write(`[running] ${message}\n`);
+    return (message) => {
+        if (output.progressJsonl)
+            writeProgressJsonl(io, "running", message);
+        else if (!output.json && !output.hookJsonOnly)
+            io.stderr.write(`[running] ${message}\n`);
+    };
 }
 function attachProgress(result, progress, output) {
     if (progress.length === 0 || output.hookJsonOnly)
@@ -842,6 +851,14 @@ function stringValue(value) {
 function shortSha(value) {
     return value ? value.slice(0, 12) : "unknown";
 }
+function compositionProposalRetry(context, parsed) {
+    return {
+        retry_command: runtimeCommand(context, ["memory", "compose", "register", "--run", requiredOption(parsed, "run"),
+            "--project-root", requiredOption(parsed, "project-root"), "--request-key", requiredOption(parsed, "request-key"),
+            "--result-file", requiredOption(parsed, "result-file"), "--json", "--progress-jsonl"]),
+        retry_instruction: "Correct only the rejected composition proposal, then execute retry_command in this same Session. No Work graph was registered by this rejected call; do not dispatch children or finish the Stage until registration succeeds."
+    };
+}
 /** All caller supplied file/stdin data is consumed here, before a managed
  * invocation is allowed to claim execution or a stage claims its hook event. */
 async function prepareCliInput(...args) {
@@ -852,7 +869,7 @@ async function prepareCliInput(...args) {
         return prepareError(error);
     }
 }
-async function prepareCliInputValue(args, context, io, scopeProjectRoot, responseFile = null, route = prepareCommandRoute(args)) {
+async function prepareCliInputValue(args, context, io, scopeProjectRoot, responseFile = null, route = prepareCommandRoute(args), progress) {
     const { family, command, parsed } = route;
     const prepared = { route };
     if (optionalOption(parsed, "reason-file")) {
@@ -941,6 +958,10 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
         prepared.codexHooks = prepareCodexHooks(context, { projectRoot: requiredOption(parsed, "project-root"), target: optionalOption(parsed, "target"), profile: optionalOption(parsed, "profile"), yes: hasOption(parsed, "yes") });
     if (route.key === "migration apply")
         prepared.migrationApply = prepareMigrationApply(context, migrationApplyInput(parsed, classifyCliOperation(args, context.env)));
+    if (route.key === "migration readiness")
+        prepared.upgradeStorageScope = {
+            projectRoot: requiredOption(parsed, "project-root"), workspaceRoot: requiredOption(parsed, "workspace-root"), requestId: requiredOption(parsed, "request-id")
+        };
     if (route.key === "migration verify")
         prepared.migrationVerification = verifyMigrationReport(context, { file: requiredOption(parsed, "file") });
     if (responseFile)
@@ -1115,6 +1136,7 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
     if (route.key === "work add-batch") {
         const file = requiredOption(parsed, "file");
         try {
+            assertGenericWorkBatchAllowed(context, requiredOption(parsed, "parent"));
             prepared.workBatch = prepareWorkBatch(context, { parentWorkId: requiredOption(parsed, "parent"), file,
                 ...(optionalOption(parsed, "stage") ? { stage: optionalOption(parsed, "stage") } : {}),
                 ...(optionalOption(parsed, "request-key") ? { requestKey: optionalOption(parsed, "request-key") } : {}) });
@@ -1210,14 +1232,15 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
             const bundle = readFlowRunExecutionBundle(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredPosition(parsed, 0, "run-id") });
             if (bundle)
                 prepared.stageBindingBundle = { stage, bundle, ...(contextSha256 ? { contextSha256 } : {}) };
-            if (bundle?.descriptor.descriptor.id === "mb-init") {
+            if (bundle && ["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id)) {
                 bundle.descriptor.stage(stage);
                 if (hasOption(parsed, "dir"))
                     throw new AppError("usage", "Memory stage layout belongs to its frozen descriptor", 2);
                 const loaded = contextFile && contextSha256 ? loadExternalStageContext({ file: contextFile, expectedSha256: contextSha256, stage }) : undefined;
                 if (loaded)
                     prepared.stageStart = { externalContext: loaded };
-                prepared.memoryStage = { operation: "start", bytes: loaded ? Buffer.from(loaded.bytes) : Buffer.alloc(0) };
+                prepared.memoryStage = { operation: "start", bytes: loaded ? Buffer.from(loaded.bytes) : Buffer.alloc(0),
+                    flowId: bundle.descriptor.descriptor.id === "mb-upgrade" ? "mb-upgrade" : "mb-init" };
                 return prepared;
             }
         }
@@ -1313,7 +1336,7 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
             throw new AppError("usage", "work finish requires exactly one of --result-file or --result-stdin", 2);
         const maxBytes = workResultByteLimit(context, requiredPosition(parsed, 0, "work-id"));
         prepared.workFinish = { result: resultFile ? prepareTextFile(resultFile, "Work result", maxBytes).text : await readStdin(io.stdin, maxBytes) };
-        prepareWorkResult(context, requiredPosition(parsed, 0, "work-id"), prepared.workFinish.result);
+        prepareWorkResult(context, requiredPosition(parsed, 0, "work-id"), prepared.workFinish.result, progress);
     }
     if (family === "stage" && command === "fanout" && requiredPosition(parsed, 0, "fanout action") === "reconcile") {
         prepared.observations = prepareNativeObservations(prepareJsonFile(requiredOption(parsed, "observations-file"), "native observations").value);
@@ -1323,10 +1346,18 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
     }
     if (family === "memory" && (["compose", "corrections"].includes(command ?? "") && parsed.positional[0] === "register"
         || command === "repair" && parsed.positional[0] === "publication-reserve")) {
-        const bytes = prepareFileBytes(requiredOption(parsed, "result-file"), `Memory ${command} result`, 1024 * 1024).bytes;
-        if (!bytes.length || bytes.length > 1024 * 1024)
-            throw new AppError("usage", "Memory operation result exceeds its byte bound", 2);
-        prepared.memoryOperationBytes = bytes;
+        try {
+            const bytes = prepareFileBytes(requiredOption(parsed, "result-file"), `Memory ${command} result`, 1024 * 1024).bytes;
+            if (!bytes.length || bytes.length > 1024 * 1024)
+                throw new AppError("usage", "Memory operation result exceeds its byte bound", 2, { phase: "prepare", effect: "no_effect", recoverable: true });
+            prepared.memoryOperationBytes = bytes;
+        }
+        catch (error) {
+            if (command === "compose" && isAppError(error) && error.details.phase === "prepare"
+                && error.details.effect === "no_effect" && error.details.recoverable === true)
+                Object.assign(error.details, compositionProposalRetry(context, parsed));
+            throw error;
+        }
     }
     if (family !== "stage" || command !== "finish")
         return prepared;
@@ -1343,9 +1374,9 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
     const semanticFile = optionalOption(parsed, "semantic-file") ?? optionalOption(parsed, "data");
     const resultFile = optionalOption(parsed, "result-file") ?? semanticFile;
     const runtime = run(projectRoot, runId);
-    if (JSON.parse(runtime.indexJson).execution_bundle?.flow_id === "mb-init") {
+    if (["mb-init", "mb-upgrade"].includes(JSON.parse(runtime.indexJson).execution_bundle?.flow_id)) {
         const bundle = readFlowRunExecutionBundle(context, { projectRoot, runId });
-        if (!bundle || bundle.descriptor.descriptor.id !== "mb-init")
+        if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
             throw new AppError("cli_input_unprepared", "Memory RUN bundle is unavailable", 1);
         bundle.descriptor.stage(stage);
         if (["dir", "outcome", "decision-file", "verification-file", "retry-check", "reason", "reason-file", "request", "work"].some(option => hasOption(parsed, option)))
@@ -1355,7 +1386,7 @@ async function prepareCliInputValue(args, context, io, scopeProjectRoot, respons
         const bytes = resultStdin ? Buffer.from(await readStdin(io.stdin, 1024 * 1024)) : prepareFileBytes(resultFile, "Memory stage result", 1024 * 1024).bytes;
         if (!bytes.length || bytes.length > 1024 * 1024)
             throw new AppError("usage", "Memory stage result exceeds its byte bound", 2);
-        prepared.memoryStage = { operation: "finish", bytes };
+        prepared.memoryStage = { operation: "finish", bytes, flowId: bundle.descriptor.descriptor.id === "mb-upgrade" ? "mb-upgrade" : "mb-init" };
         return prepared;
     }
     const terminalReplay = (name) => {
@@ -1668,6 +1699,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         });
     }
     if (family === "work" && command === "add-batch") {
+        assertGenericWorkBatchAllowed(context, requiredOption(parsed, "parent"));
         return addWorkBatch(context, { parentWorkId: requiredOption(parsed, "parent"), file: requiredOption(parsed, "file"), prepared: prepared.workBatch,
             ...(optionalOption(parsed, "stage") ? { stage: optionalOption(parsed, "stage") } : {}),
             ...(optionalOption(parsed, "request-key") ? { requestKey: optionalOption(parsed, "request-key") } : {}) });
@@ -1694,7 +1726,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         const hookEventId = optionalOption(parsed, "hook-event-id");
         const recoveryId = optionalOption(parsed, "recovery-id");
         const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "work start");
-        return startWork(context, requiredPosition(parsed, 0, "work-id"), { ...(hookEventId ? { hookEventId } : {}), ...(recoveryId ? { recoveryId } : {}), projectRoot });
+        return startWork(context, requiredPosition(parsed, 0, "work-id"), { ...(hookEventId ? { hookEventId } : {}), ...(recoveryId ? { recoveryId } : {}), projectRoot, progress: commandProgress(io, output) });
     }
     if (family === "work" && command === "finish") {
         const resultFile = optionalOption(parsed, "result-file");
@@ -1748,7 +1780,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
                 matchKey: entityReferenceVariants(runId).map(reference => stageStartMatchKey(reference, stage, projectRoot, contextSha256)),
                 errorCode: "trusted_session_binding_required", operation: "Memory stage start"
             }).eventKey;
-            const work = startMemoryStage(context, { projectRoot, runId, stage, bytes: prepared.memoryStage.bytes });
+            const work = (prepared.memoryStage.flowId === "mb-upgrade" ? startMemoryUpgradeStage : startMemoryStage)(context, { projectRoot, runId, stage, bytes: prepared.memoryStage.bytes });
             try {
                 const binding = bindStageCoordinatorWork(context, { workId: work.work_id, hookEventId: event, stage,
                     promptPath: work.prompt_path, resultPath: work.result_path, ...(contextSha256 ? { contextSha256 } : {}) });
@@ -1867,7 +1899,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             // Descriptor settlement validates exact coordinator custody and claims
             // the fresh hook atomically with result acceptance. Do not consume it
             // through the SDLC lifecycle owner before that settlement.
-            return controlledReply(finishMemoryStage(context, { projectRoot, runId, stage, bytes: prepared.memoryStage.bytes,
+            return controlledReply((prepared.memoryStage.flowId === "mb-upgrade" ? finishMemoryUpgradeStage : finishMemoryStage)(context, { projectRoot, runId, stage, bytes: prepared.memoryStage.bytes,
                 hookEventId: hookEventId ?? findRecentMatchingHookEvent(context, {
                     projectId: requireProjectByRoot(context, resolveProjectRoot(projectRoot)).id,
                     matchKey: entityReferenceVariants(runId).map(reference => stageLifecycleMatchKey("stage_finish", reference, stage, projectRoot)),
@@ -2179,6 +2211,13 @@ function dispatchEngine(context, command, parsed, classification, prepared) {
 function dispatchMigration(context, command, parsed, classification, prepared) {
     if (command === "impact")
         return assessMigrationImpact(context, { projectRoot: requiredOption(parsed, "project-root"), ...(optionalOption(parsed, "target-version") ? { targetVersion: optionalOption(parsed, "target-version") } : {}), ...(optionalOption(parsed, "mode") ? { mode: optionalOption(parsed, "mode") } : {}) });
+    if (command === "readiness") {
+        if (!prepared.upgradeStorageScope)
+            throw new AppError("validation", "Upgrade storage scope must be prepared before publication", 2);
+        // Unlike the initial readonly syntax pass, this connection is admitted
+        // prepared-existing. Physical writer checks still precede receipt writes.
+        return { ok: true, ...PreparedUpgradeStorageReadiness.prepare(context, prepared.upgradeStorageScope).apply(context) };
+    }
     if (command === "plan" || command === "report") {
         return planMigration(context, {
             projectRoot: requiredOption(parsed, "project-root"),
@@ -2425,7 +2464,7 @@ function dispatchMemory(context, command, parsed, prepared) {
         const workspaceRoot = requiredOption(parsed, "workspace-root");
         if (wave === "2") {
             const bundle = readFlowRunExecutionBundle(context, work);
-            if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || bundle.execution.snapshot().scope.workspace !== workspaceRoot)
+            if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id) || bundle.execution.snapshot().scope.workspace !== workspaceRoot)
                 throw new AppError("memory_repair_scope_invalid", "Repair workspace does not match its frozen memory RUN", 2, { phase: "prepare", effect: "no_effect" });
         }
         if (subcommand === "current-view")
@@ -2455,14 +2494,13 @@ function dispatchMemory(context, command, parsed, prepared) {
             if (error instanceof AppError && (error.code === "memory_stage_result_invalid"
                 || error.code === "memory_preflight_handler_invalid" && ["unselected_preflight_source", "proposed_source_sha256_mismatch"].includes(String(error.details.reason))) && error.details.phase === "prepare"
                 && error.details.effect === "no_effect" && error.details.recoverable === true) {
-                error.details.retry_command = runtimeCommand(context, ["memory", "compose", "register", "--run", requiredOption(parsed, "run"),
-                    "--project-root", requiredOption(parsed, "project-root"), "--request-key", requiredOption(parsed, "request-key"),
-                    "--result-file", requiredOption(parsed, "result-file"), "--json", "--progress-jsonl"]);
-                error.details.retry_instruction = "Correct only the rejected composition proposal, then execute retry_command in this same Session. No Work graph was registered by this rejected call; do not dispatch children or finish the Stage until registration succeeds.";
+                Object.assign(error.details, compositionProposalRetry(context, parsed));
             }
             throw error;
         }
     }
+    if (command === "upgrade" && subcommand === "publish")
+        return publishMemoryUpgradeFromStage(context, scope());
     if (command === "verify" && subcommand === "checks")
         return runMemoryVerificationChecks(context, scope());
     if (command === "review" && subcommand === "register")

package/dist/cli/setup.js

@@ -129,7 +129,8 @@ export async function runSetupCli(args, env, io = { stdout: process.stdout, stde
                     throw error;
                 }
             }
-            result = { ...installed, action: route.key === "setup update" ? "setup_update" : "setup_install", observed_cli: observedCli,
+            result = { ...installed, request_installation: installed.installation,
+                action: route.key === "setup update" ? "setup_update" : "setup_install", observed_cli: observedCli,
                 executor: installed.executor ? { profile_id: installed.executor.id, revision: hybridDigest(installed.executor), readiness: "unknown_requires_qualification" } : { profile_id: null, readiness: "not_configured" },
                 ...readSetupStatus(home) };
         }

package/dist/cli.js

@@ -49,10 +49,22 @@ if (args[0] === "init" || args[0] === "flow" && args[1] === "mb-init") {
     publishSetup('imports_ready');
     process.exit(await runMemoryInitCli(args, process.env));
 }
+if (args[0] === "upgrade" || args[0] === "flow" && args[1] === "mb-upgrade") {
+    const { runMemoryUpgradeCli } = await import("./cli/memory-upgrade.js");
+    process.exit(await runMemoryUpgradeCli(args, process.env));
+}
 if (args.slice(0, 3).join(" ") === "runtime storage admit") {
     const { runMemoryStorageAdmissionCli } = await import("./cli/memory-storage-admission.js");
     process.exit(runMemoryStorageAdmissionCli(args));
 }
+if (args.slice(0, 3).join(" ") === "runtime storage qualify") {
+    const { runMemoryStorageQualificationCli } = await import("./cli/memory-storage-qualification.js");
+    process.exit(runMemoryStorageQualificationCli(args));
+}
+if (args.slice(0, 3).join(" ") === "runtime storage transition") {
+    const { runMemoryStorageTransitionCli } = await import("./cli/memory-storage-transition.js");
+    process.exit(runMemoryStorageTransitionCli(args));
+}
 if (args.slice(0, 3).join(" ") === "runtime flow admit") {
     const { runMemoryFlowAdmissionCli } = await import("./cli/memory-flow-admission.js");
     process.exit(await runMemoryFlowAdmissionCli(args));

package/dist/domain/stage-handler-identities.js

@@ -18,3 +18,11 @@ export const memoryInitHandlerIdentities = Object.freeze({
     review: Object.freeze({ stage: "review", entryId: "memory-stage-entry", finishId: "memory-stage-finish" }),
     finish: Object.freeze({ stage: "finish", entryId: "memory-stage-entry", finishId: "memory-stage-finish" })
 });
+export const memoryUpgradeHandlerIdentities = Object.freeze({
+    preflight: Object.freeze({ stage: "preflight", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" }),
+    "diff-analysis": Object.freeze({ stage: "diff-analysis", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" }),
+    upgrade: Object.freeze({ stage: "upgrade", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" }),
+    verify: Object.freeze({ stage: "verify", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" }),
+    review: Object.freeze({ stage: "review", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" }),
+    finish: Object.freeze({ stage: "finish", entryId: "memory-upgrade-stage-entry", finishId: "memory-upgrade-stage-finish" })
+});

package/dist/harness-runtime/bin/dd-agy.mjs

@@ -23,7 +23,7 @@ async function hook(options) {
     const normalized = { schema_id: "dd-flow/agy-tool-event@1", event_id: identity.event_id, phase, daemon_id: identity.daemon_id, launch_cwd: identity.launch_cwd, conversation_id: payload.conversationId, parent_conversation_id: identity.parent_conversation_id, execution_num: payload.executionNum, step_index: payload.stepIdx, tool: payload.toolCall?.name, input: args, workspace_paths: payload.workspacePaths, transcript_path: payload.transcriptPath, model: payload.modelName, profile: identity.profile, ...(phase === "after" ? { error: payload.error ?? "" } : {}) };
     await invokeNativeHook({ bin: options["dd-flow-bin"] ?? identity.dd_flow_bin,
       args: ["agy", "event", "handle", "--project-root", options["project-root"] ?? identity.project_root, "--json"],
-      payload: normalized, home: options["dd-flow-home"] ?? identity.dd_flow_home, timeoutMs: budget.remaining("admission", 15_000) });
+      payload: normalized, home: options["dd-flow-home"] ?? identity.dd_flow_home, timeoutMs: budget.remaining("admission") });
   }
   return event === "PreToolUse" ? { decision: "allow" } : {};
   } catch (error) {
@@ -31,8 +31,8 @@ async function hook(options) {
     // reads only receipts matching request IDs it actually accepted this turn.
     const correctable = event === "PreToolUse" && error.code === "lifecycle_shell_syntax_invalid" && error.details?.effect === "no_effect"
       && error.details?.recoverable === true && error.details?.disposition === "pre_cli_shell_refusal";
-    try { await writeJsonAtomic(path.join(options["state-dir"], "hook-failures", `${requestId}.json`), { request_id: requestId, observed_at: new Date().toISOString(), code: error.code ?? "agy_hook_rejected", message: error.message,
-      details: { ...error.details, effect: correctable ? "no_effect" : "unknown", ...(correctable ? { native_pre_cli_refusal: true } : {}) } }); }
+    try { await budget.run(() => writeJsonAtomic(path.join(options["state-dir"], "hook-failures", `${requestId}.json`), { request_id: requestId, observed_at: new Date().toISOString(), code: error.code ?? "agy_hook_rejected", message: error.message,
+      details: { ...error.details, effect: correctable ? "no_effect" : "unknown", ...(correctable ? { native_pre_cli_refusal: true } : {}) } }, () => budget.remaining("failure_receipt_commit")), "failure_receipt"); }
     catch (storage) { process.stderr.write(`${JSON.stringify({ code: error.code, receipt_error: storage.message })}\n`); }
     throw error;
   }

package/dist/harness-runtime/bin/dd-grok.mjs

@@ -12,12 +12,12 @@ async function hook(options) {
   const budget = hookBudget();
   const stdin = await readNativeHookInput(process.stdin, budget); const payload = JSON.parse(stdin || "{}"); const identity = await callDaemon(options["state-dir"], "hook.resolve", { sessionId: payload.sessionId ?? payload.session_id, payload }, budget.remaining("identity"));
   const enriched = { ...payload, _meta: { ...(payload._meta ?? {}), ddGrok: identity } }; const args = ["grok", "event", "handle", "--project-root", options["project-root"], "--json"]; const command = options["dd-flow-bin"];
-  try { return await invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], payload: enriched, timeoutMs: budget.remaining("admission", 15_000) }); }
+  try { return await invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], payload: enriched, timeoutMs: budget.remaining("admission") }); }
   catch (error) {
     if (identity.nativeHookBinding) error.details = { ...error.details, native_hook_binding: identity.nativeHookBinding };
     try {
-      await writeNativeHookFailure(options["state-dir"], identity.nativeHookBinding, error, hookBudget(1_000, null));
-      if (identity.nativeHookBinding) await callDaemon(options["state-dir"], "hook.failed", { requestId: identity.nativeHookBinding.request_id }, 1_000);
+      await writeNativeHookFailure(options["state-dir"], identity.nativeHookBinding, error, budget);
+      if (identity.nativeHookBinding) await callDaemon(options["state-dir"], "hook.failed", { requestId: identity.nativeHookBinding.request_id }, budget.remaining("failure_notification"));
     } catch (storage) { process.stderr.write(`${JSON.stringify({ code: error.code, receipt_error: storage.message })}\n`); }
     throw error;
   }

package/dist/harness-runtime/bin/dd-zcode.mjs

@@ -37,14 +37,14 @@ async function hook(options) {
   const identity = await callDaemon(options["state-dir"], "hook.resolve", { sessionId: payload.session_id ?? payload.sessionId, payload }, budget.remaining("identity"));
   const command = options["dd-flow-bin"]; const args = ["zcode", "hook", "handle", "--project-root", options["project-root"], "--json"];
 
-  try { return await invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], timeoutMs: budget.remaining("admission", 15_000), payload: { ...payload, _meta: { ...(payload._meta ?? {}), ddZcode: identity } } }); }
+  try { return await invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], timeoutMs: budget.remaining("admission"), payload: { ...payload, _meta: { ...(payload._meta ?? {}), ddZcode: identity } } }); }
   catch (error) {
     if (identity.nativeHookBinding) error.details = { ...error.details, native_hook_binding: identity.nativeHookBinding };
     try {
-      // The 25s work budget leaves this bounded 2s evidence tail inside the
-      // qualified 30s native hook limit, even after the work deadline expired.
-      await writeNativeHookFailure(options["state-dir"], identity.nativeHookBinding, error, hookBudget(1_000, null));
-      if (identity.nativeHookBinding) await callDaemon(options["state-dir"], "hook.failed", { requestId: identity.nativeHookBinding.request_id }, 1_000);
+      // Evidence shares the original deadline; an expired admission cannot
+      // start a new independent failure-report window.
+      await writeNativeHookFailure(options["state-dir"], identity.nativeHookBinding, error, budget);
+      if (identity.nativeHookBinding) await callDaemon(options["state-dir"], "hook.failed", { requestId: identity.nativeHookBinding.request_id }, budget.remaining("failure_notification"));
     } catch (storage) { process.stderr.write(`${JSON.stringify({ code: error.code, receipt_error: storage.message })}\n`); }
     throw error;
   }

package/dist/harness-runtime/lib/agy-error-boundary.mjs

@@ -0,0 +1,58 @@
+import { parseLifecycleCommand, commandOption, commandPosition } from "./lifecycle-command.mjs";
+import { entityReferenceVariants } from "./entity-references.mjs";
+
+/** Ordered native transcript evidence, never assistant text as a success signal. */
+export function recoveredAgyErrorBoundary(text, error, floor = -1) {
+  let rows;
+  try { rows = text.trim().split("\n").filter(Boolean).map(JSON.parse); } catch { return null; }
+  let previous = -1, lastError = null, boundary = null, invocation = null;
+  for (const row of rows) {
+    if (!Number.isInteger(row.step_index) || row.step_index <= previous) return null;
+    previous = row.step_index;
+    if (row.step_index <= (floor ?? -1)) continue;
+    if (row.type === "USER_INPUT") { lastError = null; boundary = null; invocation = null; continue; }
+    if (row.type === "ERROR_MESSAGE") { lastError = row; boundary = null; invocation = null; continue; }
+    if (Array.isArray(row.tool_calls)) {
+      invocation = null;
+      if (row.tool_calls.length === 1 && row.tool_calls[0]?.name === "run_command") {
+        let command = row.tool_calls[0]?.args?.CommandLine;
+        if (typeof command === "string") {
+          try { const unquoted = JSON.parse(command); if (typeof unquoted === "string") command = unquoted; } catch { /* ordinary shell bytes */ }
+          const parsed = parseLifecycleCommand(command);
+          if ((parsed.kind === "standalone" || parsed.kind === "compound" && parsed.supported === true && parsed.invocations?.length === 1) && ["stage_finish", "work_finish", "stage_pause", "recovery_accept"].includes(parsed.invocation.operation)) invocation = parsed.invocation;
+        }
+      }
+    }
+    if (!lastError || row.type !== "GENERIC" || row.status !== "DONE" || typeof row.content !== "string" || !row.content.includes("Command exited with code 0.")) continue;
+    const output = row.content.split("Command output:\n")[1]?.replaceAll("\r", "");
+    if (!output) continue;
+    for (const match of output.matchAll(/^\s*\{/gm)) {
+      let receipt;
+      const candidate = output.slice(match.index).trim();
+      try { receipt = JSON.parse(candidate); } catch {
+        // AGY's transcript renderer can unescape control characters inside
+        // pause.user_message. Parse only the intact machine header, never the
+        // rendered question; the controller must still verify the DB receipt.
+        const end = candidate.indexOf(',\n    "user_message":');
+        if (end < 0) continue;
+        try { receipt = JSON.parse(`${candidate.slice(0, end)}}}`); } catch { continue; }
+      }
+      if (receipt.ok === true && invocation && invocation.operation !== "stage_pause") {
+        if (invocation.operation === "recovery_accept" && receipt.accepted === true && typeof receipt.recovery_id === "string") boundary = { receipt: { ok: true, outcome: "completed", lifecycle_operation: "recovery_accept", recovery_id: receipt.recovery_id }, error_step: lastError.step_index, boundary_step: row.step_index };
+        const stage = receipt.stage ?? commandOption(invocation, "stage");
+        const runId = receipt.run_id;
+        const workId = receipt.work_id ?? receipt.work?.work_id ?? commandOption(invocation, "work") ?? (invocation.operation === "work_finish" ? commandPosition(invocation, 0) : null);
+        if (invocation.operation === "work_finish" && receipt.status === "completed" && typeof workId === "string") boundary = { receipt: { ok: true, outcome: "completed", work_id: workId, lifecycle_operation: "work_finish" }, error_step: lastError.step_index, boundary_step: row.step_index };
+        if (typeof stage === "string" && typeof runId === "string" && (invocation.operation === "work_finish" || entityReferenceVariants(runId).includes(commandPosition(invocation, 0)))) {
+          boundary = { receipt: { ok: true, outcome: "completed", run_id: runId, stage, ...(workId ? { work_id: workId } : {}), lifecycle_operation: invocation.operation }, error_step: lastError.step_index, boundary_step: row.step_index };
+        }
+      }
+      if (invocation?.operation === "stage_pause" && commandOption(invocation, "stage") === receipt.stage && receipt.ok === true && receipt.outcome === "paused"
+        && [receipt.run_id, receipt.stage, receipt.work_id].every(value => typeof value === "string" && value)
+        && (receipt.outcome !== "paused" || typeof receipt.pause?.id === "string")) boundary = { receipt: { ok: true, outcome: receipt.outcome, run_id: receipt.run_id, stage: receipt.stage, work_id: receipt.work_id,
+          lifecycle_operation: "stage_pause", pause: { id: receipt.pause.id } }, error_step: lastError.step_index, boundary_step: row.step_index };
+    }
+  }
+  return boundary && lastError?.error === error ? boundary : null;
+}
+