ultracode-for-codex 0.2.4 → 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.4.tgz
+npm install --save-dev /path/to/ultracode-for-codex-0.2.6.tgz
 ```
 
 Run a workflow:
@@ -68,6 +68,10 @@ The built-in `task` and `code-review` workflows use an LLM planner first, then
 run work phase by phase. Within each phase, multiple focused Codex subagents run
 in parallel by default, followed by phase and final synthesis. The planner may
 choose a single-agent path only when parallel execution would add risk or waste.
+Planner guidance includes dynamic workflow patterns such as classify-and-act,
+fan-out-and-synthesize, adversarial verification, generate-and-filter,
+tournament, and loop-until-done, so different work types can use different
+phase shapes.
 
 ## Settings
 
@@ -80,7 +84,7 @@ Package defaults live in `settings.json`:
     "progress": "jsonl",
     "permission": "ask",
     "retryLimit": 0,
-    "timeoutMs": 180000,
+    "timeoutMs": 0,
     "background": {
       "runDir": ".ultracode-for-codex/background/{jobId}",
       "resultFile": "result.json",
@@ -94,22 +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 `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` 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
 
@@ -131,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
@@ -140,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.4.tgz
+npm install --save-dev ./ultracode-for-codex-0.2.6.tgz
 ```
 
 Optional Codex companion skill:
@@ -55,14 +55,19 @@ 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
 Codex subagents in parallel within each phase by default, and synthesize phase
 and final results. The planner chooses a single-agent path only when parallel
 execution would add risk or waste.
+Planner guidance includes classify-and-act, fan-out-and-synthesize,
+adversarial verification, generate-and-filter, tournament, and loop-until-done
+patterns so different work types can use different phase shapes.
 
 Settings defaults:
 
@@ -73,7 +78,7 @@ Settings defaults:
     "progress": "jsonl",
     "permission": "ask",
     "retryLimit": 0,
-    "timeoutMs": 180000,
+    "timeoutMs": 0,
     "background": {
       "runDir": ".ultracode-for-codex/background/{jobId}",
       "resultFile": "result.json",
@@ -87,26 +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 `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` 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
@@ -124,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,28 @@ 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`);
+            for (const [phaseIndex, phase] of event.phases.entries()) {
+                process.stderr.write(`[plan] ${phaseIndex + 1}. ${phase.title}${phase.goal ? ` - ${phase.goal}` : ''}\n`);
+                for (const agent of phase.agents) {
+                    process.stderr.write(`[plan]    - ${agent.title}${agent.label ? ` (${agent.label})` : ''}${agent.focus ? `: ${agent.focus}` : ''}\n`);
+                }
+            }
             return;
         case 'workflow.log':
             process.stderr.write(`[log] ${event.message}\n`);
@@ -357,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`);
@@ -400,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':
@@ -414,16 +471,44 @@ 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 planning snapshot: ${event.phases.length} known phase${event.phases.length === 1 ? '' : 's'}, mode=${event.mode}`,
+                taskId: event.taskId,
+                runId: event.runId,
+                mode: event.mode,
+                rationale: event.rationale,
+                phaseCount: event.phases.length,
+                planPhases: event.phases,
             };
         case 'workflow.log':
             return {
@@ -451,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,
@@ -462,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,
             };
@@ -516,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;
 }
@@ -575,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.
@@ -589,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

@@ -4,6 +4,18 @@ export type WorkflowTaskStatus = 'running' | 'completed' | 'failed';
 export type WorkflowTaskType = 'local_workflow';
 export type WorkflowSource = 'inline' | 'script_path' | 'project' | 'user' | 'plugin' | 'built_in';
 export type WorkflowPermissionDecision = 'allow' | 'deny';
+export interface WorkflowPlanAgent {
+    readonly id?: string;
+    readonly title: string;
+    readonly focus?: string;
+    readonly label?: string;
+}
+export interface WorkflowPlanPhase {
+    readonly id?: string;
+    readonly title: string;
+    readonly goal?: string;
+    readonly agents: readonly WorkflowPlanAgent[];
+}
 export type WorkflowEvent = {
     readonly type: 'workflow.started';
     readonly taskId: string;
@@ -20,6 +32,25 @@ 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;
+    readonly runId: string;
+    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;
@@ -46,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[];
@@ -192,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;
@@ -250,6 +286,8 @@ export declare class WorkflowTaskRegistry implements WorkflowRuntime {
     private runAgentAttempt;
     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;
@@ -98,6 +98,16 @@ const WORKSPACE_CONTEXT_PRIORITY_FILES = new Set([
     'package.json',
     'tsconfig.json',
 ]);
+const DYNAMIC_WORKFLOW_PATTERN_GUIDANCE = [
+    'Use dynamic workflow patterns intentionally:',
+    '- classify-and-act: classify the request, risk, or repository area before choosing phase shape.',
+    '- fan-out-and-synthesize: split independent lenses across parallel agents, then merge evidence.',
+    '- adversarial verification: assign at least one agent to challenge correctness, security, or assumptions on high-risk work.',
+    '- generate-and-filter: create candidate approaches or fixes, then select by evidence and constraints.',
+    '- tournament: compare competing alternatives when the best path is unclear.',
+    '- loop-until-done: iterate repair and verification only when there is a clear stop condition.',
+    'Prefer pipelines when later phases need earlier summaries; prefer parallel agents when independent evidence can be gathered at the same time.',
+].join('\n');
 const DEFAULT_BUILTIN_WORKFLOWS = [
     {
         name: 'task',
@@ -106,7 +116,7 @@ const DEFAULT_BUILTIN_WORKFLOWS = [
             description: 'Run an LLM-planned phase-wise parallel task workflow',
             defaultPrompt: 'Complete the requested repository task.',
             plannerKind: 'general task',
-            plannerGuidance: 'Plan phases that make the work faster and more accurate through parallel agents. Default to phase_parallel. Choose single only for tiny changes, strictly sequential investigations, or one indivisible failure mode.',
+            plannerGuidance: 'Plan phases that make the work faster and more accurate through parallel agents. Default to phase_parallel. Choose single only for tiny changes, strictly sequential investigations, or one indivisible failure mode. Pick workflow patterns that match the request instead of using one fixed shape.',
             agentGuidance: 'Complete the assigned phase work. Prefer concrete evidence, file paths, commands, and risks over broad narration.',
             finalGuidance: 'Return the completed task result, key evidence, decisions made, verification status, and residual risk.',
         }),
@@ -118,7 +128,7 @@ const DEFAULT_BUILTIN_WORKFLOWS = [
             description: 'Run an LLM-planned phase-wise parallel code review workflow',
             defaultPrompt: 'Review the current repository for correctness risks.',
             plannerKind: 'code review',
-            plannerGuidance: 'Plan an effective code review. Default to phase_parallel with multiple focused reviewers per phase. Commonly useful lenses include runtime correctness, security/capability boundaries, API/CLI contracts, persistence/retry/cancel behavior, and test coverage. Choose single only for a tiny scoped diff or one indivisible failure mode.',
+            plannerGuidance: 'Plan an effective code review. Default to phase_parallel with multiple focused reviewers per phase. Commonly useful lenses include runtime correctness, security/capability boundaries, API/CLI contracts, persistence/retry/cancel behavior, and test coverage. Prefer fan-out-and-synthesize plus adversarial verification unless the diff is tiny or one indivisible failure mode.',
             agentGuidance: 'Return material findings only. Prioritize root cause, severity, exact file/line evidence, reproduction or impact, and residual risk.',
             finalGuidance: 'Return findings ordered by severity with exact file/line references. Deduplicate overlaps, preserve dissent or uncertainty, and say clearly if there are no material findings.',
         }),
@@ -131,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,
@@ -152,6 +171,8 @@ const plan = await agent([
   ${JSON.stringify(`Plan the phase-wise execution strategy for ${input.plannerKind}.`)},
   "",
   ${JSON.stringify(input.plannerGuidance)},
+  "",
+  ${JSON.stringify(DYNAMIC_WORKFLOW_PATTERN_GUIDANCE)},
   "A phase runs after previous phase summaries are available. Within each phase, use parallel agents by default.",
   "Return 1 to 4 phases. For ordinary work, prefer 2 phases with 2 to 4 parallel agents each. Use concise stable ids.",
   "",
@@ -202,9 +223,31 @@ const plan = await agent([
   }
 });
 const selectedPhases = plan.mode === "single" ? [plan.phases[0]] : plan.phases;
+function plannedPhaseFor(phasePlan) {
+  return {
+    id: phasePlan.id,
+    title: phasePlan.title,
+    goal: phasePlan.goal,
+    agents: (plan.mode === "single" ? [phasePlan.agents[0]] : phasePlan.agents).map((phaseAgent) => ({
+      id: phaseAgent.id,
+      title: phaseAgent.title,
+      focus: phaseAgent.focus,
+      label: plan.mode === "single"
+        ? ${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.",
@@ -224,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
@@ -369,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 = {
@@ -941,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.');
@@ -973,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
@@ -985,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();
@@ -1048,6 +1089,8 @@ export class WorkflowTaskRegistry {
         host.workspaceContext = hardenCallable((options) => {
             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) => {
@@ -1185,6 +1228,7 @@ export class WorkflowTaskRegistry {
                 toolCalls: 0,
                 resultPreview: previewValue(cached.result, 160),
                 cached: true,
+                ...agentCompletionProgress(ctx, phase),
             });
             return cached.result;
         }
@@ -1248,6 +1292,7 @@ export class WorkflowTaskRegistry {
                 tokens: usage.totalTokens,
                 toolCalls,
                 resultPreview: previewValue(journalResult, 160),
+                ...agentCompletionProgress(ctx, phase),
                 ...preservedWorktreeEventProjection(preservedWorktrees),
             });
             return journalResult;
@@ -1313,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)}`);
         }
     }
@@ -1334,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) {
@@ -1418,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) => {
@@ -1444,7 +1484,8 @@ export class WorkflowTaskRegistry {
             throw outcome.error;
         }
         finally {
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
             ctx.controller.signal.removeEventListener('abort', abortFromWorkflow);
         }
     }
@@ -1494,22 +1535,67 @@ export class WorkflowTaskRegistry {
             return current;
         });
     }
+    announcePlan(ctx, plan) {
+        if (ctx.controller.signal.aborted || ctx.task.status !== 'running') {
+            throw workflowInputError('Workflow is aborted.');
+        }
+        const normalized = normalizeWorkflowExecutionPlan(plan);
+        ctx.announcedPlan = normalized;
+        this.emit(ctx.task, {
+            type: 'workflow.plan.ready',
+            taskId: ctx.task.taskId,
+            runId: ctx.task.runId,
+            ...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) {
@@ -1904,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,
@@ -1928,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,
@@ -1936,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);
 }
@@ -2642,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) {
@@ -2929,6 +3031,8 @@ function installWorkflowVmGlobals(context, globals) {
         '  define(globalThis, "parallel", { value: (...values) => __host.parallel(...values), writable: false, configurable: false });',
         '  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 });',
@@ -3612,6 +3716,59 @@ function previewValue(value, limit) {
         : JSON.stringify(value) ?? String(value);
     return preview(text, limit);
 }
+function normalizeWorkflowExecutionPlan(value) {
+    const record = asRecord(value);
+    if (!record)
+        throw workflowInputError('announcePlan(plan) requires a plan object.');
+    const mode = boundedPlanString(record.mode, 'phase_parallel', 48);
+    const rationale = optionalBoundedPlanString(record.rationale, 400);
+    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) => 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);
+}
+function optionalBoundedPlanString(value, limit) {
+    if (typeof value !== 'string' || !value.trim())
+        return undefined;
+    return boundedPlanString(value, '', limit);
+}
 function asRecord(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return null;

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.4",
+  "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": 180000,
+    "timeoutMs": 0,
     "background": {
       "runDir": ".ultracode-for-codex/background/{jobId}",
       "resultFile": "result.json",

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

@@ -13,15 +13,19 @@ 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
 phase with parallel focused subagents by default, followed by phase and final
 synthesis. A single-agent path is reserved for cases where the planner judges
 parallel execution risky or wasteful.
+Planner guidance includes classify-and-act, fan-out-and-synthesize,
+adversarial verification, generate-and-filter, tournament, and loop-until-done
+patterns so workflow shape can follow the task instead of a fixed template.
 
 ## Install And Run
 
@@ -41,22 +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.4.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` 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; 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
@@ -71,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