@nanobpm/nano-workforce 0.171.11 → 0.172.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.172.1](https://github.com/nanobpm/nano-workforce/compare/v0.172.0...v0.172.1) (2026-09-01)
+
+### Bug Fixes
+
+* **onboarding:** send full ProjectConfig on env write (install.sh Phase 2 HTTP 422) ([#693](https://github.com/nanobpm/nano-workforce/issues/693)) ([cea5a13](https://github.com/nanobpm/nano-workforce/commit/cea5a133fe2e53299432e8f61b81c8eadbf9f1ed)), closes [nanobpm/nano-workforce#692](https://github.com/nanobpm/nano-workforce/issues/692) [#692](https://github.com/nanobpm/nano-workforce/issues/692)
+
+## [0.172.0](https://github.com/nanobpm/nano-workforce/compare/v0.171.11...v0.172.0) (2026-09-01)
+
+### Features
+
+* **service:** emit repository.cloneTimeoutMs in the agent-task envelope ([#697](https://github.com/nanobpm/nano-workforce/issues/697)) ([0d8a358](https://github.com/nanobpm/nano-workforce/commit/0d8a3582769f6561d647563168a8a50d0d54f3df)), closes [#694](https://github.com/nanobpm/nano-workforce/issues/694)
+
 ## [0.171.11](https://github.com/nanobpm/nano-workforce/compare/v0.171.10...v0.171.11) (2026-09-01)
 
 ### Bug Fixes

package/app/contracts.ts

@@ -96,6 +96,14 @@ export const ENV_CONTRACTS = {
     semantics: "Poller cadence in milliseconds for the self-scheduling reconciliation loop.",
     default: "60000",
   },
+  NANO_PR_CLONE_TIMEOUT_MS: {
+    category: "env",
+    name: "NANO_PR_CLONE_TIMEOUT_MS",
+    owner: "app/repoEnvelope.ts",
+    semantics:
+      "Clone timeout in milliseconds emitted as `repository.cloneTimeoutMs` in the agent-task envelope so the c8ctl harness raises its 120s default for large-repo provisioning (branch-scoped blobless clones of big monorepos still approach/exceed 120s; issue #694). Inherited by both the review-round and merge paths via the one `repoEnvelopeVars` builder.",
+    default: "600000",
+  },
   NANO_PR_MAX_ROUNDS: {
     category: "env",
     name: "NANO_PR_MAX_ROUNDS",
@@ -384,9 +392,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 `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).",
+      "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) and a `cloneTimeoutMs` (from `NANO_PR_CLONE_TIMEOUT_MS`, default 600000 = 10 min) that raises the harness's 120s default so a large monorepo's blobless single-branch clone provisions instead of dying at 120s (issue #694). 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, sha?: string, branch?: { create: string } }',
+      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", cloneTimeoutMs: number, baseRef?: string, sha?: string, branch?: { create: string } }',
   },
   "epicSet.submit": {
     category: "wire",

package/app/repoEnvelope.ts

@@ -8,6 +8,7 @@
 // rebase) and the PRE-PR implementation dispatch (`feature.ts`: `startFeature`; `plan.ts`:
 // `startPlan` → the epic's `implement-cell`) derive from this single implementation without a
 // `plan.ts ↔ service.ts` import cycle (AGENTS.md "derivation over duplication — no drift surfaces").
+import { readEnvOr } from "./contracts.ts";
 import { isCommitSha } from "./world/index.ts";
 
 /** The reserved namespace key the c8ctl nano worker harness reads the agent-task envelope from
@@ -78,6 +79,13 @@ export function repoEnvelopeVars(
         // has a valid merge-base. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).
         singleBranch: true,
         filter: "blob:none",
+        // Raise the harness's 120s default clone timeout for large-repo provisioning (issue #694).
+        // A branch-scoped blobless clone of a 24.6k-file monorepo (`camunda/camunda`) still
+        // approaches/exceeds 120s, so we emit `cloneTimeoutMs` (default 600000 = 10 min, via the
+        // `NANO_PR_CLONE_TIMEOUT_MS` knob) rather than let the harness fall back to its 120000ms
+        // default. Emitted on ALL paths from this one builder, so BOTH the review-round path
+        // (`service.ts` `submitPr`) and the merge path (`service.ts` `startMerge`) inherit it.
+        cloneTimeoutMs: cloneTimeoutMs(),
         // The base branch this PR targets — emitted so the harness fetches its tip alongside the
         // single-branch head, keeping `origin/<base>` reachable for the diff. Omitted when unknown.
         ...(baseRef ? { baseRef } : {}),
@@ -105,3 +113,16 @@ export function repoEnvelopeVars(
     },
   };
 }
+
+/** Resolve the clone timeout (ms) the harness applies to provisioning, from the one typed knob
+ * `NANO_PR_CLONE_TIMEOUT_MS` (default 600000 = 10 min; issue #694). A branch-scoped blobless clone
+ * of a large monorepo still approaches/exceeds the harness's 120s default, so we raise it here. A
+ * non-numeric or non-positive override degrades to the registered default rather than emitting a
+ * bogus (0 / NaN) timeout the harness would then treat as "use the 120s default". */
+function cloneTimeoutMs(): number {
+  const raw = Number(readEnvOr("NANO_PR_CLONE_TIMEOUT_MS"));
+  return Number.isFinite(raw) && raw > 0 ? raw : Number(envDefaultCloneTimeoutMs);
+}
+
+/** The registered default, resolved once from the schema so the fallback stays single-sourced. */
+const envDefaultCloneTimeoutMs = readEnvOr("NANO_PR_CLONE_TIMEOUT_MS", "600000", {});

package/app/service.test.ts

@@ -483,6 +483,38 @@ test("repoEnvelopeVars emits the repository envelope keyed on the PR head branch
   assertEquals(env.repository.filter, "blob:none");
   // The base branch is emitted so the harness fetches its tip, keeping `origin/<base>` reachable.
   assertEquals(env.repository.baseRef, "main");
+  // The clone timeout is raised above the harness's 120s default for large-repo provisioning (#694).
+  assertEquals(env.repository.cloneTimeoutMs, 600000);
+});
+
+test("repoEnvelopeVars emits cloneTimeoutMs from NANO_PR_CLONE_TIMEOUT_MS, default 600000 (#694)", () => {
+  // Default (knob unset): 600000ms = 10 min, raising the harness's 120000ms default so a
+  // branch-scoped blobless clone of a large monorepo provisions instead of dying at 120s.
+  const prev = process.env.NANO_PR_CLONE_TIMEOUT_MS;
+  delete process.env.NANO_PR_CLONE_TIMEOUT_MS;
+  try {
+    const def = (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"];
+    assertEquals(def.repository.cloneTimeoutMs, 600000);
+    // Override wins.
+    process.env.NANO_PR_CLONE_TIMEOUT_MS = "900000";
+    const over = (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"];
+    assertEquals(over.repository.cloneTimeoutMs, 900000);
+    // A non-positive / non-numeric override degrades to the registered default rather than emitting
+    // a bogus 0/NaN the harness would treat as "use the 120s default".
+    process.env.NANO_PR_CLONE_TIMEOUT_MS = "0";
+    assertEquals(
+      ((repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"]).repository.cloneTimeoutMs,
+      600000,
+    );
+    process.env.NANO_PR_CLONE_TIMEOUT_MS = "notanumber";
+    assertEquals(
+      ((repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"]).repository.cloneTimeoutMs,
+      600000,
+    );
+  } finally {
+    if (prev === undefined) delete process.env.NANO_PR_CLONE_TIMEOUT_MS;
+    else process.env.NANO_PR_CLONE_TIMEOUT_MS = prev;
+  }
 });
 
 test("repoEnvelopeVars omits baseRef when the base branch is unresolved", () => {
@@ -492,6 +524,8 @@ test("repoEnvelopeVars omits baseRef when the base branch is unresolved", () =>
   assertEquals(env.repository.filter, "blob:none");
   // …but `baseRef` is omitted entirely rather than emitted as null (no key at all).
   assertEquals("baseRef" in env.repository, false);
+  // The clone timeout is still emitted (it's base-ref-independent).
+  assertEquals(env.repository.cloneTimeoutMs, 600000);
 });
 
 test("repoEnvelopeVars emits nothing when the head branch is unresolved", () => {

package/install.sh

@@ -1124,6 +1124,25 @@ build_config_body() { # $1 = redact? ("redact" to mask the token)
     "$_gh" "$(json_str "$CONSOLE_ORIGIN")" "$(json_str "$APPVIEW_BASE")" "$(json_str "${PR_REVIEW_PORT:-3000}")"
 }
 
+# Merge our env object into the project's FULL ProjectConfig and print the
+# merged object. `PUT /console/api/projects/<name>/config` is a whole-object
+# replace: it deserializes the body into the complete ProjectConfig (which
+# requires `name`, `main`, `platforms`, `lang`, …), so a partial {"env":{…}}
+# body fails with HTTP 422 "missing field name" (nanobpm/nano-workforce#692).
+# We therefore fetch the live config and set its `.env` instead of hand-building
+# a minimal body. Values are passed via the environment (not argv) so quoting is
+# never an issue; node is a hard preflight requirement so it is always present.
+# Prints the merged JSON on success; returns non-zero (empty stdout) if either
+# input is not parseable.
+merge_config_env() { # $1 = current ProjectConfig JSON, $2 = {"env":{…}} JSON
+  NWF_CFG_JSON=$1 NWF_ENV_JSON=$2 node -e '
+    const cfg = JSON.parse(process.env.NWF_CFG_JSON);
+    const env = JSON.parse(process.env.NWF_ENV_JSON).env || {};
+    cfg.env = env;
+    process.stdout.write(JSON.stringify(cfg));
+  ' 2>/dev/null
+}
+
 # Step 9 — the console must be reachable before we mutate anything.
 app_preflight() {
   info "Preflighting the console at ${CONSOLE_ORIGIN}/console"
@@ -1245,18 +1264,39 @@ app_provision() {
     esac
   fi
 
-  # 11.5 — write ProjectConfig.env (token redacted in dry-run output).
+  # 11.5 — write ProjectConfig.env (token redacted in dry-run output). The
+  # config endpoint is a whole-object replace, so we GET the current config and
+  # merge our env into it; a partial {"env":{…}} body 422s (#692).
   info "Configuring project '$PROJECT' (ProjectConfig.env)"
-  _cfg_body=$(build_config_body) || {
+  _env_body=$(build_config_body) || {
     record_failure "app: invalid ProjectConfig.env value (control characters)"
     return 1
   }
-  _cfg_show=$(build_config_body redact) || {
+  _env_show=$(build_config_body redact) || {
     record_failure "app: invalid ProjectConfig.env value (control characters)"
     return 1
   }
-  api PUT "/console/api/projects/${PROJECT}/config" "$_cfg_body" "$_cfg_show"
-  if [ "$DRY_RUN" -eq 0 ]; then
+  if [ "$DRY_RUN" -eq 1 ]; then
+    # No live config to fetch under --dry-run: show the env we would merge in.
+    api PUT "/console/api/projects/${PROJECT}/config" "$_env_body" "$_env_show"
+  else
+    api GET "/console/api/projects/${PROJECT}/config"
+    case "$API_STATUS" in
+      2*) : ;;
+      *)  err "GET project config -> $(api_outcome)"
+          [ -n "$API_BODY" ] && note "$API_BODY"
+          record_failure "app: GET config $(api_outcome)"
+          return 1 ;;
+    esac
+    _cur_cfg=$API_BODY
+    _cfg_body=$(merge_config_env "$_cur_cfg" "$_env_body") || {
+      err "could not merge env into the current ProjectConfig (unparseable config?)."
+      [ -n "$_cur_cfg" ] && note "$_cur_cfg"
+      record_failure "app: merge ProjectConfig.env"
+      return 1
+    }
+    _cfg_show=$(merge_config_env "$_cur_cfg" "$_env_show") || _cfg_show=$_cfg_body
+    api PUT "/console/api/projects/${PROJECT}/config" "$_cfg_body" "$_cfg_show"
     case "$API_STATUS" in
       2*) ok "config written (NANO_WORKFORCE_BASE_URL=${APPVIEW_BASE})" ;;
       *)  err "PUT project config -> $(api_outcome)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.171.11",
+  "version": "0.172.1",
   "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",

package/test/install-smoke.sh

@@ -302,6 +302,13 @@ const srv = http.createServer((req, res) => {
     if (m === 'POST' && url === '/console/api/extensions/install') return json(201, { id: 'nano-workforce' });
     if (m === 'POST' && url === '/console/api/projects') return mode === 'exists' ? json(409, { error: 'exists' }) : json(201, { name: 'Workforce' });
     if (m === 'PUT' && url === '/console/api/projects/Workforce/config') return json(200, { ok: true });
+    if (m === 'GET' && url === '/console/api/projects/Workforce/config') {
+      // The whole-object ProjectConfig install.sh fetches before merging `.env`
+      // and PUTting it back (nanobpm/nano-workforce#692). Must carry the required
+      // top-level fields (name, main, platforms, lang) so merge_config_env has a
+      // full object to set `.env` on.
+      return json(200, { name: 'Workforce', main: 'nano-workforce', platforms: ['console'], lang: 'ts', env: {} });
+    }
     if (m === 'POST' && url === '/console/api/projects/Workforce/run') { ran = true; return json(200, { state: 'running' }); }
     if (m === 'GET' && url === '/console/app-view/Workforce/app/api/version') {
       if (mode === 'timeout') return json(404, {});