ultracode-for-codex 0.2.5 → 0.3.0

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracode-for-codex",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "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/",
@@ -56,6 +58,7 @@
     "publish:dry-run": "npm publish --dry-run --access public",
     "publish:npm": "npm publish --access public",
     "publish:npm:provenance": "npm publish --access public --provenance",
+    "smoke:live": "node scripts/live-smoke-ultracode-for-codex.mjs",
     "test:e2e:ultracode-for-codex": "node scripts/e2e-installed-ultracode-for-codex.mjs",
     "test:all": "npm test && npm run test:e2e:ultracode-for-codex",
     "test": "npm run build && npm run verify:runtime-boundary && node --test --test-concurrency=2 test/*.test.mjs",

package/settings.json

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

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

@@ -13,9 +13,10 @@ binary, tests, package exports, journal layer, and workflow runtime code.
 
 Workflow execution runs through the local CLI command. Progress,
 cancellation, permission review, retry, and result projection stay in that
-command process. `settings.json` defaults runs to OS background execution.
-Attached runs stream stderr JSONL for Codex-readable status, while stdout
-remains the final workflow result JSON.
+command process. `settings.json` defaults runs to OS background execution; use
+that path for long Codex-launched work so Codex can keep doing other tasks and
+inspect the background job later. Attached runs stream stderr JSONL for
+Codex-readable status, while stdout remains the final workflow result JSON.
 
 The default Ultracode work shape is phase-wise parallel execution: built-in
 `task` and `code-review` first call a planner agent, then execute each planned
@@ -44,25 +45,42 @@ For source-checkout validation before publish:
 
 ```bash
 npm run pack:ultracode-for-codex
-npm install --save-dev ./artifacts/ultracode-for-codex-0.2.5.tgz
+npm install --save-dev ./artifacts/ultracode-for-codex-<version>.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`;
+- background jobs can be inspected with `status`, waited with `wait`, read with
+  `logs` and `result`, and cancelled with `cancel`;
+- background jobs can be enumerated with `jobs` or `list`, and exported without
+  deletion with `archive` or `export`;
+- `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain`
+  provide focused foreground checks;
+- attached execution is available with `--execution attached` when the caller
+  should stay connected until completion;
 - attached progress prints to stderr as JSONL by default;
 - attached final workflow result prints as JSON to stdout;
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`,
   with agent identity and label fields on agent records;
-- built-in `task` and `code-review` emit `workflow.plan.ready` before phase
-  agents start, including phase titles and planned agent role labels;
+- built-in `task` and `code-review` emit `workflow.plan.ready` as a planning
+  snapshot, not a promise that every later phase is already known;
+- `workflow.phase.planned` is emitted immediately before each phase starts and
+  carries that phase's current planned agent role labels;
+- each `workflow.phase.started` record repeats the same role labels when the
+  phase begins;
+- each `workflow.agent.completed` record includes phase progress, total known
+  agent progress, and elapsed time;
+- after a completed run, `workflow.summary.ready` reports phase-level agent
+  counts and angles, then `workflow.review.recommended` asks the current
+  session LLM to critically re-check the final result before acting on it;
 - `Ctrl-C` cancels the active attached workflow;
 - `--retry-limit <n>` retries failed workflows inside the same process;
-- `--timeout-ms` is the workflow timeout and the default per-agent silence
-  budget; the package default is `900000` ms, or 15 minutes, and it is not
-  divided by the retry budget.
+- `--timeout-ms 0` waits for completion, cancellation, or app-server exit;
+  positive values opt into a workflow deadline and per-agent silence budget,
+  and that budget is not divided by the retry budget.
 - `--permission ask|allow|deny` handles project/user/plugin/scriptPath reviews.
 - `--progress plain` switches to human-readable progress lines.
 - background file locations are controlled by `workflow.background` in
@@ -77,14 +95,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