@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/agent/runtime/checked_commands.js

@@ -0,0 +1,119 @@
+const MAX_PLAN_BYTES = 16 * 1024;
+const MAX_STEPS = 8;
+const MAX_STAGES = 8;
+const utf8 = new TextEncoder();
+const stepId = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+function object(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function keys(value, required, optional = []) {
+    return required.every(key => Object.hasOwn(value, key))
+        && Object.keys(value).every(key => required.includes(key) || optional.includes(key));
+}
+function string(value, maxBytes, allowEmpty = false) {
+    return typeof value === 'string' && (allowEmpty || value.length > 0)
+        && !value.includes('\0') && utf8.encode(value).byteLength <= maxBytes;
+}
+function jsonBytes(value) {
+    try {
+        const encoded = JSON.stringify(value);
+        return encoded === undefined ? Infinity : utf8.encode(encoded).byteLength;
+    }
+    catch {
+        return Infinity;
+    }
+}
+function exitCode(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= 255;
+}
+function codes(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 8
+        || ![...value].every(exitCode) || new Set(value).size !== value.length)
+        return null;
+    return [...value];
+}
+/** Parse a bounded literal process plan; shell text is never inferred from its arguments. */
+export function parseCheckedCommandPlan(value) {
+    if (jsonBytes(value) > MAX_PLAN_BYTES || !object(value) || !keys(value, ['steps'])
+        || !Array.isArray(value.steps) || value.steps.length < 1 || value.steps.length > MAX_STEPS)
+        return null;
+    const steps = [];
+    const ids = new Set();
+    for (const rawStep of value.steps) {
+        if (!object(rawStep) || !keys(rawStep, ['id', 'pipeline']) || typeof rawStep.id !== 'string'
+            || !stepId.test(rawStep.id) || ids.has(rawStep.id) || !Array.isArray(rawStep.pipeline)
+            || rawStep.pipeline.length < 1 || rawStep.pipeline.length > MAX_STAGES)
+            return null;
+        const pipeline = [];
+        for (const rawStage of rawStep.pipeline) {
+            if (!object(rawStage) || !keys(rawStage, ['executable', 'args'], ['acceptable_exit_codes'])
+                || !string(rawStage.executable, 512) || !Array.isArray(rawStage.args) || rawStage.args.length > 64
+                || ![...rawStage.args].every(arg => string(arg, 4096, true)))
+                return null;
+            const accepted = Object.hasOwn(rawStage, 'acceptable_exit_codes') ? codes(rawStage.acceptable_exit_codes) : [0];
+            if (!accepted)
+                return null;
+            pipeline.push({ executable: rawStage.executable, args: [...rawStage.args], acceptable_exit_codes: accepted });
+        }
+        ids.add(rawStep.id);
+        steps.push({ id: rawStep.id, pipeline });
+    }
+    const parsed = { steps };
+    return jsonBytes(parsed) <= MAX_PLAN_BYTES ? parsed : null;
+}
+/** Parse declared process outcomes without turning them into source or build qualification. */
+export function parseCheckedCommandResult(value) {
+    if (!object(value) || !keys(value, ['schema_version', 'status', 'verification', 'plan_sha256', 'steps'], ['reason'])
+        || value.schema_version !== 1 || value.verification !== 'unknown'
+        || (value.status !== 'passed' && value.status !== 'failed' && value.status !== 'incomplete'
+            && value.status !== 'timed_out' && value.status !== 'cancelled')
+        || typeof value.plan_sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(value.plan_sha256)
+        || (Object.hasOwn(value, 'reason') && !string(value.reason, 256, true))
+        || !Array.isArray(value.steps) || value.steps.length < 1 || value.steps.length > MAX_STEPS)
+        return null;
+    const steps = [];
+    const ids = new Set();
+    let predecessorUnaccepted = false;
+    let observedFailure = false;
+    for (const rawStep of value.steps) {
+        if (!object(rawStep) || !keys(rawStep, ['id', 'status', 'stages']) || typeof rawStep.id !== 'string'
+            || !stepId.test(rawStep.id) || ids.has(rawStep.id)
+            || (rawStep.status !== 'passed' && rawStep.status !== 'failed' && rawStep.status !== 'skipped' && rawStep.status !== 'unknown')
+            || !Array.isArray(rawStep.stages) || rawStep.stages.length < 1 || rawStep.stages.length > MAX_STAGES)
+            return null;
+        const stages = [];
+        for (const rawStage of rawStep.stages) {
+            if (!object(rawStage) || !keys(rawStage, ['exit_code', 'acceptable_exit_codes', 'accepted']))
+                return null;
+            const acceptedCodes = codes(rawStage.acceptable_exit_codes);
+            if (!acceptedCodes || (rawStage.exit_code !== null && !exitCode(rawStage.exit_code)))
+                return null;
+            const accepted = rawStage.exit_code === null ? null : acceptedCodes.includes(rawStage.exit_code);
+            if (rawStage.accepted !== accepted)
+                return null;
+            stages.push({ exit_code: rawStage.exit_code, acceptable_exit_codes: acceptedCodes, accepted });
+        }
+        const allKnown = stages.every(stage => stage.exit_code !== null);
+        const anyKnown = stages.some(stage => stage.exit_code !== null);
+        const failed = stages.some(stage => stage.accepted === false);
+        if ((rawStep.status === 'passed' && (!allKnown || failed))
+            || (rawStep.status === 'failed' && (!allKnown || !failed))
+            || (rawStep.status === 'unknown' && allKnown)
+            || (rawStep.status === 'skipped' && anyKnown)
+            || (predecessorUnaccepted && anyKnown))
+            return null;
+        if (rawStep.status !== 'passed')
+            predecessorUnaccepted = true;
+        observedFailure ||= failed;
+        ids.add(rawStep.id);
+        steps.push({ id: rawStep.id, status: rawStep.status, stages });
+    }
+    if ((value.status === 'passed' && !steps.every(step => step.status === 'passed'))
+        || (value.status === 'failed' && !observedFailure))
+        return null;
+    return { schema_version: 1, status: value.status, verification: 'unknown', plan_sha256: value.plan_sha256, steps,
+        ...(typeof value.reason === 'string' ? { reason: value.reason } : {}) };
+}

package/dist/agent/runtime/command_execution_policy.d.ts

@@ -0,0 +1,26 @@
+/** Declared execution limits and cleanup policy, never evidence that cleanup succeeded. */
+export interface CommandExecutionPolicy {
+    schema_version: 1;
+    mode: 'foreground' | 'background';
+    timeout_ms: number | null;
+    timeout_source: 'default' | 'explicit' | 'unlimited';
+    started_at: string;
+    deadline_at: string | null;
+    cleanup: {
+        scope: 'local_process_group' | 'local_process';
+        term_grace_ms: 250;
+        turn_interrupt: 'cancel' | 'preserve' | 'unknown';
+        host_shutdown: 'cancel';
+        remote: 'unknown';
+    };
+}
+/** A host observation of elapsed execution time, independent of wall-clock drift. */
+export interface CommandExecutionObservation {
+    observed_at: string;
+    elapsed_ms: number;
+}
+export declare const COMMAND_EXECUTION_POLICY_MAX_BYTES = 2048;
+/** Validate a bounded, detached execution policy for runtime and browser consumers. */
+export declare function parseCommandExecutionPolicy(value: unknown): CommandExecutionPolicy | null;
+/** Validate an observation without inferring elapsed time from its wall-clock timestamp. */
+export declare function parseCommandExecutionObservation(value: unknown, startedAt: string): CommandExecutionObservation | null;

package/dist/agent/runtime/command_execution_policy.js

@@ -0,0 +1,91 @@
+export const COMMAND_EXECUTION_POLICY_MAX_BYTES = 2048;
+const encoder = new TextEncoder();
+function record(value, fields) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return null;
+    const keys = Reflect.ownKeys(value);
+    if (keys.length !== fields.length || keys.some(key => typeof key !== 'string' || !fields.includes(key)))
+        return null;
+    if (keys.some(key => !Object.hasOwn(Object.getOwnPropertyDescriptor(value, key), 'value')))
+        return null;
+    return value;
+}
+function instant(value) {
+    if (typeof value !== 'string')
+        return null;
+    const milliseconds = Date.parse(value);
+    return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === value ? milliseconds : null;
+}
+function member(value, choices) {
+    return typeof value === 'string' && choices.includes(value);
+}
+function bounded(value) {
+    return encoder.encode(JSON.stringify(value)).byteLength <= COMMAND_EXECUTION_POLICY_MAX_BYTES;
+}
+/** Validate a bounded, detached execution policy for runtime and browser consumers. */
+export function parseCommandExecutionPolicy(value) {
+    try {
+        const row = record(value, ['schema_version', 'mode', 'timeout_ms', 'timeout_source', 'started_at', 'deadline_at', 'cleanup']);
+        if (!row || row.schema_version !== 1 || !member(row.mode, ['foreground', 'background'])
+            || !member(row.timeout_source, ['default', 'explicit', 'unlimited']))
+            return null;
+        const cleanup = record(row.cleanup, ['scope', 'term_grace_ms', 'turn_interrupt', 'host_shutdown', 'remote']);
+        if (!cleanup || !member(cleanup.scope, ['local_process_group', 'local_process'])
+            || cleanup.term_grace_ms !== 250 || !member(cleanup.turn_interrupt, ['cancel', 'preserve', 'unknown'])
+            || cleanup.host_shutdown !== 'cancel' || cleanup.remote !== 'unknown')
+            return null;
+        const started = instant(row.started_at);
+        if (started === null)
+            return null;
+        let timeout;
+        let deadline;
+        if (row.timeout_source === 'unlimited') {
+            if (row.timeout_ms !== null || row.deadline_at !== null)
+                return null;
+            timeout = null;
+            deadline = null;
+        }
+        else {
+            if (typeof row.timeout_ms !== 'number' || !Number.isSafeInteger(row.timeout_ms)
+                || row.timeout_ms < 1 || row.timeout_ms > 86400000)
+                return null;
+            if (row.timeout_source === 'default' && row.timeout_ms !== 30000 && row.timeout_ms !== 120000)
+                return null;
+            const end = instant(row.deadline_at);
+            if (end === null || end !== started + row.timeout_ms)
+                return null;
+            timeout = row.timeout_ms;
+            deadline = row.deadline_at;
+        }
+        if (!bounded(row))
+            return null;
+        return {
+            schema_version: 1, mode: row.mode, timeout_ms: timeout, timeout_source: row.timeout_source,
+            started_at: row.started_at, deadline_at: deadline,
+            cleanup: { scope: cleanup.scope, term_grace_ms: 250, turn_interrupt: cleanup.turn_interrupt,
+                host_shutdown: 'cancel', remote: 'unknown' },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Validate an observation without inferring elapsed time from its wall-clock timestamp. */
+export function parseCommandExecutionObservation(value, startedAt) {
+    try {
+        const row = record(value, ['observed_at', 'elapsed_ms']);
+        if (!row || typeof row.elapsed_ms !== 'number' || !Number.isSafeInteger(row.elapsed_ms) || row.elapsed_ms < 0)
+            return null;
+        const started = instant(startedAt);
+        const observed = instant(row.observed_at);
+        if (started === null || observed === null || observed < started || !bounded(row))
+            return null;
+        return { observed_at: row.observed_at, elapsed_ms: row.elapsed_ms };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/agent/runtime/command_jobs.d.ts

@@ -1,4 +1,8 @@
 import { type RunShellCommandOptions } from '../../utils/shell.js';
+import type { CheckedCommandResult } from './checked_commands.js';
+import type { CommandVerificationReceipt, CurrentVerificationProjection } from './source_verification_contract.js';
+import { type SourceInspectionGate } from './source_verification.js';
+import { type CommandExecutionPolicy } from './command_execution_policy.js';
 export type CommandStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'interrupted';
 export interface CommandReceipt {
     job_id: string;
@@ -13,6 +17,28 @@ export interface CommandReceipt {
     owner_pid?: number;
     output_truncated?: boolean;
     dropped_bytes?: number;
+    checked?: CheckedCommandResult;
+    verification?: CommandVerificationReceipt;
+    verification_current?: CurrentVerificationProjection;
+    execution_policy?: CommandExecutionPolicy;
+    /** Host observation time; a terminal duration stays fixed after process completion. */
+    observed_at?: string;
+    elapsed_ms?: number;
+}
+export interface CommandReadResult extends CommandReceipt {
+    output: string;
+    cursor: number;
+    has_more: boolean;
+}
+export interface ManagedCommandObservation {
+    sessionId: string;
+    result: CommandReadResult;
+    requestedWaitMs: number;
+    kind: 'read' | 'launch';
+}
+export interface CommandProgressResult {
+    reason: 'output' | 'terminal' | 'deadline';
+    result: CommandReadResult;
 }
 export declare function subscribeCommandJobs(sessionId: string, listener: (jobs: CommandReceipt[]) => void): () => void;
 export declare function listCommandJobs(sessionId: string): CommandReceipt[];
@@ -24,24 +50,16 @@ export declare function startCommandJob(options: {
     shell: RunShellCommandOptions;
     maxJobs: number;
     signal?: AbortSignal;
+    verification?: CommandVerificationReceipt;
+    canInspectVerificationSource?: SourceInspectionGate;
 }): Promise<CommandReceipt>;
-export declare function readCommandJob(sessionId: string, jobId: string, cursor?: number, waitMs?: number, signal?: AbortSignal): Promise<{
-    output: string;
-    cursor: number;
-    has_more: boolean;
-    job_id: string;
-    status: CommandStatus;
-    command: string;
-    cwd: string;
-    started_at: string;
-    ended_at?: string;
-    exit_code?: number;
-    error?: string;
-    log_path: string;
-    owner_pid?: number;
-    output_truncated?: boolean;
-    dropped_bytes?: number;
-}>;
-export declare function stopCommandJob(sessionId: string, jobId: string): Promise<CommandReceipt>;
+export declare function readCommandJob(sessionId: string, jobId: string, cursor?: number, waitMs?: number, signal?: AbortSignal, canInspectSource?: SourceInspectionGate): Promise<CommandReadResult>;
+export declare function waitForCommandProgress(sessionId: string, jobId: string, options: {
+    cursor?: number;
+    maxWaitMs: number;
+    signal?: AbortSignal;
+    canInspectVerificationSource?: SourceInspectionGate;
+}): Promise<CommandProgressResult>;
+export declare function stopCommandJob(sessionId: string, jobId: string, canInspectSource?: SourceInspectionGate): Promise<CommandReceipt>;
 export declare function shutdownCommandJobs(sessionId?: string): Promise<void>;
 export declare function interruptCommandJobs(sessionId: string): Promise<void>;

package/dist/agent/runtime/command_jobs.js

@@ -3,6 +3,9 @@ import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readSync,
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { runShellCommand } from '../../utils/shell.js';
+import { finishCommandVerification, projectCurrentVerification } from './source_verification.js';
+import { parseCommandExecutionPolicy } from './command_execution_policy.js';
+import { writeFileAtomicSync } from '../../utils/atomic_write.js';
 const MAX_LOG_BYTES = 16 * 1024 * 1024;
 const MAX_RETAINED_JOBS = 64;
 const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
@@ -27,6 +30,10 @@ function publish(sessionId) {
         catch { /* a view cannot change command lifecycle */ }
     }
 }
+function notifyActivity(job) {
+    for (const listener of job.activity)
+        listener();
+}
 /** Bound completed logs across all sessions; active processes keep their logs. */
 function pruneCommandLogs() {
     const root = join(process.env.ZTC_CONFIG_DIR || join(homedir(), '.ztc'), 'command-jobs');
@@ -100,12 +107,14 @@ function appendCommandOutput(sessionId, job, text) {
         if (first)
             save(sessionId, job.receipt);
     }
+    if (count > 0 || count < bytes.length)
+        notifyActivity(job);
 }
 function directory(sessionId) {
     return join(process.env.ZTC_CONFIG_DIR || join(homedir(), '.ztc'), 'command-jobs', createHash('sha256').update(sessionId).digest('hex').slice(0, 32));
 }
 function save(sessionId, receipt) {
-    writeFileSync(join(directory(sessionId), `${receipt.job_id}.json`), JSON.stringify(receipt), { mode: 0o600 });
+    writeFileAtomicSync(join(directory(sessionId), `${receipt.job_id}.json`), JSON.stringify(receipt), { mode: 0o600 });
 }
 function resolveJob(sessionId, jobId) {
     if (!/^[0-9a-f-]{36}$/.test(jobId))
@@ -120,15 +129,43 @@ function resolveJob(sessionId, jobId) {
     catch {
         throw new Error('Command job not found in this session');
     }
+    const policy = parseCommandExecutionPolicy(receipt.execution_policy);
+    if (policy && policy.started_at === receipt.started_at)
+        receipt.execution_policy = policy;
+    else
+        delete receipt.execution_policy;
     if (receipt.status === 'running') {
-        receipt = { ...receipt, status: 'interrupted', ended_at: new Date().toISOString(), error: 'Owning ZTC process ended; inspect output before retrying.' };
+        receipt = { ...receipt, status: 'interrupted', error: 'Owning ZTC process ended; inspect output before retrying.',
+            ...(receipt.verification?.process_outcome === 'running' ? { verification: { ...receipt.verification,
+                    process_outcome: 'interrupted', source_binding: 'unknown' } } : {}) };
+        // Recovery observes missing ownership, not the original process's end time.
+        delete receipt.ended_at;
+        delete receipt.observed_at;
+        delete receipt.elapsed_ms;
         save(sessionId, receipt);
     }
-    return { receipt, controller: new AbortController(), done: Promise.resolve(), loggedBytes: statSync(receipt.log_path).size };
+    return { receipt, controller: new AbortController(), done: Promise.resolve(), loggedBytes: statSync(receipt.log_path).size, activity: new Set(),
+        canInspectVerificationSource: () => false };
 }
 export function listCommandJobs(sessionId) {
     const jobs = [...(sessions.get(sessionId)?.values() ?? [])];
-    return [...jobs.filter(job => job.receipt.status === 'running'), ...jobs.filter(job => job.receipt.status !== 'running').slice(-28)].map(job => ({ ...job.receipt }));
+    return [...jobs.filter(job => job.receipt.status === 'running'), ...jobs.filter(job => job.receipt.status !== 'running').slice(-28)].map(job => observeReceipt(job.receipt));
+}
+function observeReceipt(receipt) {
+    const result = structuredClone(receipt);
+    const now = Date.now();
+    const started = Date.parse(receipt.started_at);
+    const ended = receipt.status === 'running' ? now : Date.parse(receipt.ended_at ?? '');
+    const elapsed = ended - started;
+    if (Number.isSafeInteger(elapsed) && elapsed >= 0 && now >= started) {
+        result.observed_at = new Date(now).toISOString();
+        result.elapsed_ms = elapsed;
+    }
+    else {
+        delete result.observed_at;
+        delete result.elapsed_ms;
+    }
+    return result;
 }
 export async function startCommandJob(options) {
     const { sessionId } = options;
@@ -148,9 +185,11 @@ export async function startCommandJob(options) {
     const logPath = join(directory(sessionId), `${jobId}.log`);
     writeFileSync(logPath, '', { mode: 0o600 });
     const controller = new AbortController();
-    const job = { controller, done: Promise.resolve(), loggedBytes: 0, receipt: {
+    const job = { controller, done: Promise.resolve(), loggedBytes: 0, activity: new Set(),
+        canInspectVerificationSource: options.canInspectVerificationSource ?? (() => true), receipt: {
             job_id: jobId, status: 'running', command: options.command, cwd: options.cwd,
             started_at: new Date().toISOString(), log_path: logPath, owner_pid: process.pid,
+            ...(options.verification ? { verification: structuredClone(options.verification) } : {}),
         } };
     save(sessionId, job.receipt);
     registry.set(jobId, job);
@@ -159,19 +198,40 @@ export async function startCommandJob(options) {
     options.signal?.addEventListener('abort', abort, { once: true });
     job.done = runShellCommand(options.command, options.cwd, controller.signal, options.timeoutMs, {
         ...options.shell, noTimeout: options.timeoutMs === undefined,
+        executionMode: 'background', turnInterruptPolicy: options.signal ? 'cancel' : 'preserve',
+        onExecutionPolicy: policy => {
+            job.receipt.execution_policy = structuredClone(policy);
+            job.receipt.started_at = policy.started_at;
+            options.shell.onExecutionPolicy?.(structuredClone(policy));
+            save(sessionId, job.receipt);
+            publish(sessionId);
+        },
         onOutput: (_stream, text) => appendCommandOutput(sessionId, job, text),
+        onCheckedProgress: checked => { job.receipt.checked = structuredClone(checked); save(sessionId, job.receipt); publish(sessionId); },
     }).then(result => {
         job.receipt.exit_code = result.exitCode;
-        job.receipt.status = result.exitCode === 124 ? 'timed_out' : result.exitCode === 0 ? 'completed' : 'failed';
+        if (result.checked)
+            job.receipt.checked = structuredClone(result.checked);
+        if (job.receipt.status !== 'interrupted')
+            job.receipt.status = result.checked
+                ? result.checked.status === 'passed' ? 'completed' : result.checked.status === 'timed_out' ? 'timed_out'
+                    : result.checked.status === 'cancelled' ? 'cancelled' : 'failed'
+                : result.timedOut === true ? 'timed_out' : result.exitCode === 0 ? 'completed' : 'failed';
         if (result.exitCode !== 0)
             job.receipt.error = result.stderr.slice(-4096) || `Command exited with code ${result.exitCode}`;
+        job.receipt.ended_at = new Date().toISOString();
     }, error => {
         if (job.receipt.status !== 'interrupted')
             job.receipt.status = controller.signal.aborted ? 'cancelled' : 'failed';
         job.receipt.error = error.message;
-    }).finally(() => {
-        options.signal?.removeEventListener('abort', abort);
         job.receipt.ended_at = new Date().toISOString();
+    }).finally(async () => {
+        options.signal?.removeEventListener('abort', abort);
+        if (job.receipt.verification) {
+            const outcome = job.receipt.status === 'completed' ? 'passed' : job.receipt.status === 'running' ? 'unknown' : job.receipt.status;
+            job.receipt.verification = await finishCommandVerification(job.receipt.verification, outcome, job.canInspectVerificationSource);
+            job.receipt.verification_current = await projectCurrentVerification(job.receipt.verification, job.canInspectVerificationSource);
+        }
         try {
             save(sessionId, job.receipt);
         }
@@ -184,16 +244,19 @@ export async function startCommandJob(options) {
         const terminal = [...registry.entries()].filter(([, entry]) => entry.receipt.status !== 'running');
         for (const [id] of terminal.slice(0, Math.max(0, terminal.length - 64)))
             registry.delete(id);
+        notifyActivity(job);
         publish(sessionId);
     });
-    return { ...job.receipt };
+    return observeReceipt(job.receipt);
 }
-export async function readCommandJob(sessionId, jobId, cursor = 0, waitMs = 0, signal) {
+export async function readCommandJob(sessionId, jobId, cursor = 0, waitMs = 0, signal, canInspectSource) {
     if (!Number.isSafeInteger(cursor) || cursor < 0)
         throw new Error('cursor must be a non-negative byte offset');
     if (!Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > 60000)
         throw new Error('wait_ms must be an integer between 0 and 60000');
     const job = resolveJob(sessionId, jobId);
+    if (canInspectSource)
+        job.canInspectVerificationSource = canInspectSource;
     const cancelled = () => new Error(`Command read cancelled; inspect job ${jobId} before retrying. The job may still be running.`);
     if (signal?.aborted)
         throw cancelled();
@@ -214,6 +277,19 @@ export async function readCommandJob(sessionId, jobId, cursor = 0, waitMs = 0, s
                 signal?.removeEventListener('abort', onAbort);
         }
     }
+    const result = await refreshReadVerification(job, readOutput(job, cursor), canInspectSource);
+    return observeReceipt(result);
+}
+async function refreshReadVerification(job, result, canInspectSource) {
+    if (!result.verification)
+        return result;
+    const original = job.receipt.verification;
+    const current = await projectCurrentVerification(result.verification, canInspectSource ?? job.canInspectVerificationSource);
+    if (job.receipt.verification === original)
+        job.receipt.verification_current = structuredClone(current);
+    return { ...result, verification_current: current };
+}
+function readOutput(job, cursor) {
     const size = statSync(job.receipt.log_path).size;
     if (cursor > size)
         throw new Error('cursor is beyond the command output');
@@ -240,15 +316,77 @@ export async function readCommandJob(sessionId, jobId, cursor = 0, waitMs = 0, s
                 throw new Error('cursor must be at a UTF-8 character boundary');
         }
     }
-    return { ...job.receipt, output, cursor: cursor + count, has_more: cursor + count < size };
+    return { ...observeReceipt(job.receipt), output, cursor: cursor + count, has_more: cursor + count < size };
+}
+export async function waitForCommandProgress(sessionId, jobId, options) {
+    const cursor = options.cursor ?? 0;
+    if (!Number.isSafeInteger(cursor) || cursor < 0)
+        throw new Error('cursor must be a non-negative byte offset');
+    if (!Number.isSafeInteger(options.maxWaitMs) || options.maxWaitMs < 0 || options.maxWaitMs > 60000) {
+        throw new Error('maxWaitMs must be an integer between 0 and 60000');
+    }
+    const job = resolveJob(sessionId, jobId);
+    if (options.canInspectVerificationSource)
+        job.canInspectVerificationSource = options.canInspectVerificationSource;
+    const cancelled = () => new Error(`Command read cancelled; inspect job ${jobId} before retrying. The job may still be running.`);
+    if (options.signal?.aborted)
+        throw cancelled();
+    const progress = await new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        const cleanup = () => {
+            settled = true;
+            job.activity.delete(onActivity);
+            if (timer !== undefined)
+                clearTimeout(timer);
+            options.signal?.removeEventListener('abort', onAbort);
+        };
+        const onAbort = () => { if (!settled) {
+            cleanup();
+            reject(cancelled());
+        } };
+        const inspect = (deadline) => {
+            if (settled)
+                return;
+            if (options.signal?.aborted) {
+                onAbort();
+                return;
+            }
+            try {
+                const result = readOutput(job, cursor);
+                const reason = result.status !== 'running' ? 'terminal' : result.output.length > 0 ? 'output' : deadline ? 'deadline' : null;
+                if (reason !== null) {
+                    cleanup();
+                    resolve({ reason, result });
+                }
+            }
+            catch (error) {
+                cleanup();
+                reject(error);
+            }
+        };
+        const onActivity = () => inspect(false);
+        // Register before checking bytes/status so output or completion cannot be lost.
+        job.activity.add(onActivity);
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        if (options.maxWaitMs > 0)
+            timer = setTimeout(() => inspect(true), options.maxWaitMs);
+        inspect(options.maxWaitMs === 0);
+    });
+    const result = await refreshReadVerification(job, progress.result, options.canInspectVerificationSource);
+    return { reason: progress.reason, result: observeReceipt(result) };
 }
-export async function stopCommandJob(sessionId, jobId) {
+export async function stopCommandJob(sessionId, jobId, canInspectSource) {
     const job = resolveJob(sessionId, jobId);
+    if (canInspectSource)
+        job.canInspectVerificationSource = canInspectSource;
     if (job.receipt.status === 'running') {
         job.controller.abort();
         await job.done;
     }
-    return { ...job.receipt };
+    if (job.receipt.verification)
+        job.receipt.verification_current = await projectCurrentVerification(job.receipt.verification, job.canInspectVerificationSource);
+    return observeReceipt(job.receipt);
 }
 export async function shutdownCommandJobs(sessionId) {
     const registries = sessionId ? [sessions.get(sessionId)] : [...sessions.values()];

package/dist/agent/runtime/command_panes.d.ts

@@ -0,0 +1,59 @@
+import type { RunShellCommandOptions } from '../../utils/shell.js';
+export type CommandPaneState = 'suspended' | 'running' | 'completed' | 'failed' | 'unknown';
+export interface CommandPaneView {
+    id: string;
+    name: string;
+    command: string;
+    cwd: string;
+    environmentKeys: string[];
+    state: CommandPaneState;
+    attempt: string;
+    exitCode?: number;
+    error?: string;
+    output: string;
+    evidence?: {
+        path: string;
+        sha256: string;
+    };
+}
+/** Durable definitions and command receipts are authoritative; panes are projections. */
+export declare class CommandPaneManager {
+    private readonly sessionId;
+    private readonly shellOptions;
+    private readonly file;
+    private readonly sessionDirectory;
+    private readonly listeners;
+    private readonly localJobs;
+    private readonly admittedJobs;
+    private timer?;
+    private refreshTask?;
+    private closed;
+    private lastPublished?;
+    constructor(sessionId: string, sessionCwd: string, shellOptions: () => RunShellCommandOptions);
+    private read;
+    private mutate;
+    private find;
+    pin(options: {
+        name: string;
+        command: string;
+        cwd: string;
+        env?: Record<string, string>;
+        suspended?: boolean;
+    }): Promise<CommandPaneView>;
+    /** expectedAttempt binds an action to the snapshot it was offered on. */
+    run(name: string, expectedAttempt: string): Promise<CommandPaneView>;
+    stop(name: string, expectedAttempt: string): Promise<void>;
+    unpin(name: string): Promise<void>;
+    private output;
+    list(): Promise<CommandPaneView[]>;
+    attachEvidence(name: string, expectedAttempt: string): Promise<{
+        path: string;
+        sha256: string;
+    }>;
+    subscribe(listener: (commands: CommandPaneView[]) => void): () => void;
+    private watch;
+    refresh(): Promise<void>;
+    private publish;
+    dispose(): Promise<void>;
+}
+export declare function commandPaneText(command: CommandPaneView): string;