c8ctl-plugin-nano 1.10.1 → 1.12.0

package/README.md

@@ -23,7 +23,8 @@ platform so there is nothing to compile.
 It adds a single `nano` command:
 
 ```bash
-c8ctl nano start|status|stop|restart|logs|clean|set|config
+c8ctl nano start|status|stop|restart|logs|pause|resume|clean|set|config|update
+c8ctl nano hire|work   # turn a CLI agent harness into a Nano job worker
 ```
 
 `nano start N` spawns **N** nanobpmn node processes wired to talk to each other
@@ -220,7 +221,48 @@ them into a nested object and coerces `"true"/"false"` → bool and numeric
 strings → int. The normalized shape is
 `{ schemaVersion, repository{provider,url,ref,depth,submodules,authRef}, branch{base,create,push}, setup{commands,env,secretRefs}, task{prompt,promptFile,maxIterations,timeoutMs,allowPr,prBase} }`.
 On completion the plugin writes an **output envelope** back under
-`io.nanobpm.agentResult` (`{schemaVersion, status, sandbox, image, output, truncated, stderrTruncated, exitCode, signal, error}`).
+`io.nanobpm.agentResult` (`{schemaVersion, status, sandbox, image, output, truncated, stderrTruncated, exitCode, signal, error}`). When a repository was
+provisioned (below) it also carries `{repository, branch, baseSha, headSha, commits[], pushed, pushError?, gitError?, pr?}`.
+
+**Git provisioning (host).** When `--sandbox none` (the default) and the envelope
+carries a `repository.url`, the plugin provisions a workspace on the host around
+the harness:
+
+1. resolve the optional repo credential (`repository.authRef`, or `GITHUB_TOKEN`
+   for GitHub) — absent ⇒ anonymous clone;
+2. `git clone` (honouring `depth`/`submodules`, and `repository.ref`/`branch.base`
+   as the checkout target) into a throwaway workspace under
+   `<state>/agent-runs/run-*`;
+3. create `branch.create` (if set) off that target;
+4. run the harness **in the workspace** (`cwd`), with `AGENT_WORKSPACE`,
+   `AGENT_REPO_URL`, `AGENT_REPO_BRANCH`, `AGENT_REPO_REF` exported and the job
+   envelope on stdin;
+5. on success, enumerate new commits, `git push` the branch when `branch.push`
+   (default true), and — when `task.allowPr` — **reconcile the PR the agent
+   opened** for the branch (`gh pr list --head <branch>`; `openedBy` reports the
+   PR's actual author login, or `null` when none is found).
+
+The token is delivered to git via `GIT_ASKPASS` (env), never on argv or in the
+remote URL, and is redacted from all logs/results. Credential helpers are
+**always** disabled for the clone/fetch/push (`-c credential.helper=`), even when
+a token is present, so a helper like `store`/keychain can never persist the
+job's token to disk — `GIT_ASKPASS` supplies the secret directly. When **no**
+token is resolved the clone is *additionally* anonymous **for HTTPS remotes**:
+inherited `GIT_ASKPASS`/`SSH_ASKPASS` are cleared, and the operator's global git
+config is neutralized (`GIT_CONFIG_GLOBAL` → the platform null device,
+`/dev/null` or `NUL` on Windows) so knobs like `http.*.extraHeader`
+or `url.*.insteadOf` can't silently inject operator credentials. (An **SSH**
+remote — `git@…`/`ssh://…` — can still authenticate via the host's SSH
+agent/config; use HTTPS URLs if you need a guaranteed-anonymous clone.)
+Token-backed jobs keep global config (e.g. `http.proxy`). A push failure is
+reported as `pushError` (the job still completes) so a later BPMN step can drive
+the merge; a clone/checkout failure sheds the job (retryable). Workspaces are
+deleted after each job (keep them with `--keep-runs`).
+
+```bash
+# The harness sees a cloned repo at $AGENT_WORKSPACE; branch/push/PR are handled for it.
+c8ctl nano work coder            # sandbox=none: repository-bearing jobs are provisioned on the host
+```
 
 **Sandbox.** By default the command runs on the host (`--sandbox none`). Pass
 `--sandbox docker` (or `podman`) with an `--image` to run **each job in a
@@ -236,7 +278,16 @@ c8ctl nano work coder --sandbox docker --image ghcr.io/acme/agent:1   # or overr
 Containers are labelled (`nano.managed=1`, `nano.worker`, `nano.jobKey`,
 `nano.run=<uuid>`), log-capped (`max-size=10m max-file=3`), run with `--rm`, and
 a run that outlives `--job-timeout` is force-removed. The envelope is piped on
-the container's stdin exactly as on the host.
+the container's stdin exactly as on the host. (Container-side git provisioning —
+strong isolation — is a later increment; container jobs don't clone yet.)
+
+**Host workers inherit your credentials.** A host worker (`--sandbox none`, the
+default) runs as your user and inherits your full environment and `$HOME`, so
+your existing `gh` CLI login (from `gh auth login`) or a `GH_TOKEN`/`GITHUB_TOKEN`
+env var is available to the harness with **no extra setup** — handy when the
+agent command shells out to `gh`. A **container** sandbox is isolated and does
+**not** inherit that host login; provide the token explicitly via
+`setup.secretRefs` / `--secret-resolver host` (see **Secrets** below) instead.
 
 **Secrets.** Secrets are referenced by **name**, never value. `setup.secretRefs`
 (and the repo/PR credential when `task.allowPr` is set — defaulting to
@@ -245,8 +296,29 @@ the container's stdin exactly as on the host.
 container by name (`-e NAME`) so values never appear in argv or `docker inspect`.
 A missing required secret fails the job with a clear provisioning message.
 
-**Disk hygiene.** Container sandboxes get automatic cleanup so leaked
-containers can't fill the disk: a **label-scoped** reaper runs at worker startup
+**Harness env (non-secret).** A harness often needs static startup configuration
+— e.g. a permission toggle to start a coding CLI with its tools enabled. Persist
+these on the profile at hire time and/or add them at work time (repeatable
+`--env NAME=VALUE`); work-time values extend/override the profile's:
+
+```bash
+c8ctl nano hire --name coder --rank senior --command copilot --env COPILOT_ENABLE_ALL_TOOLS=1
+c8ctl nano work coder --env EXTRA_FLAG=on          # extends/overrides the profile env
+```
+
+Interactive `hire` (no `--env`) prompts for these one `NAME=VALUE` at a time
+(blank to finish), so values may safely contain `=` or `,`.
+
+They apply on both the host and container paths. Per-job `setup.env` from the
+envelope layers on top (job-specific tuning wins), and the reserved `AGENT_*`
+variables and resolved secrets always win over user-supplied env so they can't be
+shadowed. For **secret** values use `secretRefs`, not `--env`.
+
+**Disk hygiene.** Host job **workspaces** and container sandboxes both get
+automatic cleanup so leaked artifacts can't fill the disk. Workspaces under
+`<state>/agent-runs` are removed after each job and swept at startup + on
+`--reap-interval` (leftovers older than `--reap-age`, in-flight dirs skipped).
+For container sandboxes a **label-scoped** reaper runs at worker startup
 and on an interval (`--reap-interval`, **milliseconds**, default `300000` = 5m),
 removing finished/`exited` containers older than `--reap-age` (**milliseconds**,
 default `3600000` = 1h) while **skipping any run still in flight** — it never
@@ -254,9 +326,9 @@ touches containers it didn't create and never `system prune`s. A **disk-budget
 admission shed** fails (retryable) new jobs when the engine data root has less
 than `--min-free-mb` MB free (default `1024`).
 
-> Git provisioning (clone/branch/push), agent-opened PRs, and the
-> Vercel/Sandcastle provider are **increment 2** — the envelope names above are
-> frozen so the [nano-ide element-template pack](https://github.com/jwulf/nano-ide/issues/37)
+> Container-side git provisioning (strong isolation) and the
+> Vercel/Sandcastle provider are **later increments** — the envelope names above
+> are frozen so the [nano-ide element-template pack](https://github.com/jwulf/nano-ide/issues/37)
 > can be built against this contract.
 
 ## Cleaning up disk

package/c8ctl-plugin.js

@@ -41,10 +41,12 @@ import {
   renameSync,
   realpathSync,
   statfsSync,
+  lstatSync,
+  mkdtempSync,
 } from 'node:fs';
 import { randomUUID } from 'node:crypto';
-import { homedir, platform as osPlatform } from 'node:os';
-import { join, isAbsolute, resolve as resolvePath, dirname, sep } from 'node:path';
+import { homedir, platform as osPlatform, devNull } from 'node:os';
+import { join, isAbsolute, resolve as resolvePath, dirname, basename, sep } from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline/promises';
@@ -1316,6 +1318,41 @@ function normalizeCapabilities(input) {
   return [...new Set(raw.map((c) => String(c).trim().toLowerCase()).filter(Boolean))].sort();
 }
 
+// A conventional (POSIX-ish) environment variable name.
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// Normalize a stored/model env map into a clean { NAME: "value" } object:
+// drops entries with an invalid name, coerces values to strings. Used for the
+// profile's static env and the per-job envelope's setup.env.
+function normalizeEnvMap(input) {
+  const out = {};
+  if (!isPlainObject(input)) return out;
+  for (const [k, v] of Object.entries(input)) {
+    if (!ENV_NAME_RE.test(k)) continue;
+    if (v == null) continue;
+    out[k] = String(v);
+  }
+  return out;
+}
+
+// Parse repeatable `--env NAME=VALUE` CLI input (string | string[]) into a map.
+// The value may contain `=`; only the first `=` splits. Returns { env, errors }.
+function parseEnvPairs(input) {
+  const list = input == null ? [] : (Array.isArray(input) ? input : [input]);
+  const env = {};
+  const errors = [];
+  for (const item of list) {
+    const s = String(item);
+    const eq = s.indexOf('=');
+    // Never echo the value in diagnostics — a user may pass a secret via --env.
+    if (eq <= 0) { errors.push(`--env entry ${eq === 0 ? 'has an empty name' : 'must be NAME=VALUE'} (value hidden)`); continue; }
+    const name = s.slice(0, eq);
+    if (!ENV_NAME_RE.test(name)) { errors.push(`--env name "${name}" is invalid (must match ${ENV_NAME_RE.source})`); continue; }
+    env[name] = s.slice(eq + 1);
+  }
+  return { env, errors };
+}
+
 /** A profile name must be a safe, filesystem/token-friendly slug. */
 function isValidProfileName(name) {
   return typeof name === 'string' && /^[a-z0-9][a-z0-9._-]*$/i.test(name);
@@ -1388,6 +1425,7 @@ function normalizeStoredProfile(name, profile) {
       capabilities: normalizeCapabilities(profile.capabilities),
       sandbox,
       image,
+      env: normalizeEnvMap(profile.env),
     },
   };
 }
@@ -1427,8 +1465,19 @@ async function hireWorker(req, flags) {
   let capabilities = flags?.capabilities !== undefined ? flags.capabilities : undefined;
   let sandbox = flags?.sandbox !== undefined ? String(flags.sandbox).trim().toLowerCase() : undefined;
   let image = flags?.image !== undefined ? String(flags.image).trim() : undefined;
+  const envFromFlags = flags?.env !== undefined;
+  const { env: profileEnv, errors: envErrors } = parseEnvPairs(flags?.env);
+  if (envErrors.length > 0) {
+    logger.error(envErrors.join('; '));
+    logger.info('Example: c8ctl nano hire --name coder --rank senior --command copilot --env COPILOT_ENABLE_ALL_TOOLS=1 --env FOO=bar');
+    process.exit(1);
+  }
 
   const missingRequired = !name || !rank || !command;
+  // NOTE: --env is deliberately NOT part of missingOptional — a fully-specified
+  // scripted hire must not be forced into interactive mode just to skip env.
+  // The env prompt below is gated separately on !envFromFlags, so it only runs
+  // when we're already interactive for another reason.
   const missingOptional = model === undefined || capabilities === undefined;
   const interactive = process.stdin.isTTY && process.stdout.isTTY;
 
@@ -1467,6 +1516,19 @@ async function hireWorker(req, flags) {
       if (capabilities === undefined) {
         capabilities = (await rl.question('Capabilities (comma-separated, optional): ')).trim();
       }
+      // Static harness env (permission toggles, etc.). Prompted one NAME=VALUE at
+      // a time — blank finishes — so values may safely contain '=' and ','.
+      // Skipped when --env was supplied on the command line.
+      if (!envFromFlags) {
+        console.log('Harness env vars — NAME=VALUE, blank to finish (optional):');
+        for (;;) {
+          const ans = (await rl.question('  env (NAME=VALUE): ')).trim();
+          if (!ans) break;
+          const { env: one, errors } = parseEnvPairs([ans]);
+          if (errors.length > 0) { console.log(`  ${errors.join('; ')}`); continue; }
+          Object.assign(profileEnv, one);
+        }
+      }
     } finally {
       rl.close();
     }
@@ -1509,6 +1571,7 @@ async function hireWorker(req, flags) {
     capabilities: normalizeCapabilities(capabilities),
     sandbox,
     image: image || '',
+    env: profileEnv,
     createdAt: new Date().toISOString(),
   };
   writeHire(profile);
@@ -1518,6 +1581,8 @@ async function hireWorker(req, flags) {
   logger.info(`  model: ${profile.model || '(none)'}`);
   logger.info(`  capabilities: ${profile.capabilities.join(', ') || '(none)'}`);
   logger.info(`  sandbox: ${profile.sandbox}${CONTAINER_SANDBOXES.has(profile.sandbox) ? ` (image ${profile.image})` : ''}`);
+  const envKeys = Object.keys(profile.env);
+  if (envKeys.length > 0) logger.info(`  env: ${envKeys.join(', ')}`);
   logger.info(`  job types (${matrix.length}): ${matrix.join('  ')}`);
   logger.info(`Put it to work with: c8ctl nano work ${name}`);
 }
@@ -1574,6 +1639,95 @@ const TASK_ENVELOPE_SCHEMA_VERSION = 1;
 // The result-envelope version is intentionally independent of the task-envelope
 // version so the two contracts can evolve separately without silently coupling.
 const RESULT_ENVELOPE_SCHEMA_VERSION = 1;
+
+// Structured result channel (agent → harness). A coding CLI streams a lot of
+// noisy prose/tool output on stdout, so scraping it for the job's structured
+// result is fragile. Instead the harness hands the agent a private file path in
+// `AGENT_RESULT_FILE`; the agent writes a JSON object of *job result variables*
+// there (e.g. `{ "status": "needs_input", "question": "…" }`). The harness reads
+// it after the run and merges those variables into the job's completion, so the
+// model sees them as first-class outputs. A `::nano:result:: {json}` stdout
+// sentinel (or a trailing ```json fence) is honoured as a fallback for agents
+// that cannot write the file. The harness stays app-agnostic: it merges whatever
+// object the agent returns; the *app's prompt* owns the field vocabulary.
+const AGENT_RESULT_FILE_ENV = 'AGENT_RESULT_FILE';
+const RESULT_SENTINEL = '::nano:result::';
+// Completion keys the harness owns — an agent's returned result can never
+// overwrite these (nor anything in the reserved `io.nanobpm.*` namespace), so a
+// stray `output`/`exitCode`/git field in the agent's JSON can't corrupt the
+// audit envelope or process bookkeeping.
+const RESERVED_RESULT_KEYS = new Set([
+  AGENT_RESULT_KEY, 'output', 'exitCode', 'agent', 'truncated',
+  'branch', 'commits', 'pushed', 'pullRequest',
+]);
+
+// Parse `text` as a JSON object, returning it only when it is a plain object.
+// Never throws — malformed agent output degrades to `null`.
+function parseAgentResultObject(text) {
+  if (typeof text !== 'string' || !text.trim()) return null;
+  try {
+    const v = JSON.parse(text);
+    return isPlainObject(v) ? v : null;
+  } catch { return null; }
+}
+
+// Read + parse the agent's result file, if it wrote one. Best-effort; a missing
+// or malformed file is treated as "no structured result". The file is
+// agent-controlled, so guard against a symlink or an oversized payload (DoS):
+// only a regular file no larger than the cap is read. A well-formed result is a
+// tiny JSON object, so the cap is generous.
+const MAX_RESULT_FILE_BYTES = 1_048_576; // 1 MiB
+function readAgentResultFile(path) {
+  if (!path) return null;
+  try {
+    const st = lstatSync(path); // lstat: never follow a symlink the agent planted
+    if (!st.isFile() || st.size > MAX_RESULT_FILE_BYTES) return null;
+    return parseAgentResultObject(readFileSync(path, 'utf8'));
+  } catch { return null; }
+}
+
+// Fallback extraction from stdout, robust to the surrounding transcript: prefer
+// the LAST `::nano:result:: {json}` sentinel line (cheapest + most explicit),
+// else the LAST ```json fenced block. "Last wins" so a re-stated result
+// supersedes an earlier draft.
+function parseResultFromStdout(stdout) {
+  if (typeof stdout !== 'string' || !stdout) return null;
+  const lines = stdout.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const idx = lines[i].indexOf(RESULT_SENTINEL);
+    if (idx === -1) continue;
+    const obj = parseAgentResultObject(lines[i].slice(idx + RESULT_SENTINEL.length).trim());
+    if (obj) return obj;
+  }
+  // Match the opening fence tolerantly (optional language tag, CRLF or LF) so a
+  // Windows agent's `\r\n` output still parses.
+  const fences = [...stdout.matchAll(/```[^\n]*\r?\n([\s\S]*?)```/g)];
+  for (let i = fences.length - 1; i >= 0; i--) {
+    const obj = parseAgentResultObject(fences[i][1].trim());
+    if (obj) return obj;
+  }
+  return null;
+}
+
+// The domain result variables an agent may return: the parsed object with the
+// harness-reserved keys (and the `io.nanobpm.*` namespace) stripped, so it can
+// never clobber the audit envelope, transcript, or git facts. The agent's output
+// is untrusted, so build the result on a null-prototype object and drop the
+// prototype-pollution keys — a merged `__proto__`/`constructor`/`prototype`
+// must never mutate object prototypes when spread into the job completion.
+const PROTO_POLLUTION_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function sanitizeResultVars(obj) {
+  if (!isPlainObject(obj)) return {};
+  const out = Object.create(null);
+  for (const [k, v] of Object.entries(obj)) {
+    if (RESERVED_RESULT_KEYS.has(k)) continue;
+    if (PROTO_POLLUTION_KEYS.has(k)) continue;
+    if (k.startsWith('io.nanobpm.')) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
 const SANDBOXES = ['none', 'docker', 'podman'];
 // Only container-based sandboxes need an image / disk hygiene / a runtime bin.
 const CONTAINER_SANDBOXES = new Set(['docker', 'podman']);
@@ -1657,7 +1811,7 @@ function normalizeTaskEnvelope(customHeaders, variables) {
   const repo = raw.repository;
   if (isPlainObject(repo) && str(repo.url)) {
     env.repository = {
-      provider: str(repo.provider) || 'github',
+      provider: (str(repo.provider) || 'github').toLowerCase(),
       url: str(repo.url),
       ref: str(repo.ref),
       depth: coerceInt(repo.depth, undefined),
@@ -1800,13 +1954,271 @@ function reapAgentContainers(engine, { maxAgeMs = 0, liveRunIds = new Set() } =
   return { reaped };
 }
 
+// ---- Git provisioning (issue #8, increment 2a — host harness) --------------
+// A repository-bearing task is provisioned on the HOST: clone into a throwaway
+// run dir, check out / create the working branch, run the harness with the
+// workspace as CWD, then push the branch + reconcile the agent-opened PR.
+// Container-side provisioning (strong isolation) is a later increment.
+
+function agentRunsRoot() {
+  return join(getStateHome(), 'agent-runs');
+}
+
+// Redact a token that may have been embedded in a URL or surfaced in git output,
+// plus any https userinfo (x-access-token:secret@host), before it hits a log or
+// the result envelope.
+function redactToken(text, token) {
+  let s = String(text ?? '');
+  if (token) s = s.split(token).join('***');
+  return s.replace(/(https?:\/\/)[^@/\s]+@/gi, '$1');
+}
+
+function runGit(args, { cwd, env, timeoutMs = 120_000 } = {}) {
+  try {
+    const r = spawnSync('git', args, { cwd, env, encoding: 'utf8', timeout: timeoutMs });
+    return { status: r.status ?? (r.signal ? 128 : null), stdout: r.stdout || '', stderr: r.stderr || '', signal: r.signal || null };
+  } catch (err) {
+    return { status: null, stdout: '', stderr: err.message, signal: null };
+  }
+}
+
+// Write a GIT_ASKPASS helper that echoes $GIT_TOKEN, so the token reaches git
+// via the child's ENV — never on argv or in the remote URL. Uses a Node helper
+// (askpass.js reads GIT_TOKEN and writes it verbatim), launched by a per-OS
+// shim: git can't exec a POSIX `.sh` on Windows, and a raw `.cmd` would let
+// cmd.exe re-parse token metacharacters (&, |, ^). The shim keeps the token in
+// env only and never expands it in a shell.
+function writeAskpass(dir, token) {
+  if (!token) return null;
+  const js = join(dir, 'askpass.js');
+  writeFileSync(js, 'process.stdout.write(process.env.GIT_TOKEN || "");\n', { mode: 0o600 });
+  // Launch via this process's own Node (process.execPath) rather than bare
+  // `node`, which may not be on PATH when Node was invoked by absolute path.
+  const node = process.execPath;
+  if (process.platform === 'win32') {
+    const p = join(dir, 'askpass.cmd');
+    writeFileSync(p, `@"${node}" "%~dp0askpass.js"\r\n`, { mode: 0o700 });
+    return p;
+  }
+  const p = join(dir, 'askpass.sh');
+  writeFileSync(p, `#!/bin/sh\nexec "${node}" "$(dirname "$0")/askpass.js"\n`, { mode: 0o700 });
+  try { chmodSync(p, 0o700); } catch { /* best effort */ }
+  return p;
+}
+
+// For https URLs, embed a username (no secret) so git asks GIT_ASKPASS for the
+// password. Non-https URLs and author-supplied credentials are left untouched.
+function authUrl(url, provider, hasToken) {
+  if (!hasToken) return url;
+  try {
+    const u = new URL(url);
+    if (u.protocol !== 'https:') return url;
+    if (u.username || u.password) return url; // author already embedded creds
+    u.username = provider === 'github' ? 'x-access-token' : 'git';
+    return u.toString();
+  } catch {
+    return url;
+  }
+}
+
+class ProvisionError extends Error {}
+
+// Never let git invoke the host's configured credential helper for our clone/
+// push. Reset the helper list ("") so no helper runs — even when we DO have a
+// token, because helpers like `store`/keychain would persist the job's repo
+// token to disk. GIT_ASKPASS supplies the secret directly, so no helper is
+// needed. Combined with GIT_TERMINAL_PROMPT=0 this keeps tokens ephemeral and
+// an absent-token clone genuinely anonymous.
+function credArgs() {
+  return ['-c', 'credential.helper='];
+}
+
+// Clone repo into <runDir>/workspace and check out / create the working branch.
+// Returns { workspaceDir, gitEnv, startSha, workingBranch, remote }. Throws a
+// ProvisionError (token-redacted) on any git failure so the caller can shed.
+function provisionRepo({ envelope, token, runDir, timeoutMs = 120_000 }) {
+  const repo = envelope.repository;
+  if (!repo || !repo.url) throw new ProvisionError('repository.url is required to provision a workspace');
+  const workspaceDir = join(runDir, 'workspace');
+  const askpass = writeAskpass(runDir, token);
+  const gitEnv = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_CONFIG_NOSYSTEM: '1',
+  };
+  // Drop any inherited askpass helpers so a no-token ("anonymous") clone can't
+  // authenticate with host-provided credentials. We re-set GIT_ASKPASS below
+  // only when we minted our own token-backed helper.
+  delete gitEnv.GIT_ASKPASS;
+  delete gitEnv.SSH_ASKPASS;
+  if (askpass) {
+    gitEnv.GIT_ASKPASS = askpass;
+    gitEnv.GIT_TOKEN = token;
+  } else {
+    // No token ⇒ honor the documented "anonymous" guarantee strictly: neutralize
+    // the user's global git config too, so knobs like http.<url>.extraHeader
+    // (added by `gh auth setup-git`) or url.<...>.insteadOf can't silently inject
+    // operator credentials. Only done on the anonymous path — token-backed jobs
+    // keep global config (e.g. http.proxy for reaching the remote).
+    gitEnv.GIT_CONFIG_GLOBAL = devNull;
+  }
+
+  const target = repo.ref || envelope.branch?.base || '';
+  // `git clone --branch` accepts a branch or tag name but NOT a raw commit SHA.
+  // For a SHA we clone the default branch, then fetch + check it out below.
+  const isSha = !!target && /^[0-9a-f]{7,40}$/i.test(target);
+  const cloneArgs = [...credArgs(), 'clone', '--no-tags'];
+  if (repo.depth && repo.depth > 0) cloneArgs.push('--depth', String(repo.depth));
+  if (repo.submodules) cloneArgs.push('--recurse-submodules');
+  if (target && !isSha) cloneArgs.push('--branch', target);
+  const remote = authUrl(repo.url, repo.provider || 'github', !!token);
+  cloneArgs.push(remote, workspaceDir);
+
+  const clone = runGit(cloneArgs, { env: gitEnv, timeoutMs });
+  if (clone.status !== 0) {
+    throw new ProvisionError(`git clone failed: ${redactToken(clone.stderr || clone.stdout, token).trim().slice(0, 500) || `exit ${clone.status}`}`);
+  }
+
+  if (isSha) {
+    // The SHA may not be present under a shallow clone of the default branch —
+    // fetch it explicitly (best effort), then check it out (detached HEAD).
+    const fetch = runGit([...credArgs(), 'fetch', '--no-tags', 'origin', target], { cwd: workspaceDir, env: gitEnv, timeoutMs });
+    const co = runGit(['checkout', '--detach', target], { cwd: workspaceDir, env: gitEnv });
+    if (co.status !== 0) {
+      const why = redactToken(co.stderr || fetch.stderr, token).trim().slice(0, 300);
+      throw new ProvisionError(`git checkout ${target} failed: ${why || `exit ${co.status}`}`);
+    }
+  }
+
+  // Give the harness a committer identity in case it commits (many do).
+  runGit(['config', 'user.name', process.env.GIT_AUTHOR_NAME || 'nano-agent'], { cwd: workspaceDir, env: gitEnv });
+  runGit(['config', 'user.email', process.env.GIT_AUTHOR_EMAIL || 'nano-agent@users.noreply.github.com'], { cwd: workspaceDir, env: gitEnv });
+
+  // Determine the working branch. With branch.create we make a real branch.
+  // Otherwise we're on whatever the clone checked out: a branch only if
+  // rev-parse resolves a symbolic name — a tag/sha leaves detached HEAD, in
+  // which case there is NO branch to push and workingBranch stays null so
+  // finalizeGit skips the push/PR reconcile instead of pushing a bogus ref.
+  let workingBranch = null;
+  if (envelope.branch?.create) {
+    const cb = runGit(['checkout', '-B', envelope.branch.create], { cwd: workspaceDir, env: gitEnv });
+    if (cb.status !== 0) throw new ProvisionError(`git checkout -B ${envelope.branch.create} failed: ${redactToken(cb.stderr, token).trim().slice(0, 300)}`);
+    workingBranch = envelope.branch.create;
+  } else {
+    const head = runGit(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: workspaceDir, env: gitEnv });
+    const name = (head.stdout || '').trim();
+    workingBranch = (name && name !== 'HEAD') ? name : null; // null ⇒ detached HEAD
+  }
+  const sha = runGit(['rev-parse', 'HEAD'], { cwd: workspaceDir, env: gitEnv });
+  // `git rev-parse HEAD` on an unborn branch (freshly cloned empty repo) exits
+  // non-zero and echoes the literal "HEAD" on stdout — treat that as "no base
+  // commit" (empty startSha) rather than a bogus revision.
+  return { workspaceDir, gitEnv, startSha: sha.status === 0 ? (sha.stdout || '').trim() : '', workingBranch, detached: !workingBranch, ref: target || '', remote: redactToken(repo.url, token) };
+}
+
+// Look up a PR for this branch (2a does NOT open it — the harness does, driven
+// by the prompt). Uses gh with the resolved token so it works headless. Reports
+// the PR's ACTUAL author login in `openedBy` (null when unknown/not found) —
+// gh returns whatever PR is open for the head branch, which may not be ours.
+function reconcileAgentPr({ workspaceDir, token, branch, provider }) {
+  if (provider && provider !== 'github') return { openedBy: null, found: false, error: `PR reconcile unsupported for provider "${provider}"` };
+  const env = { ...process.env };
+  if (token) {
+    env.GH_TOKEN = token;
+  } else {
+    // No job token ⇒ honor the anonymous guarantee: never let gh fall back to an
+    // operator-provided token in the ambient env. Scrub every gh auth source so
+    // PR reconcile can only use credentials we were explicitly handed.
+    for (const k of ['GH_TOKEN', 'GITHUB_TOKEN', 'GH_ENTERPRISE_TOKEN', 'GITHUB_ENTERPRISE_TOKEN']) delete env[k];
+  }
+  try {
+    const r = spawnSync('gh', ['pr', 'list', '--head', branch, '--state', 'all', '--json', 'number,url,state,isDraft,title,author', '--limit', '1'],
+      { cwd: workspaceDir, env, encoding: 'utf8', timeout: 30_000 });
+    if (r.error) return { openedBy: null, found: false, error: `gh not runnable: ${redactToken(r.error.message, token).trim().slice(0, 200)}` };
+    if (r.status !== 0) return { openedBy: null, found: false, error: redactToken(r.stderr, token).trim().slice(0, 200) || `gh pr list failed (exit ${r.status ?? 'null'}${r.signal ? `, signal ${r.signal}` : ''})` };
+    const arr = JSON.parse((r.stdout || '[]').trim() || '[]');
+    if (!Array.isArray(arr) || arr.length === 0) return { openedBy: null, found: false };
+    const pr = arr[0];
+    return { openedBy: pr.author?.login || null, found: true, number: pr.number, url: pr.url, state: pr.state, isDraft: !!pr.isDraft, title: pr.title };
+  } catch (err) {
+    return { openedBy: null, found: false, error: err.message };
+  }
+}
+
+// After the harness runs: enumerate new commits, push the branch (when
+// branch.push), and reconcile the agent-opened PR (when task.allowPr). A push
+// failure is reported (pushError) rather than thrown — the process model decides
+// what to do next, and re-running the agent would be non-idempotent.
+function finalizeGit({ workspaceDir, gitEnv, startSha, workingBranch, envelope, token }) {
+  const out = { branch: workingBranch, baseSha: startSha || null, headSha: null, commits: [], pushed: false, remote: null, pr: null };
+  const rem = runGit(['remote', 'get-url', 'origin'], { cwd: workspaceDir, env: gitEnv });
+  if (rem.status === 0) out.remote = redactToken(rem.stdout.trim(), token);
+  const headNow = runGit(['rev-parse', 'HEAD'], { cwd: workspaceDir, env: gitEnv });
+  out.headSha = headNow.status === 0 ? ((headNow.stdout || '').trim() || null) : null;
+  if (startSha) {
+    const log = runGit(['rev-list', `${startSha}..HEAD`], { cwd: workspaceDir, env: gitEnv });
+    if (log.status === 0) out.commits = log.stdout.trim().split('\n').filter(Boolean);
+  } else if (out.headSha) {
+    // Empty-repo case: provisionRepo found no initial commit (unborn branch), so
+    // there is no base to diff against — every commit now on HEAD is new. Without
+    // this, a harness that makes the repo's first commit would enumerate as "0
+    // commits" and the branch would never be pushed.
+    const log = runGit(['rev-list', 'HEAD'], { cwd: workspaceDir, env: gitEnv });
+    if (log.status === 0) out.commits = log.stdout.trim().split('\n').filter(Boolean);
+  }
+
+  if (!workingBranch) {
+    out.detached = true; // clone landed on a tag/sha ⇒ no branch to push
+  } else if (coerceBool(envelope.branch?.push, true) && out.commits.length > 0) {
+    const push = runGit([...credArgs(), 'push', '--set-upstream', 'origin', workingBranch], { cwd: workspaceDir, env: gitEnv });
+    if (push.status === 0) out.pushed = true;
+    else out.pushError = redactToken(push.stderr || push.stdout, token).trim().slice(0, 300) || `push exit ${push.status}`;
+  }
+
+  if (workingBranch && envelope.task?.allowPr) {
+    out.pr = reconcileAgentPr({ workspaceDir, token, branch: workingBranch, provider: envelope.repository?.provider || 'github' });
+  }
+  return out;
+}
+
+// Reap leftover job workspaces under the runs root. Age-gated, skips in-flight
+// run dirs, best-effort, bounded to our own directory (never touches anything we
+// did not create).
+function reapAgentRunDirs({ maxAgeMs = 0, liveRunDirs = new Set() } = {}) {
+  let reaped = 0;
+  const root = agentRunsRoot();
+  try {
+    if (!existsSync(root)) return { reaped };
+    const now = Date.now();
+    for (const name of readdirSync(root)) {
+      // Only reap the throwaway dirs this worker creates under agent-runs: the
+      // `run-*` job workspaces and the `res-*` structured-result dirs (see the
+      // `mkdtempSync(...)` calls in workAgent). Never touch unrelated files/dirs
+      // an operator may have placed under agent-runs.
+      if (!name.startsWith('run-') && !name.startsWith('res-')) continue;
+      const p = join(root, name);
+      if (liveRunDirs.has(p)) continue;
+      try {
+        const st = lstatSync(p);
+        if (!st.isDirectory()) continue; // lstat: a symlink is not a dir ⇒ skipped, never followed
+        if (maxAgeMs > 0 && now - st.mtimeMs < maxAgeMs) continue;
+        rmSync(p, { recursive: true, force: true });
+        reaped++;
+      } catch { /* skip */ }
+    }
+  } catch (err) {
+    return { reaped, error: err.message };
+  }
+  return { reaped };
+}
+
 // ---- One-shot capture (shared by host + container executors) ---------------
 const MAX_CAPTURE_BYTES = 1_048_576; // 1 MiB per stream
 
 // Spawn a child, pipe `stdinData`, capture byte-capped stdout/stderr, enforce a
 // timeout (invoking `onTimeout(child)` to tear the child down), and resolve to a
 // uniform result. Used by both the host and container executors.
-function spawnCaptureOneShot({ command, args = [], shell = false, detached = false, env, stdinData, timeoutMs, onTimeout }) {
+function spawnCaptureOneShot({ command, args = [], shell = false, detached = false, cwd, env, stdinData, timeoutMs, onTimeout, stream = false, streamPrefix = '', onStreamOut, onStreamErr }) {
   return new Promise((resolve) => {
     let child;
     const stdoutChunks = [];
@@ -1818,15 +2230,48 @@ function spawnCaptureOneShot({ command, args = [], shell = false, detached = fal
     let settled = false;
     let timer = null;
 
+    // Live "spy" tee (--stream): mirror the child's output line-by-line to a
+    // caller-supplied emitter (the worker routes these through c8ctl's
+    // output-mode-aware logger so streaming never corrupts a structured/JSON
+    // output mode; falling back to a raw console write only when none is given).
+    // Each complete line is tagged with the job prefix so interleaved jobs stay
+    // legible. A per-stream buffer holds partial lines across chunk boundaries;
+    // it is force-flushed once it exceeds STREAM_TEE_LINE_CAP so a newline-less
+    // torrent (progress bars, binary output) can't grow it without bound.
+    const STREAM_TEE_LINE_CAP = 64 * 1024;
+    const makeTee = (emit) => {
+      if (!stream) return null;
+      const sink = emit || ((line) => process.stdout.write(`${line}\n`));
+      let partial = '';
+      const flush = (text, final) => {
+        partial += text;
+        let nl;
+        while ((nl = partial.indexOf('\n')) !== -1) {
+          sink(`${streamPrefix}${partial.slice(0, nl)}`);
+          partial = partial.slice(nl + 1);
+        }
+        while (partial.length >= STREAM_TEE_LINE_CAP) {
+          sink(`${streamPrefix}${partial.slice(0, STREAM_TEE_LINE_CAP)}`);
+          partial = partial.slice(STREAM_TEE_LINE_CAP);
+        }
+        if (final && partial) { sink(`${streamPrefix}${partial}`); partial = ''; }
+      };
+      return flush;
+    };
+    const teeOut = makeTee(onStreamOut);
+    const teeErr = makeTee(onStreamErr || onStreamOut);
+
     const finish = (result) => {
       if (settled) return;
       settled = true;
       if (timer) clearTimeout(timer);
+      if (teeOut) teeOut('', true);
+      if (teeErr) teeErr('', true);
       resolve(result);
     };
 
     try {
-      child = spawn(command, args, { shell, detached, stdio: ['pipe', 'pipe', 'pipe'], env });
+      child = spawn(command, args, { shell, detached, cwd, stdio: ['pipe', 'pipe', 'pipe'], env });
     } catch (err) {
       finish({ ok: false, exitCode: null, stdout: '', stderr: '', error: err.message, truncated: false, stderrTruncated: false });
       return;
@@ -1841,6 +2286,7 @@ function spawnCaptureOneShot({ command, args = [], shell = false, detached = fal
 
     child.stdout.on('data', (d) => {
       const buf = Buffer.isBuffer(d) ? d : Buffer.from(d);
+      if (teeOut) teeOut(buf.toString('utf8'), false);
       const remaining = MAX_CAPTURE_BYTES - stdoutBytes;
       if (remaining <= 0) { stdoutTruncated = true; return; }
       if (buf.length > remaining) { stdoutChunks.push(buf.subarray(0, remaining)); stdoutBytes = MAX_CAPTURE_BYTES; stdoutTruncated = true; }
@@ -1848,6 +2294,7 @@ function spawnCaptureOneShot({ command, args = [], shell = false, detached = fal
     });
     child.stderr.on('data', (d) => {
       const buf = Buffer.isBuffer(d) ? d : Buffer.from(d);
+      if (teeErr) teeErr(buf.toString('utf8'), false);
       const remaining = MAX_CAPTURE_BYTES - stderrBytes;
       if (remaining <= 0) { stderrTruncated = true; return; }
       if (buf.length > remaining) { stderrChunks.push(buf.subarray(0, remaining)); stderrBytes = MAX_CAPTURE_BYTES; stderrTruncated = true; }
@@ -1911,33 +2358,59 @@ function baseAgentEnv(profile, job) {
  * Both paths resolve to the same result contract.
  */
 function runAgentJob(profile, job, opts = {}) {
-  const { timeoutMs, envelope, sandbox = 'none', image, runId, secretEnv = {}, passThroughSecretNames = [] } = opts;
+  const { timeoutMs, envelope, sandbox = 'none', image, runId, secretEnv = {}, passThroughSecretNames = [], cwd, extraEnv = {}, profileEnv = {}, resultFile, stream = false, streamPrefix = '', onStreamOut, onStreamErr } = opts;
   const payload = JSON.stringify(buildAgentPayload(profile, job, envelope));
   const agentEnv = baseAgentEnv(profile, job);
+  // Static, non-secret env for the harness: the worker/profile's env (e.g. a
+  // harness's permission toggles) plus the per-job envelope's setup.env
+  // (job-specific tuning wins over the profile default). Reserved AGENT_* and
+  // resolved secrets are layered on top so user env can never shadow them.
+  const staticEnv = { ...normalizeEnvMap(profileEnv), ...normalizeEnvMap(envelope?.setup?.env) };
 
   if (!CONTAINER_SANDBOXES.has(sandbox)) {
+    // Host: hand the agent the result file by its real path.
+    const resultEnv = resultFile ? { [AGENT_RESULT_FILE_ENV]: resultFile } : {};
     return spawnCaptureOneShot({
       command: profile.command,
       shell: true,
       // Own process group so the timeout handler can kill the whole tree.
       detached: process.platform !== 'win32',
-      env: { ...process.env, ...agentEnv, ...secretEnv },
+      // When a repository was provisioned, run the harness IN the workspace.
+      cwd,
+      // Reserved harness env (AGENT_* + the result-file path) is layered AFTER
+      // resolved secrets so a task-supplied secret NAME can never shadow it.
+      env: { ...process.env, ...staticEnv, ...secretEnv, ...agentEnv, ...extraEnv, ...resultEnv },
       stdinData: payload,
       timeoutMs,
       onTimeout: (child) => killTree(child),
+      stream,
+      streamPrefix,
+      onStreamOut,
+      onStreamErr,
     });
   }
 
   const engine = sandbox;
   const containerName = `nano-${runId}`;
+  // Container: bind-mount the result file's directory read-write at a fixed
+  // in-container path and point AGENT_RESULT_FILE at the mounted file, so the
+  // agent writes it inside the sandbox and the harness reads it back on the host.
+  let resultEnv = {};
+  const mountArgs = [];
+  if (resultFile) {
+    const hostDir = dirname(resultFile);
+    const containerPath = `/nano-agent/${basename(resultFile)}`;
+    mountArgs.push('-v', `${hostDir}:/nano-agent`);
+    resultEnv = { [AGENT_RESULT_FILE_ENV]: containerPath };
+  }
   // Forward env by NAME only (`-e NAME`) so secret VALUES stay out of argv and
   // `docker inspect`; docker reads the value from our child's environment.
   const envArgs = [];
   for (const k of Object.keys(agentEnv)) envArgs.push('-e', k);
+  for (const k of Object.keys(extraEnv)) envArgs.push('-e', k);
+  for (const k of Object.keys(resultEnv)) envArgs.push('-e', k);
   for (const n of passThroughSecretNames) envArgs.push('-e', n);
-  const setupEnv = isPlainObject(envelope?.setup?.env) ? envelope.setup.env : {};
-  const setupEnvValues = {};
-  for (const [k, v] of Object.entries(setupEnv)) { envArgs.push('-e', k); setupEnvValues[k] = String(v); }
+  for (const k of Object.keys(staticEnv)) envArgs.push('-e', k);
 
   const args = [
     'run', '--rm', '-i',
@@ -1948,6 +2421,7 @@ function runAgentJob(profile, job, opts = {}) {
     '--label', `nano.run=${runId}`,
     '--log-opt', 'max-size=10m',
     '--log-opt', 'max-file=3',
+    ...mountArgs,
     ...envArgs,
     image,
     'sh', '-c', profile.command,
@@ -1957,9 +2431,16 @@ function runAgentJob(profile, job, opts = {}) {
     command: engine,
     args,
     shell: false,
-    env: { ...process.env, ...agentEnv, ...secretEnv, ...setupEnvValues },
+    // Reserved harness env (AGENT_* + the result-file path) is layered AFTER
+    // resolved secrets so a task-supplied secret NAME can never shadow it. In
+    // container mode docker reads these values from our child env by NAME.
+    env: { ...process.env, ...staticEnv, ...secretEnv, ...agentEnv, ...extraEnv, ...resultEnv },
     stdinData: payload,
     timeoutMs,
+    stream,
+    streamPrefix,
+    onStreamOut,
+    onStreamErr,
     onTimeout: (child) => {
       try { spawnSync(engine, ['rm', '-f', containerName], { timeout: 15_000 }); } catch { /* best effort */ }
       try { killTree(child); } catch { /* best effort */ }
@@ -1967,11 +2448,11 @@ function runAgentJob(profile, job, opts = {}) {
   });
 }
 
-// Shape the io.nanobpm.agentResult output envelope. branch/commits/pr are
-// reserved for increment 2 (git provisioning); increment 1 reports execution.
-function buildResultEnvelope(result, { sandbox, image }) {
+// Shape the io.nanobpm.agentResult output envelope. When a repository was
+// provisioned (increment 2a), the `git` block adds branch/commits/push/PR facts.
+function buildResultEnvelope(result, { sandbox, image, git, result: agentResult } = {}) {
   const status = result.ok ? 'completed' : (result.timedOut ? 'timedOut' : 'failed');
-  return {
+  const env = {
     schemaVersion: RESULT_ENVELOPE_SCHEMA_VERSION,
     status,
     sandbox,
@@ -1983,6 +2464,21 @@ function buildResultEnvelope(result, { sandbox, image }) {
     signal: result.signal ?? null,
     error: result.error ?? null,
   };
+  // The agent's structured result (as returned via $AGENT_RESULT_FILE / sentinel),
+  // preserved verbatim for auditability even when merged into the completion vars.
+  if (isPlainObject(agentResult)) env.result = agentResult;
+  if (git) {
+    env.repository = git.remote ?? null;
+    env.branch = git.branch ?? null;
+    env.baseSha = git.baseSha ?? null;
+    env.headSha = git.headSha ?? null;
+    env.commits = git.commits ?? [];
+    env.pushed = !!git.pushed;
+    if (git.pushError) env.pushError = git.pushError;
+    if (git.pr) env.pr = git.pr;
+    if (git.error) env.gitError = git.error;
+  }
+  return env;
 }
 
 /**
@@ -2020,6 +2516,16 @@ async function workAgent(req, flags) {
     process.exit(1);
   }
 
+  // Static env for the harness: the profile's persisted env, extended/overridden
+  // by any work-time `--env NAME=VALUE` (repeatable). These carry harness startup
+  // config such as permission toggles (e.g. a coder CLI started with tools enabled).
+  const { env: workEnv, errors: workEnvErrors } = parseEnvPairs(flags?.env);
+  if (workEnvErrors.length > 0) {
+    logger.error(workEnvErrors.join('; '));
+    process.exit(1);
+  }
+  const profileEnv = { ...profile.env, ...workEnv };
+
   const intFlag = (v, dflt) => {
     const n = Number.parseInt(String(v ?? ''), 10);
     return Number.isFinite(n) && n > 0 ? n : dflt;
@@ -2055,10 +2561,34 @@ async function workAgent(req, flags) {
     ? Math.max(0, intFlag(flags['min-free-mb'], 0)) * 1_048_576
     : 1_073_741_824; // 1 GiB default floor
 
+  // Git provisioning knobs (increment 2a — host harness with a repository).
+  const cloneTimeoutMs = intFlag(flags?.['clone-timeout'], 120_000);
+  const keepRuns = coerceBool(flags?.['keep-runs'], false);
+  // --stream: tee each agent job's live stdout/stderr to this console (spy/debug),
+  // in addition to the existing byte-capped capture used for the result envelope.
+  const stream = coerceBool(flags?.stream, false);
+
   // Tracks run ids currently executing so the reaper never removes a live
   // container out from under an in-flight job.
   const liveRunIds = new Set();
+  // Tracks per-job workspace dirs currently in use so the run-dir reaper never
+  // deletes a workspace out from under an in-flight host job.
+  const liveRunDirs = new Set();
   let reaperTimer = null;
+  let runDirTimer = null;
+
+  // Run-dir hygiene runs regardless of sandbox: any sandbox=none job that carries
+  // a repository clones a throwaway workspace under the runs root, and a crashed
+  // worker can leave one behind. Bounded to our own directory, age-gated.
+  {
+    const initialRuns = reapAgentRunDirs({ maxAgeMs: reapAgeMs, liveRunDirs });
+    if (initialRuns.reaped > 0) logger.info(`Reaped ${initialRuns.reaped} leftover job workspace(s) at startup.`);
+    runDirTimer = setInterval(() => {
+      const r = reapAgentRunDirs({ maxAgeMs: reapAgeMs, liveRunDirs });
+      if (r.reaped > 0) logger.info(`Reaper removed ${r.reaped} finished job workspace(s).`);
+    }, reapIntervalMs);
+    if (typeof runDirTimer.unref === 'function') runDirTimer.unref();
+  }
 
   if (isContainer) {
     if (!containerEngineAvailable(sandbox)) {
@@ -2084,6 +2614,8 @@ async function workAgent(req, flags) {
   logger.info(`Putting "${name}" [${profile.rank}] to work → ${profile.command}`);
   logger.info(`  model: ${profile.model || '(none)'}; capabilities: ${profile.capabilities.join(', ') || '(none)'}`);
   logger.info(`  sandbox: ${sandbox}${isContainer ? ` (image ${image})` : ''}`);
+  const profileEnvKeys = Object.keys(profileEnv);
+  if (profileEnvKeys.length > 0) logger.info(`  harness env: ${profileEnvKeys.join(', ')}`);
   logger.info(`  listening on ${matrix.length} job type(s): ${matrix.join('  ')}`);
   logger.info(`  max parallel: ${maxParallelJobs}; job timeout: ${jobTimeoutMs}ms`);
   logger.info('Polling for work — press Ctrl-C to stop.');
@@ -2123,8 +2655,58 @@ async function workAgent(req, flags) {
 
         const runId = randomUUID();
         if (isContainer) liveRunIds.add(runId);
+
+        // Host git provisioning (increment 2a): sandbox=none + a repository →
+        // clone into a throwaway workspace, run the harness there, then push +
+        // reconcile the agent PR. Container-side cloning is a later increment.
+        const hasRepo = !isContainer && !!envelope.repository?.url;
+        let runDir = null;
+        let provisioned = null;
+        let cwd;
+        let extraEnv;
+        let repoToken = null;
+        if (hasRepo) {
+          const provider = envelope.repository.provider || 'github';
+          const authRef = envelope.repository.authRef || (provider === 'github' ? 'GITHUB_TOKEN' : null);
+          if (authRef) repoToken = secretResolver.resolve(authRef) || null; // optional: absent → anonymous clone
+          try {
+            mkdirSync(agentRunsRoot(), { recursive: true });
+            runDir = mkdtempSync(join(agentRunsRoot(), 'run-'));
+            liveRunDirs.add(runDir);
+            provisioned = provisionRepo({ envelope, token: repoToken, runDir, timeoutMs: cloneTimeoutMs });
+            cwd = provisioned.workspaceDir;
+            extraEnv = {
+              AGENT_WORKSPACE: provisioned.workspaceDir,
+              AGENT_REPO_URL: provisioned.remote,
+              AGENT_REPO_BRANCH: provisioned.workingBranch || '',
+              AGENT_REPO_REF: provisioned.ref || '',
+            };
+          } catch (err) {
+            if (runDir) { try { rmSync(runDir, { recursive: true, force: true }); } catch { /* best effort */ } liveRunDirs.delete(runDir); }
+            if (isContainer) liveRunIds.delete(runId);
+            const retries = Math.max(0, (Number(job.retries) || 1) - 1);
+            const msg = err instanceof ProvisionError ? err.message : `provisioning error: ${err.message}`;
+            logger.warn(`[${jobType}] job ${job.jobKey} not provisioned — ${msg}; retries left ${retries}`);
+            return job.fail({ errorMessage: msg.slice(0, 2000), retries, retryBackOff: 15_000 });
+          }
+        }
+
         let result;
+        let gitResult = null;
+        // Private structured-result channel: hand the agent a file (outside any
+        // repo clone so it can't be `git add`ed) to write its job-result vars to.
+        let resultDir = null;
+        let resultFile = null;
         try {
+          try {
+            mkdirSync(agentRunsRoot(), { recursive: true });
+            resultDir = mkdtempSync(join(agentRunsRoot(), 'res-'));
+            resultFile = join(resultDir, 'result.json');
+            // Track it so the run-dir reaper skips it while in-flight and reaps it
+            // (as a `res-*` dir) if this worker crashes before the cleanup below.
+            liveRunDirs.add(resultDir);
+          } catch { resultDir = null; resultFile = null; }
+
           result = await runAgentJob(profile, job, {
             timeoutMs: jobTimeoutMs,
             envelope,
@@ -2133,20 +2715,77 @@ async function workAgent(req, flags) {
             runId,
             secretEnv: resolved,
             passThroughSecretNames: names,
+            cwd,
+            extraEnv,
+            profileEnv,
+            resultFile,
+            stream,
+            streamPrefix: `[${jobType} ${job.jobKey}] `,
+            // Route the --stream tee through c8ctl's output-mode-aware logger so
+            // spying never corrupts a structured/JSON output mode.
+            onStreamOut: stream ? (line) => logger.info(line) : undefined,
+            onStreamErr: stream ? (line) => logger.warn(line) : undefined,
           });
+
+          // Finalize git only when the harness succeeded — never push a
+          // half-finished workspace.
+          if (provisioned && result.ok) {
+            try {
+              gitResult = finalizeGit({
+                workspaceDir: provisioned.workspaceDir,
+                gitEnv: provisioned.gitEnv,
+                startSha: provisioned.startSha,
+                workingBranch: provisioned.workingBranch,
+                envelope,
+                token: repoToken,
+              });
+            } catch (err) {
+              gitResult = { remote: provisioned.remote, branch: provisioned.workingBranch, baseSha: provisioned.startSha || null, commits: [], pushed: false, error: redactToken(err.message, repoToken) };
+            }
+          } else if (provisioned) {
+            gitResult = { remote: provisioned.remote, branch: provisioned.workingBranch, baseSha: provisioned.startSha || null, commits: [], pushed: false };
+          }
         } finally {
           if (isContainer) liveRunIds.delete(runId);
+          if (runDir && !keepRuns) { try { rmSync(runDir, { recursive: true, force: true }); } catch { /* best effort */ } }
+          if (runDir) liveRunDirs.delete(runDir);
         }
 
-        const resultEnvelope = buildResultEnvelope(result, { sandbox, image });
+        // Read the agent's structured result: the file it wrote, else a stdout
+        // sentinel/`json fence fallback. The raw object is attached to the audit
+        // envelope; the sanitized (reserved-key-stripped) vars are merged into the
+        // job completion so the model sees `status`/`summary`/… as first-class
+        // outputs. Read before deleting the temp dir.
+        const rawResult = readAgentResultFile(resultFile) ?? parseResultFromStdout(result.stdout);
+        if (resultDir) { try { rmSync(resultDir, { recursive: true, force: true }); } catch { /* best effort */ } liveRunDirs.delete(resultDir); }
+        const resultVars = sanitizeResultVars(rawResult);
+
+        const resultEnvelope = buildResultEnvelope(result, { sandbox, image, git: gitResult, result: rawResult });
         if (result.ok) {
-          logger.info(`[${jobType}] job ${job.jobKey} complete (exit 0)${result.truncated ? ' [output truncated]' : ''}`);
+          const gitNote = gitResult
+            ? ` [${gitResult.branch ? `branch ${gitResult.branch}` : 'detached HEAD'}: ${gitResult.commits.length} commit(s), ${gitResult.branch ? (gitResult.pushed ? 'pushed' : (gitResult.pushError ? 'push FAILED' : 'not pushed')) : 'no branch to push'}${gitResult.pr?.found ? `, PR #${gitResult.pr.number}` : ''}]`
+            : '';
+          logger.info(`[${jobType}] job ${job.jobKey} complete (exit 0)${result.truncated ? ' [output truncated]' : ''}${gitNote}`);
+          if (gitResult?.pushError) logger.warn(`[${jobType}] job ${job.jobKey}: branch push failed — ${gitResult.pushError}`);
+          // Guard the operator against silent empty escalations: a success that
+          // yields no *effective* result vars (no file/sentinel at all, an empty
+          // `{}`, or only reserved keys that were sanitized away) means the
+          // model's status/decision vars stay unset and any status gateway will
+          // fall through to its default. Warn on the merged-vars emptiness, not
+          // just a missing rawResult.
+          const resultKeys = Object.keys(resultVars);
+          if (resultKeys.length === 0) logger.warn(`[${jobType}] job ${job.jobKey}: agent returned no usable result vars — write a JSON object of result variables to $AGENT_RESULT_FILE (or print a "${RESULT_SENTINEL} {…}" line) so downstream gateways see status/summary/etc.`);
+          else logger.info(`[${jobType}] job ${job.jobKey}: merged agent result vars [${resultKeys.join(', ')}]`);
           return job.complete({
+            ...resultVars,
             [AGENT_RESULT_KEY]: resultEnvelope,
             output: result.stdout,
             exitCode: 0,
             agent: profile.name,
             truncated: Boolean(result.truncated),
+            ...(gitResult
+              ? { branch: gitResult.branch, commits: gitResult.commits, pushed: gitResult.pushed, pullRequest: gitResult.pr || null }
+              : {}),
           });
         }
         const retries = Math.max(0, (Number(job.retries) || 1) - 1);
@@ -2171,6 +2810,7 @@ async function workAgent(req, flags) {
       stopping = true;
       logger.info(`Received ${signal} — stopping ${workers.length} worker(s)...`);
       if (reaperTimer) clearInterval(reaperTimer);
+      if (runDirTimer) clearInterval(runDirTimer);
       let stopFailures = 0;
       await Promise.all(
         workers.map(async (w) => {
@@ -3433,14 +4073,30 @@ export {
   hostEnvSecretResolver,
   buildAgentPayload,
   buildResultEnvelope,
+  parseAgentResultObject,
+  readAgentResultFile,
+  parseResultFromStdout,
+  sanitizeResultVars,
+  parseEnvPairs,
+  normalizeEnvMap,
   reapAgentContainers,
   diskBudgetOk,
   containerEngineAvailable,
   runAgentJob,
+  provisionRepo,
+  finalizeGit,
+  reconcileAgentPr,
+  reapAgentRunDirs,
+  authUrl,
+  redactToken,
+  agentRunsRoot,
+  ProvisionError,
   normalizeStoredProfile,
   jobTypeMatrix,
   AGENT_TASK_NS,
   AGENT_RESULT_KEY,
+  RESULT_SENTINEL,
+  RESERVED_RESULT_KEYS,
   SANDBOXES,
 };
 
@@ -3476,6 +4132,7 @@ export const metadata = {
         { command: 'c8ctl nano update --check', description: 'Check whether a newer nano release is available' },
         { command: 'c8ctl nano hire', description: 'Interactively create a CLI agent worker profile (name, rank, command, model, capabilities)' },
         { command: 'c8ctl nano hire --name reviewer --rank senior --command copilot --model gpt-5 --capabilities code-review,testing', description: 'Create a profile non-interactively' },
+        { command: 'c8ctl nano hire --name coder --rank senior --command copilot --env COPILOT_ENABLE_ALL_TOOLS=1', description: 'Persist a harness startup env var (e.g. permissions) on the profile' },
         { command: 'c8ctl nano hire --list', description: 'List hired agent profiles' },
         { command: 'c8ctl nano hire --name coder --rank senior --command "agent-harness" --sandbox docker --image ghcr.io/acme/agent:1', description: 'Create a profile that runs each job in a throwaway Docker container' },
         { command: 'c8ctl nano work reviewer', description: 'Spawn Nano job workers for the "reviewer" profile and poll for work' },
@@ -3527,10 +4184,14 @@ export const commands = {
       capabilities: { type: 'string', description: 'hire: comma-separated capability list' },
       sandbox: { type: 'string', description: 'hire/work: execution sandbox none|docker|podman (default none). Containers isolate each job.' },
       image: { type: 'string', description: 'hire/work: container image the agent runs in (required for --sandbox docker|podman)' },
+      env: { type: 'string', multiple: true, description: 'hire/work: static env var for the harness as NAME=VALUE (repeatable); persisted on hire, work extends/overrides. E.g. permission toggles.' },
       'secret-resolver': { type: 'string', description: 'work: secret resolver for task secretRefs (host = process env; default host)' },
-      'reap-age': { type: 'string', description: 'work: age in ms before a finished agent container is reaped (default 3600000)' },
-      'reap-interval': { type: 'string', description: 'work: how often to sweep finished agent containers in ms (default 300000)' },
+      'reap-age': { type: 'string', description: 'work: age in ms before a finished agent container or job workspace is reaped (default 3600000)' },
+      'reap-interval': { type: 'string', description: 'work: how often to sweep finished agent containers and job workspaces in ms (default 300000)' },
       'min-free-mb': { type: 'string', description: 'work: shed jobs when the engine data root has less than this many MB free (default 1024)' },
+      'clone-timeout': { type: 'string', description: 'work: max time in ms for cloning a task repository on the host (default 120000)' },
+      'keep-runs': { type: 'boolean', description: 'work: keep per-job workspaces under <state>/agent-runs instead of deleting them after each job (debug)' },
+      stream: { type: 'boolean', description: 'work: tee each agent job\'s live stdout/stderr to this console, prefixed with the job type + key (spy/debug)' },
       list: { type: 'boolean', description: 'hire: list existing agent profiles instead of creating one' },
       'max-parallel': { type: 'string', description: 'work: max concurrent jobs per worker (default 1)' },
       'job-timeout': { type: 'string', description: 'work: max harness runtime per job in ms; the spawned process is killed past this (default 300000)' },
@@ -3676,8 +4337,8 @@ function printUsage() {
   console.log('  c8ctl nano set <bin|model-dir> <path>');
   console.log('  c8ctl nano config');
   console.log('  c8ctl nano update [--check]');
-  console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--list]');
-  console.log('  c8ctl nano work <profileName> [--max-parallel <n>] [--job-timeout <ms>] [--sandbox none|docker|podman] [--image <ref>] [--secret-resolver host] [--min-free-mb <n>]');
+  console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--list]');
+  console.log('  c8ctl nano work <profileName> [--max-parallel <n>] [--job-timeout <ms>] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--secret-resolver host] [--min-free-mb <n>] [--clone-timeout <ms>] [--keep-runs] [--stream]');
   console.log('');
   console.log('Subcommands:');
   console.log('  start    Spawn an N-node local cluster wired to talk to each other on localhost');
@@ -3715,13 +4376,16 @@ function printUsage() {
   console.log('  --capabilities <a,b> hire: comma-separated capability list');
   console.log('  --sandbox <s>        hire/work: execution sandbox none|docker|podman (default none)');
   console.log('  --image <ref>        hire/work: container image the agent runs in (required for docker|podman)');
+  console.log('  --env NAME=VALUE     hire/work: static env var for the harness (repeatable); persisted on hire, work extends/overrides');
   console.log('  --list               hire: list existing agent profiles instead of creating one');
   console.log('  --max-parallel <n>   work: max concurrent jobs per worker (default 1)');
   console.log('  --job-timeout <ms>   work: max harness runtime per job in ms (default 300000)');
   console.log('  --secret-resolver <r> work: secret resolver for task secretRefs (host; default host)');
-  console.log('  --reap-age <ms>      work: age before a finished agent container is reaped (default 3600000)');
-  console.log('  --reap-interval <ms> work: how often to sweep finished agent containers (default 300000)');
+  console.log('  --reap-age <ms>      work: age before a finished agent container/workspace is reaped (default 3600000)');
+  console.log('  --reap-interval <ms> work: how often to sweep finished agent containers/workspaces (default 300000)');
   console.log('  --min-free-mb <n>    work: shed jobs when the engine data root has < this many MB free (default 1024)');
+  console.log('  --clone-timeout <ms> work: max time to clone a task repository on the host (default 120000)');
+  console.log('  --keep-runs          work: keep per-job workspaces instead of deleting them (debug)');
   console.log('');
   console.log('Persistent assets:');
   console.log('  Models and workers live in the workspace dir (NANOBPMN_WORKSPACE_DIR),');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.10.1",
+  "version": "1.12.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -49,12 +49,12 @@
     "semantic-release": "^25.0.3"
   },
   "optionalDependencies": {
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.10.1",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.10.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.10.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.10.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.10.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.10.1",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.10.1"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.12.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.12.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.12.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.12.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.12.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.12.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.12.0"
   }
 }