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

package/dist/services/release-provenance.js

@@ -0,0 +1,160 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { inspectReleaseArchive } from "./release-archive.js";
+import { produceReleaseArchive } from "./release-archive-producer.js";
+function refuse(reason) {
+    throw new AppError("release_provenance", "Producer source provenance cannot be verified", 1, { reason, phase: "release_production", effect: "no_effect" });
+}
+function gitBytes(directory, args, maxBuffer = 1024 * 1024, input) {
+    const env = { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: process.platform === "win32" ? "NUL" : "/dev/null" };
+    for (const name of Object.keys(env))
+        if (name.startsWith("GIT_") && !["GIT_OPTIONAL_LOCKS", "GIT_CONFIG_NOSYSTEM", "GIT_CONFIG_GLOBAL"].includes(name))
+            delete env[name];
+    const result = spawnSync("git", ["-c", "core.fsmonitor=false", "-c", "core.untrackedCache=false", ...args], {
+        cwd: directory, env, timeout: 10_000, maxBuffer, input
+    });
+    if (result.status !== 0 || result.error)
+        refuse("git_source_unavailable");
+    return result.stdout;
+}
+/** Read-only source/tag verification. No fetch, tag creation, commit or cleanup. */
+export function verifyProducerSource(root, source, version) {
+    if (!source || !/^[a-f0-9]{40}$/.test(source.commit) || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(source.repository)
+        || !/^[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?$/.test(version)
+        || (source.kind !== "source_checkout" && source.kind !== "published_release")
+        || (source.kind === "source_checkout" ? source.tag !== null : source.tag !== `v${version}`))
+        refuse("invalid_source_identity");
+    let directory;
+    try {
+        directory = fs.realpathSync(root);
+    }
+    catch {
+        return refuse("source_unavailable");
+    }
+    const git = (args) => gitBytes(directory, args).toString("utf8").trim();
+    const top = git(["rev-parse", "--show-toplevel"]);
+    try {
+        if (fs.realpathSync(top) !== directory)
+            refuse("source_root_mismatch");
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("source_root_mismatch");
+    }
+    const origin = git(["remote", "get-url", "origin"]);
+    if (![`https://github.com/${source.repository}`, `https://github.com/${source.repository}.git`, `git@github.com:${source.repository}.git`, `ssh://git@github.com/${source.repository}.git`].includes(origin))
+        refuse("source_repository_mismatch");
+    if (git(["status", "--porcelain", "--untracked-files=all"]))
+        refuse("source_not_clean");
+    const commit = git(["rev-parse", "HEAD"]), tree = git(["rev-parse", "HEAD^{tree}"]);
+    if (commit !== source.commit)
+        refuse("source_commit_mismatch");
+    if (readBoundedReleaseFile(path.join(directory, "VERSION"), 1024).toString("utf8").trim() !== version)
+        refuse("source_version_mismatch");
+    if (source.tag && git(["rev-parse", "--verify", `refs/tags/${source.tag}^{commit}`]) !== commit)
+        refuse("source_tag_mismatch");
+    return { commit, tree, version };
+}
+/** Exact committed release tree, with only the four canon directory aliases
+ * materialized as regular files. No mutable worktree reads or export filters.
+ */
+function committedBlobs(root, commit) {
+    if (!/^[a-f0-9]{40}$/.test(commit))
+        refuse("invalid_source_identity");
+    const blobs = new Map();
+    const links = [];
+    const listing = gitBytes(root, ["ls-tree", "-rz", "--full-tree", commit], 16 * 1024 * 1024).toString("utf8");
+    for (const record of listing.split("\0").filter(Boolean)) {
+        const match = /^(100644|100755|120000) blob ([a-f0-9]{40})\t(.+)$/.exec(record);
+        if (!match)
+            refuse("unsupported_committed_tree_entry");
+        const mode = match[1], hash = match[2], name = match[3];
+        if (mode === "120000")
+            links.push({ name, hash });
+        else
+            blobs.set(name, { hash, executable: mode === "100755" });
+    }
+    const aliases = { code: "mb-sdlc/code", plan: "mb-sdlc/plan", merge: "mb-sdlc/merge", specify: "mb-sdlc/specify" };
+    for (const link of links) {
+        const match = /^(\.memory-bank\/)?dd-flow\/(code|plan|merge|specify)$/.exec(link.name);
+        if (!match)
+            refuse("unreviewed_committed_alias");
+        const target = gitBytes(root, ["cat-file", "blob", link.hash]).toString("utf8");
+        if (target !== aliases[match[2]])
+            refuse("unreviewed_committed_alias");
+        const targetPrefix = `${path.posix.dirname(link.name)}/${target}/`;
+        const children = [...blobs].filter(([name]) => name.startsWith(targetPrefix));
+        if (!children.length)
+            refuse("empty_committed_alias");
+        for (const [name, blob] of children) {
+            const alias = `${link.name}/${name.slice(targetPrefix.length)}`;
+            if (blobs.has(alias))
+                refuse("committed_alias_collision");
+            blobs.set(alias, blob);
+        }
+    }
+    return blobs;
+}
+export function verifyCanonArchiveSource(root, commit, identity, compressed) {
+    const blobs = committedBlobs(root, commit), entries = inspectReleaseArchive(identity, compressed);
+    const roots = new Set(entries.map(entry => entry.path.split("/")[0]));
+    if (roots.size !== 1)
+        refuse("canon_archive_root_ambiguous");
+    const prefix = `${[...roots][0]}/`;
+    const directories = new Set();
+    for (const name of blobs.keys()) {
+        const parts = name.split("/");
+        for (let index = 1; index < parts.length; index++)
+            directories.add(parts.slice(0, index).join("/"));
+    }
+    const seen = new Set();
+    for (const entry of entries) {
+        if (entry.path === prefix.slice(0, -1) && entry.kind === "directory")
+            continue;
+        const name = entry.path.slice(prefix.length);
+        if (entry.kind === "directory") {
+            if (!directories.has(name))
+                refuse("canon_archive_extra_entry");
+            continue;
+        }
+        const blob = blobs.get(name);
+        if (!blob)
+            refuse("canon_archive_extra_entry");
+        const hash = createHash("sha1").update(`blob ${entry.bytes.length}\0`).update(entry.bytes).digest("hex");
+        if (hash !== blob.hash || Boolean(entry.mode & 0o111) !== blob.executable)
+            refuse("canon_archive_blob_mismatch");
+        seen.add(name);
+    }
+    if (seen.size !== blobs.size)
+        refuse("canon_archive_missing_entry");
+}
+/** Produce from immutable Git objects in one bounded batch, not worktree files. */
+export function produceCanonArchive(root, commit) {
+    const blobs = committedBlobs(root, commit), hashes = [...new Set([...blobs.values()].map(blob => blob.hash))];
+    const batch = gitBytes(root, ["cat-file", "--batch"], 512 * 1024 * 1024, Buffer.from(hashes.join("\n") + "\n"));
+    const contents = new Map();
+    let offset = 0;
+    for (const hash of hashes) {
+        const newline = batch.indexOf(10, offset);
+        if (newline < 0)
+            refuse("invalid_git_blob_batch");
+        const match = /^([a-f0-9]{40}) blob ([0-9]+)$/.exec(batch.subarray(offset, newline).toString("ascii"));
+        if (!match || match[1] !== hash)
+            refuse("invalid_git_blob_batch");
+        const size = Number(match[2]), end = newline + 1 + size;
+        if (!Number.isSafeInteger(size) || end >= batch.length || batch[end] !== 10)
+            refuse("invalid_git_blob_batch");
+        contents.set(hash, batch.subarray(newline + 1, end));
+        offset = end + 1;
+    }
+    if (offset !== batch.length)
+        refuse("invalid_git_blob_batch");
+    const bytes = produceReleaseArchive([...blobs].map(([name, blob]) => ({ path: `canon/${name}`, bytes: contents.get(blob.hash), executable: blob.executable })));
+    verifyCanonArchiveSource(root, commit, { url: "https://producer.invalid/canon.tgz", bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") }, bytes);
+    return bytes;
+}

package/dist/services/release-registry.js

@@ -0,0 +1,66 @@
+import { valid, prerelease } from "semver";
+import { AppError } from "../shared/errors.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+function refuse(reason) {
+    throw new AppError("release_registry", "Release selection cannot be resolved", 1, { reason, phase: "release_selection", effect: "no_effect", help: "setup" });
+}
+function object(value, keys, required = keys) {
+    if (!value || typeof value !== "object" || Array.isArray(value)
+        || required.some(key => !Object.hasOwn(value, key))
+        || Object.keys(value).some(key => !keys.includes(key)))
+        refuse("invalid_registry_shape");
+    return value;
+}
+/** Operator registry is a selector, not signing authority or qualification evidence. */
+export function selectRegistryRelease(input, channel, version) {
+    if (!["stable", "preview", "development"].includes(channel))
+        refuse("invalid_selected_channel");
+    const registry = object(input, ["schema_id", "releases", "defaults"]);
+    if (registry.schema_id !== "dd-flow/release-registry@1" || !Array.isArray(registry.releases)
+        || registry.releases.length < 1 || registry.releases.length > 10_000)
+        refuse("invalid_registry_shape");
+    const defaults = object(registry.defaults, ["stable", "preview", "development"], []);
+    const entries = new Map();
+    for (const value of registry.releases) {
+        const entry = object(value, ["channel", "version", "envelope_url"]);
+        if (!["stable", "preview", "development"].includes(String(entry.channel))
+            || typeof entry.version !== "string" || valid(entry.version) !== entry.version
+            || (entry.channel === "stable" && prerelease(entry.version)) || typeof entry.envelope_url !== "string")
+            refuse("invalid_registry_entry");
+        let url;
+        try {
+            url = new URL(entry.envelope_url);
+        }
+        catch {
+            return refuse("invalid_registry_url");
+        }
+        if (url.protocol !== "https:" || url.username || url.password || url.hash || (url.port && url.port !== "443"))
+            refuse("invalid_registry_url");
+        const key = `${entry.channel}/${entry.version}`;
+        if (entries.has(key))
+            refuse("duplicate_registry_selection");
+        entries.set(key, { channel: entry.channel, version: entry.version, envelope_url: entry.envelope_url });
+    }
+    for (const [key, selected] of Object.entries(defaults)) {
+        if (typeof selected !== "string" || !entries.has(`${key}/${selected}`))
+            refuse("invalid_registry_default");
+    }
+    const selected = version ?? defaults[channel];
+    if (typeof selected !== "string" || valid(selected) !== selected)
+        refuse("missing_or_invalid_release_version");
+    const entry = entries.get(`${channel}/${selected}`);
+    if (!entry)
+        refuse("release_not_in_selected_channel");
+    return { ...entry };
+}
+export function readRegistryRelease(file, channel, version) {
+    const bytes = readBoundedReleaseFile(file, 4 * 1024 * 1024);
+    let input;
+    try {
+        input = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return refuse("invalid_registry_json");
+    }
+    return selectRegistryRelease(input, channel, version);
+}

package/dist/services/release-source.js

@@ -0,0 +1,194 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createPublicKey } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { authenticateReleaseEnvelope, releaseProducerKeyId } from "./release-envelope.js";
+import { verifyReleaseArchive } from "./release-manifest.js";
+import { downloadReleaseArchive } from "./release-download.js";
+function refuse(reason) {
+    throw new AppError("release_source", "Release source cannot be read", 1, { reason, phase: "release_source", effect: "no_effect", help: "setup" });
+}
+/** Bounded regular-file reads; paths, parser excerpts and key material never enter diagnostics. */
+export function readBoundedReleaseFile(file, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+        refuse("invalid_source_limit");
+    let fd;
+    try {
+        if (!fs.lstatSync(file).isFile())
+            refuse("source_not_regular_file");
+        fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("source_unavailable");
+    }
+    try {
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size < 1 || stat.size > maxBytes)
+            refuse("source_size_outside_limit");
+        const bytes = Buffer.alloc(stat.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const received = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+            if (!received)
+                refuse("source_changed_during_read");
+            offset += received;
+        }
+        if (fs.readSync(fd, Buffer.alloc(1), 0, 1, offset) !== 0)
+            refuse("source_changed_during_read");
+        return bytes;
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("source_unavailable");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function json(bytes) {
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return refuse("invalid_source_json");
+    }
+}
+/** Explicit operator trust input is separate from the release bundle. No implicit key enrollment. */
+export function readTrustedReleaseProducers(file) {
+    const input = json(readBoundedReleaseFile(file, 1024 * 1024));
+    if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).length !== 2 || Object.keys(input).some(key => !["producers", "schema_id"].includes(key)))
+        refuse("invalid_trust_shape");
+    const settings = input;
+    if (settings.schema_id !== "dd-flow/release-trust@1" || !Array.isArray(settings.producers) || settings.producers.length < 1 || settings.producers.length > 100)
+        refuse("invalid_trust_shape");
+    const result = new Map();
+    for (const input of settings.producers) {
+        if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).length !== 3 || Object.keys(input).some(key => !["channels", "public_key_pem", "repository"].includes(key)))
+            refuse("invalid_producer_shape");
+        const producer = input;
+        if (typeof producer.public_key_pem !== "string" || !/^-----BEGIN PUBLIC KEY-----\r?\n[A-Za-z0-9+/=\r\n]+-----END PUBLIC KEY-----\r?\n?$/.test(producer.public_key_pem) ||
+            typeof producer.repository !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(producer.repository) ||
+            !Array.isArray(producer.channels) || producer.channels.length < 1 || producer.channels.length > 3 ||
+            producer.channels.some(channel => !["stable", "preview", "development"].includes(channel)) || new Set(producer.channels).size !== producer.channels.length)
+            refuse("invalid_producer_scope");
+        try {
+            const publicKey = createPublicKey(producer.public_key_pem), id = releaseProducerKeyId(publicKey);
+            if (result.has(id))
+                refuse("duplicate_producer_key");
+            result.set(id, { publicKey, repository: producer.repository, channels: new Set(producer.channels) });
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            return refuse("invalid_producer_key");
+        }
+    }
+    return result;
+}
+/** Authenticate metadata before reading archives; all integrity checks precede installation writes. */
+export function readLocalReleaseBundle(root, producers, compatibility) {
+    try {
+        if (!fs.lstatSync(root).isDirectory())
+            refuse("source_not_directory");
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("source_unavailable");
+    }
+    const envelope = json(readBoundedReleaseFile(path.join(root, "release-envelope.json"), 24 * 1024 * 1024));
+    const authenticated = authenticateReleaseEnvelope(envelope, producers, compatibility);
+    const canonArchive = readBoundedReleaseFile(path.join(root, "canon.tgz"), Math.min(authenticated.manifest.canon.archive.bytes, 256 * 1024 * 1024));
+    const engineArchive = readBoundedReleaseFile(path.join(root, "engine.tgz"), Math.min(authenticated.manifest.engine.archive.bytes, 256 * 1024 * 1024));
+    verifyReleaseArchive(authenticated.manifest.canon.archive, canonArchive);
+    verifyReleaseArchive(authenticated.manifest.engine.archive, engineArchive);
+    return { envelope, authenticated, canonArchive, engineArchive };
+}
+function remoteUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        return refuse("invalid_remote_source");
+    }
+    // The explicit source selects a transport origin, never a signing key.
+    if (url.protocol !== "https:" || url.username || url.password || url.hash || (url.port && url.port !== "443"))
+        refuse("unsafe_remote_source");
+    return url;
+}
+/** Remote metadata is untrusted until signature verification; archives are fetched only afterward.
+ * Redirects, cross-origin artifacts and implicit credential forwarding are never admitted.
+ */
+export async function readRemoteReleaseBundle(source, producers, compatibility, options = {}) {
+    const url = remoteUrl(source), timeoutMs = options.timeoutMs ?? 60_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000)
+        refuse("invalid_source_timeout");
+    const fetcher = options.fetch ?? globalThis.fetch;
+    let response;
+    try {
+        response = await fetcher(url, { redirect: "error", signal: AbortSignal.timeout(timeoutMs), credentials: "omit" });
+    }
+    catch {
+        return refuse("remote_source_unavailable_or_redirect");
+    }
+    if (!response.ok || !response.body) {
+        await response.body?.cancel();
+        return refuse("remote_source_http_failure");
+    }
+    const maxBytes = 24 * 1024 * 1024, length = response.headers.get("content-length");
+    if (length !== null && (!/^[0-9]+$/.test(length) || Number(length) < 1 || Number(length) > maxBytes)) {
+        await response.body.cancel();
+        return refuse("remote_source_size_outside_limit");
+    }
+    const reader = response.body.getReader(), chunks = [];
+    let received = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            received += value.byteLength;
+            if (received > maxBytes) {
+                await reader.cancel();
+                return refuse("remote_source_size_outside_limit");
+            }
+            chunks.push(Buffer.from(value));
+        }
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("remote_source_interrupted");
+    }
+    finally {
+        reader.releaseLock();
+    }
+    if (!received || (length !== null && Number(length) !== received))
+        refuse("remote_source_length_mismatch");
+    const envelope = json(Buffer.concat(chunks, received));
+    const authenticated = authenticateReleaseEnvelope(envelope, producers, compatibility);
+    if (options.expectedVersion !== undefined && authenticated.manifest.version !== options.expectedVersion)
+        refuse("selected_version_mismatch");
+    for (const artifact of [authenticated.manifest.canon.archive, authenticated.manifest.engine.archive]) {
+        if (remoteUrl(artifact.url).origin !== url.origin)
+            refuse("cross_origin_artifact_refused");
+    }
+    const archives = [];
+    for (const artifact of ["canon", "engine"]) {
+        archives.push(await downloadReleaseArchive(authenticated.manifest[artifact].archive, {
+            allowedHosts: new Set([url.hostname]), timeoutMs, fetch: fetcher,
+            ...(options.onProgress ? { onProgress: progress => options.onProgress({ artifact, ...progress }) } : {})
+        }));
+    }
+    return { envelope, authenticated, canonArchive: archives[0], engineArchive: archives[1] };
+}
+/** One source selector for setup/update; local bundles remain fully offline. */
+export async function readReleaseBundle(source, producers, compatibility, options = {}) {
+    if (/^https?:\/\//i.test(source))
+        return readRemoteReleaseBundle(source, producers, compatibility, options);
+    return readLocalReleaseBundle(source, producers, compatibility);
+}

package/dist/services/run-controller.js

@@ -699,6 +699,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 if (manifest.request.capture_root)
                     await captureControllerBoundary(executionContext, row, manifest, completed, null, assertPhysicalOwner);
                 setStatus("stop_target_reached");
+                setFlowRunRecoveryPaused(context, row.project_id, row.run_id, true);
                 appendEvent(context, row.controller_id, "stop_target_reached", { stage: state.stage, attempt: completed.attempt ?? null });
                 return;
             }

package/dist/services/run-health.js

@@ -0,0 +1,149 @@
+import { AppError } from "../shared/errors.js";
+import { managedProcessBinding, managedProcessRuntimeHome, managedProcessStatus, managedProcessObservation, processTreeIsAlive } from "./managed-processes.js";
+import { reconcileStoredFlowRun } from "./runs.js";
+import { recoveryGuard } from "./run-recovery.js";
+import { spawnSync } from "node:child_process";
+function physicalInventory() {
+    const reply = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], { encoding: 'utf8', timeout: 5000 });
+    if (reply.status !== 0)
+        return null;
+    return reply.stdout.trim().split('\n').map(line => line.trim().split(/\s+/)).filter(parts => parts.length === 3).map(parts => ({ pid: Number(parts[0]), group: Number(parts[1]), zombie: parts[2].startsWith('Z') }));
+}
+const terminalRun = (status) => ["done", "failed", "cancelled", "discarded"].includes(status);
+const waiting = new Set(["waiting_for_user", "waiting_for_context", "waiting_for_capacity", "waiting_for_children", "waiting_for_merge", "stop_target_reached", "paused", "control_requested"]);
+const table = (context, name) => Boolean(context.db.get("SELECT 1 FROM sqlite_schema WHERE name = ?", [name]));
+const latest = (values) => values.filter((value) => typeof value === "string" && Number.isFinite(Date.parse(value))).sort((a, b) => Date.parse(b) - Date.parse(a))[0] ?? null;
+/** Evidence only: lease expiry and quiet providers never prove an exit. */
+export function assessRunHealth(input) {
+    const phase = input.phase ?? null;
+    let state = "unknown", reason = "owner_identity_missing";
+    if (terminalRun(input.status)) {
+        state = "settled";
+        reason = "saved_terminal_result";
+    }
+    else if (input.childrenAlive && input.owner === "absent") {
+        state = "owner_lost";
+        reason = "native_children_still_active";
+    }
+    else if (phase === 'recovery_required' || phase === 'capture_failed') {
+        state = input.owner === 'absent' ? 'owner_lost' : 'unknown';
+        reason = phase;
+    }
+    else if (phase && waiting.has(phase) || ["waiting_for_user", "blocked"].includes(input.status)) {
+        state = "waiting";
+        reason = phase ?? input.status;
+    }
+    else if (input.owner === "absent") {
+        state = "owner_lost";
+        reason = "physical_owner_retired";
+    }
+    else if (input.owner === "alive") {
+        const age = input.lastProgress ? Date.parse(input.now) - Date.parse(input.lastProgress) : NaN;
+        state = Number.isFinite(age) && age > input.noProgressMs ? "no_progress" : "active";
+        reason = state === "no_progress" ? "progress_overdue" : "physical_owner_observed";
+    }
+    else if (input.status === "paused") {
+        state = "waiting";
+        reason = "saved_pause";
+    }
+    return { schema_id: "dd-flow/run-health@1", state, reason, phase, owner_state: input.owner, last_progress_at: input.lastProgress ?? null, last_heartbeat_at: input.heartbeat ?? null, observed_at: input.now, controller_id: input.controllerId ?? null, generation: input.generation ?? null, no_progress_ms: input.noProgressMs };
+}
+/** No dispatch, cancellation, process signals or provider calls. All changes
+ * are fenced by the retained RUN revision, controller and process binding. */
+export function reconcileFlowRunHealth(context, input = {}) {
+    const noProgressMs = input.noProgressMs ?? 30 * 60_000;
+    if (!Number.isSafeInteger(noProgressMs) || noProgressMs < 1_000)
+        throw new AppError("usage", "no-progress-ms must be an integer of at least 1000", 2);
+    const runs = context.db.all(`SELECT * FROM runs${input.runId ? " WHERE (id = ? OR short_id = ?)" : ""}`, input.runId ? [input.runId, input.runId] : []).filter(run => !input.projectRoot || run.project_root === input.projectRoot);
+    if (input.runId && runs.length !== 1)
+        throw new AppError("not_found", "RUN scope is missing or ambiguous", 1);
+    const processes = physicalInventory();
+    const alive = (record) => {
+        if (!record.pid)
+            return !['stopped', 'failed'].includes(record.state);
+        const physical = processes?.find(item => item.pid === record.pid);
+        if (processes && (!physical || physical.zombie)) {
+            const metadata = JSON.parse(record.metadata_json);
+            // A retired group leader may still own physical children. Merely ending
+            // the controller does not settle those children or remote provider work.
+            return Boolean(metadata.process_group_id && processes.some(item => item.group === metadata.process_group_id && !item.zombie));
+        }
+        return !record.pid_started_at || processTreeIsAlive(record);
+    };
+    return { ok: true, results: runs.map(run => {
+            const index = JSON.parse(run.index_json);
+            const controllers = table(context, "run_controllers") ? context.db.all("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? ORDER BY generation DESC, created_at DESC", [run.project_id, run.id]) : [];
+            const controller = controllers[0];
+            const manifest = controller ? JSON.parse(controller.manifest_json) : null;
+            const resourceContext = manifest?.resource_home ? { ...context, env: { ...context.env, DD_FLOW_RESOURCE_HOME: manifest.resource_home } } : context;
+            let records = [], inventoryComplete = false;
+            try {
+                records = managedProcessStatus(resourceContext).filter(record => record.project_id === run.project_id && record.run_id === run.id && managedProcessRuntimeHome(record, context) === context.ddFlowHome);
+                inventoryComplete = true;
+            }
+            catch { /* Missing registry is uncertainty, never retirement proof. */ }
+            const physical = controller && records.find(record => record.id === controller.process_id && record.lease_token === controller.process_lease_token && record.owner_id === controller.controller_id && record.kind === "run-controller");
+            const owner = physical?.pid && physical.pid_started_at ? processes && !processes.some(item => item.pid === physical.pid && !item.zombie) && !alive(physical) ? 'absent' : managedProcessObservation(physical) : "unknown";
+            const retireController = Boolean(controller && owner === 'absent' && !['completed', 'cancelled', 'superseded', 'stop_target_reached', 'recovery_required', 'capture_failed', 'waiting_for_user', 'waiting_for_context', 'control_requested', 'paused'].includes(controller.status));
+            const phase = retireController ? 'recovery_required' : controller?.status ?? null;
+            const childrenAlive = records.some(record => record.id !== physical?.id && alive(record)) || Boolean(physical && owner === 'absent' && alive(physical));
+            const progressEvent = controller && table(context, "run_controller_events") ? context.db.get("SELECT MAX(created_at) AS at FROM run_controller_events WHERE controller_id = ? AND event_type NOT IN ('health_reconciled','heartbeat')", [controller.controller_id])?.at : null;
+            const workProgress = table(context, "works") ? context.db.get("SELECT MAX(at) AS at FROM (SELECT created_at AS at FROM works WHERE project_id=? AND run_id=? UNION ALL SELECT started_at FROM works WHERE project_id=? AND run_id=? UNION ALL SELECT completed_at FROM works WHERE project_id=? AND run_id=?)", [run.project_id, run.id, run.project_id, run.id, run.project_id, run.id])?.at : null;
+            let hookProgress = null;
+            if (table(context, 'hook_events') && table(context, 'sessions'))
+                try {
+                    hookProgress = context.db.get("SELECT MAX(h.created_at) AS at FROM hook_events h JOIN sessions s ON s.session_id=h.session_id AND s.project_id=h.project_id WHERE s.project_id=? AND s.run_id=? AND h.event_name IN ('PostToolUse','UserPromptSubmit','SubagentStop','Stop','SessionStart')", [run.project_id, run.id])?.at ?? null;
+                }
+                catch { /* Legacy hooks have no certified Run membership. */ }
+            const lastProgress = latest([run.created_at, progressEvent, workProgress, hookProgress, ...index.stage_runs.flatMap(stage => [stage.started_at, stage.completed_at])]);
+            const policy = input.noProgressMs ?? (phase === 'starting' ? 120_000 : phase === 'capturing' ? 300_000 : 30 * 60_000);
+            const health = assessRunHealth({ status: run.status, phase, owner, childrenAlive, lastProgress, heartbeat: physical?.updated_at ?? null, now: context.now(), noProgressMs: policy, controllerId: controller?.controller_id ?? null, generation: controller?.generation ?? null });
+            if (terminalRun(run.status) && (childrenAlive || owner === "alive")) {
+                health.state = "unknown";
+                health.reason = "terminal_result_has_live_runtime";
+            }
+            const sessionState = controller ? JSON.parse(controller.state_json) : null;
+            const nativeSettled = Boolean(sessionState?.sessions.length && sessionState.sessions.every(session => session.stopped === true));
+            const outcomeUnknown = controller && table(context, "run_controller_operations") && context.db.get("SELECT 1 FROM run_controller_operations WHERE controller_id = ? AND generation = ? AND status IN ('accepted','outcome_unknown') LIMIT 1", [controller.controller_id, controller.generation]);
+            let transition;
+            const guard = table(context, 'run_recovery_guards') ? recoveryGuard(context, run.project_id, run.id) : null;
+            const currentGeneration = !guard || !controller || controller.generation === guard.generation;
+            if (!terminalRun(run.status) && currentGeneration) {
+                if (controller && ["recovery_required", "capture_failed"].includes(controller.status))
+                    transition = "paused";
+                else if (controller?.status === "stop_target_reached" && owner !== "alive" && nativeSettled && inventoryComplete && !childrenAlive)
+                    transition = "paused";
+                else if (health.state === "owner_lost" && owner === "absent") {
+                    transition = controller?.last_error_json && nativeSettled && inventoryComplete && !childrenAlive && !outcomeUnknown && !guard ? "failed" : "paused";
+                }
+            }
+            const nextStatus = transition ?? run.status;
+            if (transition === 'failed') {
+                health.state = 'settled';
+                health.reason = 'saved_terminal_result';
+            }
+            const unchanged = index.health && JSON.stringify({ ...index.health, observed_at: null }) === JSON.stringify({ ...health, observed_at: null }) && nextStatus === run.status;
+            let changed = false;
+            if (input.apply && !unchanged) {
+                // Verify the same physical inventory immediately before publishing. A
+                // replacement/renewal invalidates this observation, even with the same PID.
+                const binding = (items) => JSON.stringify(items.map(item => ({ ...managedProcessBinding(item, manifest?.resource_home ?? context.ddFlowHome), state: item.state, updated_at: item.updated_at, lease_expires_at: item.lease_expires_at })));
+                if (inventoryComplete) {
+                    const fresh = managedProcessStatus(resourceContext).filter(record => record.project_id === run.project_id && record.run_id === run.id && managedProcessRuntimeHome(record, context) === context.ddFlowHome);
+                    if (binding(fresh) !== binding(records) || physical && owner === "absent" && managedProcessObservation(physical) !== 'absent')
+                        throw new AppError("run_health_changed", "Runtime ownership changed during reconciliation", 1);
+                }
+                context.db.writeTransaction(() => {
+                    const current = controller && context.db.get("SELECT * FROM run_controllers WHERE controller_id = ?", [controller.controller_id]);
+                    if (controller && JSON.stringify(current) !== JSON.stringify(controller))
+                        throw new AppError("run_health_changed", "Controller changed during reconciliation", 1);
+                    reconcileStoredFlowRun(context, run, health, transition, inventoryComplete && owner !== "alive" && !childrenAlive && nativeSettled);
+                    if (controller && retireController) {
+                        context.db.run("UPDATE run_controllers SET status = 'recovery_required', updated_at = ? WHERE controller_id = ? AND owner_token = ? AND generation = ?", [context.now(), controller.controller_id, controller.owner_token, controller.generation]);
+                    }
+                    changed = true;
+                });
+            }
+            return { project_id: run.project_id, run_id: run.id, previous_status: run.status, status: nextStatus, health, changed, would_change: !unchanged };
+        }) };
+}