c8ctl-plugin-nano 1.11.0 → 1.13.0

package/README.md

@@ -281,6 +281,14 @@ a run that outlives `--job-timeout` is force-removed. The envelope is piped on
 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
 `GITHUB_TOKEN` for GitHub) are resolved via a pluggable `--secret-resolver`

package/c8ctl-plugin.js

@@ -28,7 +28,7 @@
  *   c8ctl nano restart [<nodes>] [--purge] ...
  */
 
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn, spawnSync, execFileSync, execSync } from 'node:child_process';
 import {
   existsSync,
   mkdirSync,
@@ -46,7 +46,7 @@ import {
 } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { homedir, platform as osPlatform, devNull } from 'node:os';
-import { join, isAbsolute, resolve as resolvePath, dirname, sep } from 'node:path';
+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';
@@ -1639,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']);
@@ -2102,10 +2191,11 @@ function reapAgentRunDirs({ maxAgeMs = 0, liveRunDirs = new Set() } = {}) {
     if (!existsSync(root)) return { reaped };
     const now = Date.now();
     for (const name of readdirSync(root)) {
-      // Only reap the `run-*` workspaces this worker creates (see the
-      // `mkdtempSync(join(agentRunsRoot(), 'run-'))` in workAgent). Never touch
-      // unrelated files/dirs an operator may have placed under agent-runs.
-      if (!name.startsWith('run-')) continue;
+      // 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 {
@@ -2128,7 +2218,7 @@ 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, cwd, 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 = [];
@@ -2140,10 +2230,43 @@ 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);
     };
 
@@ -2163,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; }
@@ -2170,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; }
@@ -2233,7 +2358,7 @@ 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 = [], cwd, extraEnv = {}, profileEnv = {} } = 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
@@ -2243,6 +2368,8 @@ function runAgentJob(profile, job, opts = {}) {
   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,
@@ -2250,20 +2377,38 @@ function runAgentJob(profile, job, opts = {}) {
       detached: process.platform !== 'win32',
       // When a repository was provisioned, run the harness IN the workspace.
       cwd,
-      env: { ...process.env, ...staticEnv, ...agentEnv, ...extraEnv, ...secretEnv },
+      // 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);
   for (const k of Object.keys(staticEnv)) envArgs.push('-e', k);
 
@@ -2276,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,
@@ -2285,9 +2431,16 @@ function runAgentJob(profile, job, opts = {}) {
     command: engine,
     args,
     shell: false,
-    env: { ...process.env, ...staticEnv, ...agentEnv, ...extraEnv, ...secretEnv },
+    // 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 */ }
@@ -2297,7 +2450,7 @@ function runAgentJob(profile, job, opts = {}) {
 
 // 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 } = {}) {
+function buildResultEnvelope(result, { sandbox, image, git, result: agentResult } = {}) {
   const status = result.ok ? 'completed' : (result.timedOut ? 'timedOut' : 'failed');
   const env = {
     schemaVersion: RESULT_ENVELOPE_SCHEMA_VERSION,
@@ -2311,6 +2464,9 @@ function buildResultEnvelope(result, { sandbox, image, git } = {}) {
     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;
@@ -2408,6 +2564,9 @@ async function workAgent(req, flags) {
   // 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.
@@ -2534,7 +2693,20 @@ async function workAgent(req, flags) {
 
         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,
@@ -2546,6 +2718,13 @@ async function workAgent(req, flags) {
             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
@@ -2572,14 +2751,33 @@ async function workAgent(req, flags) {
           if (runDir) liveRunDirs.delete(runDir);
         }
 
-        const resultEnvelope = buildResultEnvelope(result, { sandbox, image, git: gitResult });
+        // 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) {
           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,
@@ -2679,21 +2877,90 @@ function compareSemver(a, b) {
   return 0;
 }
 
+/**
+ * Resolve how npm must be spawned on the given platform. Spawning `npm`
+ * directly is not portable: on Windows npm is a `npm.cmd` shim, so bare
+ * `"npm"` fails with ENOENT and `"npm.cmd"` fails with EINVAL under the
+ * CVE-2024-27980 hardening. On Windows the shim is therefore run through
+ * cmd.exe (`shell: true`) with every argument double-quoted, and the two
+ * constructs that survive double quotes — an embedded `"` and a `%VAR%`
+ * reference — are rejected rather than escaped.
+ *
+ * This mirrors the host CLI's own `buildNpmInvocation`; it is the local
+ * fallback for `runNpm` when the host runner (`c8ctl.npm`) is unavailable.
+ * `platform` is a parameter so the Windows branch is unit-testable on POSIX.
+ */
+function buildNpmInvocation(args, platform = process.platform) {
+  if (platform !== 'win32') {
+    return { command: 'npm', args: [...args], shell: false };
+  }
+  for (const arg of args) {
+    if (/["\r\n\0]/.test(arg)) {
+      throw new Error(
+        `Refusing to run npm: argument contains a quote or line break that cannot be passed safely to cmd.exe: ${JSON.stringify(arg)}`,
+      );
+    }
+    if (/%[A-Z_][^%]*?%/i.test(arg)) {
+      throw new Error(
+        `Refusing to run npm: argument contains a cmd.exe environment variable reference: ${JSON.stringify(arg)}`,
+      );
+    }
+  }
+  return {
+    command: 'npm.cmd',
+    args: args.map((arg) => `"${arg.replace(/(\\+)$/, '$1$1')}"`),
+    shell: true,
+  };
+}
+
+/** Local, platform-aware npm runner used when the host `c8ctl.npm` is absent. */
+function runNpmLocal(args, { stdout = false, stdio } = {}) {
+  const { command, args: resolved, shell } = buildNpmInvocation(args);
+  if (shell) {
+    const cmdLine = [command, ...resolved].join(' ');
+    if (stdout) {
+      return { stdout: execSync(cmdLine, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' }) };
+    }
+    execSync(cmdLine, { stdio });
+    return undefined;
+  }
+  if (stdout) {
+    return {
+      stdout: execFileSync(command, resolved, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', shell: false }),
+    };
+  }
+  execFileSync(command, resolved, { stdio, shell: false });
+  return undefined;
+}
+
+/**
+ * Run npm portably. Prefers the host CLI's cross-platform runner
+ * (`globalThis.c8ctl.npm`, added in c8ctl's plugin runtime); falls back to the
+ * local platform-aware invocation for older hosts and for the detached update
+ * refresh, which runs without the host runtime. Throws on a nonzero exit.
+ */
+function runNpm(args, { stdout = false, stdio } = {}) {
+  const host = globalThis.c8ctl;
+  if (host && typeof host.npm === 'function') {
+    return stdout ? host.npm({ args, stdout: true }) : host.npm({ args, stdio });
+  }
+  return runNpmLocal(args, { stdout, stdio });
+}
+
 /** Latest published version of `name` per the npm registry (throws on failure). */
 function npmLatestVersion(name) {
-  const res = spawnSync('npm', ['view', name, 'version'], { encoding: 'utf8' });
-  if (res.error) throw new Error(res.error.message);
-  if (res.status !== 0) {
-    throw new Error((res.stderr || '').trim() || `npm view exited ${res.status}`);
-  }
-  return res.stdout.trim();
+  const { stdout } = runNpm(['view', name, 'version'], { stdout: true });
+  return stdout.trim();
 }
 
 /** True when this plugin lives under npm's global node_modules (so `-g` updates it). */
 function isGlobalInstall() {
-  const res = spawnSync('npm', ['root', '-g'], { encoding: 'utf8' });
-  if (res.status !== 0) return false;
-  const root = res.stdout.trim();
+  let root;
+  try {
+    root = runNpm(['root', '-g'], { stdout: true }).stdout.trim();
+  } catch {
+    return false;
+  }
   return Boolean(root) && pluginDir.startsWith(root);
 }
 
@@ -2811,9 +3078,9 @@ function updatePlugin(req) {
   const where = info.mode === 'managed' ? 'the c8ctl plugin store' : "npm's global prefix";
   console.log(`Pulling ${name}@${latest} into ${where}...`);
   console.log('');
-  const res = spawnSync('npm', installArgs, { stdio: 'inherit' });
-  if (res.error) throw new Error(res.error.message);
-  if (res.status !== 0) {
+  try {
+    runNpm(installArgs, { stdio: 'inherit' });
+  } catch (err) {
     let hint;
     if (info.mode === 'managed') {
       hint = `You can also run:\n${manual}`;
@@ -2822,8 +3089,9 @@ function updatePlugin(req) {
     } else {
       hint = `You may need elevated permissions: sudo ${manual.trim()}`;
     }
+    const code = typeof err?.status === 'number' ? ` (exit ${err.status})` : '';
     throw new Error(
-      `npm ${installArgs.join(' ')} failed (exit ${res.status}). ${hint}`,
+      `npm ${installArgs.join(' ')} failed${code}. ${hint}`,
     );
   }
   console.log('');
@@ -2883,13 +3151,28 @@ function updateNotifierDisabled() {
  * fresh result is used on the *next* invocation.
  */
 function spawnUpdateRefresh(name, cacheFile) {
+  // The refresh runs in a detached bare-node child that has no host runtime, so
+  // it cannot use c8ctl.npm. Resolve the portable npm invocation here (single
+  // source of truth) and bake the decided command into a generic runner in the
+  // child — the child makes no platform decision of its own.
+  let inv;
+  try {
+    inv = buildNpmInvocation(['view', name, 'version']);
+  } catch {
+    return; /* unsafe argument for cmd.exe; skip this cycle */
+  }
   const script =
-    'const{spawnSync}=require("child_process");' +
+    'const{execFileSync,execSync}=require("child_process");' +
     'const{readFileSync,writeFileSync}=require("fs");' +
+    `const cmd=${JSON.stringify(inv.command)},args=${JSON.stringify(inv.args)},shell=${JSON.stringify(inv.shell)};` +
     `let prev={};try{prev=JSON.parse(readFileSync(${JSON.stringify(cacheFile)},"utf8"))}catch{}` +
     'const out=Object.assign({},prev,{lastCheck:Date.now()});' +
-    `const r=spawnSync("npm",["view",${JSON.stringify(name)},"version"],{encoding:"utf8"});` +
-    'if(r.status===0){out.latest=String(r.stdout||"").trim()}' +
+    'try{' +
+    'const o=shell' +
+    '?execSync([cmd,...args].join(" "),{stdio:["ignore","pipe","pipe"],encoding:"utf8"})' +
+    ':execFileSync(cmd,args,{stdio:["ignore","pipe","pipe"],encoding:"utf8",shell:false});' +
+    'out.latest=String(o||"").trim()' +
+    '}catch{}' +
     `try{writeFileSync(${JSON.stringify(cacheFile)},JSON.stringify(out))}catch{}`;
   try {
     const child = spawn(process.execPath, ['-e', script], { detached: true, stdio: 'ignore' });
@@ -3864,6 +4147,7 @@ function parseProcessosRequest(args, flags) {
 // Internal helpers exported for tests/tooling only. c8ctl consumes just
 // `metadata` and `commands`; these named exports are inert to it.
 export { resolveBinary, findBinary, launcherEnvMarkers };
+export { buildNpmInvocation };
 export {
   normalizeTaskEnvelope,
   collectEnvelopeFrom,
@@ -3875,6 +4159,10 @@ export {
   hostEnvSecretResolver,
   buildAgentPayload,
   buildResultEnvelope,
+  parseAgentResultObject,
+  readAgentResultFile,
+  parseResultFromStdout,
+  sanitizeResultVars,
   parseEnvPairs,
   normalizeEnvMap,
   reapAgentContainers,
@@ -3893,6 +4181,8 @@ export {
   jobTypeMatrix,
   AGENT_TASK_NS,
   AGENT_RESULT_KEY,
+  RESULT_SENTINEL,
+  RESERVED_RESULT_KEYS,
   SANDBOXES,
 };
 
@@ -3987,6 +4277,7 @@ export const commands = {
       '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)' },
@@ -4133,7 +4424,7 @@ function printUsage() {
   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>] [--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]');
+  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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.11.0",
+  "version": "1.13.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.11.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.11.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.11.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.11.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.11.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.11.0",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.11.0"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.13.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.13.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.13.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.13.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.13.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.13.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.13.0"
   }
 }