@llblab/pi-actors 0.43.0 → 0.44.0

package/dist/lib/file-state.js

@@ -3,12 +3,16 @@
  * Zones: file persistence, atomic writes, runtime state support
  * Owns generic durable JSON file writes shared by registry config and async run state.
  */
+import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, parse, resolve } from "node:path";
-const FILE_MUTATION_LOCK_TIMEOUT_MS = 5000;
+const FILE_MUTATION_LOCK_TIMEOUT_MS = process.platform === "win32" ? 30000 : 15000;
 const FILE_MUTATION_LOCK_STALE_MS = 30000;
+const FILE_MUTATION_LOCK_RECLAIM_POLL_MS = 100;
+const FILE_MUTATION_LOCK_REMOVAL_GRACE_MS = 250;
+const FILE_MUTATION_LOCK_MAX_WAIT_MS = 50;
 const FILE_MUTATION_LOCK_ROOT = join(tmpdir(), "pi-actors-file-locks");
 function canonicalMutationPath(path) {
     const absolute = resolve(path);
@@ -42,6 +46,20 @@ export function mutationLockPath(path) {
         .digest("hex");
     return join(FILE_MUTATION_LOCK_ROOT, `${key}.lock`);
 }
+function isZombieProcess(pid) {
+    if (process.platform === "linux")
+        try {
+            const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+            return stat.slice(stat.lastIndexOf(")") + 2).startsWith("Z ");
+        }
+        catch {
+            return false;
+        }
+    if (process.platform !== "darwin")
+        return false;
+    const result = spawnSync("ps", ["-p", String(pid), "-o", "stat="], { encoding: "utf8" });
+    return result.status === 0 && result.stdout.trim().startsWith("Z");
+}
 function lockOwnerStatus(lockPath) {
     try {
         const owner = JSON.parse(readFileSync(join(lockPath, "owner.json"), "utf8"));
@@ -50,6 +68,9 @@ function lockOwnerStatus(lockPath) {
             return "unknown";
         try {
             process.kill(pid, 0);
+            if (Date.now() - statSync(lockPath).mtimeMs > FILE_MUTATION_LOCK_REMOVAL_GRACE_MS &&
+                isZombieProcess(pid))
+                return "dead";
             return "alive";
         }
         catch (error) {
@@ -71,17 +92,59 @@ function readLockToken(lockPath) {
         return undefined;
     }
 }
+function prepareLockBoundary(lockPath, token, onBeforePublish) {
+    const pendingPath = `${lockPath}.${process.pid}.${token}.pending`;
+    try {
+        mkdirSync(pendingPath);
+        writeFileSync(join(pendingPath, "owner.json"), `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`, "utf8");
+        onBeforePublish?.();
+        return pendingPath;
+    }
+    catch (error) {
+        try {
+            rmSync(pendingPath, { recursive: true, force: true });
+        }
+        catch { }
+        throw error;
+    }
+}
+function removeLockBoundary(lockPath, token) {
+    if (readLockToken(lockPath) !== token)
+        return false;
+    if (process.platform === "win32")
+        try {
+            rmSync(lockPath, { recursive: true, force: true, maxRetries: 20, retryDelay: 5 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    const removingPath = `${lockPath}.${process.pid}.${randomUUID()}.removing`;
+    try {
+        renameSync(lockPath, removingPath);
+    }
+    catch {
+        return false;
+    }
+    try {
+        rmSync(removingPath, { recursive: true, force: true });
+    }
+    catch { }
+    return true;
+}
 function tryReclaimRemovalBoundary(reclaimPath) {
     if (!existsSync(reclaimPath))
         return;
     try {
-        const inspectedToken = readLockToken(reclaimPath);
         const age = Date.now() - statSync(reclaimPath).mtimeMs;
+        if (age <= FILE_MUTATION_LOCK_REMOVAL_GRACE_MS)
+            return;
+        const inspectedToken = readLockToken(reclaimPath);
         const ownerStatus = lockOwnerStatus(reclaimPath);
         if ((ownerStatus === "dead" ||
             (ownerStatus === "unknown" && age > FILE_MUTATION_LOCK_STALE_MS)) &&
             readLockToken(reclaimPath) === inspectedToken) {
-            rmSync(reclaimPath, { recursive: true, force: true });
+            removeLockBoundary(reclaimPath, inspectedToken);
         }
     }
     catch {
@@ -91,28 +154,28 @@ function tryReclaimRemovalBoundary(reclaimPath) {
 function withRemovalBoundary(lockPath, action) {
     const reclaimPath = `${lockPath}.reclaim`;
     const token = randomUUID();
+    const pendingPath = prepareLockBoundary(reclaimPath, token);
     try {
-        mkdirSync(reclaimPath);
         try {
-            writeFileSync(join(reclaimPath, "owner.json"), `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`, "utf8");
+            renameSync(pendingPath, reclaimPath);
         }
-        catch (error) {
-            rmSync(reclaimPath, { recursive: true, force: true });
-            throw error;
+        catch {
+            tryReclaimRemovalBoundary(reclaimPath);
+            return false;
+        }
+        try {
+            action();
+            return true;
+        }
+        finally {
+            removeLockBoundary(reclaimPath, token);
         }
-    }
-    catch {
-        tryReclaimRemovalBoundary(reclaimPath);
-        return false;
-    }
-    try {
-        action();
-        return true;
     }
     finally {
-        if (readLockToken(reclaimPath) === token) {
-            rmSync(reclaimPath, { recursive: true, force: true });
+        try {
+            rmSync(pendingPath, { recursive: true, force: true });
         }
+        catch { }
     }
 }
 function tryReclaimMutationLock(lockPath, options) {
@@ -129,8 +192,7 @@ function tryReclaimMutationLock(lockPath, options) {
             (ownerStatus === "unknown" && age > FILE_MUTATION_LOCK_STALE_MS)) &&
             readLockToken(lockPath) === inspectedToken) {
             options.onBeforeReclaimRemove?.();
-            rmSync(lockPath, { recursive: true, force: true });
-            reclaimed = true;
+            reclaimed = removeLockBoundary(lockPath, inspectedToken);
         }
     })) {
         return false;
@@ -142,32 +204,45 @@ export function acquireFileMutationLock(path, options = {}) {
     const lockPath = mutationLockPath(path);
     const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
     const token = randomUUID();
+    const pendingPath = prepareLockBoundary(lockPath, token, options.onBeforeLockPublish);
     let contentionReported = false;
-    for (;;) {
-        try {
-            mkdirSync(lockPath);
+    let nextReclaimAt = 0;
+    let waitMs = 10;
+    try {
+        for (;;) {
             try {
-                writeFileSync(join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`, "utf8");
+                renameSync(pendingPath, lockPath);
+                break;
             }
             catch (error) {
-                rmSync(lockPath, { recursive: true, force: true });
-                throw error;
+                if (!contentionReported) {
+                    contentionReported = true;
+                    options.onContention?.();
+                }
+                const now = Date.now();
+                if (now >= nextReclaimAt) {
+                    nextReclaimAt = now + FILE_MUTATION_LOCK_RECLAIM_POLL_MS;
+                    if (tryReclaimMutationLock(lockPath, options)) {
+                        waitMs = 10;
+                        continue;
+                    }
+                }
+                if (now >= deadline) {
+                    throw new Error(`Timed out waiting for file mutation lock: ${canonicalMutationPath(path)}`, {
+                        cause: error,
+                    });
+                }
+                const jitter = Math.floor(Math.random() * Math.max(1, Math.floor(waitMs / 2)));
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, waitMs + jitter);
+                waitMs = Math.min(FILE_MUTATION_LOCK_MAX_WAIT_MS, waitMs + 5);
             }
-            break;
         }
-        catch (error) {
-            if (!contentionReported) {
-                contentionReported = true;
-                options.onContention?.();
-            }
-            tryReclaimMutationLock(lockPath, options);
-            if (Date.now() >= deadline) {
-                throw new Error(`Timed out waiting for file mutation lock: ${canonicalMutationPath(path)}`, {
-                    cause: error,
-                });
-            }
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+    finally {
+        try {
+            rmSync(pendingPath, { recursive: true, force: true });
         }
+        catch { }
     }
     let released = false;
     return () => {
@@ -177,9 +252,7 @@ export function acquireFileMutationLock(path, options = {}) {
         const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
         let removalContentionReported = false;
         while (!withRemovalBoundary(lockPath, () => {
-            if (readLockToken(lockPath) === token) {
-                rmSync(lockPath, { recursive: true, force: true });
-            }
+            removeLockBoundary(lockPath, token);
         })) {
             if (!removalContentionReported) {
                 removalContentionReported = true;
@@ -200,11 +273,12 @@ export function withFileMutationLock(path, mutate, options = {}) {
         release();
     }
 }
-export function writeTextAtomic(path, content) {
+export function writeTextAtomic(path, content, options = {}) {
     mkdirSync(dirname(path), { recursive: true });
     const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
     try {
         writeFileSync(tempPath, content, "utf8");
+        options.onBeforeReplace?.();
         renameSync(tempPath, path);
     }
     catch (error) {

package/dist/lib/inspector-overlay.d.ts

@@ -41,6 +41,7 @@ export declare class ActorInspectorOverlay {
     private killDialogChoice;
     private rowIndex;
     private runCache?;
+    private selectedTraceId?;
     private runIndex;
     private selectorIndex;
     private selectorMode?;
@@ -81,6 +82,7 @@ export declare class ActorInspectorOverlay {
     private readRunMeta;
     private documentProjection;
     private inlineDocumentValue;
+    private labeledDocumentLines;
     private labeledScalarLines;
     private document;
     private wrapDocument;

package/dist/lib/inspector-overlay.js

@@ -3,12 +3,17 @@
  * Zones: owned actor selection, Recipe/Trace/Control tabs, safe Run Kill confirmation
  * Owns manual kernel navigation; evidence parsing and lifecycle mutation stay in ports.
  */
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import * as path from "node:path";
 import { matchesKey, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
 import * as ActorInspector from "./inspector.js";
+import * as ControlProjection from "./control-projection.js";
 import * as RunsControls from "./runs-controls.js";
 import * as RunControlDelivery from "./runs-control-delivery.js";
+import * as RunsTrace from "./runs-trace.js";
+import * as Limits from "./limits.js";
+import { computeRunControlCapacity } from "./run-evidence-policy.js";
+import * as RuntimeTriage from "./runtime-triage.js";
 import * as TraceProjection from "./trace-projection.js";
 const TABS = ["recipe", "trace", "control"];
 const TRACE_SOURCES = [
@@ -39,6 +44,7 @@ export class ActorInspectorOverlay {
     killDialogChoice = "cancel";
     rowIndex = 0;
     runCache;
+    selectedTraceId;
     runIndex = 0;
     selectorIndex = 0;
     selectorMode;
@@ -56,9 +62,7 @@ export class ActorInspectorOverlay {
         this.theme = options.theme;
         this.tui = options.tui;
         this.refreshTimer = setInterval(() => {
-            this.runCache = undefined;
-            if (this.focus !== "list" && this.focus !== "detail")
-                this.traceCache = undefined;
+            this.invalidate();
             this.tui.requestRender();
         }, 1_000);
         this.refreshTimer.unref?.();
@@ -66,7 +70,10 @@ export class ActorInspectorOverlay {
     dispose() {
         clearInterval(this.refreshTimer);
     }
-    invalidate() { }
+    invalidate() {
+        this.runCache = undefined;
+        this.traceCache = undefined;
+    }
     handleInput(data) {
         const runs = this.runs();
         this.runIndex = Math.min(this.runIndex, Math.max(0, runs.length - 1));
@@ -90,11 +97,14 @@ export class ActorInspectorOverlay {
                 this.focus = this.tab === "trace" ? "tabs" : "runs";
             }
             else if (this.focus === "detail") {
+                this.selectedTraceId = this.traceDetail?.id;
                 this.traceDetail = undefined;
                 this.detailScroll = 0;
                 this.focus = "list";
             }
             else if (this.focus === "document" || this.focus === "list") {
+                if (this.focus === "list")
+                    this.selectedTraceId = undefined;
                 this.focus = "tabs";
             }
             else {
@@ -146,9 +156,12 @@ export class ActorInspectorOverlay {
                 this.focus = "runs";
             }
             else if (matchesKey(data, "down")) {
-                this.focus = this.tab === "trace" && this.traceItems(runs[this.runIndex]).length > 0
-                    ? "list"
-                    : "document";
+                const items = this.tab === "trace" ? this.traceItems(runs[this.runIndex]) : [];
+                this.focus = items.length > 0 ? "list" : "document";
+                if (this.focus === "list") {
+                    this.rowIndex = 0;
+                    this.selectedTraceId = items[0]?.id;
+                }
             }
             else if (matchesKey(data, "return")) {
                 if (this.tab === "trace")
@@ -158,12 +171,17 @@ export class ActorInspectorOverlay {
             }
         }
         else if (this.focus === "list") {
-            const count = this.traceItems(runs[this.runIndex]).length;
-            if (matchesKey(data, "left"))
+            const items = this.traceItems(runs[this.runIndex]);
+            const count = items.length;
+            if (matchesKey(data, "left")) {
+                this.selectedTraceId = undefined;
                 this.focus = "tabs";
+            }
             else if (matchesKey(data, "up")) {
-                if (this.rowIndex === 0)
+                if (this.rowIndex === 0) {
+                    this.selectedTraceId = undefined;
                     this.focus = "tabs";
+                }
                 else
                     this.rowIndex -= 1;
             }
@@ -177,13 +195,15 @@ export class ActorInspectorOverlay {
                 this.rowIndex = Math.min(Math.max(0, count - 1), this.rowIndex + this.contentViewportRows());
             }
             else if (matchesKey(data, "return") || matchesKey(data, "right")) {
-                const item = this.traceItems(runs[this.runIndex])[this.rowIndex];
+                const item = items[this.rowIndex];
                 if (item) {
                     this.traceDetail = item;
                     this.detailScroll = 0;
                     this.focus = "detail";
                 }
             }
+            if (this.focus === "list")
+                this.selectedTraceId = items[this.rowIndex]?.id;
         }
         if (data.toLowerCase() === "f" && this.tab === "trace") {
             this.cycleTraceSource(runs[this.runIndex]);
@@ -239,6 +259,7 @@ export class ActorInspectorOverlay {
         this.documentScroll = 0;
         this.detailScroll = 0;
         this.rowIndex = 0;
+        this.selectedTraceId = undefined;
         this.traceDetail = undefined;
     }
     cycleRun(runs, direction) {
@@ -260,6 +281,7 @@ export class ActorInspectorOverlay {
             this[key] += this.contentViewportRows();
         }
         else if (matchesKey(data, "left") && target === "detail") {
+            this.selectedTraceId = this.traceDetail?.id;
             this.traceDetail = undefined;
             this.detailScroll = 0;
             this.focus = "list";
@@ -361,7 +383,10 @@ export class ActorInspectorOverlay {
         if (!confirmation || !this.killRun)
             return;
         try {
-            this.feedback = this.killRun(confirmation.run, confirmation.runInstanceId);
+            const result = this.killRun(confirmation.run, confirmation.runInstanceId);
+            this.feedback = result.ok ? undefined : result;
+            if (result.ok)
+                this.invalidate();
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -386,8 +411,7 @@ export class ActorInspectorOverlay {
             `${this.theme.fg("muted", "Run:")} ${this.theme.fg("accent", `run:${confirmation.run}`)}`,
             `${this.theme.fg("muted", "Current status:")} ${this.theme.fg("warning", confirmation.status)}`,
             "",
-            this.theme.fg("text", "This sends canonical kill Control."),
-            this.theme.fg("error", "The action is destructive and cannot be undone."),
+            this.theme.fg("text", "This invokes generation-fenced runtime kill."),
             "",
             `${cancel}    ${kill}`,
             "",
@@ -478,33 +502,45 @@ export class ActorInspectorOverlay {
     }
     renderTraceList(run) {
         const items = this.traceItems(run);
+        const summary = RunsTrace.summarizeRunTraceJournal(RunsTrace.readRunTraceJournal(path.join(this.stateRoot, run.run)));
+        const banner = summary.history_complete ? [] : [this.theme.fg("warning", ` ! Trace history incomplete: ${summary.compacted ? `${summary.compactions_total} compaction(s), ` : ""}${summary.dropped_event_count_exact ? summary.dropped_events : "unknown"} dropped event(s), ${summary.dropped_bytes} bytes`)];
         if (items.length === 0)
-            return [this.theme.fg("muted", " No Trace evidence")];
+            return [...banner, this.theme.fg("muted", " No Trace evidence")];
+        if (this.selectedTraceId) {
+            const selectedIndex = items.findIndex((item) => item.id === this.selectedTraceId);
+            if (selectedIndex >= 0)
+                this.rowIndex = selectedIndex;
+            else
+                this.selectedTraceId = undefined;
+        }
         this.rowIndex = Math.min(this.rowIndex, items.length - 1);
+        if (this.focus === "list" && !this.selectedTraceId) {
+            this.selectedTraceId = items[this.rowIndex]?.id;
+        }
         const viewportRows = this.contentViewportRows();
         const maxStart = Math.max(0, items.length - viewportRows);
         const start = Math.max(0, Math.min(this.rowIndex - Math.floor(viewportRows / 2), maxStart));
         this.contentStripeIndices = items
             .slice(start, start + viewportRows)
             .map((_item, offset) => start + offset);
-        return items.slice(start, start + viewportRows).map((item, offset) => {
-            const index = start + offset;
-            const detail = item.detail && typeof item.detail === "object"
-                ? item.detail
-                : {};
-            const marker = item.level === "error"
-                ? this.theme.fg("error", "!")
-                : detail.attention
-                    ? this.theme.fg("warning", "•")
-                    : this.theme.fg("muted", "·");
-            const prefix = this.focus === "list" && index === this.rowIndex
-                ? this.theme.fg("accent", " ▶ ")
-                : "   ";
-            const row = `${prefix}${this.theme.fg("text", `#${index + 1}`)} ${marker} ${this.theme.fg("muted", item.source)}/${this.theme.fg(item.level === "error" ? "error" : "accent", item.kind)}  ${this.theme.fg("text", item.summary)}`;
-            return this.focus === "list" && index === this.rowIndex
-                ? this.theme.fg("accent", row)
-                : row;
-        });
+        return [...banner, ...items.slice(start, start + viewportRows - banner.length).map((item, offset) => {
+                const index = start + offset;
+                const detail = item.detail && typeof item.detail === "object"
+                    ? item.detail
+                    : {};
+                const marker = item.level === "error"
+                    ? this.theme.fg("error", "!")
+                    : detail.attention
+                        ? this.theme.fg("warning", "A")
+                        : " ";
+                const prefix = this.focus === "list" && index === this.rowIndex
+                    ? this.theme.fg("accent", " ▶ ")
+                    : "   ";
+                const row = `${prefix}${this.theme.fg("text", `#${items.length - index}`)} ${marker} ${this.theme.fg("muted", item.source)}/${this.theme.fg(item.level === "error" ? "error" : "accent", item.kind)}  ${this.theme.fg("text", item.summary)}`;
+                return this.focus === "list" && index === this.rowIndex
+                    ? this.theme.fg("accent", row)
+                    : row;
+            })];
     }
     renderTraceDetail(width) {
         if (!this.traceDetail)
@@ -520,13 +556,29 @@ export class ActorInspectorOverlay {
             ? RunControlDelivery.readRunControlEndpoint(stateDir, run.runInstanceId)
             : undefined;
         const meta = this.readRunMeta(stateDir);
+        const journal = RunsControls.readRunControlJournalFromStateDir(stateDir);
+        const capacity = computeRunControlCapacity(journal.records);
+        const stalePending = journal.records.reduce((count, control) => count + Number(Boolean(RuntimeTriage.classifyRuntimeControl({ run: run.run,
+            runInstanceId: run.runInstanceId, status: run.status }, control, Date.now()).stale)), 0);
         return {
             status: run.status,
             run_instance_id: run.runInstanceId,
+            pending: capacity.pending, pending_limit: capacity.limit,
+            available: capacity.available, backpressured: capacity.backpressured,
+            journal_bytes: (() => { try {
+                return statSync(RunsControls.runControlsFile(stateDir)).size;
+            }
+            catch {
+                return 0;
+            } })(),
+            journal_limit: Limits.RUN_CONTROL_JOURNAL_MAX_BYTES,
+            stale_pending: stalePending,
+            diagnostics: journal.diagnostics.map((item) => item.line === undefined
+                ? { reason: "unreadable_control_journal" } : { line: item.line, reason: "invalid_control_json" }),
             actor_actions: Array.isArray(meta.control) ? meta.control : [],
             runtime_actions: run.status === "running" ? ["kill"] : ["archive", "prune"],
             endpoint,
-            recent_controls: RunsControls.readRunControlsFromStateDir(stateDir).slice(-20).reverse(),
+            recent_controls: journal.records.slice(-20).reverse().map((control) => ControlProjection.projectRunControl(control)),
         };
     }
     allTraceItems(run) {
@@ -567,14 +619,7 @@ export class ActorInspectorOverlay {
     }
     documentProjection(value, width) {
         const sections = value && typeof value === "object" && !Array.isArray(value)
-            ? Object.entries(value).map(([key, item]) => {
-                const inline = this.inlineDocumentValue(item);
-                return inline !== undefined
-                    ? [`${key}: ${inline}`]
-                    : item && typeof item === "object"
-                        ? [`${key}:`, ...this.document(item, 1)]
-                        : this.labeledScalarLines(key, item);
-            })
+            ? Object.entries(value).map(([key, item]) => this.labeledDocumentLines(key, item))
             : [this.document(value)];
         const lines = [];
         const stripes = [];
@@ -596,19 +641,22 @@ export class ActorInspectorOverlay {
             return undefined;
         }
         if (value && typeof value === "object") {
-            const entries = Object.entries(value);
-            if (entries.length === 0)
+            if (Object.keys(value).length === 0)
                 return "{}";
-            if (entries.length <= 3 &&
-                entries.every(([, item]) => (item === null || typeof item !== "object") &&
-                    !(typeof item === "string" && /[\r\n]/u.test(item)))) {
-                return `{ ${entries
-                    .map(([key, item]) => `${key}: ${String(item ?? "none")}`)
-                    .join(", ")} }`;
-            }
         }
         return undefined;
     }
+    labeledDocumentLines(key, value, depth = 0) {
+        const inline = this.inlineDocumentValue(value);
+        if (inline !== undefined)
+            return [`${"  ".repeat(depth)}${key}: ${inline}`];
+        if (value && typeof value === "object") {
+            const indent = "  ".repeat(depth);
+            const nested = this.document(value, depth);
+            return [`${indent}${key}: ${nested[0].slice(indent.length)}`, ...nested.slice(1)];
+        }
+        return this.labeledScalarLines(key, value, depth);
+    }
     labeledScalarLines(key, value, depth = 0) {
         const indent = "  ".repeat(depth);
         const [first = "", ...rest] = String(value ?? "none").split(/\r?\n/u);
@@ -624,25 +672,32 @@ export class ActorInspectorOverlay {
         if (inline !== undefined)
             return [`${"  ".repeat(depth)}${inline}`];
         if (Array.isArray(value)) {
-            return value.flatMap((item, index) => {
-                const marker = `${"  ".repeat(depth)}- #${index + 1}`;
-                const itemInline = this.inlineDocumentValue(item);
-                return itemInline !== undefined
-                    ? [`${marker}: ${itemInline}`]
-                    : [marker, ...this.document(item, depth + 1)];
-            });
+            const indent = "  ".repeat(depth);
+            return [
+                `${indent}[`,
+                ...value.flatMap((item, index) => {
+                    const marker = `${indent}  - #${index + 1}`;
+                    const itemInline = this.inlineDocumentValue(item);
+                    return itemInline !== undefined
+                        ? [`${marker}: ${itemInline}`]
+                        : [marker, ...this.document(item, depth + 2)];
+                }),
+                `${indent}]`,
+            ];
         }
         if (typeof value === "object") {
-            return Object.entries(value).flatMap(([key, item]) => {
-                const itemInline = this.inlineDocumentValue(item);
-                if (itemInline !== undefined) {
-                    return [`${"  ".repeat(depth)}${key}: ${itemInline}`];
-                }
-                if (item && typeof item === "object") {
-                    return [`${"  ".repeat(depth)}${key}:`, ...this.document(item, depth + 1)];
-                }
-                return this.labeledScalarLines(key, item, depth);
-            });
+            const indent = "  ".repeat(depth);
+            const entries = Object.entries(value);
+            return [
+                `${indent}{`,
+                ...entries.flatMap(([key, item], index) => {
+                    const lines = this.labeledDocumentLines(key, item, depth + 1);
+                    if (index < entries.length - 1)
+                        lines[lines.length - 1] += ",";
+                    return lines;
+                }),
+                `${indent}}`,
+            ];
         }
         return String(value)
             .split(/\r?\n/u)

package/dist/lib/limits.d.ts

@@ -1,12 +1,14 @@
 /**
- * Shared output and preview size limits.
- * Zones: output governance, Trace previews, inspect defaults
+ * Shared output, preview, and Control envelope limits.
+ * Zones: output governance, Trace previews, Inspect defaults, Control portability
  */
 export declare const DEFAULT_INSPECT_LINES = 40;
 export declare const TOOL_OUTPUT_MAX_BYTES: number;
 export declare const TOOL_OUTPUT_MAX_LINES = 2000;
 export declare const COMPACT_PREVIEW_CHARS = 160;
-export declare const CONTROL_INPUT_MAX_BYTES: number;
+export declare const CONTROL_ACTION_MAX_LENGTH = 64;
+export declare const CONTROL_INPUT_MAX_BYTES = 380;
+export declare const CONTROL_WIRE_MAX_BYTES = 512;
 export declare const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export declare const DOCTOR_ACTION_PREVIEW_CHARS = 72;
 export declare const SESSION_EVIDENCE_MAX_TURNS = 100;
@@ -14,3 +16,13 @@ export declare const SESSION_EVIDENCE_TEXT_CHARS = 4000;
 export declare const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;
 export declare const TRACE_EVENT_MAX_BYTES: number;
 export declare const TRACE_EVENT_MAX_READ = 200;
+export declare const TRACE_JOURNAL_MAX_EVENTS = 2048;
+export declare const TRACE_JOURNAL_TARGET_EVENTS = 1536;
+export declare const TRACE_JOURNAL_MAX_BYTES: number;
+export declare const TRACE_JOURNAL_TARGET_BYTES: number;
+export declare const RUN_CONTROL_PENDING_LIMIT = 64;
+export declare const RUN_CONTROL_TERMINAL_LIMIT = 128;
+export declare const RUN_CONTROL_ERROR_MAX_BYTES: number;
+export declare const RUN_CONTROL_JOURNAL_MAX_BYTES: number;
+export declare const RUN_RETENTION_MAX_RECORDS = 256;
+export declare const RUN_RETENTION_MAX_BYTES: number;