ultracode-for-codex 0.3.3 → 0.3.4

package/docs/provenance-audit.md

@@ -1,13 +1,13 @@
 # Provenance Audit
 
-Date: 2026-06-22
+Date: 2026-06-23
 
 ## Scope
 
 This audit checked:
 
 - tracked repository files;
-- generated npm package contents for `ultracode-for-codex@0.3.3`;
+- generated npm package contents for `ultracode-for-codex@0.3.4`;
 - 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`;
-- audited package metadata version is `0.3.3`;
+- audited package metadata version is `0.3.4`;
 - npm publish state is verified separately during release preparation.
 
 ## Evidence

package/docs/ultracode-p3b-resume-cache.md

@@ -1,17 +1,34 @@
 # Ultracode Resume Cache Contract
 
-This is the current same-session resume/cache contract. It builds on
-`docs/ultracode-p3a-journal-design.md`.
+This is the current local resume/cache contract. It builds on
+`docs/ultracode-p3a-journal-design.md` and the durable local workflow state
+under `${ULTRACODE_FOR_CODEX_HOME:-~/.ultracode-for-codex}`.
 
 ## Scope
 
-Resume/cache is runtime-internal and same-session. User-facing recovery uses
-same-run retry or explicit CLI reruns.
+Resume/cache is local and command-owned. Same-process runtime calls may pass
+`resumeFromRunId` directly, and CLI users may pass `--resume-from-run-id` to
+resume a completed run from preserved script, result, and journal state.
 
 ## Rules
 
-- `resumeFromRunId` accepts only workflow `runId` values already known by the
-  current `WorkflowTaskRegistry`.
+- `resumeFromRunId` accepts workflow `runId` values known by the current
+  `WorkflowTaskRegistry` or completed run ids with durable result and journal
+  state under the same workflow state directory.
+- CLI `--resume-from-run-id` reuses the original persisted runtime script and
+  rejects any additional workflow source selector. Without `--args`, it also
+  reuses the original args.
+- Durable result records store the minimal runtime-owned retry input needed for
+  resume. Journal paths and contents remain local state and are not printed in
+  ordinary CLI output.
+- Durable resume requires a matching terminal `workflow.run.completed` journal
+  entry for the selected run id.
+- Durable resume binds the result record's script path and persisted script
+  metadata back to the journal's `workflow.run.started` script path and source
+  identity.
+- Inherited resume args come from the source journal's `workflow.run.started`
+  entry. If the durable result record also stores args, they must match the
+  journal args.
 - Running source runs fail with `workflow_resume_running`.
 - Completed agent prefixes are reused only when the current `agentCallKey`
   matches the source journal prefix.
@@ -31,10 +48,12 @@ values such as label and phase stay outside the cache identity.
 
 ## Verification
 
-- `test/workflow-runtime.test.mjs` covers exact cache hits and retry/cancel
-  interactions.
+- `test/workflow-runtime.test.mjs` covers exact cache hits, retry/cancel
+  interactions, and cross-registry completed-run resume.
 - `test/workflow-journal.test.mjs` validates the journal reader used to derive
   cache entries.
+- `scripts/e2e-installed-ultracode-for-codex.mjs` covers packaged
+  `code-review` resume with cached agent completions.
 
 Realization:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracode-for-codex",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Run Codex-native Ultracode orchestration with an optional local CLI runtime.",
   "keywords": [
     "codex",

package/settings.json

@@ -6,7 +6,7 @@
     "retryLimit": 0,
     "timeoutMs": 0,
     "background": {
-      "runDir": ".ultracode-for-codex/background/{jobId}",
+      "runDir": "{stateRoot}/background/{jobId}",
       "resultFile": "result.json",
       "progressFile": "progress.jsonl",
       "metadataFile": "metadata.json",

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

@@ -56,6 +56,10 @@ CLI behavior:
   deletion with `archive` or `export`;
 - `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain`
   provide focused foreground checks;
+- `--resume-from-run-id <runId>` resumes a completed local workflow from
+  preserved runtime state, rejects additional workflow source selectors, and
+  reuses completed agent results only when the runtime-owned call keys still
+  match;
 - attached execution is available with `--execution attached` when the caller
   should stay connected until completion;
 - attached progress prints to stderr as JSONL by default;
@@ -101,9 +105,12 @@ CLI behavior:
   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.
+- Treat workflow state under `${ULTRACODE_FOR_CODEX_HOME:-~/.ultracode-for-codex}`
+  as sensitive local data. Project-local `.ultracode-for-codex/` is legacy
+  state and should stay ignored if present.
+- `--resume-from-run-id` reads preserved script, result, and completed journal
+  state from the global workflow state root; script path, script source
+  identity, and inherited args must match the completed journal.
 - Use `isolation: "worktree"` only inside a git repo with at least one commit;
   isolated worktrees are intentionally preserved for review, including clean
   worktrees.