ultracode-for-codex 0.3.3 → 0.3.4

package/README.md

@@ -162,6 +162,16 @@ npm exec -- ultracode-for-codex run \
   --args '{"prompt":"check the release plan"}'
 ```
 
+Resume a completed local workflow from preserved runtime state:
+
+```bash
+npm exec -- ultracode-for-codex run \
+  --accept-llm-guide=v1 \
+  --execution attached \
+  --cwd /path/to/project \
+  --resume-from-run-id run_...
+```
+
 ## What Gets Installed
 
 The package includes:
@@ -174,11 +184,14 @@ The package includes:
 
 ## Local State
 
-CLI background runs write local workflow state under `.ultracode-for-codex/` in
-the target project. Treat that folder as local runtime data. It may contain
-progress, metadata, transcripts, and results for the run.
+CLI runs write workflow state under `${ULTRACODE_FOR_CODEX_HOME:-~/.ultracode-for-codex}`.
+The runtime keeps background metadata, journals, transcripts, generated scripts,
+and results outside the target project so review evidence stays focused on the
+workspace itself.
 
-Add it to `.gitignore` if your project does not already ignore it:
+Project workflow sources may still live in `.codex/workflows/`. If an older
+workspace already has `.ultracode-for-codex/`, keep it ignored and treat it as
+legacy sensitive local data:
 
 ```gitignore
 .ultracode-for-codex/

package/ULTRACODE_INSTALL.md

@@ -22,7 +22,7 @@ Skill commands:
 
 The packaged `settings.json` defaults CLI workflow runs to OS background
 execution with result and progress files under
-`.ultracode-for-codex/background/{jobId}`.
+`${ULTRACODE_FOR_CODEX_HOME:-~/.ultracode-for-codex}/background/{jobId}`.
 
 Production surface:
 
@@ -124,7 +124,7 @@ Settings defaults:
     "retryLimit": 0,
     "timeoutMs": 0,
     "background": {
-      "runDir": ".ultracode-for-codex/background/{jobId}",
+      "runDir": "{stateRoot}/background/{jobId}",
       "resultFile": "result.json",
       "progressFile": "progress.jsonl",
       "metadataFile": "metadata.json",
@@ -166,6 +166,9 @@ Useful controls:
   acting on it.
 - Press `Ctrl-C` once to cancel the running workflow.
 - Use `--retry-limit <n>` to retry failed runs in the same process.
+- Use `--resume-from-run-id <runId>` to resume a completed local workflow from
+  preserved runtime state. Resume always uses the original persisted workflow
+  source; without `--args`, it also reuses the original args.
 - `--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.
@@ -196,12 +199,18 @@ Useful controls:
 - Keep `journalPath`, `journal.jsonl`, and journal contents out of CLI output.
   Local runtime state may still contain runtime-owned
   `transcriptDir`, `scriptPath`, and result files.
-- `resumeFromRunId` remains a runtime-internal same-session capability; the
-  CLI uses retry or explicit reruns for user-facing recovery.
+- `--resume-from-run-id` reads the preserved runtime script, result record, and
+  completed journal from the workflow state directory under
+  `${ULTRACODE_FOR_CODEX_HOME:-~/.ultracode-for-codex}`; completed agent
+  results are reused only when their runtime-owned call keys still match. The
+  script path, script source identity, and inherited args must match the
+  completed journal.
 - Use `isolation: "worktree"` only in git repositories with at least one commit.
   Isolated worktrees are intentionally preserved for review, including clean
   worktrees.
-- Treat `.ultracode-for-codex` workflow state as sensitive local data.
+- Treat workflow state under `${ULTRACODE_FOR_CODEX_HOME:-~/.ultracode-for-codex}`
+  as sensitive local data. Project-local `.ultracode-for-codex/` directories are
+  legacy state and should stay ignored.
 
 ## First Checks After Install
 
@@ -224,5 +233,5 @@ workflow.
   progress and completion summary examples for native orchestration.
 - `skills/ultracode-for-codex-cli/SKILL.md`: explicit CLI runtime command.
 - `docs/ultracode-p3a-journal-design.md`: implemented journal contract.
-- `docs/ultracode-p3b-resume-cache.md`: runtime-internal resume/cache contract.
+- `docs/ultracode-p3b-resume-cache.md`: local resume/cache contract.
 - `docs/ultracode-p3c-worktree-isolation.md`: worktree isolation contract.

package/dist/cli.js

@@ -10,10 +10,12 @@ 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 { defaultUltracodeStateRoot, resolveUltracodeStatePath } from './runtime/state-root.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';
 const PROGRESS_KIND = 'ultracode.workflow.progress';
+const WORKFLOW_RUN_ID_RE = /^run_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 async function main(argv) {
     const [command = 'help', ...args] = argv;
     if (command === 'help' || command === '--help' || command === '-h') {
@@ -56,13 +58,18 @@ async function runWorkflow(args) {
     }
     const cwd = options.cwd ?? process.cwd();
     const executionMode = parseExecutionMode(options.execution);
-    if (executionMode === 'background')
+    const inputPromise = workflowLaunchInputFromOptions(options);
+    if (executionMode === 'background') {
+        const input = await inputPromise;
+        if (input.resumeFromRunId)
+            await assertBackgroundResumeSource(cwd, input.resumeFromRunId);
         return launchBackgroundWorkflow(args, cwd);
+    }
     const timeoutMs = parseIntOption(options.timeoutMs, workflowDefaultTimeoutMs());
     const retryLimit = parseRetryLimit(options.retryLimit);
     const permissionPolicy = parsePermissionPolicy(options.permission);
     const progressMode = parseProgressMode(options.progress);
-    const input = await workflowLaunchInputFromOptions(options);
+    const input = await inputPromise;
     const backend = new CodexSubagentBackend({
         command: options.command,
         cwd,
@@ -107,6 +114,27 @@ async function runWorkflow(args) {
         await runtime.close();
     }
 }
+async function assertBackgroundResumeSource(cwd, runId) {
+    const runtime = new WorkflowTaskRegistry({
+        backend: RESUME_PREFLIGHT_BACKEND,
+        cwd,
+        requestTimeoutMs: 0,
+    });
+    try {
+        await runtime.validateResumeSource(runId);
+    }
+    finally {
+        await runtime.close();
+    }
+}
+const RESUME_PREFLIGHT_BACKEND = {
+    name: 'resume-preflight',
+    model: 'resume-preflight',
+    async generate() {
+        throw new Error('Resume preflight must not run subagents.');
+    },
+    async close() { },
+};
 export function parseOptions(args) {
     const out = { _: [] };
     for (let i = 0; i < args.length; i += 1) {
@@ -619,10 +647,9 @@ function backgroundProcessIdentityMatches(metadata, commandLine) {
 async function backgroundArchivePath(options, jobId) {
     if (options.outputPath)
         return resolve(options.outputPath);
-    const cwd = options.cwd ?? process.cwd();
     const archiveDir = options.outDir
         ? resolve(options.outDir)
-        : resolve(cwd, '.ultracode-for-codex', 'archive');
+        : join(defaultUltracodeStateRoot(), 'archive');
     return join(archiveDir, `${jobId}.json`);
 }
 async function readBackgroundProgress(progressPath) {
@@ -813,6 +840,9 @@ function delay(ms) {
 }
 function resolveBackgroundRunDir(cwd, template, jobId) {
     const expanded = template.replaceAll('{jobId}', jobId);
+    if (expanded.includes('{stateRoot}') || expanded === '~' || expanded.startsWith('~/')) {
+        return resolveUltracodeStatePath(expanded);
+    }
     return isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
 }
 function assertDistinctBackgroundPaths(paths) {
@@ -832,9 +862,7 @@ async function workflowLaunchInputFromOptions(options) {
     if (options._.length > 1)
         throw new Error('run accepts at most one positional workflow script file.');
     const scriptFile = options.scriptFile ?? positionalScriptFile;
-    if (options.resumeFromRunId) {
-        throw new Error('CLI resume is not available yet; use --retry-limit for same-run retry or rerun the workflow command.');
-    }
+    const hasResumeFromRunId = options.resumeFromRunId !== undefined;
     const sourceSelectors = [
         options.script !== undefined ? '--script' : '',
         scriptFile ? '--script-file' : '',
@@ -844,17 +872,33 @@ async function workflowLaunchInputFromOptions(options) {
     if (sourceSelectors.length > 1) {
         throw new Error(`Choose only one workflow source selector: ${sourceSelectors.join(', ')}.`);
     }
-    if (sourceSelectors.length === 0) {
-        throw new Error('run requires --script, --script-file, --script-path, --name, or a positional script file.');
+    if (hasResumeFromRunId)
+        validateCliResumeFromRunId(options.resumeFromRunId);
+    if (hasResumeFromRunId && sourceSelectors.length > 0) {
+        throw new Error('--resume-from-run-id cannot be combined with --script, --script-file, --script-path, --name, or a positional script file.');
     }
+    if (sourceSelectors.length === 0 && !hasResumeFromRunId) {
+        throw new Error('run requires --script, --script-file, --script-path, --name, --resume-from-run-id, or a positional script file.');
+    }
+    const parsedArgs = await parseArgsPayload(options);
+    const shouldIncludeArgs = options.args !== undefined || options.argsFile !== undefined || !hasResumeFromRunId;
     return {
         ...(options.script !== undefined ? { script: options.script } : {}),
         ...(scriptFile ? { script: await readFile(scriptFile, 'utf8') } : {}),
         ...(options.scriptPath ? { scriptPath: options.scriptPath } : {}),
         ...(options.name ? { name: options.name } : {}),
-        args: await parseArgsPayload(options),
+        ...(hasResumeFromRunId ? { resumeFromRunId: options.resumeFromRunId } : {}),
+        ...(shouldIncludeArgs ? { args: parsedArgs } : {}),
     };
 }
+function validateCliResumeFromRunId(value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error('resumeFromRunId must be a non-empty workflow runId string.');
+    }
+    if (!WORKFLOW_RUN_ID_RE.test(value.trim())) {
+        throw new Error('resumeFromRunId must be a workflow runId in run_<uuid> format.');
+    }
+}
 async function parseArgsPayload(options) {
     if (options.args !== undefined && options.argsFile) {
         throw new Error('Use either --args or --args-file, not both.');
@@ -1426,7 +1470,8 @@ Options:
   --script-file <path>               Workflow script file. A positional file path is also accepted.
   --script-path <path>               Runtime-owned persisted workflow script path.
   --name <name>                      Named workflow from .codex/workflows or built-ins.
-  --args <json>                      Workflow args JSON. Default: {}.
+  --resume-from-run-id <runId>        Resume a completed local workflow run from preserved runtime state.
+  --args <json>                      Workflow args JSON. Default: {}; resume runs inherit prior args when omitted.
   --args-file <path>                 Read workflow args JSON from a file.
   --permission <ask|allow|deny>      Permission review behavior. Default: settings.json (${workflowDefaultPermissionPolicy()}).
   --retry-limit <number>             Retry failed workflows in the same process. Default: settings.json (${workflowDefaultRetryLimit()}).

package/dist/runtime/state-root.d.ts

@@ -0,0 +1,3 @@
+export declare function defaultUltracodeStateRoot(): string;
+export declare function defaultWorkflowStateDir(cwd?: string): string;
+export declare function resolveUltracodeStatePath(value: string): string;

package/dist/runtime/state-root.js

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+const ULTRACODE_HOME_ENV = 'ULTRACODE_FOR_CODEX_HOME';
+export function defaultUltracodeStateRoot() {
+    const configured = process.env[ULTRACODE_HOME_ENV]?.trim();
+    if (configured)
+        return resolveHomePath(configured);
+    return join(homedir(), '.ultracode-for-codex');
+}
+export function defaultWorkflowStateDir(cwd = process.cwd()) {
+    const root = resolve(cwd);
+    const digest = createHash('sha256').update(root).digest('hex').slice(0, 16);
+    const label = safeWorkspaceLabel(basename(root) || 'workspace');
+    return join(defaultUltracodeStateRoot(), 'workspaces', `${label}-${digest}`);
+}
+export function resolveUltracodeStatePath(value) {
+    return resolveHomePath(value.replaceAll('{stateRoot}', defaultUltracodeStateRoot()));
+}
+function resolveHomePath(value) {
+    if (value === '~')
+        return homedir();
+    if (value.startsWith('~/'))
+        return join(homedir(), value.slice(2));
+    return resolve(value);
+}
+function safeWorkspaceLabel(value) {
+    return value.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'workspace';
+}

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

@@ -241,9 +241,12 @@ export declare class WorkflowTaskRegistry implements WorkflowRuntime {
     private readonly agentStallRetryLimit;
     constructor(options: WorkflowTaskRegistryOptions);
     launch(input: WorkflowLaunchInput): Promise<WorkflowLaunchResult>;
+    validateResumeSource(resumeFromRunId: string): Promise<void>;
     private prepareResumePlan;
     private workflowTaskByRunId;
+    private durableWorkflowResumeSource;
     private createResumeCache;
+    private readCompletedResumeJournal;
     private resolveLaunchInput;
     private workflowPermissionRequired;
     private resolveTrustedScriptPathMetadata;