akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

package/dist/core/standards/resolve-standards-context.js

@@ -28,24 +28,12 @@ function refType(ref) {
     const body = ref.includes("//") ? ref.slice(ref.indexOf("//") + 2) : ref;
     // 0.9.0 conceptId `<stash-subdir>/<name>`: delegate to the D-R2 reverse table
     // so the leading stash subdir maps back to its asset type (the canonical path).
-    const conceptType = typeNameFromConceptId(body)?.type;
-    if (conceptType !== undefined)
-        return conceptType;
-    // DOCUMENTED EXCEPTION (ref-grammar decision D-R3 migration window): a tolerant
-    // legacy `type:name` arm survives ONLY because live callers still hand this
-    // recognition-only seam the old spelling — `propose.ts` builds
-    // `${options.type}:${options.name}`, and a pre-migration stored ref may still
-    // reach here before the 0.10.0 grammar removal. It never crosses a storage
-    // boundary, so it stays until those feeders flip.
-    const colon = body.indexOf(":");
-    if (colon > 0)
-        return body.slice(0, colon).trim() || undefined;
-    return undefined;
+    return typeNameFromConceptId(body)?.type;
 }
 /**
  * Resolve the standards context for a write target identified by its asset ref.
  *
- * @param ref       Canonical asset ref of the write target (e.g. `skill:foo`).
+ * @param ref       Canonical asset ref of the write target (e.g. `skills/foo`).
  *                  When undefined, the target is a general authoring flow.
  * @param stashRoot Stash root directory.
  */

package/dist/core/standards/resolve-stash-standards.js

@@ -53,14 +53,14 @@ function collectMarkdownFiles(dir) {
     return results;
 }
 /**
- * Derive a fact ref (`fact:conventions/naming`) from an absolute markdown path
+ * Derive a fact ref (`facts/conventions/naming`) from an absolute markdown path
  * relative to the facts root. Mirrors the canonical-name derivation in
  * `asset-spec.ts` (POSIX separators, `.md` stripped).
  */
 function toFactRef(factsRoot, absPath) {
     const rel = path.relative(factsRoot, absPath).split(path.sep).join("/");
     const name = rel.endsWith(".md") ? rel.slice(0, -3) : rel;
-    return `fact:${name}`;
+    return `${FACTS_SUBDIR}/${name}`;
 }
 export function resolveStashStandards(stashRoot) {
     const factsRoot = path.join(stashRoot, FACTS_SUBDIR);

package/dist/core/standards/resolve-type-conventions.js

@@ -28,9 +28,9 @@ import { placementTypes } from "../asset/asset-placement.js";
 import { parseFrontmatter } from "../asset/frontmatter.js";
 /** Sub-path (under the stash root) for per-type SOFT convention facts. */
 export const TYPE_CONVENTIONS_SUBDIR = path.join("facts", "conventions", "assets");
-/** The `fact:` ref prefix for a per-type convention, e.g. `fact:conventions/assets/skill`. */
+/** The slash conceptId for a per-type convention, e.g. `facts/conventions/assets/skill`. */
 export function typeConventionRef(type) {
-    return `fact:conventions/assets/${type}`;
+    return `facts/conventions/assets/${type}`;
 }
 /**
  * Read the SOFT authoring-convention body for asset type `type`, if a stash

package/dist/core/state/migrations.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { runMigrations as runSqliteMigrations } from "../../storage/engines/sqlite-migrations.js";
+import { assertMigrationRegistry, runMigrations as runSqliteMigrations, } from "../../storage/engines/sqlite-migrations.js";
 export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
     {
@@ -59,7 +59,7 @@ export const STATE_MIGRATIONS = [
       --   id          TEXT PK     — UUID (crypto.randomUUID()); stable directory name.
       --   stash_dir   TEXT        — absolute stash root; multi-stash installs need
       --                             this to partition proposal lists per stash.
-      --   ref         TEXT        — target asset ref (e.g. "lesson:alpha");
+      --   ref         TEXT        — target asset ref (e.g. "lessons/alpha");
       --                             indexed for ref-scoped queue views.
       --   status      TEXT        — "pending" | "accepted" | "rejected"; indexed
       --                             so pending-queue queries are fast.
@@ -76,7 +76,7 @@ export const STATE_MIGRATIONS = [
       --   metadata_json TEXT      — JSON object for future proposal fields.
       --                             Current fields stored here: sourceRun,
       --                             review, confidence, gateDecision (#577),
-      --                             backupContent, eligibilitySource.
+      --                             backupContent.
       --
       -- ADD COLUMN extension points (future migrations):
       --   ALTER TABLE proposals ADD COLUMN source_run TEXT DEFAULT NULL;
@@ -350,11 +350,12 @@ export const STATE_MIGRATIONS = [
     //
     // VESTIGIAL as of the Chunk-8 fold: the legacy `proposal.json` import moved
     // OUT of the live per-operation path and INTO the one-time migrator
-    // (`src/migrate/legacy/proposal-fs-import.ts`, wired through `akm migrate apply`),
+    // (`scripts/akm-migrate/migrate/legacy/proposal-fs-import.ts`, wired through
+    // `akm-migrate apply`),
     // whose idempotency is INSERT OR IGNORE on the proposal UUID plus migrate-apply's
-    // own journal — it no longer reads or writes this ledger. The CREATE TABLE
-    // stays because the migration registry is APPEND-ONLY and checksum-sealed:
-    // removing a released fragment would make the schema_migrations ledger of an
+    // incomplete sentinel — it no longer reads or writes this ledger. The CREATE TABLE
+    // stays because migration IDs are append-only: removing a released migration
+    // would make the schema_migrations ledger of an
     // already-migrated rc database stop being an exact ordered prefix, and the
     // runner would refuse to open it. The empty table is harmless.
     //
@@ -832,17 +833,17 @@ export const STATE_MIGRATIONS = [
     //
     // The state.db half of the three-DB merge (plan §3.2/§8, normative §11.4,
     // chunk-8 cutover design §1). This migration is PURE,
-    // SEALABLE, IDEMPOTENT DDL ONLY — `CREATE TABLE IF NOT EXISTS` (+ indexes),
+    // IDEMPOTENT DDL ONLY — `CREATE TABLE IF NOT EXISTS` (+ indexes),
     // never a DROP or a data move. The actual data movement (the workflow.db merge,
     // the usage_events rescue from index.db, the full old-ref→item_ref re-key, and
-    // the workflow.db delete / index.db quarantine) is CODE — a journaled step of
-    // the migrate-apply flow (`src/cli/config-migrate.ts` `cutover-applied` phase),
-    // driven by `src/migrate/legacy/three-db-cutover.ts`. See the no-DROP contract
-    // carve-out note in `src/core/state-db.ts`.
+    // the workflow.db delete / index.db quarantine) is idempotent migrate-apply
+    // code driven by
+    // `scripts/akm-migrate/migrate/legacy/three-db-cutover.ts`. See the no-DROP
+    // contract carve-out note in `src/core/state-db.ts`.
     //
     // The three workflow tables are the 10 pre-cutover workflow migrations
-    // (the frozen `src/migrate/legacy/workflow-migrations-bodies.ts` base schema +
-    // 001–010) folded into one baseline at their FINAL post-010 shape — column
+    // (the frozen `scripts/akm-migrate/migrate/legacy/workflow-migrations-bodies.ts`
+    // base schema + 001–010) folded into one baseline at their FINAL post-010 shape — column
     // lists, CHECK constraints, and indexes copied verbatim. `usage_events` mirrors
     // index.db's former `ensureUsageEventsSchema` (`src/indexer/usage/usage-events.ts`),
     // its new durable home. `legacy_state` mirrors `ensureLegacyStateTable`
@@ -958,7 +959,32 @@ export const STATE_MIGRATIONS = [
       );
     `,
     },
+    // ── Migration 021 — asset_salience / asset_outcome: missing_since (#733) ────
+    //
+    // Orphan-GC grace clock (Workstream C / #733,
+    // docs/architecture/specs/0.9.0-close-out-plan.md). Neither table carries a
+    // column that records when a row's ref STOPPED resolving against
+    // `entries.item_ref` — `updated_at` is bumped by improve itself on every
+    // touch, so it cannot double as a "went missing" timestamp.
+    //
+    // `missing_since` is stamped by `runOrphanStateGcPass`
+    // (src/commands/improve/loop-stages.ts) the first time a row's ref fails to
+    // resolve against the live index, cleared the moment the ref resolves
+    // again, and used to gate deletion once `STATE_GC_GRACE_MS` (7 days) has
+    // elapsed — and ONLY when `improve.stateGc.collect` is true (default
+    // false). Mirrors the additive ADD-COLUMN style of migration 011.
+    //
+    // NULL = never missing (the steady-state default for every existing row —
+    // both a fresh row and a pre-migration row read back NULL here).
+    {
+        id: "021-asset-state-missing-since",
+        up: `
+      ALTER TABLE asset_salience ADD COLUMN missing_since INTEGER DEFAULT NULL;
+      ALTER TABLE asset_outcome ADD COLUMN missing_since INTEGER DEFAULT NULL;
+    `,
+    },
 ];
+assertMigrationRegistry(STATE_MIGRATIONS);
 /**
  * Apply every pending migration in a single transaction per migration.
  *
@@ -968,8 +994,5 @@ export const STATE_MIGRATIONS = [
  * Called automatically by `openStateDatabase()`.
  */
 export function runMigrations(db, options) {
-    runSqliteMigrations(db, STATE_MIGRATIONS, {
-        applyPending: options?.applyPending,
-        generationMarker: options?.generationMarker,
-    });
+    runSqliteMigrations(db, STATE_MIGRATIONS, { applyPending: options?.applyPending });
 }

package/dist/core/state-db-scope.js

@@ -0,0 +1,134 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Ambient, run-scoped state.db connection reuse.
+ *
+ * `openStateDatabase` is NOT cheap: every call registers a `state-db`
+ * maintenance activity (a lockfile create under the maintenance barrier), opens
+ * a throwaway read-only preflight handle to assert the migration ledger, then
+ * opens the real handle and applies pragmas. Paying that per repository call
+ * — twice per dispatched workflow unit (insert + finish), plus once per
+ * `appendEvent` (two events per unit) — is the dominant cost of a wide `map`
+ * fan-out.
+ *
+ * This module adds the ONE thing the codebase was missing: a way to say "for
+ * the duration of this async operation, everything that talks to state.db
+ * shares a single handle". It deliberately does NOT introduce a pool, a cache
+ * with an eviction policy, or a background keep-alive timer — those all leak
+ * handles across the test harness's per-test data-dir swaps. The scope owns
+ * exactly one connection and closes it in a `finally`.
+ *
+ * ## Why this is safe
+ *
+ * SQLite connections must not be shared across THREADS. This is a single
+ * process running a single-threaded JS event loop: `bun:sqlite` statement
+ * execution and `withImmediateTransaction`'s `BEGIN IMMEDIATE … COMMIT` bodies
+ * are fully synchronous, so two logically concurrent units can never interleave
+ * statements on the shared handle — the runtime cannot preempt a synchronous
+ * transaction body. Sharing one handle therefore REMOVES in-process writer
+ * contention (`SQLITE_BUSY` against ourselves) rather than creating it.
+ * Cross-process behaviour is untouched: WAL mode, the 30 s `busy_timeout` and
+ * the run-lease protocol all still arbitrate between processes exactly as
+ * before.
+ *
+ * The one hazard of an {@link AsyncLocalStorage}-carried handle is async work
+ * that ESCAPES the scope: the context propagates into a promise that settles
+ * after the scope's `finally` closed the handle. {@link borrowScopedStateDb}
+ * guards that with a `closed` flag — once a scope is torn down it stops
+ * lending, and escapee callers transparently fall back to opening their own
+ * connection (the pre-existing behaviour). A use-after-close is structurally
+ * impossible.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import path from "node:path";
+import { getStateDbPath, openStateDatabase } from "./state-db.js";
+const scopeStorage = new AsyncLocalStorage();
+/** Every scope with a live handle, so the exit backstop can close them all. */
+const liveScopes = new Set();
+let exitHookInstalled = false;
+function installExitBackstop() {
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    // Idempotent, synchronous backstop: a process that exits mid-scope (a
+    // `process.exit()` from a command, an uncaught fatal) still releases the
+    // handle and its maintenance-activity lockfile. Normal teardown happens in
+    // the scope's own `finally`, which removes the scope from `liveScopes`
+    // first, so this never double-closes.
+    process.on("exit", closeAllStateDbScopes);
+}
+/**
+ * Close every scope-owned handle. Idempotent and safe to call at any time: a
+ * closed scope stops lending, so in-flight borrowers fall back to their own
+ * connections instead of using a dead handle. Module-private: the per-scope
+ * `finally` plus the process-exit backstop above are what guarantee no handle
+ * leak — export this the day a caller actually wires deterministic teardown.
+ */
+function closeAllStateDbScopes() {
+    for (const scope of [...liveScopes])
+        closeScope(scope);
+}
+function closeScope(scope) {
+    scope.closed = true;
+    liveScopes.delete(scope);
+    const db = scope.db;
+    scope.db = undefined;
+    if (!db)
+        return;
+    try {
+        db.close();
+    }
+    catch {
+        // A close failure must never mask the caller's own error (or wedge exit).
+    }
+}
+/**
+ * The ambient scoped handle for `dbPath` (default: the canonical state.db), or
+ * `undefined` when there is no live scope for that exact path.
+ *
+ * The path comparison matters: the test harness repoints `AKM_DATA_DIR` between
+ * tests, and a scope entered against one data dir must never lend its handle to
+ * a caller resolving a different one.
+ */
+export function borrowScopedStateDb(dbPath) {
+    const scope = scopeStorage.getStore();
+    if (!scope || scope.closed)
+        return undefined;
+    if (path.resolve(dbPath ?? getStateDbPath()) !== scope.dbPath)
+        return undefined;
+    scope.db ??= openStateDatabase(scope.dbPath);
+    liveScopes.add(scope);
+    return scope.db;
+}
+/**
+ * Run `fn` with one shared state.db connection ambient for its whole async
+ * extent. The handle is opened on FIRST borrow (never eagerly) and closed once
+ * `fn` settles.
+ *
+ * Nesting is a no-op join: an inner scope for the same path reuses the outer
+ * scope's handle and does not close it, so a caller can enter a scope without
+ * knowing whether an outer frame already did.
+ */
+export async function withStateDbScope(fn, opts) {
+    const dbPath = path.resolve(opts?.path ?? getStateDbPath());
+    const outer = scopeStorage.getStore();
+    if (outer && !outer.closed && outer.dbPath === dbPath)
+        return fn();
+    const scope = { dbPath, db: undefined, closed: false };
+    installExitBackstop();
+    try {
+        return await scopeStorage.run(scope, fn);
+    }
+    finally {
+        closeScope(scope);
+    }
+}
+/** Test seam: how many scope-owned handles are currently open. Must return to 0. */
+export function openScopedStateDbCount() {
+    let count = 0;
+    for (const scope of liveScopes)
+        if (scope.db)
+            count++;
+    return count;
+}

package/dist/core/state-db.js

@@ -45,11 +45,10 @@
  * merge-target tables at their final shape. The one-time, filesystem-derived,
  * fail-closed DATA movement (the workflow.db merge, the usage_events rescue, the
  * full old-ref→item_ref re-key, and the workflow.db unlink / index.db quarantine
- * rename) is deliberately NOT a sealed SQL migration body: it is a journaled step
- * of the migrate-apply coordinator (`src/cli/config-migrate.ts` `cutover-applied`
- * phase → `src/migrate/legacy/three-db-cutover.ts`). So the no-DROP contract here
- * is intact — the physical workflow.db deletion happens outside the ledger DDL,
- * under the backup-verified-restorable fail-closed gate.
+ * rename) runs as idempotent code in the migrate-apply coordinator
+ * (`scripts/akm-migrate/migrate/legacy/three-db-cutover.ts`). So the no-DROP
+ * contract here is intact: physical workflow.db deletion happens outside the
+ * ledger DDL, after a verified backup and committed data transaction.
  *
  * ## Schema design: indexed columns vs. metadata_json
  *
@@ -73,7 +72,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { openDatabase } from "../storage/database.js";
 import { assertCurrentMigrationLedger, assertMigrationLedger } from "../storage/engines/sqlite-migrations.js";
-import { openManagedDatabase, withManagedDb, withManagedDbAsync } from "../storage/managed-db.js";
+import { openManagedDatabase, withManagedDb } from "../storage/managed-db.js";
 import { acquireMaintenanceActivitySync } from "./maintenance-barrier.js";
 import { assertNoPendingMigrationOperation } from "./migration-operation.js";
 import { getDataDir } from "./paths.js";
@@ -182,14 +181,6 @@ export function openStateDatabase(dbPath) {
 export function withStateDb(fn, opts) {
     return withManagedDb(() => openStateDatabase(opts?.path), fn, opts);
 }
-/**
- * Async sibling of {@link withStateDb} — for `fn`s that hold the handle across
- * an `await` (the sync version would close it too early). Same borrow/own +
- * optional `path` override semantics.
- */
-export function withStateDbAsync(fn, opts) {
-    return withManagedDbAsync(() => openStateDatabase(opts?.path), fn, opts);
-}
 /**
  * Fire-and-forget telemetry write to state.db (Chunk-8 WI-8.3: usage_events'
  * durable home). Skips entirely when state.db does not exist yet (never

package/dist/core/structured.js

@@ -15,7 +15,7 @@
  *
  * Layering: this file lives in `core/` — NOT `llm/` — because the agent path
  * must be able to reach it and `agent/ ⇏ llm/` is an enforced invariant
- * (`tests/architecture/agent-no-llm-sdk-guard.test.ts`). The transport is
+ * (`tests/integration/architecture/agent-no-llm-sdk-guard.test.ts`). The transport is
  * always injected; this module never performs IO of its own.
  *
  * Retry semantics: only parse/validation misses are retried (with corrective

package/dist/core/subprocess.js

@@ -12,8 +12,10 @@
  *     kill reaps the whole descendant tree — no orphaned children.
  *   • A SIGTERM→SIGKILL kill ladder on timeout/abort — a child that ignores
  *     SIGTERM is force-killed after a grace period instead of wedging forever.
- *   • Bounded output capture ({@link readStream}) that cannot block past the
- *     wall budget even when the child leaves a pipe endpoint open.
+ *   • Time-bounded output capture ({@link readStream}) that cannot block past
+ *     the wall budget even when the child leaves a pipe endpoint open, plus an
+ *     OPT-IN RETENTION cap (`maxOutputBytes`); see {@link readStream} for what
+ *     the cap does and does not bound.
  *   • Injectable `spawnFn`/`setTimeoutFn`/`clearTimeoutFn` seams so callers
  *     can drive the machinery deterministically in tests.
  *
@@ -70,33 +72,115 @@ export function scheduleKillLadder(proc, opts) {
     if (typeof sigkillTimer !== "number")
         sigkillTimer.unref?.();
 }
+/**
+ * The joined, human-readable reason ONE managed run's capture is incomplete, or
+ * `undefined` when both pipes drained cleanly.
+ *
+ * Shared so every caller that promotes captured output treats an incomplete
+ * capture the same way. A pipe that errored, or that hit the stream-drain
+ * timeout because a background descendant kept the fd open after the leader
+ * exited 0, yields a PARTIAL string — and a caller that reads only `exitCode`
+ * would promote that partial as if it were the command's whole output.
+ * `maxBytes` overflow is deliberately NOT reported here: it is a distinct,
+ * caller-classified condition (see {@link StreamReadResult.overflowed}), not a
+ * drain malfunction.
+ */
+export function streamCaptureFailure(stdout, stderr) {
+    const failures = [];
+    if (stdout.error)
+        failures.push(`stdout read failed: ${errorText(stdout.error)}`);
+    if (stderr.error)
+        failures.push(`stderr read failed: ${errorText(stderr.error)}`);
+    if (stdout.timedOut)
+        failures.push("stdout drain timed out");
+    if (stderr.timedOut)
+        failures.push("stderr drain timed out");
+    return failures.length === 0 ? undefined : failures.join("; ");
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 const STREAM_READ_TIMEOUT = Symbol("stream-read-timeout");
+/**
+ * Index at or before `limit` where a UTF-8 CHARACTER starts, so a retention cut
+ * never lands inside a multi-byte sequence. Continuation bytes are `10xxxxxx`;
+ * a well-formed sequence has at most three of them, so this walks back at most
+ * three positions.
+ */
+function utf8BoundaryAtOrBefore(value, limit) {
+    let cut = limit;
+    while (cut > 0 && (value[cut] & 0xc0) === 0x80)
+        cut--;
+    return cut;
+}
 /**
  * Drain a readable stream to text, optionally racing each read against a
  * timeout so a process that is killed via SIGTERM/SIGKILL but whose pipe
  * endpoints stay open (e.g. background threads still holding the fd) cannot
  * block the caller indefinitely. On timeout we return whatever was decoded
  * before the pipe stopped draining.
+ *
+ * ## The `maxBytes` cap bounds MEMORY, not the child
+ *
+ * The drain ALWAYS runs to the end of the stream. `maxBytes` caps only what is
+ * RETAINED: once the cap is reached the loop keeps calling `reader.read()` and
+ * throws the bytes away. That is what makes the cap safe to impose on a
+ * process that is still running — a reader that stopped pulling would fill the
+ * pipe buffer and BLOCK the child on its next write, turning "the output got
+ * long" into "the command hangs until the wall timeout". Draining and
+ * discarding costs nothing but the reads, and the child finishes normally.
  */
 export async function readStream(stream, opts) {
     if (!stream)
-        return { text: "", timedOut: false };
+        return { text: "", timedOut: false, overflowed: false, bytesRead: 0, retainedBytes: 0 };
     const reader = stream.getReader();
     const decoder = new TextDecoder();
+    const maxBytes = opts?.maxBytes;
     let text = "";
+    let bytesRead = 0;
+    let retainedBytes = 0;
+    let overflowed = false;
+    /**
+     * Common per-chunk accumulate. Uncapped it appends everything. Capped, it
+     * appends until the cap and then only COUNTS — the caller's loop keeps reading
+     * either way, which is the whole point.
+     */
+    const absorb = (value) => {
+        bytesRead += value.byteLength;
+        if (maxBytes === undefined) {
+            retainedBytes += value.byteLength;
+            text += decoder.decode(value, { stream: true });
+            return;
+        }
+        // Already past the cap: discard. Never resume retaining — a gap in the
+        // middle would splice two disjoint regions into one string.
+        if (overflowed)
+            return;
+        if (retainedBytes + value.byteLength <= maxBytes) {
+            retainedBytes += value.byteLength;
+            text += decoder.decode(value, { stream: true });
+            return;
+        }
+        overflowed = true;
+        const keep = utf8BoundaryAtOrBefore(value, maxBytes - retainedBytes);
+        if (keep > 0) {
+            retainedBytes += keep;
+            text += decoder.decode(value.subarray(0, keep), { stream: true });
+        }
+    };
     if (!opts?.timeoutMs) {
         try {
             while (true) {
                 const chunk = await reader.read();
                 if (chunk.done)
                     break;
-                text += decoder.decode(chunk.value, { stream: true });
+                absorb(chunk.value);
             }
             text += decoder.decode();
-            return { text, timedOut: false };
+            return { text, timedOut: false, overflowed, bytesRead, retainedBytes };
         }
         catch (error) {
-            return { text, timedOut: false, error };
+            return { text, timedOut: false, error, overflowed, bytesRead, retainedBytes };
         }
         finally {
             try {
@@ -109,33 +193,46 @@ export async function readStream(stream, opts) {
     }
     const setTimeoutImpl = opts.setTimeoutFn ?? setTimeout;
     const clearTimeoutImpl = opts.clearTimeoutFn ?? clearTimeout;
+    const timeoutMs = opts.timeoutMs;
     let timer;
+    let drained = false;
     const timeoutPromise = new Promise((resolve) => {
-        timer = setTimeoutImpl(() => {
-            timer = undefined;
-            resolve(STREAM_READ_TIMEOUT);
-        }, opts.timeoutMs);
-        if (typeof timer !== "number")
-            timer.unref?.();
+        const arm = () => {
+            // The drain already finished while the deadline was still waiting to be
+            // armed; a timer started now would belong to nobody.
+            if (drained)
+                return;
+            timer = setTimeoutImpl(() => {
+                timer = undefined;
+                resolve(STREAM_READ_TIMEOUT);
+            }, timeoutMs);
+            if (typeof timer !== "number")
+                timer.unref?.();
+        };
+        if (opts.armTimeoutAfter)
+            void opts.armTimeoutAfter.then(arm, arm);
+        else
+            arm();
     });
     try {
         while (true) {
             const chunk = await Promise.race([reader.read(), timeoutPromise]);
             if (chunk === STREAM_READ_TIMEOUT) {
                 void reader.cancel().catch(() => { });
-                return { text, timedOut: true };
+                return { text, timedOut: true, overflowed, bytesRead, retainedBytes };
             }
             if (chunk.done)
                 break;
-            text += decoder.decode(chunk.value, { stream: true });
+            absorb(chunk.value);
         }
         text += decoder.decode();
-        return { text, timedOut: false };
+        return { text, timedOut: false, overflowed, bytesRead, retainedBytes };
     }
     catch (error) {
-        return { text, timedOut: false, error };
+        return { text, timedOut: false, error, overflowed, bytesRead, retainedBytes };
     }
     finally {
+        drained = true;
         if (timer !== undefined) {
             clearTimeoutImpl(timer);
         }
@@ -147,7 +244,29 @@ export async function readStream(stream, opts) {
         }
     }
 }
-const EMPTY_READ = { text: "", timedOut: false };
+const EMPTY_READ = {
+    text: "",
+    timedOut: false,
+    overflowed: false,
+    bytesRead: 0,
+    retainedBytes: 0,
+};
+/**
+ * Drain deadline for a run with no wall budget, counted from the child's EXIT
+ * (never from capture — see {@link runManagedSubprocess}). It bounds only the
+ * window in which a descendant can keep an inherited pipe open after the leader
+ * is gone, so it can be generous without ever capping the run itself.
+ */
+const UNBOUNDED_STREAM_READ_SAFETY_MS = 60 * 60 * 1000;
+/**
+ * Drain deadline for a run WITH a wall budget, counted from the moment the
+ * pipe's owner left — the child exited, or (a child that survived its own kill
+ * ladder) the budget expired. Anything still holding the fd open then is a
+ * background descendant, not the command, so this is the same 2 s the old
+ * capture-anchored deadline allowed past the budget; only its starting point
+ * moved earlier.
+ */
+const POST_EXIT_STREAM_DRAIN_GRACE_MS = 2_000;
 function toError(err) {
     return err instanceof Error ? err : new Error(String(err));
 }
@@ -206,8 +325,18 @@ export async function runManagedSubprocess(cmd, opts) {
     // Skipped entirely when timeoutMs is null.
     let timedOut = false;
     let timer;
+    // Settles when a bounded run's wall budget expires — the second way (after
+    // the child's own exit) a captured pipe can stop belonging to a live command.
+    // See the drain-deadline note below.
+    let onBudgetExpiry;
+    const budgetExpired = capture && timeoutMs !== null
+        ? new Promise((resolve) => {
+            onBudgetExpiry = resolve;
+        })
+        : undefined;
     if (timeoutMs !== null) {
         timer = setTimeoutImpl(() => {
+            onBudgetExpiry?.();
             scheduleKillLadder(proc, {
                 onKill: () => {
                     timedOut = true;
@@ -238,24 +367,33 @@ export async function runManagedSubprocess(cmd, opts) {
         else
             abortSignal.addEventListener("abort", onAbort, { once: true });
     }
-    // Stream-drain timeout: the wall budget plus a 2 s grace, or 30 s when there
-    // is no kill timer. Ensures the caller never hangs past the budget even if a
-    // killed child leaves a pipe write-end open in a background thread.
-    const streamDrainTimeoutMs = timeoutMs !== null ? timeoutMs + 2_000 : 30_000;
-    const stdoutPromise = capture
-        ? readStream(proc.stdout ?? null, {
-            timeoutMs: streamDrainTimeoutMs,
-            setTimeoutFn: setTimeoutImpl,
-            clearTimeoutFn: clearTimeoutImpl,
-        })
-        : Promise.resolve(EMPTY_READ);
-    const stderrPromise = capture
-        ? readStream(proc.stderr ?? null, {
-            timeoutMs: streamDrainTimeoutMs,
-            setTimeoutFn: setTimeoutImpl,
-            clearTimeoutFn: clearTimeoutImpl,
-        })
-        : Promise.resolve(EMPTY_READ);
+    // Stream-drain timeout: a short grace once nothing living owns the pipe any
+    // more, or a one-hour safety bound when execution itself is unbounded.
+    //
+    // Neither is armed while the command is still running: every byte up to then
+    // is a live process's, and cancelling the reader would discard the output of
+    // work that is still going. What ends that ownership is where the two cases
+    // differ. Unbounded, the caller asked for NO cap on the run, so only the
+    // child's own exit can end it. Bounded, the wall budget ends it too — a child
+    // that outlived its own kill ladder is not something akm can keep waiting on
+    // — which leaves the SAME budget + grace ceiling as before for a command that
+    // really did spend its whole budget, and cuts the common case that used to
+    // stall: a leader exiting in milliseconds no longer holds the drain (and with
+    // it the unit, and with it a fan-out slot) open for a budget it never came
+    // close to spending.
+    const streamDrainTimeoutMs = timeoutMs !== null ? POST_EXIT_STREAM_DRAIN_GRACE_MS : UNBOUNDED_STREAM_READ_SAFETY_MS;
+    // Settles on a rejected `proc.exited` too: either way the child is gone.
+    const childSettled = capture ? proc.exited.catch(() => undefined) : undefined;
+    const pipeOwnerGone = childSettled && budgetExpired ? Promise.race([childSettled, budgetExpired]) : childSettled;
+    const readOpts = {
+        timeoutMs: streamDrainTimeoutMs,
+        setTimeoutFn: setTimeoutImpl,
+        clearTimeoutFn: clearTimeoutImpl,
+        ...(pipeOwnerGone ? { armTimeoutAfter: pipeOwnerGone } : {}),
+        ...(opts.maxOutputBytes !== undefined ? { maxBytes: opts.maxOutputBytes } : {}),
+    };
+    const stdoutPromise = capture ? readStream(proc.stdout ?? null, readOpts) : Promise.resolve(EMPTY_READ);
+    const stderrPromise = capture ? readStream(proc.stderr ?? null, readOpts) : Promise.resolve(EMPTY_READ);
     // Optional stdin payload (captured mode only). Race the write/close against
     // proc.exited so a child that never drains stdin cannot pin us past the
     // timeout.
@@ -299,5 +437,13 @@ export async function runManagedSubprocess(cmd, opts) {
     clearTimeoutImpl(timer);
     abortSignal?.removeEventListener("abort", onAbort);
     const [stdoutRead, stderrRead] = await Promise.all([stdoutPromise, stderrPromise]);
-    return { exitCode, stdout: stdoutRead.text, stderr: stderrRead.text, timedOut, aborted, stdoutRead, stderrRead };
+    return {
+        exitCode,
+        stdout: stdoutRead.text,
+        stderr: stderrRead.text,
+        timedOut,
+        aborted,
+        stdoutRead,
+        stderrRead,
+    };
 }