@the-open-engine/zeroshot 6.5.0 → 6.7.0

package/bin/zeroshot-cluster-worker.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+'use strict';
+
+const {
+  bindProcessLifecycle,
+  redirectConsoleToStderr,
+} = require('../lib/cluster-worker/process-stdio');
+
+// stdout is the worker protocol transport. Route ambient engine logging away
+// from it before constructing the production adapter.
+redirectConsoleToStderr();
+
+const { runClusterWorkerExecutable } = require('../lib/cluster-worker/executable');
+
+const runtime = runClusterWorkerExecutable();
+bindProcessLifecycle(runtime);

package/cli/index.js

@@ -73,9 +73,13 @@ const { runInspectCommand } = require('./commands/inspect');
 const { runCmdproof } = require('./commands/cmdproof');
 const {
   markDetachedSetupFailed,
+  patchDetachedResumeCluster,
   registerDetachedSetupCluster,
   removeDetachedSetupCluster,
+  revertDetachedResumeCluster,
+  waitForResumeOwnership,
 } = require('../lib/detached-startup');
+const { isProcessRunning: isClusterProcessAlive } = require('../lib/process-liveness');
 // Setup wizard removed - use: zeroshot settings set <key> <value>
 const { checkForUpdates, printLegacyDistroNotice } = require('./lib/update-checker');
 const { checkBinDirOnPath, printPathWarning } = require('../lib/path-check');
@@ -245,12 +249,12 @@ function printDetachedClusterStart(options, clusterId, logPath) {
   console.log(`Attach:  zeroshot attach ${clusterId}`);
 }
 
-function createDaemonLogFile(clusterId) {
+function createDaemonLogFile(logName) {
   const storageDir = path.join(os.homedir(), '.zeroshot');
   if (!fs.existsSync(storageDir)) {
     fs.mkdirSync(storageDir, { recursive: true });
   }
-  const logPath = path.join(storageDir, `${clusterId}-daemon.log`);
+  const logPath = path.join(storageDir, `${logName}-daemon.log`);
   return fs.openSync(logPath, 'w');
 }
 
@@ -291,17 +295,32 @@ function buildDaemonEnv(options, clusterId, targetCwd, stdinText) {
   };
 }
 
-async function spawnDetachedCluster(options, clusterId, stdinText) {
+// Generic detached-child primitive shared by `run --detach` and
+// `resume --detach`: spawn a re-invocation of this same CLI (same argv) with
+// daemon env vars set, detach it from this process, and return its PID.
+// Callers own registering/patching cluster state around the spawn - this
+// function knows nothing about run vs. resume.
+function spawnDetachedChild(env, cwd, logFd) {
   const { spawn } = require('child_process');
-  const logFd = createDaemonLogFile(clusterId);
-  const targetCwd = detectGitRepoRoot();
-  const logPath = path.join(os.homedir(), '.zeroshot', `${clusterId}-daemon.log`);
   const daemon = spawn(process.execPath, process.argv.slice(1), {
     detached: true,
     stdio: ['ignore', logFd, logFd],
-    cwd: targetCwd,
-    env: buildDaemonEnv(options, clusterId, targetCwd, stdinText),
+    cwd,
+    env,
   });
+  daemon.unref();
+  return daemon;
+}
+
+async function spawnDetachedCluster(options, clusterId, stdinText) {
+  const logFd = createDaemonLogFile(clusterId);
+  const targetCwd = detectGitRepoRoot();
+  const logPath = path.join(os.homedir(), '.zeroshot', `${clusterId}-daemon.log`);
+  const daemon = spawnDetachedChild(
+    buildDaemonEnv(options, clusterId, targetCwd, stdinText),
+    targetCwd,
+    logFd
+  );
   await registerDetachedSetupCluster({
     clusterId,
     pid: daemon.pid,
@@ -310,11 +329,53 @@ async function spawnDetachedCluster(options, clusterId, stdinText) {
     runOptions: options,
     cwd: targetCwd,
   });
-  daemon.unref();
   fs.closeSync(logFd);
   printDetachedClusterStart(options, clusterId, logPath);
 }
 
+// Resume's daemon env is deliberately NOT buildDaemonEnv: run-only keys like
+// ZEROSHOT_DOCKER/ZEROSHOT_WORKTREE/ZEROSHOT_PR are derived by resume from
+// the cluster's own persisted state, and spreading them here would fight
+// that. The resumed process needs only to know it's the daemon and which
+// cluster it owns; `id`/`prompt` already travel as plain argv (commander
+// re-parses the same argv in the child), not through env.
+function buildResumeDaemonEnv(clusterId, targetCwd) {
+  return {
+    ...process.env,
+    ZEROSHOT_DAEMON: '1',
+    ZEROSHOT_CLUSTER_ID: clusterId,
+    ZEROSHOT_CWD: targetCwd,
+  };
+}
+
+// Parent-side half of `resume --detach`: spawn the daemon, then atomically
+// hand it ownership of the cluster record (patchDetachedResumeCluster).
+// If another live daemon already owns this cluster (a concurrent resume
+// won the race), abort and kill the child we just spawned rather than
+// leaving a duplicate process running.
+async function spawnDetachedResume(clusterId) {
+  const logFd = createDaemonLogFile(`${clusterId}-resume`);
+  const targetCwd = detectGitRepoRoot();
+  const logPath = path.join(os.homedir(), '.zeroshot', `${clusterId}-resume-daemon.log`);
+  const storageDir = path.join(os.homedir(), '.zeroshot');
+  const daemon = spawnDetachedChild(buildResumeDaemonEnv(clusterId, targetCwd), targetCwd, logFd);
+
+  try {
+    await patchDetachedResumeCluster({ clusterId, daemonPid: daemon.pid, storageDir });
+  } catch (patchError) {
+    try {
+      process.kill(daemon.pid, 'SIGTERM');
+    } catch {
+      // Already gone - nothing to clean up.
+    }
+    fs.closeSync(logFd);
+    throw patchError;
+  }
+
+  fs.closeSync(logFd);
+  return { pid: daemon.pid, logPath };
+}
+
 function resolveClusterId(generateName) {
   const clusterId = process.env.ZEROSHOT_CLUSTER_ID || generateName('cluster');
   process.env.ZEROSHOT_CLUSTER_ID = clusterId;
@@ -3214,9 +3275,70 @@ program
           provider: providerName,
         });
 
+        // === DETACH HANDOFF: hand the resume off to a daemon and return ===
+        // This is the parent's half only - it never calls orchestrator.resume()
+        // itself. Fail fast here (before spawning anything) on the same
+        // liveness check orchestrator.resume() would otherwise apply, so a
+        // cluster that's genuinely still running doesn't waste a daemon spawn.
+        if (shouldRunDetached(options)) {
+          if (cluster.state === 'running' && isClusterProcessAlive(cluster.pid)) {
+            throw new Error(
+              `Cluster ${id} is still running. Use 'zeroshot stop' first if you want to restart it.`
+            );
+          }
+          orchestrator.close();
+          const { pid, logPath } = await spawnDetachedResume(id);
+          console.log(chalk.green(`✓ Resume daemon started for ${id}`));
+          console.log(`  Daemon PID: ${pid}`);
+          console.log(`  Daemon log: ${logPath}`);
+          console.log('');
+          console.log(chalk.dim(`Monitor: zeroshot logs ${id} -f`));
+          console.log(chalk.dim(`Status:  zeroshot status ${id}`));
+          return;
+        }
+
+        // === DAEMON SIDE: this process IS the spawned resume daemon ===
+        // Wait for the parent's atomic pid/state patch to name *this* PID as
+        // owner before touching the cluster - closes the gap between spawn()
+        // returning a PID and that patch landing, so a daemon that lost a
+        // concurrent resume --detach race never gets to call resume() at all.
+        const isResumeDaemon =
+          Boolean(options.detach) &&
+          process.env.ZEROSHOT_DAEMON === '1' &&
+          process.env.ZEROSHOT_CLUSTER_ID === id;
+
+        if (isResumeDaemon) {
+          const storageDir = path.join(os.homedir(), '.zeroshot');
+          const owned = await waitForResumeOwnership({
+            clusterId: id,
+            daemonPid: process.pid,
+            storageDir,
+          });
+          if (!owned) {
+            console.error(
+              chalk.red(
+                `Resume daemon for ${id} never received ownership handoff from parent process; aborting.`
+              )
+            );
+            process.exit(1);
+          }
+        }
+
         // Resume cluster
         console.log(chalk.cyan(`Resuming cluster ${id}...`));
-        const result = await orchestrator.resume(id, prompt);
+        let result;
+        try {
+          result = await orchestrator.resume(id, prompt);
+        } catch (resumeError) {
+          if (isResumeDaemon) {
+            await revertDetachedResumeCluster({
+              clusterId: id,
+              storageDir: path.join(os.homedir(), '.zeroshot'),
+              error: resumeError,
+            });
+          }
+          throw resumeError;
+        }
 
         console.log(chalk.green(`✓ Cluster resumed`));
         if (result.resumeType === 'failure') {
@@ -3232,8 +3354,9 @@ program
           }
         }
 
-        // === DAEMON MODE: Exit and let cluster run in background ===
-        if (options.detach) {
+        // === DAEMON MODE: stay alive in the background, let signals stop the cluster ===
+        if (isResumeDaemon) {
+          setupDaemonCleanup(orchestrator, id);
           console.log('');
           console.log(chalk.dim(`Follow logs with: zeroshot logs ${id} -f`));
           return;

package/docs/openengine-cluster-protocol/v1/legacy-worker.md

@@ -0,0 +1,117 @@
+# Legacy Zeroshot cluster worker
+
+`createLegacyClusterWorker()` exposes the current Node Zeroshot engine as the bounded
+`legacy.zeroshot.ship@1` worker. It is an implementation binding for a parent process, not an Open
+Engine Cluster Protocol transport or a graph executor.
+
+```js
+const { createLegacyClusterWorker } = require('@the-open-engine/zeroshot/lib/cluster-worker');
+
+const worker = createLegacyClusterWorker({
+  profileRegistry,
+  artifactResolver,
+  artifactReceiptSink,
+  engineAdapter,
+});
+
+await worker.start({
+  source: 'issue',
+  issue: 'https://github.com/example/project/issues/123',
+  artifacts: [],
+  isolationProfile: 'isolation.worktree@1',
+  providerProfile: 'provider.default@1',
+});
+
+for await (const event of worker.events()) {
+  // Live lifecycle transitions only; no durable cursor or replay guarantee.
+}
+
+const receipt = await worker.result();
+```
+
+The five public operations are `start(request)`, `status()`, `events()`, `stop()`, and `result()`.
+One facade owns at most one cluster. There is no guidance, permission, authentication, writable
+attach, or arbitrary-input operation.
+
+## Closed input
+
+Requests validate against the generated `LegacyShipRequest` schema. They select exactly one source:
+
+- `issue`: nonempty `issue`, no prompt, and no artifacts;
+- `prompt`: nonempty `prompt`, no issue, and no artifacts;
+- `artifact`: one or more byte-free `ArtifactRef` receipts and no issue or prompt.
+
+`isolationProfile` and `providerProfile` are opaque registry handles. Unknown fields are rejected,
+so payloads cannot carry credentials, tokens, environment maps, endpoints, models, timeouts,
+filesystem paths, commands, or launch flags. The production deployment registry resolves only
+worktree, Docker, PR, or ship isolation. A missing, unknown, or non-isolated profile fails before
+the engine allocates a ledger, worktree, or container.
+
+Artifact input fails before allocation unless the embedding product injects a real resolver. After
+the engine allocates the worktree or Docker workspace but before any agent starts, that resolver
+materializes declared receipts as read-only content inside the allocated isolation and returns an
+engine-private, byte-free manifest. Echoing receipts without making their content readable is not a
+resolver. Artifact receipt sinks convert declared durable output to canonical byte-free receipts.
+Without a sink, successful output contains an empty artifact list. Raw provider and agent output
+remains engine diagnostic data and never enters the stable result.
+
+## Lifecycle and termination
+
+The monotonic lifecycle is `idle`, `starting`, `running`, optional `stopping`, then exactly one of
+`completed`, `failed`, `timed_out`, `stopped`, or `malformed`. Completion and failure are folded from
+the engine cluster record and durable `CLUSTER_COMPLETE` or `CLUSTER_FAILED` ledger messages. PID
+liveness can add diagnostics but cannot manufacture success.
+
+Completion, declared failure, malformed output, the registry-owned execution deadline, and explicit
+stop race under one terminal latch. The first accepted authority is immutable; late messages do not
+change the receipt or emit another terminal event. Profile resolution, artifact staging, engine
+start, and artifact receipt collection all remain within that deadline and can be preempted by
+explicit stop. Completion becomes authoritative only after its canonical receipt has been bounded
+and validated, so a stalled receipt sink cannot suppress timeout or stop. Profile resolution,
+artifact staging, and receipt collection receive one cancellation signal. If an injected operation
+ignores that signal and completes late, its registry `release` or port `cleanup` hook retains
+resource ownership and runs after the terminal receipt is fixed. A late operation or cleanup
+failure is reported through the injected cleanup-failure reporter, or as a process warning when no
+reporter is configured; it is never silently discarded or allowed to rewrite terminal truth.
+
+A synchronous pre-allocation rejection leaves the facade idle and releases its one-start claim.
+`stop()` and `result()` then reject as not started, and the caller may retry with a valid request.
+
+`stop()` delegates to the engine stop path and waits no longer than the deployment profile's
+shutdown deadline. It reports `effective: false` when the engine rejects or does not acknowledge
+stop in time. The acknowledgement deadline does not abandon resource ownership: if engine
+allocation occurs later while start is still pending, background cleanup stops that cluster. Stop
+always reports
+`externalEffectsRolledBack: false`: provider, repository, or tool side effects may already have
+happened.
+
+Engine completion must contain either a canonical `LegacyShipResult` or an explicit bounded summary.
+Engine failures must contain a valid closed error-code/reason pair. Missing completion data, invalid
+failure values, and invalid failure pairs terminate as `malformed`; the facade never fills them with
+success or crash defaults. Engine status observation is synchronous so a durable-ledger observation
+failure can immediately fail closed instead of becoming an unobserved rejected promise.
+
+## Executable
+
+`zeroshot-cluster-worker` reads bounded NDJSON commands from stdin and writes only NDJSON protocol
+frames to stdout. Diagnostics use stderr. A process owns one worker resource.
+
+```json
+{"id":"1","method":"start","params":{"request":{"source":"prompt","prompt":"Run task","artifacts":[],"isolationProfile":"isolation.docker@1","providerProfile":"provider.default@1"}}}
+{"id":"2","method":"status","params":{}}
+{"id":"3","method":"events","params":{}}
+{"id":"4","method":"result","params":{}}
+{"id":"5","method":"stop","params":{}}
+```
+
+Responses are `{ "type": "response", "id", "ok", "result" }` or contain a closed error object.
+An `events` subscription also receives `{ "type": "event", "id", "event" }` frames. Arrays,
+malformed or oversized JSON, unknown methods, unknown parameters, and duplicate starts fail closed.
+EOF, SIGINT, and SIGTERM request explicit stop and wait no longer than the shutdown deadline. They do
+not imply rollback. Cleanup that settles inside that executable deadline is drained; if allocation
+never registers or settles, the process invokes its internal adapter-release port and exits at the
+deadline without adding a sixth public worker operation.
+
+`result` and `stop` race the in-flight `start` operation against terminal receipt availability. A
+startup timeout or allocated-engine start failure therefore returns canonical terminal truth even
+when the adapter's original start promise never fulfills.

package/lib/cluster-worker/contracts.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const path = require('path');
+const Ajv2020 = require('ajv/dist/2020');
+const workerSchema = require(
+  path.join('..', '..', 'protocol', 'openengine-cluster', 'v1', 'worker.schema.json')
+);
+
+const MAX_SUMMARY_BYTES = 4096;
+const METHODS = Object.freeze(['start', 'status', 'events', 'stop', 'result']);
+const TERMINAL_STATES = Object.freeze(['completed', 'failed', 'timed_out', 'stopped', 'malformed']);
+
+const ajv = new Ajv2020({ allErrors: true, strict: false, allowUnionTypes: true });
+
+function compileDefinition(name) {
+  if (!workerSchema.$defs[name]) {
+    throw new Error(`Worker schema definition ${name} is missing`);
+  }
+  return ajv.compile({ $ref: `#/$defs/${name}`, $defs: workerSchema.$defs });
+}
+
+const validators = Object.freeze({
+  LegacyShipRequest: compileDefinition('LegacyShipRequest'),
+  LegacyShipResult: compileDefinition('LegacyShipResult'),
+  WorkerOutcome: compileDefinition('WorkerOutcome'),
+  ArtifactRef: compileDefinition('ArtifactRef'),
+});
+
+function formatErrors(errors) {
+  return (errors || []).map((error) => `${error.instancePath || '/'} ${error.message}`).join('; ');
+}
+
+function assertDefinition(name, value) {
+  const validate = validators[name];
+  if (!validate(value)) {
+    const error = new TypeError(`Invalid ${name}: ${formatErrors(validate.errors)}`);
+    error.code = 'INVALID_CONTRACT';
+    error.validationErrors = validate.errors;
+    throw error;
+  }
+  return value;
+}
+
+function byteLength(value) {
+  return Buffer.byteLength(value, 'utf8');
+}
+
+function assertBoundedSummary(summary) {
+  if (typeof summary !== 'string' || byteLength(summary) > MAX_SUMMARY_BYTES) {
+    throw new TypeError(`Summary must be a string of at most ${MAX_SUMMARY_BYTES} UTF-8 bytes`);
+  }
+  return summary;
+}
+
+function validateLegacyShipRequest(value) {
+  return assertDefinition('LegacyShipRequest', value);
+}
+
+function validateLegacyShipResult(value) {
+  assertDefinition('LegacyShipResult', value);
+  assertBoundedSummary(value.summary);
+  return value;
+}
+
+function validateWorkerOutcome(value) {
+  return assertDefinition('WorkerOutcome', value);
+}
+
+function validateArtifactRef(value) {
+  return assertDefinition('ArtifactRef', value);
+}
+
+function assertPlainObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+}
+
+function assertExactKeys(value, allowed, label) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new TypeError(`${label} contains unknown fields: ${unknown.join(', ')}`);
+  }
+}
+
+function validateCommandFrame(value) {
+  assertPlainObject(value, 'Command frame');
+  assertExactKeys(value, ['id', 'method', 'params'], 'Command frame');
+  if (
+    !(
+      (typeof value.id === 'string' && value.id.length > 0 && value.id.length <= 128) ||
+      (Number.isSafeInteger(value.id) && value.id >= 0)
+    )
+  ) {
+    throw new TypeError(
+      'Command frame id must be a nonempty string up to 128 characters or a nonnegative integer'
+    );
+  }
+  if (!METHODS.includes(value.method)) {
+    throw new TypeError(`Unknown worker method: ${String(value.method)}`);
+  }
+  assertPlainObject(value.params, 'Command frame params');
+  if (value.method === 'start') {
+    assertExactKeys(value.params, ['request'], 'start params');
+    if (!Object.prototype.hasOwnProperty.call(value.params, 'request')) {
+      throw new TypeError('start params require request');
+    }
+    validateLegacyShipRequest(value.params.request);
+  } else {
+    assertExactKeys(value.params, [], `${value.method} params`);
+  }
+  return value;
+}
+
+function validateLifecycleStatus(value) {
+  assertPlainObject(value, 'Lifecycle status');
+  assertExactKeys(
+    value,
+    ['state', 'clusterId', 'sequence', 'stopRequested', 'terminal'],
+    'Lifecycle status'
+  );
+  const states = ['idle', 'starting', 'running', 'stopping', ...TERMINAL_STATES];
+  if (!states.includes(value.state)) throw new TypeError(`Invalid lifecycle state: ${value.state}`);
+  if (value.clusterId !== null && typeof value.clusterId !== 'string') {
+    throw new TypeError('Lifecycle clusterId must be a string or null');
+  }
+  if (!Number.isSafeInteger(value.sequence) || value.sequence < 0) {
+    throw new TypeError('Lifecycle sequence must be a nonnegative integer');
+  }
+  if (typeof value.stopRequested !== 'boolean') {
+    throw new TypeError('Lifecycle stopRequested must be boolean');
+  }
+  if (value.terminal !== TERMINAL_STATES.includes(value.state)) {
+    throw new TypeError('Lifecycle terminal flag does not match state');
+  }
+  return value;
+}
+
+function validateCompletedReceipt(value) {
+  assertExactKeys(value, ['state', 'clusterId', 'finishedAt', 'result'], 'Terminal receipt');
+  validateLegacyShipResult(value.result);
+}
+
+function validateStoppedReceipt(value) {
+  assertExactKeys(value, ['state', 'clusterId', 'finishedAt', 'stop'], 'Terminal receipt');
+  assertPlainObject(value.stop, 'Stop receipt');
+  assertExactKeys(
+    value.stop,
+    ['requested', 'effective', 'externalEffectsRolledBack'],
+    'Stop receipt'
+  );
+  const valid =
+    value.stop.requested === true &&
+    typeof value.stop.effective === 'boolean' &&
+    value.stop.externalEffectsRolledBack === false;
+  if (!valid) throw new TypeError('Invalid stop receipt');
+}
+
+function validateFailureReceipt(value) {
+  assertExactKeys(value, ['state', 'clusterId', 'finishedAt', 'outcome'], 'Terminal receipt');
+  validateWorkerOutcome(value.outcome);
+  if (value.outcome.status !== 'error')
+    throw new TypeError('Failure receipt requires error outcome');
+}
+
+function validateTerminalReceipt(value) {
+  assertPlainObject(value, 'Terminal receipt');
+  if (!TERMINAL_STATES.includes(value.state)) {
+    throw new TypeError(`Invalid terminal receipt state: ${value.state}`);
+  }
+  if (typeof value.clusterId !== 'string' || !value.clusterId) {
+    throw new TypeError('Terminal receipt requires clusterId');
+  }
+  if (!Number.isFinite(value.finishedAt)) {
+    throw new TypeError('Terminal receipt requires numeric finishedAt');
+  }
+  if (value.state === 'completed') validateCompletedReceipt(value);
+  else if (value.state === 'stopped') validateStoppedReceipt(value);
+  else validateFailureReceipt(value);
+  return value;
+}
+
+module.exports = {
+  MAX_SUMMARY_BYTES,
+  METHODS,
+  TERMINAL_STATES,
+  validateLegacyShipRequest,
+  validateLegacyShipResult,
+  validateWorkerOutcome,
+  validateArtifactRef,
+  validateCommandFrame,
+  validateLifecycleStatus,
+  validateTerminalReceipt,
+};