@nanobpm/nano-workforce 0.171.9 → 0.171.10

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.171.10](https://github.com/nanobpm/nano-workforce/compare/v0.171.9...v0.171.10) (2026-09-01)
+
+### Bug Fixes
+
+* **service:** emit world-restore SHA under harness-read `sha` key ([#696](https://github.com/nanobpm/nano-workforce/issues/696)) ([9794994](https://github.com/nanobpm/nano-workforce/commit/97949948913087c84f79bf0fcaa283c85a7cab0e)), closes [#324](https://github.com/nanobpm/nano-workforce/issues/324) [#695](https://github.com/nanobpm/nano-workforce/issues/695)
+
 ## [0.171.9](https://github.com/nanobpm/nano-workforce/compare/v0.171.8...v0.171.9) (2026-09-01)
 
 ### Bug Fixes

package/app/contracts.ts

@@ -384,9 +384,9 @@ export const WIRE_CONTRACTS = {
     name: "io.nanobpm.agentTask.repository",
     owner: "app/repoEnvelope.ts",
     semantics:
-      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`, app/repoEnvelope.ts) and the c8ctl worker harness consumes to provision an isolated clone — instead of the agent inheriting the worker's launch dir (issue #684). `ref` is the branch checked out: the PR HEAD branch on the PR-based paths (review-round / fix-ci / rebase), or — on the PRE-PR implementation path (feature.bpmn / plan-fanout's `implement-cell`, issue #684; the delivery-graph runner's agent cells, issue #686) — the BASE branch, off which the harness cuts a new feature branch named by the optional `branch.create` (the deterministic `feat/<task.id>`, emitted only for a single-task feature run; the epic seed AND the delivery-graph run-root seed omit it so each fan-out slice's agent branches per node/MI child). Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `commitSha` — the last durable push-checkpoint — is emitted so a REPLACEMENT activation on a fresh worktree reconstructs the tree to the EXACT pushed SHA (inverting the round's `git push` into `git fetch && git checkout <sha>`), omitted when the PR has no checkpoint yet. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).",
+      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`, app/repoEnvelope.ts) and the c8ctl worker harness consumes to provision an isolated clone — instead of the agent inheriting the worker's launch dir (issue #684). `ref` is the branch checked out: the PR HEAD branch on the PR-based paths (review-round / fix-ci / rebase), or — on the PRE-PR implementation path (feature.bpmn / plan-fanout's `implement-cell`, issue #684; the delivery-graph runner's agent cells, issue #686) — the BASE branch, off which the harness cuts a new feature branch named by the optional `branch.create` (the deterministic `feat/<task.id>`, emitted only for a single-task feature run; the epic seed AND the delivery-graph run-root seed omit it so each fan-out slice's agent branches per node/MI child). Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `sha` — the last durable push-checkpoint — is emitted so a REPLACEMENT activation on a fresh worktree reconstructs the tree to the EXACT pushed SHA (inverting the round's `git push` into `git fetch && git checkout <sha>`), omitted when the PR has no checkpoint yet. The field is named `sha` because that is the field the c8ctl harness's `provisionRepo` reads to drive the checkout — an earlier `commitSha` key was a silent no-op (issue #695). Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).",
     shape:
-      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string, commitSha?: string, branch?: { create: string } }',
+      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string, sha?: string, branch?: { create: string } }',
   },
   "epicSet.submit": {
     category: "wire",

package/app/repoEnvelope.ts

@@ -36,10 +36,12 @@ const AGENT_TASK_NS = "io.nanobpm.agentTask";
  * that base reachable for the diff.
  *
  * World-restore (issue #324, ADR 0062 Slice 4/5): when a PR already has a durable push-checkpoint,
- * `commitSha` is emitted so a REPLACEMENT activation (a fresh worktree after a lease loss)
- * reconstructs the working tree to the EXACT pushed SHA — the inversion of the round's outbound
- * `git push` into an inbound `git fetch && git checkout <sha>` — rather than to a branch tip that may
- * have moved. Omitted (no key) when the PR has no checkpoint yet, so a first activation clones the
+ * the last pushed SHA is emitted under the `sha` key so a REPLACEMENT activation (a fresh worktree
+ * after a lease loss) reconstructs the working tree to the EXACT pushed SHA — the inversion of the
+ * round's outbound `git push` into an inbound `git fetch && git checkout <sha>` — rather than to a
+ * branch tip that may have moved. The key is `sha` (not `commitSha`) because that is the field the
+ * c8ctl worker harness actually reads to drive the checkout; the earlier `commitSha` key was a silent
+ * no-op (issue #695). Omitted (no key) when the PR has no checkpoint yet, so a first activation clones the
  * head branch normally.
  *
  * Pre-PR provisioning (issue #684): the implementation path (feature.bpmn / plan-fanout's
@@ -80,13 +82,16 @@ export function repoEnvelopeVars(
         // single-branch head, keeping `origin/<base>` reachable for the diff. Omitted when unknown.
         ...(baseRef ? { baseRef } : {}),
         // World-restore (issue #324): the last pushed SHA a replacement activation reconstructs the
-        // working tree to (inverting the round's push into a fetch+checkout). Only emitted when it is
-        // a well-formed 40-hex commit SHA: `commitSha` is forwarded to the harness as an EXACT
-        // checkout target, so a non-SHA ref or a whitespace-tainted value could reconstruct to an
-        // unintended ref (a moved branch tip) or fail provisioning. A malformed value degrades to
+        // working tree to (inverting the round's push into a fetch+checkout). Emitted under the key
+        // `sha` — the field the c8ctl worker harness actually reads (`provisionRepo` normalizes
+        // `repo.sha` and drives `git fetch origin <sha>` + `git checkout --detach <sha>` off it); a
+        // prior `commitSha` key was a silent no-op the harness never read (issue #695). Only emitted
+        // when the value is a well-formed 40-hex commit SHA: it is forwarded to the harness as an
+        // EXACT checkout target, so a non-SHA ref or a whitespace-tainted value could reconstruct to
+        // an unintended ref (a moved branch tip) or fail provisioning. A malformed value degrades to
         // omission — the harness then clones the head branch tip, the pre-#324 behaviour. Omitted too
         // when the PR has no durable push-checkpoint yet.
-        ...(isCommitSha(commitSha) ? { commitSha } : {}),
+        ...(isCommitSha(commitSha) ? { sha: commitSha } : {}),
         // Pre-PR provisioning (issue #684): the implementation path (feature.bpmn / plan-fanout's
         // implement-cell) dispatches its agent BEFORE any PR exists, so `ref` is the BASE branch, not a
         // head. `branchCreate` asks the harness to cut the deterministic `feat/<task.id>` feature branch

package/app/service.test.ts

@@ -534,20 +534,24 @@ test("repoEnvelopeVars emits nothing for a malformed repo (not owner/repo)", ()
   }
 });
 
-test("repoEnvelopeVars emits commitSha only for a well-formed 40-hex SHA (world-restore, #324)", () => {
+test("repoEnvelopeVars emits the push-checkpoint under the harness-read `sha` key, only for a well-formed 40-hex SHA (world-restore, #324/#695)", () => {
   const sha = "77ee0993cc6ad4493da0f7551212ef16722135db";
   const env = (repoEnvelopeVars("owner/repo", "feat/x", "main", sha) as any)["io.nanobpm.agentTask"];
-  assertEquals(env.repository.commitSha, sha, "a valid 40-hex SHA is threaded through as the exact checkout target");
-  // A non-SHA ref, an abbreviated SHA, or a whitespace-tainted value is dropped (no `commitSha` key):
-  // it is forwarded to the harness as an EXACT checkout target, so a bad value could reconstruct to a
-  // moved branch tip or fail provisioning. Omission degrades to the pre-#324 head-branch-tip clone.
+  // The emitted key MUST be `sha` — the field the c8ctl harness `provisionRepo` reads to drive
+  // `git fetch origin <sha>` + `git checkout --detach <sha>`. A prior `commitSha` key was a silent
+  // no-op the harness never read (issue #695), so guard the exact wire name here, not just presence.
+  assertEquals(env.repository.sha, sha, "a valid 40-hex SHA is threaded through under the harness-read `sha` key");
+  assertEquals("commitSha" in env.repository, false, "the retired `commitSha` key must never be emitted (silent no-op, #695)");
+  // A non-SHA ref, an abbreviated SHA, or a whitespace-tainted value is dropped (no `sha` key): it is
+  // forwarded to the harness as an EXACT checkout target, so a bad value could reconstruct to a moved
+  // branch tip or fail provisioning. Omission degrades to the pre-#324 head-branch-tip clone.
   for (const bad of ["main", "feat/x", "77ee099", `${sha} `, ` ${sha}`, `${sha}\n`, "z".repeat(40), `${sha}0`, ""]) {
     const r = (repoEnvelopeVars("owner/repo", "feat/x", "main", bad) as any)["io.nanobpm.agentTask"].repository;
-    assertEquals("commitSha" in r, false, `expected no commitSha for "${JSON.stringify(bad)}"`);
+    assertEquals("sha" in r, false, `expected no sha for "${JSON.stringify(bad)}"`);
   }
   // Omitted entirely when there is no checkpoint SHA at all (the common first-activation case).
   const none = (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"].repository;
-  assertEquals("commitSha" in none, false);
+  assertEquals("sha" in none, false);
 });
 
 // Pre-PR provisioning (issue #684): the implementation path has no head branch yet, so it passes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.171.9",
+  "version": "0.171.10",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",