ultracode-for-codex 0.2.5 → 0.3.0

package/dist/cli.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import { spawn } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { realpathSync } from 'node:fs';
-import { mkdir, open, readFile, writeFile } from 'node:fs/promises';
-import { isAbsolute, join, resolve } from 'node:path';
+import { chmod, mkdir, open, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createInterface } from 'node:readline/promises';
 import { CodexSubagentBackend } from './codex/subagent-backend.js';
 import { WorkflowTaskRegistry } from './runtime/workflow-runtime.js';
 import { UltracodeRequestError } from './runtime/types.js';
+import { ultracodePackageVersion } from './runtime/package-info.js';
 import { renderUltracodeInstallGuideNotice } from './ultracode-install-guide.js';
 import { codexDefaultReasoningEffort, codexDefaultVerbosity, isReasoningEffort, isVerbosity, isWorkflowExecutionMode, isWorkflowPermissionPolicy, isWorkflowProgressMode, workflowBackgroundDefaults, workflowDefaultExecutionMode, workflowDefaultPermissionPolicy, workflowDefaultProgressMode, workflowDefaultRetryLimit, workflowDefaultTimeoutMs, } from './settings.js';
 const ULTRACODE_INSTALL_GUIDE_ACCEPT_VERSION = 'v1';
@@ -19,12 +20,30 @@ async function main(argv) {
         process.stdout.write(helpText());
         return 0;
     }
+    if (command === 'version' || command === '--version' || command === '-v') {
+        process.stdout.write(`ultracode-for-codex ${ultracodePackageVersion()}\n`);
+        return 0;
+    }
     if (command === '--llm-guide' || command === 'llm-guide') {
         process.stdout.write(renderUltracodeInstallGuideNotice());
         return 0;
     }
     if (command === 'run')
         return runWorkflow(args);
+    if (command === 'status')
+        return showBackgroundStatus(args);
+    if (command === 'wait')
+        return waitForBackgroundJob(args);
+    if (command === 'logs')
+        return showBackgroundLogs(args);
+    if (command === 'result')
+        return showBackgroundResult(args);
+    if (command === 'cancel')
+        return cancelBackgroundJob(args);
+    if (command === 'jobs' || command === 'list')
+        return listBackgroundJobs(args);
+    if (command === 'archive' || command === 'export')
+        return archiveBackgroundJob(args);
     process.stderr.write(`Unknown command: ${command}\n\n${helpText()}`);
     return 1;
 }
@@ -64,6 +83,7 @@ async function runWorkflow(args) {
             const snapshot = await streamCommandWorkflow(runtime, launch, progressMode);
             if (snapshot.status === 'completed') {
                 process.stdout.write(`${JSON.stringify(snapshot.result ?? null, null, 2)}\n`);
+                renderWorkflowCompletionGuidance(snapshot, progressMode);
                 return 0;
             }
             renderFailedSnapshot(snapshot, progressMode);
@@ -121,10 +141,11 @@ async function launchBackgroundWorkflow(args, cwd) {
     await mkdir(runDir, { recursive: true });
     const stdout = await open(resultPath, 'w');
     const stderr = await open(progressPath, 'w');
+    const entryPath = cliEntryPath();
     let childPid = 0;
     try {
         const child = spawn(process.execPath, [
-            cliEntryPath(),
+            entryPath,
             'run',
             ...args,
             '--execution',
@@ -155,6 +176,9 @@ async function launchBackgroundWorkflow(args, cwd) {
         progressPath,
         metadataPath,
         pidPath,
+        nodePath: process.execPath,
+        cliEntryPath: entryPath,
+        commandLineHint: `${process.execPath} ${entryPath} run`,
     }, null, 2)}\n`);
     process.stdout.write(`${JSON.stringify({
         kind: 'ultracode.workflow.background',
@@ -169,6 +193,624 @@ async function launchBackgroundWorkflow(args, cwd) {
     }, null, 2)}\n`);
     return 0;
 }
+async function showBackgroundStatus(args) {
+    const options = parseOptions(args);
+    const status = await inspectBackgroundJob(options);
+    if (wantsPlain(options)) {
+        process.stdout.write(renderBackgroundStatusPlain(status));
+        return 0;
+    }
+    process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+    return 0;
+}
+async function waitForBackgroundJob(args) {
+    const options = parseOptions(args);
+    const timeoutMs = parseNonNegativeIntOption(options.timeoutMs, 0, 'timeout-ms');
+    const intervalMs = parsePositiveIntOption(options.intervalMs, 1_000, 'interval-ms');
+    const waited = await waitForTerminalBackgroundJob(options, timeoutMs, intervalMs);
+    if (waited.timedOut) {
+        const payload = {
+            ...waited.status,
+            waitTimedOut: true,
+            waitTimeoutMs: timeoutMs,
+        };
+        if (wantsPlain(options))
+            process.stdout.write(renderBackgroundStatusPlain(payload));
+        else
+            process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return 124;
+    }
+    if (wantsResult(options) && waited.status.status === 'completed') {
+        return await printBackgroundResult(await resolveBackgroundJobRef(options), waited.status);
+    }
+    if (wantsPlain(options))
+        process.stdout.write(renderBackgroundStatusPlain(waited.status));
+    else
+        process.stdout.write(`${JSON.stringify(waited.status, null, 2)}\n`);
+    return waited.status.status === 'completed' ? 0 : 1;
+}
+async function showBackgroundLogs(args) {
+    const options = parseOptions(args);
+    const ref = await resolveBackgroundJobRef(options);
+    const progress = await readBackgroundProgress(ref.progressPath);
+    if (!progress.exists) {
+        process.stderr.write(`Background progress file not found: ${ref.progressPath}\n`);
+        return 1;
+    }
+    const filtered = options.event
+        ? progress.events.filter((event) => event.event === options.event)
+        : progress.events;
+    const tail = options.tail === undefined ? 0 : parseNonNegativeIntOption(options.tail, 0, 'tail');
+    const selected = tail > 0 ? filtered.slice(-tail) : filtered;
+    if (wantsPlain(options)) {
+        process.stdout.write(selected.map(renderProgressEventPlain).join(''));
+    }
+    else {
+        process.stdout.write(selected.map((event) => JSON.stringify(event)).join('\n'));
+        if (selected.length > 0)
+            process.stdout.write('\n');
+    }
+    return 0;
+}
+async function showBackgroundResult(args) {
+    const options = parseOptions(args);
+    const ref = await resolveBackgroundJobRef(options);
+    const status = await inspectBackgroundJob(options);
+    return await printBackgroundResult(ref, status);
+}
+async function printBackgroundResult(ref, status) {
+    const text = await readTextFileIfPresent(ref.resultPath);
+    if (text !== null && text.trim()) {
+        process.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+        return 0;
+    }
+    process.stderr.write(`Background result is not ready: ${status.status}${status.reason ? ` (${status.reason})` : ''}\n`);
+    return status.status === 'failed' ? 1 : 2;
+}
+async function cancelBackgroundJob(args) {
+    const options = parseOptions(args);
+    const ref = await resolveBackgroundJobRef(options);
+    const metadata = await readBackgroundMetadata(ref.metadataPath);
+    const pid = metadata.pid || await readPid(ref.pidPath);
+    if (!pid || pid <= 0) {
+        process.stderr.write(`Background job pid not found: ${ref.pidPath}\n`);
+        return 1;
+    }
+    const signal = parseSignalOption(options.signal);
+    const alive = isProcessAlive(pid);
+    const commandLine = alive ? backgroundProcessCommandLine(pid) : undefined;
+    const identityVerified = !alive || backgroundProcessIdentityMatches(metadata, commandLine);
+    const cancelResult = {
+        kind: 'ultracode.workflow.background.cancel',
+        version: 1,
+        status: alive
+            ? identityVerified ? 'signalled' : 'identity_mismatch'
+            : 'not_running',
+        jobId: metadata.jobId,
+        pid,
+        signal,
+        identityVerified,
+        ...(commandLine ? { processCommandLine: commandLine } : {}),
+        metadataPath: ref.metadataPath,
+        resultPath: ref.resultPath,
+        progressPath: ref.progressPath,
+        pidPath: ref.pidPath,
+    };
+    if (alive && !identityVerified) {
+        if (wantsPlain(options))
+            process.stdout.write(renderBackgroundCancelPlain(cancelResult));
+        else
+            process.stdout.write(`${JSON.stringify(cancelResult, null, 2)}\n`);
+        return 1;
+    }
+    if (alive) {
+        process.kill(pid, signal);
+    }
+    if (wantsWait(options)) {
+        const timeoutMs = parseNonNegativeIntOption(options.timeoutMs, 0, 'timeout-ms');
+        const intervalMs = parsePositiveIntOption(options.intervalMs, 1_000, 'interval-ms');
+        const waited = await waitForTerminalBackgroundJob(options, timeoutMs, intervalMs);
+        const payload = {
+            kind: 'ultracode.workflow.background.cancel.wait',
+            version: 1,
+            cancel: cancelResult,
+            terminalStatus: waited.status,
+            waitTimedOut: waited.timedOut,
+            ...(waited.timedOut ? { waitTimeoutMs: timeoutMs } : {}),
+        };
+        if (wantsPlain(options)) {
+            process.stdout.write(`${renderBackgroundCancelPlain(cancelResult)}${renderBackgroundStatusPlain(waited.status)}`);
+        }
+        else {
+            process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        }
+        return waited.timedOut ? 124 : 0;
+    }
+    if (wantsPlain(options))
+        process.stdout.write(renderBackgroundCancelPlain(cancelResult));
+    else
+        process.stdout.write(`${JSON.stringify(cancelResult, null, 2)}\n`);
+    return 0;
+}
+async function listBackgroundJobs(args) {
+    const options = parseOptions(args);
+    const list = await backgroundJobsList(options);
+    if (wantsPlain(options)) {
+        process.stdout.write(renderBackgroundJobsPlain(list));
+        return 0;
+    }
+    process.stdout.write(`${JSON.stringify(list, null, 2)}\n`);
+    return 0;
+}
+async function archiveBackgroundJob(args) {
+    const options = parseOptions(args);
+    const ref = await resolveBackgroundJobRef(options);
+    const metadata = await readBackgroundMetadata(ref.metadataPath);
+    const status = await inspectBackgroundJob(options);
+    const progress = await readBackgroundProgress(ref.progressPath);
+    const resultText = await readTextFileIfPresent(ref.resultPath);
+    const archivePath = await backgroundArchivePath(options, metadata.jobId);
+    const record = {
+        kind: 'ultracode.workflow.background.archive',
+        version: 1,
+        archivedAt: new Date().toISOString(),
+        archivePath,
+        status,
+        metadata,
+        progressEvents: progress.events,
+        malformedProgressLineCount: progress.malformedLineCount,
+        resultText,
+    };
+    await mkdir(dirname(archivePath), { recursive: true });
+    await writeFile(archivePath, `${JSON.stringify(record, null, 2)}\n`);
+    await chmod(archivePath, 0o600).catch(() => undefined);
+    const projection = {
+        kind: 'ultracode.workflow.background.archive.created',
+        version: 1,
+        jobId: metadata.jobId,
+        archivePath,
+        status: status.status,
+        progressEventCount: progress.events.length,
+    };
+    if (wantsPlain(options)) {
+        process.stdout.write(`[archive] ${metadata.jobId} ${status.status} -> ${archivePath}\n`);
+    }
+    else {
+        process.stdout.write(`${JSON.stringify(projection, null, 2)}\n`);
+    }
+    return 0;
+}
+async function inspectBackgroundJob(options) {
+    const ref = await resolveBackgroundJobRef(options);
+    const metadata = await readBackgroundMetadata(ref.metadataPath);
+    const pid = metadata.pid || await readPid(ref.pidPath);
+    const alive = pid ? isProcessAlive(pid) : false;
+    const progress = await readBackgroundProgress(ref.progressPath);
+    const resultText = await readTextFileIfPresent(ref.resultPath);
+    const resultReady = Boolean(resultText?.trim());
+    const statusEvents = progress.events.filter((event) => !isPostCompletionGuidanceEvent(event));
+    const lastEvent = statusEvents.at(-1);
+    const terminalEvent = [...statusEvents].reverse().find((event) => (event.event === 'workflow.completed'
+        || event.event === 'workflow.failed'
+        || event.event === 'workflow.terminal_failure'));
+    const status = backgroundStatusFrom({ terminalEvent, resultReady, alive });
+    return {
+        kind: 'ultracode.workflow.background.status',
+        version: 1,
+        status,
+        jobId: metadata.jobId ?? ref.jobId,
+        pid,
+        alive,
+        launchedAt: metadata.launchedAt,
+        cwd: metadata.cwd ?? ref.cwd,
+        resultPath: ref.resultPath,
+        progressPath: ref.progressPath,
+        metadataPath: ref.metadataPath,
+        pidPath: ref.pidPath,
+        resultReady,
+        progressEventCount: progress.events.length,
+        malformedProgressLineCount: progress.malformedLineCount,
+        lastEvent: lastEvent?.event,
+        lastStatus: lastEvent?.status,
+        lastSummary: lastEvent?.summary,
+        reason: terminalEvent?.reason,
+        error: terminalEvent?.error,
+        completedAgentCount: lastNumericField(progress.events, 'completedAgentCount'),
+        knownAgentCount: lastNumericField(progress.events, 'knownAgentCount'),
+        phase: lastStringField(progress.events, 'phase'),
+        phaseCompletedAgentCount: lastNumericField(progress.events, 'phaseCompletedAgentCount'),
+        phaseKnownAgentCount: lastNumericField(progress.events, 'phaseKnownAgentCount'),
+        elapsedMs: lastNumericField(progress.events, 'elapsedMs'),
+    };
+}
+async function waitForTerminalBackgroundJob(options, timeoutMs, intervalMs) {
+    const startedAt = Date.now();
+    while (true) {
+        const status = await inspectBackgroundJob(options);
+        if (isTerminalBackgroundStatus(status.status))
+            return { status, timedOut: false };
+        if (timeoutMs > 0 && Date.now() - startedAt >= timeoutMs)
+            return { status, timedOut: true };
+        await delay(intervalMs);
+    }
+}
+async function backgroundJobsList(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const settings = workflowBackgroundDefaults();
+    const backgroundRoot = resolveBackgroundJobsRoot(cwd, settings.runDir);
+    const jobs = [];
+    const invalidJobs = [];
+    let entries = [];
+    try {
+        entries = await readdir(backgroundRoot);
+    }
+    catch (err) {
+        if (!isNodeErrorCode(err, 'ENOENT'))
+            throw err;
+    }
+    for (const entry of entries) {
+        const candidateDir = join(backgroundRoot, entry);
+        const candidateMetadataPath = join(candidateDir, settings.metadataFile);
+        const candidateStat = await stat(candidateMetadataPath).catch((err) => {
+            if (isNodeErrorCode(err, 'ENOENT') || isNodeErrorCode(err, 'ENOTDIR'))
+                return null;
+            throw err;
+        });
+        if (!candidateStat?.isFile())
+            continue;
+        try {
+            const metadata = await readBackgroundMetadata(candidateMetadataPath);
+            jobs.push(await inspectBackgroundJob({
+                ...options,
+                _: [],
+                metadataPath: metadata.metadataPath || candidateMetadataPath,
+                cwd,
+            }));
+        }
+        catch (err) {
+            invalidJobs.push({ path: candidateMetadataPath, error: errorMessage(err) });
+        }
+    }
+    jobs.sort((a, b) => String(b.launchedAt ?? '').localeCompare(String(a.launchedAt ?? '')));
+    return {
+        kind: 'ultracode.workflow.background.jobs',
+        version: 1,
+        cwd,
+        backgroundRoot,
+        count: jobs.length,
+        jobs,
+        invalidJobs,
+    };
+}
+async function resolveBackgroundJobRef(options) {
+    if (options._.length > 1) {
+        throw new Error('Background commands accept at most one positional job id or metadata path.');
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const positional = options._[0];
+    const positionalLooksLikePath = positional
+        ? positional.includes('/') || positional.includes('\\') || positional.endsWith('.json')
+        : false;
+    const jobId = options.jobId ?? (positional && !positionalLooksLikePath ? positional : undefined);
+    const metadataPathOption = options.metadataPath ?? (positional && positionalLooksLikePath ? positional : undefined);
+    let ref;
+    if (metadataPathOption) {
+        const metadataPath = resolve(metadataPathOption);
+        const metadata = await readBackgroundMetadata(metadataPath);
+        ref = {
+            jobId: metadata.jobId,
+            cwd: metadata.cwd,
+            metadataPath,
+            resultPath: options.resultPath ? resolve(options.resultPath) : requireMetadataPath(metadata.resultPath, 'resultPath'),
+            progressPath: options.progressPath ? resolve(options.progressPath) : requireMetadataPath(metadata.progressPath, 'progressPath'),
+            pidPath: options.pidPath ? resolve(options.pidPath) : requireMetadataPath(metadata.pidPath, 'pidPath'),
+        };
+    }
+    else if (jobId) {
+        const settings = workflowBackgroundDefaults();
+        const runDir = resolveBackgroundRunDir(cwd, settings.runDir, jobId);
+        ref = {
+            jobId,
+            cwd,
+            metadataPath: options.metadataPath ? resolve(options.metadataPath) : join(runDir, settings.metadataFile),
+            resultPath: options.resultPath ? resolve(options.resultPath) : join(runDir, settings.resultFile),
+            progressPath: options.progressPath ? resolve(options.progressPath) : join(runDir, settings.progressFile),
+            pidPath: options.pidPath ? resolve(options.pidPath) : join(runDir, settings.pidFile),
+        };
+    }
+    else {
+        throw new Error('Background command requires a job id, metadata path, or --job-id.');
+    }
+    assertDistinctBackgroundPaths([ref.resultPath, ref.progressPath, ref.metadataPath, ref.pidPath]);
+    return ref;
+}
+async function readBackgroundMetadata(metadataPath) {
+    const text = await readTextFileIfPresent(metadataPath);
+    if (text === null)
+        throw new Error(`Background metadata file not found: ${metadataPath}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`Background metadata file is not valid JSON: ${errorMessage(err)}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Background metadata must contain a JSON object.');
+    }
+    return validateBackgroundMetadata(parsed, metadataPath);
+}
+async function readPid(pidPath) {
+    const text = await readTextFileIfPresent(pidPath);
+    if (text === null)
+        return undefined;
+    const pid = Number.parseInt(text.trim(), 10);
+    return Number.isFinite(pid) ? pid : undefined;
+}
+function validateBackgroundMetadata(value, metadataPath) {
+    const kind = requiredString(value.kind, 'kind');
+    if (kind !== 'ultracode.workflow.background') {
+        throw new Error(`Background metadata kind must be ultracode.workflow.background: ${metadataPath}`);
+    }
+    const version = requiredInteger(value.version, 'version');
+    if (version !== 1)
+        throw new Error(`Background metadata version must be 1: ${metadataPath}`);
+    const status = requiredString(value.status, 'status');
+    if (status !== 'launched')
+        throw new Error(`Background metadata status must be launched: ${metadataPath}`);
+    const pid = requiredInteger(value.pid, 'pid');
+    if (pid < 0)
+        throw new Error(`Background metadata pid must be non-negative: ${metadataPath}`);
+    const metadata = {
+        kind: 'ultracode.workflow.background',
+        version: 1,
+        status: 'launched',
+        jobId: requiredString(value.jobId, 'jobId'),
+        pid,
+        launchedAt: requiredString(value.launchedAt, 'launchedAt'),
+        cwd: requiredString(value.cwd, 'cwd'),
+        resultPath: requiredString(value.resultPath, 'resultPath'),
+        progressPath: requiredString(value.progressPath, 'progressPath'),
+        metadataPath: requiredString(value.metadataPath, 'metadataPath'),
+        pidPath: requiredString(value.pidPath, 'pidPath'),
+        ...(typeof value.nodePath === 'string' && value.nodePath ? { nodePath: value.nodePath } : {}),
+        ...(typeof value.cliEntryPath === 'string' && value.cliEntryPath ? { cliEntryPath: value.cliEntryPath } : {}),
+        ...(typeof value.commandLineHint === 'string' && value.commandLineHint ? { commandLineHint: value.commandLineHint } : {}),
+    };
+    for (const [key, path] of Object.entries({
+        cwd: metadata.cwd,
+        resultPath: metadata.resultPath,
+        progressPath: metadata.progressPath,
+        metadataPath: metadata.metadataPath,
+        pidPath: metadata.pidPath,
+    })) {
+        if (!isAbsolute(path))
+            throw new Error(`Background metadata ${key} must be an absolute path: ${metadataPath}`);
+    }
+    return metadata;
+}
+function requiredString(value, key) {
+    if (typeof value === 'string' && value.trim())
+        return value;
+    throw new Error(`Background metadata ${key} must be a non-empty string.`);
+}
+function requiredInteger(value, key) {
+    if (typeof value === 'number' && Number.isInteger(value))
+        return value;
+    throw new Error(`Background metadata ${key} must be an integer.`);
+}
+function backgroundProcessCommandLine(pid) {
+    try {
+        return execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function backgroundProcessIdentityMatches(metadata, commandLine) {
+    if (!metadata.cliEntryPath || !commandLine)
+        return true;
+    return commandLine.includes(metadata.cliEntryPath)
+        && (!metadata.nodePath || commandLine.includes(metadata.nodePath) || commandLine.includes('node'));
+}
+async function backgroundArchivePath(options, jobId) {
+    if (options.outputPath)
+        return resolve(options.outputPath);
+    const cwd = options.cwd ?? process.cwd();
+    const archiveDir = options.outDir
+        ? resolve(options.outDir)
+        : resolve(cwd, '.ultracode-for-codex', 'archive');
+    return join(archiveDir, `${jobId}.json`);
+}
+async function readBackgroundProgress(progressPath) {
+    const text = await readTextFileIfPresent(progressPath);
+    if (text === null)
+        return { exists: false, events: [], malformedLineCount: 0 };
+    if (!text.trim())
+        return { exists: true, events: [], malformedLineCount: 0 };
+    const lines = text.split(/\r?\n/);
+    if (lines.at(-1) === '')
+        lines.pop();
+    const events = [];
+    let malformedLineCount = 0;
+    for (const [index, line] of lines.entries()) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed
+                && typeof parsed === 'object'
+                && !Array.isArray(parsed)
+                && parsed.kind === PROGRESS_KIND
+                && parsed.version === 1
+                && typeof parsed.event === 'string') {
+                events.push(parsed);
+            }
+            else {
+                malformedLineCount += 1;
+            }
+        }
+        catch {
+            if (index !== lines.length - 1)
+                malformedLineCount += 1;
+        }
+    }
+    return { exists: true, events, malformedLineCount };
+}
+async function readTextFileIfPresent(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (isNodeErrorCode(err, 'ENOENT'))
+            return null;
+        throw err;
+    }
+}
+function requireMetadataPath(value, key) {
+    if (!value)
+        throw new Error(`Background metadata is missing ${key}.`);
+    return value;
+}
+function backgroundStatusFrom(input) {
+    if (input.terminalEvent?.event === 'workflow.completed')
+        return 'completed';
+    if (input.terminalEvent?.event === 'workflow.failed' || input.terminalEvent?.event === 'workflow.terminal_failure')
+        return 'failed';
+    if (input.resultReady)
+        return 'completed';
+    return input.alive ? 'running' : 'exited_unknown';
+}
+function isTerminalBackgroundStatus(status) {
+    return status === 'completed' || status === 'failed' || status === 'exited_unknown';
+}
+function resolveBackgroundJobsRoot(cwd, template) {
+    const marker = '__ultracode_job_marker__';
+    return dirname(resolveBackgroundRunDir(cwd, template, marker));
+}
+function wantsPlain(options) {
+    return options.plain === 'true' || options.format === 'plain' || options.progress === 'plain';
+}
+function wantsResult(options) {
+    return options.result === 'true';
+}
+function wantsWait(options) {
+    return options.wait === 'true';
+}
+function renderBackgroundStatusPlain(status) {
+    const parts = [
+        `[job] ${status.jobId ?? 'unknown'} ${status.status}`,
+        status.pid !== undefined ? `pid=${status.pid}` : '',
+        `alive=${status.alive}`,
+        status.resultReady ? 'result=ready' : 'result=pending',
+        status.waitTimedOut ? `wait=timeout(${status.waitTimeoutMs}ms)` : '',
+    ].filter(Boolean);
+    const lines = [parts.join(' ')];
+    if (status.lastEvent || status.lastSummary) {
+        lines.push(`[job] last=${status.lastEvent ?? 'unknown'} ${status.lastSummary ?? ''}`.trimEnd());
+    }
+    if (status.completedAgentCount !== undefined && status.knownAgentCount !== undefined) {
+        lines.push(`[job] agents=${status.completedAgentCount}/${status.knownAgentCount}${status.phase ? ` phase=${status.phase}` : ''}`);
+    }
+    if (status.reason || status.error) {
+        lines.push(`[job] failure=${status.reason ?? 'unknown'} ${status.error ?? ''}`.trimEnd());
+    }
+    lines.push(`[job] resultPath=${status.resultPath}`);
+    lines.push(`[job] progressPath=${status.progressPath}`);
+    return `${lines.join('\n')}\n`;
+}
+function renderBackgroundJobsPlain(list) {
+    const lines = [`[jobs] ${list.count} jobs in ${list.backgroundRoot}`];
+    for (const job of list.jobs) {
+        lines.push(`[jobs] ${job.jobId ?? 'unknown'} ${job.status} pid=${job.pid ?? 'unknown'} alive=${job.alive} result=${job.resultReady ? 'ready' : 'pending'}`);
+    }
+    for (const invalid of list.invalidJobs) {
+        lines.push(`[jobs] invalid ${invalid.path}: ${invalid.error}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function renderBackgroundCancelPlain(cancel) {
+    return `[cancel] ${cancel.jobId} ${cancel.status} pid=${cancel.pid} signal=${cancel.signal} identity=${cancel.identityVerified ? 'verified' : 'unverified'}\n`;
+}
+function renderProgressEventPlain(event) {
+    const label = [
+        `[${event.event}]`,
+        event.status ? `status=${event.status}` : '',
+        event.phase ? `phase=${event.phase}` : '',
+        event.label ? `agent=${event.label}` : '',
+        event.summary,
+    ].filter(Boolean).join(' ');
+    return `${label}\n`;
+}
+function isPostCompletionGuidanceEvent(event) {
+    return event.event === 'workflow.summary.ready'
+        || event.event === 'workflow.review.recommended';
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        if (isNodeErrorCode(err, 'ESRCH'))
+            return false;
+        if (isNodeErrorCode(err, 'EPERM'))
+            return true;
+        throw err;
+    }
+}
+function parseSignalOption(value) {
+    if (value === undefined)
+        return 'SIGINT';
+    const normalized = value.startsWith('SIG') ? value : `SIG${value}`;
+    const allowed = new Set(['SIGINT', 'SIGTERM', 'SIGHUP']);
+    if (allowed.has(normalized))
+        return normalized;
+    throw new Error('signal must be one of SIGINT, SIGTERM, or SIGHUP.');
+}
+function parsePositiveIntOption(value, fallback, label) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        throw new Error(`${label} must be a positive integer.`);
+    return parsed;
+}
+function parseNonNegativeIntOption(value, fallback, label) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        throw new Error(`${label} must be a non-negative integer.`);
+    return parsed;
+}
+function lastNumericField(events, key) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const value = events[index]?.[key];
+        if (typeof value === 'number')
+            return value;
+    }
+    return undefined;
+}
+function lastStringField(events, key) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const value = events[index]?.[key];
+        if (typeof value === 'string')
+            return value;
+    }
+    return undefined;
+}
+function isNodeErrorCode(err, code) {
+    return err instanceof Error && err.code === code;
+}
+function delay(ms) {
+    return new Promise((resolveDelay) => {
+        setTimeout(resolveDelay, ms);
+    });
+}
 function resolveBackgroundRunDir(cwd, template, jobId) {
     const expanded = template.replaceAll('{jobId}', jobId);
     return isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
@@ -347,8 +989,19 @@ function renderWorkflowEvent(event, progressMode) {
         case 'workflow.started':
             process.stderr.write(`[workflow] started ${event.workflowName} task=${event.taskId} run=${event.runId}\n`);
             return;
+        case 'workflow.phase.planned':
+            process.stderr.write(`[phase-plan] ${event.title} (${event.plannedAgentCount} agents)${event.goal ? ` - ${event.goal}` : ''}\n`);
+            for (const agent of event.plannedAgents) {
+                process.stderr.write(`[phase-plan]    - ${agent.title}${agent.label ? ` (${agent.label})` : ''}${agent.focus ? `: ${agent.focus}` : ''}\n`);
+            }
+            return;
         case 'workflow.phase.started':
-            process.stderr.write(`[phase] ${event.title}${event.detail ? ` - ${event.detail}` : ''}\n`);
+            process.stderr.write(`[phase] ${event.title}${event.plannedAgentCount ? ` (${event.plannedAgentCount} agents)` : ''}${event.detail ? ` - ${event.detail}` : ''}\n`);
+            if (event.plannedAgents) {
+                for (const agent of event.plannedAgents) {
+                    process.stderr.write(`[phase]    - ${agent.title}${agent.label ? ` (${agent.label})` : ''}${agent.focus ? `: ${agent.focus}` : ''}\n`);
+                }
+            }
             return;
         case 'workflow.plan.ready':
             process.stderr.write(`[plan] mode=${event.mode} phases=${event.phases.length}${event.rationale ? ` - ${event.rationale}` : ''}\n`);
@@ -366,7 +1019,7 @@ function renderWorkflowEvent(event, progressMode) {
             process.stderr.write(`[agent:${event.agentIndex + 1}] started ${event.label}\n`);
             return;
         case 'workflow.agent.completed':
-            process.stderr.write(`[agent:${event.agentIndex + 1}] completed ${event.label} tokens=${event.tokens} preview=${formatPreview(event.resultPreview)}${event.cached ? ' cached=true' : ''}\n`);
+            process.stderr.write(`[agent:${event.agentIndex + 1}] completed ${event.label} | ${agentCompletionProgressSummary(event)} | tokens=${event.tokens} preview=${formatPreview(event.resultPreview)}${event.cached ? ' cached=true' : ''}\n`);
             return;
         case 'workflow.agent.failed':
             process.stderr.write(`[agent:${event.agentIndex + 1}] failed ${event.label} ${event.error}\n`);
@@ -395,6 +1048,110 @@ function renderFailedSnapshot(snapshot, progressMode) {
     }
     process.stderr.write(`[workflow] terminal failure task=${snapshot.taskId} reason=${snapshot.failureReason ?? 'unknown'} error=${snapshot.error ?? 'unknown'}\n`);
 }
+function renderWorkflowCompletionGuidance(snapshot, progressMode) {
+    const phasesSummary = workflowPhaseExecutionSummary(snapshot.events);
+    const totalPlannedAgentCount = phasesSummary.reduce((sum, phase) => sum + phase.agentCount, 0);
+    const reviewRecommendation = criticalReviewRecommendation();
+    if (progressMode === 'jsonl') {
+        writeJsonlProgress({
+            event: 'workflow.summary.ready',
+            status: 'completed',
+            summary: `Workflow completed with ${phasesSummary.length} phase${phasesSummary.length === 1 ? '' : 's'} and ${totalPlannedAgentCount} planned phase agent${totalPlannedAgentCount === 1 ? '' : 's'}`,
+            taskId: snapshot.taskId,
+            runId: snapshot.runId,
+            workflowName: snapshot.workflowName,
+            phasesSummary,
+            totalPhaseCount: phasesSummary.length,
+            totalPlannedAgentCount,
+        });
+        writeJsonlProgress({
+            event: 'workflow.review.recommended',
+            status: 'review_recommended',
+            summary: reviewRecommendation,
+            taskId: snapshot.taskId,
+            runId: snapshot.runId,
+            workflowName: snapshot.workflowName,
+            recommendation: reviewRecommendation,
+        });
+        return;
+    }
+    if (phasesSummary.length > 0) {
+        process.stderr.write('[workflow-summary] phase/agent angles\n');
+        for (const phase of phasesSummary) {
+            process.stderr.write(`[workflow-summary] Phase ${phase.title}: ${phase.agentCount} agent${phase.agentCount === 1 ? '' : 's'}${phase.goal ? ` - ${phase.goal}` : ''}\n`);
+            for (const agent of phase.agents) {
+                process.stderr.write(`[workflow-summary]   - ${agent.title}${agent.label ? ` (${agent.label})` : ''}${agent.angle ? `: ${agent.angle}` : ''}\n`);
+            }
+        }
+    }
+    else {
+        process.stderr.write('[workflow-summary] no phase-level agent plan was recorded\n');
+    }
+    process.stderr.write(`[review-recommendation] ${reviewRecommendation}\n`);
+}
+function workflowPhaseExecutionSummary(events) {
+    const phases = new Map();
+    const phaseTitlesWithPlannedAgents = new Set();
+    for (const event of events) {
+        if (event.type !== 'workflow.phase.planned' && event.type !== 'workflow.phase.started')
+            continue;
+        const plannedAgents = event.plannedAgents ?? [];
+        if (plannedAgents.length > 0)
+            phaseTitlesWithPlannedAgents.add(event.title);
+        const existing = phases.get(event.title);
+        const agents = plannedAgents.length > 0
+            ? plannedAgents.map((agent) => ({
+                title: agent.title,
+                ...(agent.label ? { label: agent.label } : {}),
+                ...(agent.focus ? { angle: agent.focus } : {}),
+            }))
+            : existing?.agents ?? [];
+        phases.set(event.title, {
+            title: event.title,
+            ...(event.goal ?? existing?.goal ? { goal: event.goal ?? existing?.goal } : {}),
+            agentCount: agents.length || existing?.agentCount || 0,
+            agents,
+        });
+    }
+    for (const event of events) {
+        if (event.type !== 'workflow.agent.started' || !event.phase)
+            continue;
+        const existing = phases.get(event.phase);
+        if (!existing) {
+            phases.set(event.phase, {
+                title: event.phase,
+                agentCount: 1,
+                agents: [{
+                        title: event.label,
+                        label: event.label,
+                        angle: event.promptPreview,
+                    }],
+            });
+            continue;
+        }
+        if (phaseTitlesWithPlannedAgents.has(event.phase))
+            continue;
+        if (existing.agents.some((agent) => agent.label === event.label || agent.title === event.label))
+            continue;
+        const agents = [
+            ...existing.agents,
+            {
+                title: event.label,
+                label: event.label,
+                angle: event.promptPreview,
+            },
+        ];
+        phases.set(event.phase, {
+            ...existing,
+            agentCount: agents.length,
+            agents,
+        });
+    }
+    return [...phases.values()];
+}
+function criticalReviewRecommendation() {
+    return 'Session LLM should critically re-check the final result before acting: verify whether the conclusion is justified, internally consistent, supported by the observed workflow evidence, and missing material counterarguments.';
+}
 function renderControlProgress(event, progressMode, payload, plainText) {
     if (progressMode === 'jsonl') {
         writeJsonlProgress({ event, ...payload });
@@ -409,6 +1166,38 @@ function writeJsonlProgress(payload) {
         ...payload,
     })}\n`);
 }
+function phaseStartedSummary(event) {
+    const agentText = event.plannedAgentCount
+        ? `${event.plannedAgentCount} planned agent${event.plannedAgentCount === 1 ? '' : 's'}`
+        : '';
+    const suffix = [agentText, event.detail ?? event.goal].filter(Boolean).join(': ');
+    return suffix ? `Phase ${event.title}: ${suffix}` : `Phase ${event.title}`;
+}
+function phasePlannedSummary(event) {
+    return `Phase ${event.title} planned: ${event.plannedAgentCount} planned agent${event.plannedAgentCount === 1 ? '' : 's'}`;
+}
+function agentCompletionProgressSummary(event) {
+    const parts = [];
+    if (event.phase
+        && event.phaseCompletedAgentCount !== undefined
+        && event.phaseKnownAgentCount !== undefined) {
+        parts.push(`Phase ${event.phase} (${event.phaseCompletedAgentCount}/${event.phaseKnownAgentCount})`);
+    }
+    parts.push(`${event.completedAgentCount} out of ${event.knownAgentCount} agents have completed the task`);
+    parts.push(`${formatElapsedDuration(event.elapsedMs)} elapsed`);
+    return parts.join(', ');
+}
+function formatElapsedDuration(ms) {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0)
+        return `${hours}h ${minutes}m ${seconds}s`;
+    if (minutes > 0)
+        return `${minutes}m ${seconds}s`;
+    return `${seconds}s`;
+}
 function progressPayloadForEvent(event) {
     switch (event.type) {
         case 'workflow.started':
@@ -423,22 +1212,38 @@ function progressPayloadForEvent(event) {
                 workflowSourcePath: event.workflowSourcePath,
                 scriptHash: event.scriptHash,
             };
+        case 'workflow.phase.planned':
+            return {
+                event: event.type,
+                status: 'planned',
+                summary: phasePlannedSummary(event),
+                taskId: event.taskId,
+                runId: event.runId,
+                phaseIndex: event.phaseIndex,
+                title: event.title,
+                goal: event.goal,
+                plannedAgentCount: event.plannedAgentCount,
+                plannedAgents: event.plannedAgents,
+            };
         case 'workflow.phase.started':
             return {
                 event: event.type,
                 status: 'running',
-                summary: event.detail ? `Phase ${event.title}: ${event.detail}` : `Phase ${event.title}`,
+                summary: phaseStartedSummary(event),
                 taskId: event.taskId,
                 runId: event.runId,
                 phaseIndex: event.phaseIndex,
                 title: event.title,
                 detail: event.detail,
+                goal: event.goal,
+                plannedAgentCount: event.plannedAgentCount,
+                plannedAgents: event.plannedAgents,
             };
         case 'workflow.plan.ready':
             return {
                 event: event.type,
                 status: 'planned',
-                summary: `Workflow plan ready: ${event.phases.length} phase${event.phases.length === 1 ? '' : 's'}, mode=${event.mode}`,
+                summary: `Workflow planning snapshot: ${event.phases.length} known phase${event.phases.length === 1 ? '' : 's'}, mode=${event.mode}`,
                 taskId: event.taskId,
                 runId: event.runId,
                 mode: event.mode,
@@ -472,7 +1277,7 @@ function progressPayloadForEvent(event) {
             return {
                 event: event.type,
                 status: 'completed',
-                summary: `Agent ${event.agentIndex + 1} completed`,
+                summary: `Agent ${event.agentIndex + 1} completed: ${event.label}. ${agentCompletionProgressSummary(event)}`,
                 taskId: event.taskId,
                 runId: event.runId,
                 agentIndex: event.agentIndex,
@@ -483,6 +1288,11 @@ function progressPayloadForEvent(event) {
                 toolCalls: event.toolCalls,
                 resultPreview: event.resultPreview,
                 cached: event.cached,
+                elapsedMs: event.elapsedMs,
+                completedAgentCount: event.completedAgentCount,
+                knownAgentCount: event.knownAgentCount,
+                phaseCompletedAgentCount: event.phaseCompletedAgentCount,
+                phaseKnownAgentCount: event.phaseKnownAgentCount,
                 worktreePreserved: event.worktreePreserved,
                 preservedWorktrees: event.preservedWorktrees,
             };
@@ -537,7 +1347,7 @@ function parseIntOption(value, fallback) {
     if (value === undefined)
         return fallback;
     const parsed = Number.parseInt(value, 10);
-    if (!Number.isFinite(parsed) || parsed <= 0)
+    if (!Number.isFinite(parsed) || parsed < 0)
         return fallback;
     return parsed;
 }
@@ -594,8 +1404,18 @@ function helpText() {
 
 Commands:
   run        Run a workflow as a local CLI command.
+  status     Show a background workflow status record.
+  wait       Wait for a background workflow to reach a terminal state.
+  logs       Print a background workflow progress JSONL file.
+  result     Print a completed background workflow result JSON.
+  cancel     Send SIGINT to a background workflow command.
+  jobs       List background workflow jobs.
+  list       Alias for jobs.
+  archive    Export one background workflow job state to an archive JSON file.
+  export     Alias for archive.
 
 Options:
+  --version, -v                     Print the package version.
   --llm-guide                       Print the Ultracode install and usage guide.
   --accept-llm-guide <version>       Required for run. Current version: ${ULTRACODE_INSTALL_GUIDE_ACCEPT_VERSION}.
   --script <js>                      Inline workflow script.
@@ -610,10 +1430,27 @@ Options:
   --execution <background|attached>  Execution mode. Default: settings.json (${workflowDefaultExecutionMode()}).
   --command <path>                   Override Codex CLI binary path.
   --model <model>                    Pass a model to Codex app-server.
-  --timeout-ms <number>              Runtime timeout. Default: settings.json (${workflowDefaultTimeoutMs()}).
+  --timeout-ms <number>              Runtime timeout; 0 waits for completion/cancel. Default: settings.json (${workflowDefaultTimeoutMs()}).
   --cwd <dir>                        Working directory for workflow execution. Default: current cwd.
   --reasoning-effort <effort>        Codex reasoning effort. Default: settings.json (${codexDefaultReasoningEffort()}).
   --verbosity <verbosity>            Codex verbosity. Default: settings.json (${codexDefaultVerbosity()}).
+
+Background command options:
+  <jobId|metadataPath>               Background job id or metadata.json path.
+  --job-id <id>                      Background job id.
+  --metadata-path <path>             Path to metadata.json from a launch record.
+  --result-path <path>               Override result.json path.
+  --progress-path <path>             Override progress.jsonl path.
+  --pid-path <path>                  Override pid path.
+  --interval-ms <number>             wait polling interval. Default: 1000.
+  --tail <number>                    logs line count. Default: all lines.
+  --event <event>                    logs event filter, such as workflow.agent.completed.
+  --signal <SIGINT|SIGTERM|SIGHUP>   cancel signal. Default: SIGINT.
+  --plain                            Print a human-readable background summary.
+  --result                           wait prints the workflow result on completion.
+  --wait                             cancel waits for terminal workflow status.
+  --out-dir <dir>                    archive output directory. Default: .ultracode-for-codex/archive.
+  --output-path <path>               archive output file path.
 `;
 }
 function isMainModule() {