ultracode-for-codex 0.2.5 → 0.3.0

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.3.0`;
 - the locally installed companion Codex skill.
 
 Generated build output and package tarballs were checked as projections of the
@@ -23,7 +23,8 @@ License transition completed:
 
 - Apache-2.0 `LICENSE` file is present;
 - `package.json` and `package-lock.json` declare `Apache-2.0`;
-- package version is prepared as `0.2.3` for the license-bearing patch release.
+- release-candidate package version is `0.3.0`;
+- npm latest before this release remains `0.2.6`.
 
 ## Evidence