ultracode-for-codex 0.2.6 → 0.3.0

package/README.md

@@ -26,7 +26,7 @@ npm run pack:ultracode-for-codex
 Install the tarball from a target project:
 
 ```bash
-npm install --save-dev /path/to/ultracode-for-codex-0.2.6.tgz
+npm install --save-dev /path/to/ultracode-for-codex-<version>.tgz
 ```
 
 Run a workflow:
@@ -41,6 +41,17 @@ npm exec -- ultracode-for-codex run \
 
 By default this prints a background launch record to stdout. The record contains
 `jobId`, `pid`, `resultPath`, `progressPath`, `metadataPath`, and `pidPath`.
+Use the job id to inspect or control the background run:
+
+```bash
+npm exec -- ultracode-for-codex status <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex wait <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex logs <jobId> --cwd /path/to/target-repo --tail 40
+npm exec -- ultracode-for-codex result <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex cancel <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex jobs --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex archive <jobId> --cwd /path/to/target-repo
+```
 
 Run attached to the current terminal:
 
@@ -102,12 +113,21 @@ The package default workflow timeout is `0`, meaning the workflow waits until it
 completes, is cancelled, or the Codex app-server exits. Set `--timeout-ms` to a
 positive value to opt into a deadline for one run.
 Use the default background execution for long Codex-launched work so Codex can
-continue other tasks and inspect `progressPath` or `resultPath` later. Use
+continue other tasks and inspect the job later with `status`, `logs`, or
+`result`. Use
 `--execution attached` only when the caller must block until the final result.
 
 ## CLI Controls
 
 - Use `--version` or `-v` to print the installed package version.
+- Use `status`, `wait`, `logs`, `result`, and `cancel` with a background
+  `jobId` or `metadata.json` path to inspect, wait for, read, or cancel OS
+  background runs.
+- Use `jobs` or `list` to enumerate local background runs.
+- Use `archive` or `export` to write a sensitive local JSON bundle for one run
+  without deleting runtime state.
+- Use `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain`
+  for shorter foreground checks.
 - Progress is printed to stderr as JSONL by default.
 - The final workflow result is printed as JSON to stdout.
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
@@ -120,6 +140,10 @@ continue other tasks and inspect `progressPath` or `resultPath` later. Use
   begins.
 - Each `workflow.agent.completed` record includes phase progress, total known
   agent progress, and elapsed time.
+- After a completed run, `workflow.summary.ready` reports each phase with its
+  planned agent count and angle/focus list, then `workflow.review.recommended`
+  asks the current session LLM to critically re-check the final result before
+  acting on it.
 - Press `Ctrl-C` once to cancel the active workflow.
 - Use `--retry-limit <n>` to retry failed workflows inside the same process.
 - `--timeout-ms 0` waits for completion, cancellation, or app-server exit.
@@ -196,6 +220,12 @@ For supported CI/CD environments, provenance is available as an explicit opt-in:
 npm run publish:npm:provenance
 ```
 
+Optional live smoke against the local Codex CLI:
+
+```bash
+ULTRACODE_LIVE_SMOKE=1 npm run smoke:live
+```
+
 Useful local run:
 
 ```bash

package/ULTRACODE_INSTALL.md

@@ -13,6 +13,15 @@ workflow runs to OS background execution with result and progress files under
 Production surface:
 
 - `ultracode-for-codex run`
+- `ultracode-for-codex status`
+- `ultracode-for-codex wait`
+- `ultracode-for-codex logs`
+- `ultracode-for-codex result`
+- `ultracode-for-codex cancel`
+- `ultracode-for-codex jobs`
+- `ultracode-for-codex list`
+- `ultracode-for-codex archive`
+- `ultracode-for-codex export`
 
 Progress, cancellation, permission review, retry, and final result projection
 are handled inside the CLI process. Progress is JSONL on stderr by
@@ -31,7 +40,7 @@ npm exec -- ultracode-for-codex --llm-guide
 For source-checkout validation, install the generated tarball instead:
 
 ```bash
-npm install --save-dev ./ultracode-for-codex-0.2.6.tgz
+npm install --save-dev ./ultracode-for-codex-<version>.tgz
 ```
 
 Optional Codex companion skill:
@@ -57,8 +66,20 @@ npm exec -- ultracode-for-codex run \
 
 The default run prints a background launch record to stdout. Prefer that
 background path for long Codex-launched work so Codex can continue other tasks
-and inspect `progressPath` or `resultPath` later. Use `--execution attached`
-only when the caller must block until completion.
+and inspect the job later with `status`, `logs`, or `result`. Use
+`--execution attached` only when the caller must block until completion.
+
+Use the background `jobId` from the launch record to inspect or control the run:
+
+```bash
+npm exec -- ultracode-for-codex status <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex wait <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex logs <jobId> --cwd /path/to/project --tail 40
+npm exec -- ultracode-for-codex result <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex cancel <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex jobs --cwd /path/to/project
+npm exec -- ultracode-for-codex archive <jobId> --cwd /path/to/project
+```
 
 Use built-in `task` for general work and `code-review` for review-specific work.
 Both start with an LLM planner, execute phase by phase, run multiple focused
@@ -93,6 +114,13 @@ Settings defaults:
 Useful controls:
 
 - `--version` or `-v` prints the installed package version.
+- `status`, `wait`, `logs`, `result`, and `cancel` accept a background `jobId`
+  or `metadata.json` path.
+- `jobs` and `list` enumerate local background runs.
+- `archive` and `export` write a sensitive local JSON bundle for one run without
+  deleting runtime state.
+- `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain` are
+  available for shorter foreground checks.
 - Progress events are printed to stderr as JSONL by default.
 - The final workflow result is printed as JSON to stdout.
 - The package default workflow timeout is `0`, meaning the workflow waits until
@@ -107,6 +135,10 @@ Useful controls:
   begins.
 - Each `workflow.agent.completed` record includes phase progress, total known
   agent progress, and elapsed time.
+- After a completed run, `workflow.summary.ready` reports each phase with its
+  planned agent count and angle/focus list, then `workflow.review.recommended`
+  asks the current session LLM to critically re-check the final result before
+  acting on it.
 - Press `Ctrl-C` once to cancel the running workflow.
 - Use `--retry-limit <n>` to retry failed runs in the same process.
 - `--timeout-ms 0` waits for completion, cancellation, or app-server exit.

package/dist/cli.d.ts

@@ -20,5 +20,20 @@ interface ParsedOptions {
     readonly resumeFromRunId?: string;
     readonly permission?: string;
     readonly retryLimit?: string;
+    readonly jobId?: string;
+    readonly metadataPath?: string;
+    readonly resultPath?: string;
+    readonly progressPath?: string;
+    readonly pidPath?: string;
+    readonly intervalMs?: string;
+    readonly tail?: string;
+    readonly signal?: string;
+    readonly plain?: string;
+    readonly format?: string;
+    readonly event?: string;
+    readonly result?: string;
+    readonly wait?: string;
+    readonly outDir?: string;
+    readonly outputPath?: string;
 }
 export declare function parseOptions(args: readonly string[]): ParsedOptions;

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/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';
@@ -30,6 +30,20 @@ async function main(argv) {
     }
     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;
 }
@@ -69,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);
@@ -126,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',
@@ -160,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',
@@ -174,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);
@@ -411,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 });
@@ -663,6 +1404,15 @@ 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.
@@ -684,6 +1434,23 @@ Options:
   --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() {

package/docs/provenance-audit.md

@@ -7,7 +7,7 @@ Date: 2026-06-22
 This audit checked:
 
 - tracked repository files;
-- generated npm package contents for `ultracode-for-codex@0.2.6`;
+- generated npm package contents for `ultracode-for-codex@0.3.0`;
 - the locally installed companion Codex skill.
 
 Generated build output and package tarballs were checked as projections of the
@@ -23,7 +23,8 @@ License transition completed:
 
 - Apache-2.0 `LICENSE` file is present;
 - `package.json` and `package-lock.json` declare `Apache-2.0`;
-- package version is prepared as `0.2.6`.
+- release-candidate package version is `0.3.0`;
+- npm latest before this release remains `0.2.6`.
 
 ## Evidence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracode-for-codex",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Run local Codex-backed workflows from a command-owned CLI runtime.",
   "keywords": [
     "codex",
@@ -58,6 +58,7 @@
     "publish:dry-run": "npm publish --dry-run --access public",
     "publish:npm": "npm publish --access public",
     "publish:npm:provenance": "npm publish --access public --provenance",
+    "smoke:live": "node scripts/live-smoke-ultracode-for-codex.mjs",
     "test:e2e:ultracode-for-codex": "node scripts/e2e-installed-ultracode-for-codex.mjs",
     "test:all": "npm test && npm run test:e2e:ultracode-for-codex",
     "test": "npm run build && npm run verify:runtime-boundary && node --test --test-concurrency=2 test/*.test.mjs",

package/skills/ultracode-for-codex/SKILL.md

@@ -15,8 +15,8 @@ Workflow execution runs through the local CLI command. Progress,
 cancellation, permission review, retry, and result projection stay in that
 command process. `settings.json` defaults runs to OS background execution; use
 that path for long Codex-launched work so Codex can keep doing other tasks and
-inspect `progressPath` or `resultPath` later. Attached runs stream stderr JSONL
-for Codex-readable status, while stdout remains the final workflow result JSON.
+inspect the background job later. Attached runs stream stderr JSONL for
+Codex-readable status, while stdout remains the final workflow result JSON.
 
 The default Ultracode work shape is phase-wise parallel execution: built-in
 `task` and `code-review` first call a planner agent, then execute each planned
@@ -45,7 +45,7 @@ For source-checkout validation before publish:
 
 ```bash
 npm run pack:ultracode-for-codex
-npm install --save-dev ./artifacts/ultracode-for-codex-0.2.6.tgz
+npm install --save-dev ./artifacts/ultracode-for-codex-<version>.tgz
 ```
 
 CLI behavior:
@@ -53,6 +53,12 @@ CLI behavior:
 - `--version` or `-v` prints the installed package version;
 - default execution is `background`; stdout contains a launch record with
   `jobId`, `pid`, `resultPath`, `progressPath`, `metadataPath`, and `pidPath`;
+- background jobs can be inspected with `status`, waited with `wait`, read with
+  `logs` and `result`, and cancelled with `cancel`;
+- background jobs can be enumerated with `jobs` or `list`, and exported without
+  deletion with `archive` or `export`;
+- `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain`
+  provide focused foreground checks;
 - attached execution is available with `--execution attached` when the caller
   should stay connected until completion;
 - attached progress prints to stderr as JSONL by default;
@@ -67,6 +73,9 @@ CLI behavior:
   phase begins;
 - each `workflow.agent.completed` record includes phase progress, total known
   agent progress, and elapsed time;
+- after a completed run, `workflow.summary.ready` reports phase-level agent
+  counts and angles, then `workflow.review.recommended` asks the current
+  session LLM to critically re-check the final result before acting on it;
 - `Ctrl-C` cancels the active attached workflow;
 - `--retry-limit <n>` retries failed workflows inside the same process;
 - `--timeout-ms 0` waits for completion, cancellation, or app-server exit;