ultracode-for-codex 0.2.5 → 0.3.0

package/README.md

@@ -26,7 +26,7 @@ npm run pack:ultracode-for-codex
 Install the tarball from a target project:
 
 ```bash
-npm install --save-dev /path/to/ultracode-for-codex-0.2.5.tgz
+npm install --save-dev /path/to/ultracode-for-codex-<version>.tgz
 ```
 
 Run a workflow:
@@ -41,6 +41,17 @@ npm exec -- ultracode-for-codex run \
 
 By default this prints a background launch record to stdout. The record contains
 `jobId`, `pid`, `resultPath`, `progressPath`, `metadataPath`, and `pidPath`.
+Use the job id to inspect or control the background run:
+
+```bash
+npm exec -- ultracode-for-codex status <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex wait <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex logs <jobId> --cwd /path/to/target-repo --tail 40
+npm exec -- ultracode-for-codex result <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex cancel <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex jobs --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex archive <jobId> --cwd /path/to/target-repo
+```
 
 Run attached to the current terminal:
 
@@ -84,7 +95,7 @@ Package defaults live in `settings.json`:
     "progress": "jsonl",
     "permission": "ask",
     "retryLimit": 0,
-    "timeoutMs": 900000,
+    "timeoutMs": 0,
     "background": {
       "runDir": ".ultracode-for-codex/background/{jobId}",
       "resultFile": "result.json",
@@ -98,25 +109,51 @@ Package defaults live in `settings.json`:
 
 Use `--execution attached`, `--progress`, `--permission`, `--retry-limit`, and
 `--timeout-ms` to override settings for one run.
-The package default workflow timeout is `900000` ms, or 15 minutes.
+The package default workflow timeout is `0`, meaning the workflow waits until it
+completes, is cancelled, or the Codex app-server exits. Set `--timeout-ms` to a
+positive value to opt into a deadline for one run.
+Use the default background execution for long Codex-launched work so Codex can
+continue other tasks and inspect the job later with `status`, `logs`, or
+`result`. Use
+`--execution attached` only when the caller must block until the final result.
 
 ## CLI Controls
 
+- Use `--version` or `-v` to print the installed package version.
+- Use `status`, `wait`, `logs`, `result`, and `cancel` with a background
+  `jobId` or `metadata.json` path to inspect, wait for, read, or cancel OS
+  background runs.
+- Use `jobs` or `list` to enumerate local background runs.
+- Use `archive` or `export` to write a sensitive local JSON bundle for one run
+  without deleting runtime state.
+- Use `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain`
+  for shorter foreground checks.
 - Progress is printed to stderr as JSONL by default.
 - The final workflow result is printed as JSON to stdout.
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
   agent records also include stable agent identity and label fields.
-- Built-in `task` and `code-review` emit `workflow.plan.ready` before phase
-  agents start, including phase titles and planned agent role labels.
+- Built-in `task` and `code-review` emit `workflow.plan.ready` as a planning
+  snapshot, not a promise that every later phase is already known.
+- `workflow.phase.planned` is emitted immediately before each phase starts and
+  carries that phase's current planned agent role labels. Each
+  `workflow.phase.started` record repeats the same role labels when the phase
+  begins.
+- Each `workflow.agent.completed` record includes phase progress, total known
+  agent progress, and elapsed time.
+- After a completed run, `workflow.summary.ready` reports each phase with its
+  planned agent count and angle/focus list, then `workflow.review.recommended`
+  asks the current session LLM to critically re-check the final result before
+  acting on it.
 - Press `Ctrl-C` once to cancel the active workflow.
 - Use `--retry-limit <n>` to retry failed workflows inside the same process.
-- `--timeout-ms` is the workflow timeout and the default per-agent silence
-  budget; it is not divided by the retry budget.
+- `--timeout-ms 0` waits for completion, cancellation, or app-server exit.
+  Positive values opt into a workflow deadline and per-agent silence budget;
+  that budget is not divided by the retry budget.
 - Use `--permission ask|allow|deny` for project/user/plugin/scriptPath workflow
   permission reviews.
 - Use `--progress plain` for human-readable log lines.
 - Use `--execution background` for OS background runs and `--execution attached`
-  when Codex should read progress until completion.
+  only when the caller should stay connected until completion.
 
 ## Codex Companion Skill
 
@@ -138,8 +175,8 @@ want Codex to auto-load the package boundaries and verification routine.
   planner-selected phase-wise parallel subagents, then synthesize each phase and
   the final result.
 - Workflow execution is local and command-owned; settings default to OS
-  background execution and `--execution attached` keeps the process connected
-  until completion.
+  background execution so long runs can keep waiting while Codex does other
+  work.
 - `.ultracode-for-codex` workflow state is sensitive local data.
 - `journalPath`, `journal.jsonl`, and journal contents stay out of CLI output.
   Local runtime state may still contain runtime-owned
@@ -147,8 +184,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
 
@@ -184,6 +220,12 @@ For supported CI/CD environments, provenance is available as an explicit opt-in:
 npm run publish:npm:provenance
 ```
 
+Optional live smoke against the local Codex CLI:
+
+```bash
+ULTRACODE_LIVE_SMOKE=1 npm run smoke:live
+```
+
 Useful local run:
 
 ```bash

package/ULTRACODE_INSTALL.md

@@ -13,6 +13,15 @@ workflow runs to OS background execution with result and progress files under
 Production surface:
 
 - `ultracode-for-codex run`
+- `ultracode-for-codex status`
+- `ultracode-for-codex wait`
+- `ultracode-for-codex logs`
+- `ultracode-for-codex result`
+- `ultracode-for-codex cancel`
+- `ultracode-for-codex jobs`
+- `ultracode-for-codex list`
+- `ultracode-for-codex archive`
+- `ultracode-for-codex export`
 
 Progress, cancellation, permission review, retry, and final result projection
 are handled inside the CLI process. Progress is JSONL on stderr by
@@ -31,7 +40,7 @@ npm exec -- ultracode-for-codex --llm-guide
 For source-checkout validation, install the generated tarball instead:
 
 ```bash
-npm install --save-dev ./ultracode-for-codex-0.2.5.tgz
+npm install --save-dev ./ultracode-for-codex-<version>.tgz
 ```
 
 Optional Codex companion skill:
@@ -55,8 +64,22 @@ 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 the job later with `status`, `logs`, or `result`. Use
+`--execution attached` only when the caller must block until completion.
+
+Use the background `jobId` from the launch record to inspect or control the run:
+
+```bash
+npm exec -- ultracode-for-codex status <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex wait <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex logs <jobId> --cwd /path/to/project --tail 40
+npm exec -- ultracode-for-codex result <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex cancel <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex jobs --cwd /path/to/project
+npm exec -- ultracode-for-codex archive <jobId> --cwd /path/to/project
+```
 
 Use built-in `task` for general work and `code-review` for review-specific work.
 Both start with an LLM planner, execute phase by phase, run multiple focused
@@ -76,7 +99,7 @@ Settings defaults:
     "progress": "jsonl",
     "permission": "ask",
     "retryLimit": 0,
-    "timeoutMs": 900000,
+    "timeoutMs": 0,
     "background": {
       "runDir": ".ultracode-for-codex/background/{jobId}",
       "resultFile": "result.json",
@@ -90,29 +113,49 @@ Settings defaults:
 
 Useful controls:
 
+- `--version` or `-v` prints the installed package version.
+- `status`, `wait`, `logs`, `result`, and `cancel` accept a background `jobId`
+  or `metadata.json` path.
+- `jobs` and `list` enumerate local background runs.
+- `archive` and `export` write a sensitive local JSON bundle for one run without
+  deleting runtime state.
+- `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain` are
+  available for shorter foreground checks.
 - Progress events are printed to stderr as JSONL by default.
 - The final workflow result is printed as JSON to stdout.
-- The package default workflow timeout is `900000` ms, or 15 minutes.
+- The package default workflow timeout is `0`, meaning the workflow waits until
+  it completes, is cancelled, or the Codex app-server exits.
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
   agent records also include stable agent identity and label fields.
-- Built-in `task` and `code-review` emit `workflow.plan.ready` before phase
-  agents start, including phase titles and planned agent role labels.
+- Built-in `task` and `code-review` emit `workflow.plan.ready` as a planning
+  snapshot, not a promise that every later phase is already known.
+- `workflow.phase.planned` is emitted immediately before each phase starts and
+  carries that phase's current planned agent role labels. Each
+  `workflow.phase.started` record repeats the same role labels when the phase
+  begins.
+- Each `workflow.agent.completed` record includes phase progress, total known
+  agent progress, and elapsed time.
+- After a completed run, `workflow.summary.ready` reports each phase with its
+  planned agent count and angle/focus list, then `workflow.review.recommended`
+  asks the current session LLM to critically re-check the final result before
+  acting on it.
 - Press `Ctrl-C` once to cancel the running workflow.
 - Use `--retry-limit <n>` to retry failed runs in the same process.
-- `--timeout-ms` is the workflow timeout and the default per-agent silence
-  budget; it is not divided by the retry budget.
+- `--timeout-ms 0` waits for completion, cancellation, or app-server exit.
+  Positive values opt into a workflow deadline and per-agent silence budget;
+  that budget is not divided by the retry budget.
 - Use `--permission ask|allow|deny` for project/user/plugin/scriptPath
   workflow permission reviews.
 - Use `--progress plain` for human-readable log lines.
 - Use `--execution background` for OS background runs and `--execution attached`
-  for current-terminal progress streaming.
+  only when the caller should stay connected until completion.
 
 ## Runtime Contract
 
 - Use Codex app-server over stdio as the production backend.
 - Keep workflow execution local and command-owned; settings default to OS
-  background execution and `--execution attached` keeps the process connected
-  until completion.
+  background execution so long runs can keep waiting while Codex does other
+  work.
 - Route progress, cancellation, permission review, retry, and result projection
   through the CLI command.
 - Keep stdout reserved for the final JSON result; stream progress records to
@@ -130,13 +173,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.d.ts

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