ultracode-for-codex 0.2.5 → 0.2.6

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.5.tgz
+npm install --save-dev /path/to/ultracode-for-codex-0.2.6.tgz
 ```
 
 Run a workflow:
@@ -84,7 +84,7 @@ Package defaults live in `settings.json`:
     "progress": "jsonl",
     "permission": "ask",
     "retryLimit": 0,
-    "timeoutMs": 900000,
+    "timeoutMs": 0,
     "background": {
       "runDir": ".ultracode-for-codex/background/{jobId}",
       "resultFile": "result.json",
@@ -98,25 +98,38 @@ Package defaults live in `settings.json`:
 
 Use `--execution attached`, `--progress`, `--permission`, `--retry-limit`, and
 `--timeout-ms` to override settings for one run.
-The package default workflow timeout is `900000` ms, or 15 minutes.
+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
+`--execution attached` only when the caller must block until the final result.
 
 ## CLI Controls
 
+- Use `--version` or `-v` to print the installed package version.
 - 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`;
   agent records also include stable agent identity and label fields.
-- Built-in `task` and `code-review` emit `workflow.plan.ready` before phase
-  agents start, including phase titles and planned agent role labels.
+- Built-in `task` and `code-review` emit `workflow.plan.ready` as a planning
+  snapshot, not a promise that every later phase is already known.
+- `workflow.phase.planned` is emitted immediately before each phase starts and
+  carries that phase's current planned agent role labels. Each
+  `workflow.phase.started` record repeats the same role labels when the phase
+  begins.
+- Each `workflow.agent.completed` record includes phase progress, total known
+  agent progress, and elapsed time.
 - Press `Ctrl-C` once to cancel the active workflow.
 - Use `--retry-limit <n>` to retry failed workflows inside the same process.
-- `--timeout-ms` is the workflow timeout and the default per-agent silence
-  budget; it is not divided by the retry budget.
+- `--timeout-ms 0` waits for completion, cancellation, or app-server exit.
+  Positive values opt into a workflow deadline and per-agent silence budget;
+  that budget is not divided by the retry budget.
 - Use `--permission ask|allow|deny` for project/user/plugin/scriptPath workflow
   permission reviews.
 - Use `--progress plain` for human-readable log lines.
 - Use `--execution background` for OS background runs and `--execution attached`
-  when Codex should read progress until completion.
+  only when the caller should stay connected until completion.
 
 ## Codex Companion Skill
 
@@ -138,8 +151,8 @@ want Codex to auto-load the package boundaries and verification routine.
   planner-selected phase-wise parallel subagents, then synthesize each phase and
   the final result.
 - Workflow execution is local and command-owned; settings default to OS
-  background execution and `--execution attached` keeps the process connected
-  until completion.
+  background execution so long runs can keep waiting while Codex does other
+  work.
 - `.ultracode-for-codex` workflow state is sensitive local data.
 - `journalPath`, `journal.jsonl`, and journal contents stay out of CLI output.
   Local runtime state may still contain runtime-owned
@@ -147,8 +160,7 @@ want Codex to auto-load the package boundaries and verification routine.
 - `resumeFromRunId` remains runtime-internal and same-session; users retry the
   active run or rerun the workflow command.
 - `agent(..., { isolation: "worktree" })` runs the agent in a detached git
-  worktree, removes it when clean, and preserves changed or unsafe-to-clean
-  worktrees for review.
+  worktree and preserves the worktree for review, including clean worktrees.
 
 ## Development
 

package/ULTRACODE_INSTALL.md

@@ -31,7 +31,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.5.tgz
+npm install --save-dev ./ultracode-for-codex-0.2.6.tgz
 ```
 
 Optional Codex companion skill:
@@ -55,8 +55,10 @@ npm exec -- ultracode-for-codex run \
   --args '{"prompt":"review the current change"}'
 ```
 
-The default run prints a background launch record to stdout. Use
-`--execution attached` when Codex should read progress until completion.
+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.
 
 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
@@ -76,7 +78,7 @@ Settings defaults:
     "progress": "jsonl",
     "permission": "ask",
     "retryLimit": 0,
-    "timeoutMs": 900000,
+    "timeoutMs": 0,
     "background": {
       "runDir": ".ultracode-for-codex/background/{jobId}",
       "resultFile": "result.json",
@@ -90,29 +92,38 @@ Settings defaults:
 
 Useful controls:
 
+- `--version` or `-v` prints the installed package version.
 - 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 `900000` ms, or 15 minutes.
+- The package default workflow timeout is `0`, meaning the workflow waits until
+  it completes, is cancelled, or the Codex app-server exits.
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
   agent records also include stable agent identity and label fields.
-- Built-in `task` and `code-review` emit `workflow.plan.ready` before phase
-  agents start, including phase titles and planned agent role labels.
+- Built-in `task` and `code-review` emit `workflow.plan.ready` as a planning
+  snapshot, not a promise that every later phase is already known.
+- `workflow.phase.planned` is emitted immediately before each phase starts and
+  carries that phase's current planned agent role labels. Each
+  `workflow.phase.started` record repeats the same role labels when the phase
+  begins.
+- Each `workflow.agent.completed` record includes phase progress, total known
+  agent progress, and elapsed time.
 - Press `Ctrl-C` once to cancel the running workflow.
 - Use `--retry-limit <n>` to retry failed runs in the same process.
-- `--timeout-ms` is the workflow timeout and the default per-agent silence
-  budget; it is not divided by the retry budget.
+- `--timeout-ms 0` waits for completion, cancellation, or app-server exit.
+  Positive values opt into a workflow deadline and per-agent silence budget;
+  that budget is not divided by the retry budget.
 - Use `--permission ask|allow|deny` for project/user/plugin/scriptPath
   workflow permission reviews.
 - Use `--progress plain` for human-readable log lines.
 - Use `--execution background` for OS background runs and `--execution attached`
-  for current-terminal progress streaming.
+  only when the caller should stay connected until completion.
 
 ## Runtime Contract
 
 - Use Codex app-server over stdio as the production backend.
 - Keep workflow execution local and command-owned; settings default to OS
-  background execution and `--execution attached` keeps the process connected
-  until completion.
+  background execution so long runs can keep waiting while Codex does other
+  work.
 - Route progress, cancellation, permission review, retry, and result projection
   through the CLI command.
 - Keep stdout reserved for the final JSON result; stream progress records to
@@ -130,13 +141,15 @@ Useful controls:
 - `resumeFromRunId` remains a runtime-internal same-session capability; the
   CLI uses retry or explicit reruns for user-facing recovery.
 - Use `isolation: "worktree"` only in git repositories with at least one commit.
-  Changed or unsafe-to-clean worktrees are intentionally preserved for review.
+  Isolated worktrees are intentionally preserved for review, including clean
+  worktrees.
 - Treat `.ultracode-for-codex` workflow state as sensitive local data.
 
 ## First Checks After Install
 
 ```bash
 npm exec -- ultracode-for-codex --help
+npm exec -- ultracode-for-codex --version
 npm exec -- ultracode-for-codex --llm-guide
 ```
 

package/dist/cli.js

@@ -9,6 +9,7 @@ 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,6 +20,10 @@ 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;
@@ -347,8 +352,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 +382,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`);
@@ -409,6 +425,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 +471,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 +536,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 +547,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 +606,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;
 }
@@ -596,6 +665,7 @@ Commands:
   run        Run a workflow as a local CLI command.
 
 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,7 +680,7 @@ 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()}).

package/dist/codex/subagent-backend.d.ts

@@ -20,6 +20,7 @@ export declare class CodexSubagentBackend implements SubagentBackend {
     private readonly cwd;
     private readonly configuredModel?;
     private readonly timeoutMs;
+    private readonly rpcTimeoutMs;
     private readonly reasoningEffort;
     private readonly verbosity;
     private child;

package/dist/codex/subagent-backend.js

@@ -6,9 +6,11 @@ import { isAbsolute, join, relative, resolve } from 'node:path';
 import readline from 'node:readline';
 import { codexDefaultReasoningEffort, codexDefaultVerbosity, } from '../settings.js';
 import { estimateTokens } from '../runtime/types.js';
+import { ultracodePackageVersion } from '../runtime/package-info.js';
 import { codexChildProcessEnv } from './env.js';
 const USAGE_NOTIFICATION_GRACE_MS = 100;
 const BUFFERED_TURN_STATE_TTL_MS = 30_000;
+const DEFAULT_CODEX_RPC_TIMEOUT_MS = 30_000;
 const FALLBACK_CODEX_MODEL = 'gpt-5.5';
 const WORKSPACE_DYNAMIC_TOOL_NAMESPACE = 'workspace';
 const MAX_WORKSPACE_TOOL_READ_BYTES = 200_000;
@@ -72,6 +74,7 @@ export class CodexSubagentBackend {
     cwd;
     configuredModel;
     timeoutMs;
+    rpcTimeoutMs;
     reasoningEffort;
     verbosity;
     child = null;
@@ -89,7 +92,8 @@ export class CodexSubagentBackend {
         this.cwd = options.cwd;
         this.model = options.model ?? 'codex-subagent';
         this.configuredModel = options.model;
-        this.timeoutMs = options.timeoutMs;
+        this.timeoutMs = normalizeOptionalTimeoutMs(options.timeoutMs);
+        this.rpcTimeoutMs = this.timeoutMs > 0 ? this.timeoutMs : DEFAULT_CODEX_RPC_TIMEOUT_MS;
         this.reasoningEffort = options.reasoningEffort ?? codexDefaultReasoningEffort();
         this.verbosity = options.verbosity ?? codexDefaultVerbosity();
     }
@@ -220,7 +224,7 @@ export class CodexSubagentBackend {
             clientInfo: {
                 name: 'ultracode_for_codex',
                 title: 'Ultracode for Codex',
-                version: '0.2.0',
+                version: ultracodePackageVersion(),
             },
             capabilities: {
                 experimentalApi: true,
@@ -284,8 +288,8 @@ export class CodexSubagentBackend {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pending.delete(id);
-                reject(new Error(`${method} timed out after ${this.timeoutMs}ms`));
-            }, this.timeoutMs);
+                reject(new Error(`${method} timed out after ${this.rpcTimeoutMs}ms`));
+            }, this.rpcTimeoutMs);
             this.pending.set(id, { method, resolve, reject, timer });
         });
     }
@@ -498,13 +502,16 @@ export class CodexSubagentBackend {
         const key = `${threadId}:${turnId}`;
         return new Promise((resolve, reject) => {
             let waiter;
-            const timer = setTimeout(() => {
-                this.turnWaiters.delete(key);
-                cleanup();
-                reject(new Error(`turn timed out after ${this.timeoutMs}ms`));
-            }, this.timeoutMs);
+            const timer = this.timeoutMs > 0
+                ? setTimeout(() => {
+                    this.turnWaiters.delete(key);
+                    cleanup();
+                    reject(new Error(`turn timed out after ${this.timeoutMs}ms`));
+                }, this.timeoutMs)
+                : null;
             const cleanup = () => {
-                clearTimeout(timer);
+                if (timer)
+                    clearTimeout(timer);
                 if (waiter?.usageGraceTimer) {
                     clearTimeout(waiter.usageGraceTimer);
                     waiter.usageGraceTimer = undefined;
@@ -660,6 +667,11 @@ function estimatedUsage(prompt, text) {
         source: 'estimated',
     };
 }
+function normalizeOptionalTimeoutMs(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return 0;
+    return Math.floor(value);
+}
 function turnStateKey(threadId, turnId) {
     return typeof threadId === 'string' && typeof turnId === 'string'
         ? `${threadId}:${turnId}`

package/dist/runtime/package-info.d.ts

@@ -0,0 +1 @@
+export declare function ultracodePackageVersion(): string;

package/dist/runtime/package-info.js

@@ -0,0 +1,12 @@
+import { readFileSync } from 'node:fs';
+let cachedPackageVersion;
+export function ultracodePackageVersion() {
+    if (cachedPackageVersion)
+        return cachedPackageVersion;
+    const packageJson = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+    if (typeof packageJson.version !== 'string' || !packageJson.version.trim()) {
+        throw new Error('Package version is missing from package.json.');
+    }
+    cachedPackageVersion = packageJson.version;
+    return cachedPackageVersion;
+}

package/dist/runtime/workflow-journal.d.ts

@@ -131,5 +131,4 @@ export declare function computeWorkflowAgentCallKey(input: {
 }): string;
 export declare function workflowJournalHash(entryWithoutEntryHash: unknown): string;
 export declare function readWorkflowJournal(journalPath: string): Promise<WorkflowJournalReadResult>;
-export declare function cleanupWorkflowJournalTranscriptDir(transcriptDir: string): Promise<void>;
 export {};

package/dist/runtime/workflow-journal.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { constants as fsConstants } from 'node:fs';
-import { chmod, lstat, mkdir, open, readFile, rm, stat } from 'node:fs/promises';
+import { chmod, lstat, mkdir, open, readFile, stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 export class WorkflowJournalError extends Error {
     cause;
@@ -250,9 +250,6 @@ export async function readWorkflowJournal(journalPath) {
     validateWorkflowJournal(entries);
     return { entries, truncatedTail };
 }
-export async function cleanupWorkflowJournalTranscriptDir(transcriptDir) {
-    await rm(transcriptDir, { recursive: true, force: true });
-}
 function parseJournalLine(line, lineNumber) {
     if (Buffer.byteLength(line, 'utf8') > MAX_LINE_BYTES) {
         throw new WorkflowJournalValidationError(`journal line ${lineNumber} exceeds ${MAX_LINE_BYTES} bytes.`);

package/dist/runtime/workflow-runtime.d.ts

@@ -32,6 +32,9 @@ export type WorkflowEvent = {
     readonly phaseIndex: number;
     readonly title: string;
     readonly detail?: string;
+    readonly goal?: string;
+    readonly plannedAgentCount?: number;
+    readonly plannedAgents?: readonly WorkflowPlanAgent[];
 } | {
     readonly type: 'workflow.plan.ready';
     readonly taskId: string;
@@ -39,6 +42,15 @@ export type WorkflowEvent = {
     readonly mode: string;
     readonly rationale?: string;
     readonly phases: readonly WorkflowPlanPhase[];
+} | {
+    readonly type: 'workflow.phase.planned';
+    readonly taskId: string;
+    readonly runId: string;
+    readonly phaseIndex: number;
+    readonly title: string;
+    readonly goal?: string;
+    readonly plannedAgentCount: number;
+    readonly plannedAgents: readonly WorkflowPlanAgent[];
 } | {
     readonly type: 'workflow.log';
     readonly taskId: string;
@@ -65,6 +77,11 @@ export type WorkflowEvent = {
     readonly toolCalls: number;
     readonly resultPreview?: string;
     readonly cached?: boolean;
+    readonly elapsedMs: number;
+    readonly completedAgentCount: number;
+    readonly knownAgentCount: number;
+    readonly phaseCompletedAgentCount?: number;
+    readonly phaseKnownAgentCount?: number;
     readonly worktreePath?: string;
     readonly worktreePreserved?: boolean;
     readonly preservedWorktrees?: readonly WorkflowAgentPreservedWorktree[];
@@ -211,7 +228,7 @@ interface BuiltinWorkflow {
 export interface WorkflowAgentPreservedWorktree {
     readonly path: string;
     readonly attemptIndex: number;
-    readonly reason: 'changed' | 'stalled' | 'aborted' | 'status_unavailable' | 'cleanup_failed';
+    readonly reason: 'clean' | 'changed' | 'stalled' | 'aborted' | 'status_unavailable';
 }
 export declare class WorkflowTaskRegistry implements WorkflowRuntime {
     private readonly options;
@@ -270,6 +287,7 @@ export declare class WorkflowTaskRegistry implements WorkflowRuntime {
     private parallel;
     private pipeline;
     private announcePlan;
+    private announcePhasePlan;
     private phase;
     private completeTask;
     private failTask;

package/dist/runtime/workflow-runtime.js

@@ -1,12 +1,12 @@
 import { execFile } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { chmod, mkdir, readdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { promisify } from 'node:util';
 import { createContext, runInContext } from 'node:vm';
 import { UltracodeRequestError, estimateTokens } from './types.js';
-import { WORKFLOW_JOURNAL_GENESIS_AGENT_CALL_KEY, WORKFLOW_JOURNAL_WRITE_FAILED_REASON, WorkflowJournalError, WorkflowJournalWriter, cleanupWorkflowJournalTranscriptDir, computeWorkflowAgentCallKey, isWorkflowJournalError, normalizeJournalJsonValue, readWorkflowJournal, workflowJournalPath, } from './workflow-journal.js';
+import { WORKFLOW_JOURNAL_GENESIS_AGENT_CALL_KEY, WORKFLOW_JOURNAL_WRITE_FAILED_REASON, WorkflowJournalError, WorkflowJournalWriter, computeWorkflowAgentCallKey, isWorkflowJournalError, normalizeJournalJsonValue, readWorkflowJournal, workflowJournalPath, } from './workflow-journal.js';
 const MAX_SCRIPT_BYTES = 64 * 1024;
 const MAX_AGENT_CALLS = 1000;
 const MAX_PARALLELISM = 16;
@@ -141,6 +141,15 @@ const DEFAULT_BUILTIN_WORKFLOWS = [
 };
 const input = args && typeof args === "object" ? args : {};
 const prompts = Array.isArray(input.prompts) ? input.prompts : [];
+if (prompts.length > 0) {
+  announcePhasePlan({
+    title: "Batch",
+    agents: prompts.map((_, index) => ({
+      title: "Batch " + (index + 1),
+      label: "batch-" + (index + 1)
+    }))
+  });
+}
 phase("Batch");
 return await parallel(prompts.map((prompt, index) => () => agent(
   prompt == null ? "" : "" + prompt,
@@ -214,10 +223,8 @@ const plan = await agent([
   }
 });
 const selectedPhases = plan.mode === "single" ? [plan.phases[0]] : plan.phases;
-announcePlan({
-  mode: plan.mode,
-  rationale: plan.rationale,
-  phases: selectedPhases.map((phasePlan) => ({
+function plannedPhaseFor(phasePlan) {
+  return {
     id: phasePlan.id,
     title: phasePlan.title,
     goal: phasePlan.goal,
@@ -229,11 +236,18 @@ announcePlan({
         ? ${JSON.stringify(`${input.name}-single`)}
         : ${JSON.stringify(`${input.name}-`)} + phasePlan.id + "-" + phaseAgent.id
     }))
-  }))
+  };
+}
+const firstPhasePlan = plannedPhaseFor(selectedPhases[0]);
+announcePlan({
+  mode: plan.mode,
+  rationale: plan.rationale,
+  phases: [firstPhasePlan]
 });
 if (plan.mode === "single") {
-  const singlePhase = selectedPhases[0];
+  const singlePhase = firstPhasePlan;
   const singleAgent = singlePhase.agents[0];
+  announcePhasePlan(singlePhase);
   phase(singlePhase.title);
   return await agent([
     "Single-agent execution selected by the LLM planner.",
@@ -253,7 +267,9 @@ if (plan.mode === "single") {
 }
 const phaseOutputs = [];
 const priorSummaries = [];
-for (const phasePlan of selectedPhases) {
+for (const rawPhasePlan of selectedPhases) {
+  const phasePlan = plannedPhaseFor(rawPhasePlan);
+  announcePhasePlan(phasePlan);
   phase(phasePlan.title);
   const agents = phasePlan.agents;
   const agentOutputs = agents.length < 2
@@ -398,11 +414,6 @@ export class WorkflowTaskRegistry {
             }
         }
         catch (err) {
-            await cleanupWorkflowJournalTranscriptDir(transcriptDir).catch(() => undefined);
-            if (!resolved.scriptPath) {
-                await rm(scriptPath, { force: true }).catch(() => undefined);
-                await rm(workflowScriptMetadataPath(scriptPath), { force: true }).catch(() => undefined);
-            }
             throw workflowJournalRequestError(err);
         }
         const task = {
@@ -970,9 +981,11 @@ export class WorkflowTaskRegistry {
             controller.abort();
             return;
         }
-        const workflowTimer = setTimeout(() => {
-            controller.abort();
-        }, this.options.requestTimeoutMs);
+        const workflowTimer = this.options.requestTimeoutMs > 0
+            ? setTimeout(() => {
+                controller.abort();
+            }, this.options.requestTimeoutMs)
+            : null;
         try {
             if (controller.signal.aborted)
                 throw workflowInputError('Workflow is aborted.');
@@ -1002,9 +1015,7 @@ export class WorkflowTaskRegistry {
                 toolCalls: ctx.toolCalls,
                 durationMs: Date.now() - ctx.startedAt,
             });
-            if (completedSnapshot.status !== 'completed') {
-                await rm(resultPath, { force: true }).catch(() => undefined);
-            }
+            void completedSnapshot;
         }
         catch (err) {
             const abortFailure = controller.signal.aborted
@@ -1014,7 +1025,8 @@ export class WorkflowTaskRegistry {
             await this.failTask(task, abortFailure ? abortFailure.message : workflowErrorMessage(err), abortFailure ? abortFailure.reason : workflowFailureReason(err));
         }
         finally {
-            clearTimeout(workflowTimer);
+            if (workflowTimer)
+                clearTimeout(workflowTimer);
             for (const timer of ctx.timers.values())
                 clearTimeout(timer);
             ctx.timers.clear();
@@ -1078,6 +1090,7 @@ export class WorkflowTaskRegistry {
             return this.trackWorkflowPromise(ctx, this.workspaceContext(ctx, options));
         });
         host.announcePlan = hardenCallable((plan) => this.announcePlan(ctx, plan));
+        host.announcePhasePlan = hardenCallable((phasePlan) => this.announcePhasePlan(ctx, phasePlan));
         host.phase = hardenCallable((title) => this.phase(ctx, title));
         host.log = hardenCallable(log);
         host.consoleLog = hardenCallable((...values) => {
@@ -1215,6 +1228,7 @@ export class WorkflowTaskRegistry {
                 toolCalls: 0,
                 resultPreview: previewValue(cached.result, 160),
                 cached: true,
+                ...agentCompletionProgress(ctx, phase),
             });
             return cached.result;
         }
@@ -1278,6 +1292,7 @@ export class WorkflowTaskRegistry {
                 tokens: usage.totalTokens,
                 toolCalls,
                 resultPreview: previewValue(journalResult, 160),
+                ...agentCompletionProgress(ctx, phase),
                 ...preservedWorktreeEventProjection(preservedWorktrees),
             });
             return journalResult;
@@ -1343,7 +1358,6 @@ export class WorkflowTaskRegistry {
             };
         }
         catch (err) {
-            await rm(worktreePath, { recursive: true, force: true }).catch(() => undefined);
             throw workflowInputError(`worktree isolation could not create an isolated worktree: ${workflowErrorMessage(err)}`);
         }
     }
@@ -1364,16 +1378,10 @@ export class WorkflowTaskRegistry {
                 preservedWorktree: preservedWorktree(worktree, 'changed'),
             };
         }
-        try {
-            await removeCleanGitWorktree(worktree);
-        }
-        catch {
-            return {
-                preserved: true,
-                preservedWorktree: preservedWorktree(worktree, 'cleanup_failed'),
-            };
-        }
-        return { preserved: false };
+        return {
+            preserved: true,
+            preservedWorktree: preservedWorktree(worktree, 'clean'),
+        };
     }
     async runAgentWithStallRetries(ctx, input) {
         for (let retryIndex = 0; retryIndex <= this.agentStallRetryLimit; retryIndex += 1) {
@@ -1448,10 +1456,12 @@ export class WorkflowTaskRegistry {
             throw workflowInputError('Workflow is aborted.');
         }
         ctx.controller.signal.addEventListener('abort', abortFromWorkflow, { once: true });
-        const timer = setTimeout(() => {
-            timedOut = true;
-            attemptController.abort();
-        }, this.agentStallTimeoutMs);
+        const timer = this.agentStallTimeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                attemptController.abort();
+            }, this.agentStallTimeoutMs)
+            : null;
         try {
             const generated = this.options.backend.generate(request, attemptController.signal).then((result) => ({ type: 'result', result }), (err) => ({ type: 'error', error: err }));
             const aborted = new Promise((resolve) => {
@@ -1474,7 +1484,8 @@ export class WorkflowTaskRegistry {
             throw outcome.error;
         }
         finally {
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
             ctx.controller.signal.removeEventListener('abort', abortFromWorkflow);
         }
     }
@@ -1529,6 +1540,7 @@ export class WorkflowTaskRegistry {
             throw workflowInputError('Workflow is aborted.');
         }
         const normalized = normalizeWorkflowExecutionPlan(plan);
+        ctx.announcedPlan = normalized;
         this.emit(ctx.task, {
             type: 'workflow.plan.ready',
             taskId: ctx.task.taskId,
@@ -1536,22 +1548,54 @@ export class WorkflowTaskRegistry {
             ...normalized,
         });
     }
+    announcePhasePlan(ctx, phasePlan) {
+        if (ctx.controller.signal.aborted || ctx.task.status !== 'running') {
+            throw workflowInputError('Workflow is aborted.');
+        }
+        const normalized = normalizeWorkflowPhasePlan(phasePlan, 'announcePhasePlan(phasePlan)');
+        ctx.pendingPhasePlan = normalized;
+        const phaseIndex = ctx.task.events
+            .filter((event) => event.type === 'workflow.phase.started')
+            .length;
+        this.emit(ctx.task, {
+            type: 'workflow.phase.planned',
+            taskId: ctx.task.taskId,
+            runId: ctx.task.runId,
+            phaseIndex,
+            title: normalized.title,
+            ...(normalized.goal ? { goal: normalized.goal } : {}),
+            plannedAgentCount: normalized.agents.length,
+            plannedAgents: normalized.agents,
+        });
+    }
     phase(ctx, title) {
         if (typeof title !== 'string' || title.trim() === '') {
             throw workflowInputError('phase() requires a non-empty string title.');
         }
-        ctx.currentPhase = title;
+        const normalizedTitle = title.trim();
+        ctx.currentPhase = normalizedTitle;
         const phaseIndex = ctx.task.events
             .filter((event) => event.type === 'workflow.phase.started')
             .length;
-        const detail = ctx.parsed.meta.phases?.find((item) => item.title === title)?.detail;
+        const detail = ctx.parsed.meta.phases?.find((item) => item.title === normalizedTitle)?.detail;
+        const pendingPhase = ctx.pendingPhasePlan?.title === normalizedTitle
+            ? ctx.pendingPhasePlan
+            : undefined;
+        if (pendingPhase)
+            ctx.pendingPhasePlan = undefined;
+        const plannedPhase = pendingPhase ?? workflowPlannedPhase(ctx.announcedPlan, phaseIndex, normalizedTitle);
         this.emit(ctx.task, {
             type: 'workflow.phase.started',
             taskId: ctx.task.taskId,
             runId: ctx.task.runId,
             phaseIndex,
-            title,
+            title: normalizedTitle,
             ...(detail ? { detail } : {}),
+            ...(plannedPhase?.goal ? { goal: plannedPhase.goal } : {}),
+            ...(plannedPhase ? {
+                plannedAgentCount: plannedPhase.agents.length,
+                plannedAgents: plannedPhase.agents,
+            } : {}),
         });
     }
     async completeTask(ctx, result, event) {
@@ -1946,19 +1990,6 @@ function uniqueStrings(values) {
     }
     return out;
 }
-async function removeCleanGitWorktree(worktree) {
-    try {
-        await gitOutput(worktree.gitRoot, ['worktree', 'remove', '--force', worktree.path]);
-    }
-    catch (err) {
-        if (/No such file|not a working tree|is not a working tree/i.test(workflowErrorMessage(err))) {
-            await rm(worktree.path, { recursive: true, force: true }).catch(() => undefined);
-            await gitOutput(worktree.gitRoot, ['worktree', 'prune']).catch(() => undefined);
-            return;
-        }
-        throw err;
-    }
-}
 function preservedWorktree(worktree, reason) {
     return {
         path: worktree.path,
@@ -1970,7 +2001,7 @@ function preservedWorktreeEventProjection(preservedWorktrees) {
     if (preservedWorktrees.length === 0)
         return {};
     const primary = preservedWorktrees.find((item) => item.reason === 'changed')
-        ?? preservedWorktrees.find((item) => item.reason === 'cleanup_failed' || item.reason === 'status_unavailable')
+        ?? preservedWorktrees.find((item) => item.reason === 'status_unavailable')
         ?? preservedWorktrees[0];
     return {
         worktreePath: primary?.path,
@@ -1978,6 +2009,33 @@ function preservedWorktreeEventProjection(preservedWorktrees) {
         preservedWorktrees: [...preservedWorktrees],
     };
 }
+function workflowPlannedPhase(plan, phaseIndex, title) {
+    const indexed = plan?.phases[phaseIndex];
+    if (indexed?.title === title)
+        return indexed;
+    return plan?.phases.find((phase) => phase.title === title);
+}
+function agentCompletionProgress(ctx, phase) {
+    const completedAgentCount = ctx.task.events
+        .filter((event) => event.type === 'workflow.agent.completed')
+        .length + 1;
+    const base = {
+        elapsedMs: Date.now() - ctx.startedAt,
+        completedAgentCount,
+        knownAgentCount: ctx.agentCount,
+    };
+    if (!phase)
+        return base;
+    const phaseCompletedAgentCount = ctx.task.events
+        .filter((event) => event.type === 'workflow.agent.completed' && event.phase === phase)
+        .length + 1;
+    const phaseKnownAgentCount = Math.max(phaseCompletedAgentCount, ctx.task.events.filter((event) => event.type === 'workflow.agent.started' && event.phase === phase).length);
+    return {
+        ...base,
+        phaseCompletedAgentCount,
+        phaseKnownAgentCount,
+    };
+}
 function shortHash(value) {
     return createHash('sha256').update(value).digest('hex').slice(0, 12);
 }
@@ -2684,6 +2742,8 @@ function normalizeAgentStallTimeoutMs(configured, requestTimeoutMs) {
     if (configured !== undefined && Number.isFinite(configured) && configured > 0) {
         return Math.max(1, Math.floor(configured));
     }
+    if (configured === 0 || requestTimeoutMs === 0)
+        return 0;
     return Math.max(1, Math.floor(requestTimeoutMs));
 }
 function workflowTaskSnapshot(task) {
@@ -2972,6 +3032,7 @@ function installWorkflowVmGlobals(context, globals) {
         '  define(globalThis, "pipeline", { value: (...values) => __host.pipeline(...values), writable: false, configurable: false });',
         '  define(globalThis, "workspaceContext", { value: (...values) => __host.workspaceContext(...values), writable: false, configurable: false });',
         '  define(globalThis, "announcePlan", { value: (...values) => __host.announcePlan(...values), writable: false, configurable: false });',
+        '  define(globalThis, "announcePhasePlan", { value: (...values) => __host.announcePhasePlan(...values), writable: false, configurable: false });',
         '  define(globalThis, "phase", { value: (...values) => __host.phase(...values), writable: false, configurable: false });',
         '  define(globalThis, "log", { value: (...values) => __host.log(...values), writable: false, configurable: false });',
         '  define(globalThis, "workflow", { value: (...values) => __host.workflow(...values), writable: false, configurable: false });',
@@ -3664,38 +3725,41 @@ function normalizeWorkflowExecutionPlan(value) {
     const rawPhases = Array.isArray(record.phases) ? Array.from(record.phases) : [];
     if (rawPhases.length === 0)
         throw workflowInputError('announcePlan(plan) requires at least one phase.');
-    const phases = rawPhases.slice(0, 16).map((phaseValue, phaseIndex) => {
-        const phase = asRecord(phaseValue);
-        if (!phase)
-            throw workflowInputError(`announcePlan(plan).phases[${phaseIndex}] must be an object.`);
-        const rawAgents = Array.isArray(phase.agents) ? Array.from(phase.agents) : [];
-        if (rawAgents.length === 0) {
-            throw workflowInputError(`announcePlan(plan).phases[${phaseIndex}].agents requires at least one agent.`);
-        }
-        return {
-            ...(typeof phase.id === 'string' && phase.id.trim() ? { id: boundedPlanString(phase.id, '', 48) } : {}),
-            title: boundedPlanString(phase.title, `Phase ${phaseIndex + 1}`, 96),
-            ...(typeof phase.goal === 'string' && phase.goal.trim() ? { goal: boundedPlanString(phase.goal, '', 600) } : {}),
-            agents: rawAgents.slice(0, 16).map((agentValue, agentIndex) => {
-                const agent = asRecord(agentValue);
-                if (!agent) {
-                    throw workflowInputError(`announcePlan(plan).phases[${phaseIndex}].agents[${agentIndex}] must be an object.`);
-                }
-                return {
-                    ...(typeof agent.id === 'string' && agent.id.trim() ? { id: boundedPlanString(agent.id, '', 48) } : {}),
-                    title: boundedPlanString(agent.title, `Agent ${agentIndex + 1}`, 96),
-                    ...(typeof agent.focus === 'string' && agent.focus.trim() ? { focus: boundedPlanString(agent.focus, '', 600) } : {}),
-                    ...(typeof agent.label === 'string' && agent.label.trim() ? { label: boundedPlanString(agent.label, '', 96) } : {}),
-                };
-            }),
-        };
-    });
+    const phases = rawPhases
+        .slice(0, 16)
+        .map((phaseValue, phaseIndex) => normalizeWorkflowPhasePlan(phaseValue, `announcePlan(plan).phases[${phaseIndex}]`, phaseIndex));
     return {
         mode,
         ...(rationale ? { rationale } : {}),
         phases,
     };
 }
+function normalizeWorkflowPhasePlan(value, label, phaseIndex = 0) {
+    const phase = asRecord(value);
+    if (!phase)
+        throw workflowInputError(`${label} must be an object.`);
+    const rawAgents = Array.isArray(phase.agents) ? Array.from(phase.agents) : [];
+    if (rawAgents.length === 0) {
+        throw workflowInputError(`${label}.agents requires at least one agent.`);
+    }
+    return {
+        ...(typeof phase.id === 'string' && phase.id.trim() ? { id: boundedPlanString(phase.id, '', 48) } : {}),
+        title: boundedPlanString(phase.title, `Phase ${phaseIndex + 1}`, 96),
+        ...(typeof phase.goal === 'string' && phase.goal.trim() ? { goal: boundedPlanString(phase.goal, '', 600) } : {}),
+        agents: rawAgents.slice(0, 16).map((agentValue, agentIndex) => {
+            const agent = asRecord(agentValue);
+            if (!agent) {
+                throw workflowInputError(`${label}.agents[${agentIndex}] must be an object.`);
+            }
+            return {
+                ...(typeof agent.id === 'string' && agent.id.trim() ? { id: boundedPlanString(agent.id, '', 48) } : {}),
+                title: boundedPlanString(agent.title, `Agent ${agentIndex + 1}`, 96),
+                ...(typeof agent.focus === 'string' && agent.focus.trim() ? { focus: boundedPlanString(agent.focus, '', 600) } : {}),
+                ...(typeof agent.label === 'string' && agent.label.trim() ? { label: boundedPlanString(agent.label, '', 96) } : {}),
+            };
+        }),
+    };
+}
 function boundedPlanString(value, fallback, limit) {
     const text = typeof value === 'string' && value.trim() ? value.trim() : fallback;
     return preview(text, limit);

package/dist/settings.js

@@ -34,7 +34,7 @@ export function loadSettings() {
             progress: readWorkflowProgressModeSetting(workflow?.progress, 'workflow.progress'),
             permission: readWorkflowPermissionPolicySetting(workflow?.permission, 'workflow.permission'),
             retryLimit: readNonNegativeIntegerSetting(workflow?.retryLimit, 'workflow.retryLimit'),
-            timeoutMs: readPositiveIntegerSetting(workflow?.timeoutMs, 'workflow.timeoutMs'),
+            timeoutMs: readNonNegativeIntegerSetting(workflow?.timeoutMs, 'workflow.timeoutMs'),
             background: {
                 runDir: readTemplateSetting(background?.runDir, 'workflow.background.runDir', true),
                 resultFile: readRelativePathSetting(background?.resultFile, 'workflow.background.resultFile'),
@@ -119,11 +119,6 @@ function readNonNegativeIntegerSetting(value, key) {
         return value;
     throw new Error(`${key} must be a non-negative integer.`);
 }
-function readPositiveIntegerSetting(value, key) {
-    if (typeof value === 'number' && Number.isInteger(value) && value > 0)
-        return value;
-    throw new Error(`${key} must be a positive integer.`);
-}
 function readTemplateSetting(value, key, requireJobId) {
     const text = readNonEmptyStringSetting(value, key);
     if (requireJobId && !text.includes('{jobId}')) {

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.3`;
+- generated npm package contents for `ultracode-for-codex@0.2.6`;
 - the locally installed companion Codex skill.
 
 Generated build output and package tarballs were checked as projections of the
@@ -23,7 +23,7 @@ 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.3` for the license-bearing patch release.
+- package version is prepared as `0.2.6`.
 
 ## Evidence
 

package/docs/ultracode-p3c-worktree-isolation.md

@@ -11,8 +11,8 @@ P3-C is done when:
 
 - the runtime creates a detached git worktree before the backend call;
 - the backend turn runs with that worktree as its workspace;
-- unchanged isolated worktrees are removed after the agent finishes;
-- changed or unsafe-to-clean worktrees are preserved for review;
+- isolated worktrees are preserved after the agent finishes, including clean,
+  changed, stalled, aborted, or status-unavailable worktrees;
 - `semanticOpts.isolation` participates in the agent cache key.
 
 ## Authority Model
@@ -22,8 +22,8 @@ P3-C is done when:
 | isolation request | workflow script | Only `isolation: "worktree"` is accepted. |
 | worktree path | runtime | Runtime creates paths outside the source repo working tree. |
 | backend cwd | runtime request packet | Subagent backend executes the turn in `worktreePath`. |
-| changed/unchanged decision | runtime git status | `git status --porcelain --untracked-files=all --ignored=matching` decides preserve vs cleanup. |
-| preserved path projection | runtime event | Changed or unsafe-to-clean worktrees are surfaced on agent final events. |
+| changed/unchanged decision | runtime git status | `git status --porcelain --untracked-files=all --ignored=matching` decides the preservation reason. |
+| preserved path projection | runtime event | Preserved worktrees are surfaced on agent final events. |
 
 The accepted isolation values are `"none"` and `"worktree"`; any other value
 fails as invalid workflow input.
@@ -48,13 +48,13 @@ copied into the isolated worktree.
 4. Pass `worktreePath` to the subagent backend and append path-free worktree
    context to the backend prompt.
 5. Inspect worktree status after the attempt settles.
-6. Remove clean worktrees.
-7. Preserve changed, stalled, aborted, status-unavailable, or cleanup-failed
-   worktrees and surface them on the agent final event.
+6. Preserve the worktree with reason `clean`, `changed`, `stalled`, `aborted`,
+   or `status_unavailable` and surface it on the agent final event.
 
 ## Verification
 
 - `test/codex-isolation.test.mjs` verifies Codex backend request projection.
-- `test/workflow-runtime.test.mjs` verifies changed worktree preservation.
+- `test/workflow-runtime.test.mjs` verifies clean and changed worktree
+  preservation.
 - `scripts/e2e-installed-ultracode-for-codex.mjs` verifies packaged CLI workflow
   execution through the fake Codex app-server boundary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracode-for-codex",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Run local Codex-backed workflows from a command-owned CLI runtime.",
   "keywords": [
     "codex",
@@ -36,6 +36,8 @@
     "dist/ultracode-install-guide.d.ts",
     "dist/settings.js",
     "dist/settings.d.ts",
+    "dist/runtime/package-info.js",
+    "dist/runtime/package-info.d.ts",
     "dist/codex/",
     "dist/runtime/",
     "skills/ultracode-for-codex/",

package/settings.json

@@ -4,7 +4,7 @@
     "progress": "jsonl",
     "permission": "ask",
     "retryLimit": 0,
-    "timeoutMs": 900000,
+    "timeoutMs": 0,
     "background": {
       "runDir": ".ultracode-for-codex/background/{jobId}",
       "resultFile": "result.json",

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

@@ -13,9 +13,10 @@ binary, tests, package exports, journal layer, and workflow runtime code.
 
 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.
-Attached runs stream stderr JSONL for Codex-readable status, while stdout
-remains the final workflow result JSON.
+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.
 
 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
@@ -44,25 +45,33 @@ For source-checkout validation before publish:
 
 ```bash
 npm run pack:ultracode-for-codex
-npm install --save-dev ./artifacts/ultracode-for-codex-0.2.5.tgz
+npm install --save-dev ./artifacts/ultracode-for-codex-0.2.6.tgz
 ```
 
 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`;
-- attached execution is available with `--execution attached`;
+- attached execution is available with `--execution attached` when the caller
+  should stay connected until completion;
 - attached progress prints to stderr as JSONL by default;
 - attached final workflow result prints as JSON to stdout;
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`,
   with agent identity and label fields on agent records;
-- built-in `task` and `code-review` emit `workflow.plan.ready` before phase
-  agents start, including phase titles and planned agent role labels;
+- built-in `task` and `code-review` emit `workflow.plan.ready` as a planning
+  snapshot, not a promise that every later phase is already known;
+- `workflow.phase.planned` is emitted immediately before each phase starts and
+  carries that phase's current planned agent role labels;
+- each `workflow.phase.started` record repeats the same role labels when the
+  phase begins;
+- each `workflow.agent.completed` record includes phase progress, total known
+  agent progress, and elapsed time;
 - `Ctrl-C` cancels the active attached workflow;
 - `--retry-limit <n>` retries failed workflows inside the same process;
-- `--timeout-ms` is the workflow timeout and the default per-agent silence
-  budget; the package default is `900000` ms, or 15 minutes, and it is not
-  divided by the retry budget.
+- `--timeout-ms 0` waits for completion, cancellation, or app-server exit;
+  positive values opt into a workflow deadline and per-agent silence budget,
+  and that budget is not divided by the retry budget.
 - `--permission ask|allow|deny` handles project/user/plugin/scriptPath reviews.
 - `--progress plain` switches to human-readable progress lines.
 - background file locations are controlled by `workflow.background` in
@@ -77,14 +86,15 @@ CLI behavior:
 - Built-in `task` and `code-review` inject deterministic workspace context into
   planner-selected phase-wise parallel subagents.
 - Keep workflow execution local and command-owned; settings default to OS
-  background execution and `--execution attached` keeps the process connected
-  until completion.
+  background execution so long runs can keep waiting while Codex does other
+  work.
 - Keep `journalPath`, `journal.jsonl`, and journal contents out of CLI output.
 - Treat `.ultracode-for-codex` workflow state as sensitive local data.
 - Keep `resumeFromRunId` runtime-internal unless cross-process resume
   gets an explicit durable design.
 - Use `isolation: "worktree"` only inside a git repo with at least one commit;
-  changed or unsafe worktrees are intentionally preserved for review.
+  isolated worktrees are intentionally preserved for review, including clean
+  worktrees.
 
 ## Packaging And Verification