@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/launch/README.md

@@ -0,0 +1,214 @@
+# pa launch — agent launcher
+
+Identity: `@stravica-ai/engineering-pa-cli` › `launch` — boot a scoped agent instance bound to an identity and task.
+
+## Status
+
+**Shipped.** Handles single-agent single-task execution against any operator repo with roster and schedule files. Dry-run mode. Audit log per tooling standard §15. Per-task concurrency lock, default-on (see "Concurrency lock" below).
+
+## Install / invoke
+
+```bash
+# Via pa top-level CLI
+pnpm exec pa launch --agent=<name> --task=<id> [--dry-run]
+
+# Via standalone bin
+pnpm exec launch --agent=<name> --task=<id> [--dry-run]
+```
+
+## Commands
+
+### `launch --agent=<name> --task=<id> [--dry-run]`
+
+Boots a scoped agent instance:
+
+1. Resolves the operator repo root (`DAVE_REPO_ROOT` / `PA_REPO_ROOT` env var, or `.git` walk from `cwd`).
+2. Loads identity from `operator/knowledge/hr/roster/<name>.json`.
+3. Loads task definition from `schedules/<id>.json`.
+4. Builds a `LaunchPlan` (pure — no I/O).
+5. On `--dry-run`: prints the plan as JSON, exits 0.
+6. Otherwise: via the chokepoint runner — creates intake folder, spawns task command, writes audit record.
+
+**Flags:**
+
+| Flag | Required | Description |
+|---|---|---|
+| `--agent` | yes | Agent name — maps to `operator/knowledge/hr/roster/<name>.json` |
+| `--task` | yes | Task ID — maps to `schedules/<id>.json` |
+| `--dry-run` | no | Print LaunchPlan as JSON; skip execution and audit write |
+| `-h`, `--help` | no | Show usage |
+
+## Identity file schema
+
+Loaded from `operator/knowledge/hr/roster/<name>.json`. **Format: JSON.** No YAML/frontmatter parser — the roster is already JSON across the platform.
+
+Required fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | string | Agent identifier (must match filename stem) |
+| `name` | string | Display name |
+| `roleId` | string | Role identifier (e.g. `system-admin`) |
+| `runFolder` | string | Path relative to repo root (e.g. `agents/ian`) |
+| `status` | string | Agent status (`active` \| other) |
+
+Optional fields (`currentTeam`, `createdBy`, `createdDate`, `history`) are preserved but not read by the launcher.
+
+## Task definition schema
+
+Loaded from `schedules/<id>.json`. **Format: JSON.**
+
+Required fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | string | Task identifier (must match filename stem) |
+| `command` | string | Command to execute — split on whitespace, passed to `spawn` without a shell. **Must not contain `'` or `"`** (no shell-quoting — see below) |
+
+Optional fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `workingDirectory` | string | cwd for spawn; supports `${DAVE_ROOT}`, `${PA_REPO_ROOT}`, `${DAVE_REPO_ROOT}` tokens |
+| `name` | string | Display name |
+| `description` | string | Human-readable description |
+| `schedule` | string | Cron expression (read by cron — not used by launcher) |
+| `enabled` | boolean | Read by scheduler — not used by launcher |
+| `lockStaleAfterMinutes` | number | Per-task staleness override for the concurrency lock (see below). Default: the core lock's 2-hour threshold |
+
+## `command` is not a shell expression
+
+The runner spawns the command **directly** — no shell, no expansion, no operators. The string is split on whitespace and handed to `child_process.spawn()` as `(bin, args[])`.
+
+If the command contains `'` or `"`, `task-loader` rejects it at load time with exit code 2 (a `--dry-run` also fails). This is a deliberate guard: silently splitting `bash -c "a && b"` on whitespace shreds it to `spawn('bash', ['-c', '"a', '&&', 'b"'])`, bash exits 2 with `unexpected EOF`, and cron mails the operator every interval until someone notices.
+
+If you need shell features, you have two options:
+
+1. **Wrap the work in a script file** and put the script path in `command`: `command: "/path/to/wrapper.sh"`. The runner spawns the script; the script does whatever it likes.
+2. **Move the shell wrapper to the cron entry**, not the task command. The scheduler installer can take a quoted bash invocation in the cron crontab; the launcher's `command` field cannot.
+
+## Concurrency lock (default-on)
+
+Two runs of the **same task** must not overlap — a second concurrent run
+consumes the same inputs (staging areas) and produces duplicate effects and
+git races. Every non-dry-run launch therefore acquires a per-task lock via
+the shared core utility (`@stravica-ai/engineering-pa-core` › `acquireLock` —
+full contract in `packages/core/docs/lock.md`) before spawning. No opt-in
+flag; protection is the default.
+
+- **Lock path:** `<repoRoot>/.cache/launch/<taskId>.lock` — per task, so two
+  *different* tasks overlap freely. `.cache/` is the gitignored
+  operational-state area (tooling standard §16).
+- **On contention** (live same-task lock): the run **exits 0** with a
+  greppable skip line on stdout —
+  `[launch] <agent>/<task>: skipped — lock held (held by pid <pid> since <ts>; lock <path>)`
+  — writes a `noop-locked` audit record, and spawns nothing. Exit 0 (not 2)
+  because an overlap skip is a healthy no-op on a cron schedule, matching
+  `sync`'s `noop-locked` precedent; exit 2 would generate cron mail for
+  expected behaviour. Automation that needs to detect skips reads the audit
+  record or greps the log line.
+- **Stale locks are broken automatically** with a
+  `[launch] warning: broke stale lock ...` line on stderr, and the run
+  proceeds. Staleness: dead pid (primary — recovers crashed runs
+  immediately), or age past the threshold (backstop for pid reuse /
+  unreadable lock files). Threshold: the core default of **2 hours**
+  (sized so legitimately long sweeps — observed 1288+ seconds — are never
+  stolen mid-run), overridable per task via `lockStaleAfterMinutes` in
+  `schedules/<id>.json`.
+- **Release:** on every exit path (success, task failure, spawn error). A
+  crashed run leaves a dead-pid lock that the next tick breaks.
+- **First run:** no lock file or `.cache/launch/` directory needed; the
+  empty state is the common case.
+
+## LaunchPlan object
+
+The planner produces a `LaunchPlan` (JSON-serialisable, no I/O):
+
+```jsonc
+{
+  "repoRoot": "/abs/path/to/operator-repo",
+  "agent": { "id": "ian", "name": "Ian", "roleId": "system-admin", "runFolder": "agents/ian" },
+  "task": { "id": "upstream-triage", "command": "node ...", "workingDirectory": null, "description": null },
+  "intakeFolderPath": "/abs/path/to/agents/ian/staging",
+  "auditLogPath": "/abs/path/to/agents/ian/runs.jsonl",
+  "lockPath": "/abs/path/to/.cache/launch/upstream-triage.lock",
+  "lockStaleAfterMs": null // null = core default (2 h); set via task lockStaleAfterMinutes
+}
+```
+
+## Chokepoint discipline
+
+`runner.mjs` is the **sole module** that:
+- Creates directories (`mkdir`)
+- Appends audit records (`appendFile`)
+- Acquires/releases the per-task concurrency lock
+- Spawns child processes (`spawn`)
+
+The lock lives in the chokepoint so programmatic callers cannot bypass it:
+a plan handed to `execute()` without a `lockPath` still gets a derived
+per-task lock.
+
+All other modules (`identity.mjs`, `task-loader.mjs`, `planner.mjs`) are pure — no I/O, no spawning. Tests inject a fake spawner into the runner; no mock libraries.
+
+Launched agents **must not** do git operations. They write files to disk; the sync tool (`pa sync`) picks up changes on its tick.
+
+## Exit codes (tooling standard §6)
+
+| Code | Meaning |
+|---|---|
+| `0` | OK |
+| `1` | Usage error (missing flags, unknown flag) |
+| `2` | Logical failure (agent not found, task not found, missing required field) |
+| `3` | Transport / IO failure (file unreadable, spawn failed) |
+
+## Audit record contract (tooling standard §15)
+
+Every non-dry-run exit path appends one JSON line to `<runFolder>/runs.jsonl`:
+
+```jsonc
+{ "ts": "2026-05-17T12:00:00Z", "status": "ok", "agentId": "ian", "taskId": "upstream-triage", "exitCode": 0 }
+```
+
+`status` vocabulary: `ok` | `noop-locked` | `fail-exit-<N>` | `fail-spawn`
+
+`noop-locked` records carry a `reason` field naming the lock holder
+(`"lock contention: held by pid <pid> since <ts>"`). Per §15 monitors treat
+`noop-*` as healthy/fresh.
+
+`runs.jsonl` is an operational artefact — it must be gitignored in the operator repo. It is never committed.
+
+## Project layout
+
+```
+packages/cli/src/launch/
+  README.md             this file — the contract
+  cli.mjs               arg parsing, flag validation, exit-code translation
+  commands/
+    launch.mjs          thin glue: load → plan → execute
+  identity.mjs          pure: load + validate agent identity from roster JSON
+  task-loader.mjs       pure: load + validate task definition from schedules JSON
+  planner.mjs           pure: build LaunchPlan object (no I/O)
+  repo-root.mjs         pure: operator repo root discovery (env var + .git walk)
+  runner.mjs            CHOKEPOINT: all file writes + process spawn
+packages/cli/test/launch/
+  cli.test.mjs          end-to-end: --help, --dry-run, live execution, error paths
+  identity.test.mjs     unit: happy path, missing agent, invalid JSON, missing field
+  task-loader.test.mjs  unit: happy path, missing task, invalid JSON, missing field
+  planner.test.mjs      unit: output shape, null defaults, purity
+  runner.test.mjs       unit: ok/fail/spawn-error paths via fake spawner
+  fixtures/             synthetic roster + schedule for tests
+```
+
+## Tests
+
+```bash
+# Run launch tests only
+node --test 'packages/cli/test/launch/**/*.test.mjs'
+
+# Run all CLI package tests
+pnpm --filter @stravica-ai/engineering-pa-cli test
+```
+
+## Standards
+
+Follows the [tooling standard](../../../../core/knowledge/standards/tooling.md): Node.js only, zero npm deps, `node:test`, `node:util.parseArgs` with `strict: true`, camelCase JSON, chokepoint pattern (§7), audit record contract (§15), gitignore operational artefacts (§16).

package/dist/engineering-pa-cli/src/launch/cli.mjs

@@ -0,0 +1,51 @@
+// cli.mjs — pa launch: boot a scoped agent instance bound to an identity and task.
+import { parseArgs } from 'node:util';
+
+const USAGE = `pa launch — boot a scoped agent instance bound to an identity and task
+
+Usage:
+  pa launch --agent=<name> --task=<id> [--dry-run]
+  pa launch -h, --help
+
+Options:
+  --agent     Agent name — maps to operator/knowledge/hr/roster/<name>.json
+  --task      Task ID   — maps to schedules/<id>.json
+  --dry-run   Print the LaunchPlan as JSON without executing
+  -h, --help  Show this help
+
+Exit codes (tooling standard §6):
+  0 ok | 1 usage error | 2 operational failure | 3 transport/IO failure
+`;
+
+export async function run(argv) {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        agent: { type: 'string' },
+        task: { type: 'string' },
+        'dry-run': { type: 'boolean', default: false },
+      },
+      strict: true,
+    }));
+  } catch (err) {
+    process.stderr.write(`[pa launch] ${err.message}\n`);
+    process.stderr.write(USAGE);
+    return 1;
+  }
+
+  if (!values.agent || !values.task) {
+    process.stderr.write('[pa launch] --agent and --task are required\n');
+    process.stderr.write(USAGE);
+    return 1;
+  }
+
+  const { executeLaunch } = await import('./commands/launch.mjs');
+  return await executeLaunch(values.agent, values.task, { dryRun: values['dry-run'] });
+}

package/dist/engineering-pa-cli/src/launch/commands/launch.mjs

@@ -0,0 +1,106 @@
+// launch.mjs — thin glue: load identity → load task → build plan → execute.
+import { hostname } from 'node:os';
+
+import { hostMatches } from '../../../../engineering-pa-core/src/scheduler/host.mjs';
+
+import { getRepoRoot } from '../repo-root.mjs';
+import { loadIdentity } from '../identity.mjs';
+import { loadTask } from '../task-loader.mjs';
+import { buildPlan } from '../planner.mjs';
+import { execute } from '../runner.mjs';
+
+// Override env var for the host-enforcement gate below — mirrors
+// `scheduler install`'s `--force-host` CLI flag, but as an env var since
+// `launch` is invoked automatically by cron/launchd/systemd (no operator
+// present to pass a flag). Same override SEMANTICS as install, different
+// delivery mechanism because the calling context is different.
+const FORCE_HOST_ENV = 'DAVE_FORCE_HOST';
+
+export async function executeLaunch(agentName, taskId, { dryRun = false } = {}) {
+  let repoRoot;
+  try {
+    repoRoot = await getRepoRoot();
+  } catch (err) {
+    process.stderr.write(`[launch] ${err.message}\n`);
+    return err.exitCode ?? 2;
+  }
+
+  let identity;
+  try {
+    identity = await loadIdentity(repoRoot, agentName);
+  } catch (err) {
+    process.stderr.write(`[launch] identity: ${err.message}\n`);
+    return err.exitCode ?? 2;
+  }
+
+  let task;
+  try {
+    task = await loadTask(repoRoot, taskId);
+  } catch (err) {
+    process.stderr.write(`[launch] task: ${err.message}\n`);
+    return err.exitCode ?? 2;
+  }
+
+  // Host-enforcement gate — refuse to RUN a task whose schedule file
+  // declares a foreign host, mirroring `scheduler install`'s refusal.
+  // Missing `host` field is not a constraint (data backfill is
+  // estate-side); DAVE_FORCE_HOST=1 overrides a mismatch, same semantics
+  // as install's --force-host, just delivered via env since launch is
+  // invoked non-interactively. --dry-run is judgement-call exempt from
+  // the hard refusal (it never executes anything — a plan preview from a
+  // non-owning host, e.g. a Project Lead debugging another host's task,
+  // is legitimate) but still surfaces the mismatch as a warning so it's
+  // never silently invisible.
+  if (task.host) {
+    const currentHost = hostname();
+    const forceHost = process.env[FORCE_HOST_ENV] === '1' || process.env[FORCE_HOST_ENV] === 'true';
+    if (!hostMatches(task.host, currentHost)) {
+      if (dryRun) {
+        process.stderr.write(
+          `[launch] warning: task "${taskId}" declares host "${task.host}" but this machine is `
+          + `"${currentHost}" — dry-run proceeds (would refuse on a real run without ${FORCE_HOST_ENV}=1)\n`,
+        );
+      } else if (forceHost) {
+        process.stderr.write(
+          `[launch] warning: task "${taskId}" declares host "${task.host}" but this machine is `
+          + `"${currentHost}" — proceeding anyway due to ${FORCE_HOST_ENV}=1\n`,
+        );
+      } else {
+        process.stderr.write(
+          `[launch] task "${taskId}" declares host "${task.host}" but this machine is `
+          + `"${currentHost}" — refusing to run. Set ${FORCE_HOST_ENV}=1 to override.\n`,
+        );
+        return 2;
+      }
+    }
+  }
+
+  const plan = buildPlan(repoRoot, identity, task);
+
+  if (dryRun) {
+    process.stdout.write(JSON.stringify(plan, null, 2) + '\n');
+    return 0;
+  }
+
+  try {
+    const result = await execute(plan);
+    if (result.status === 'noop-locked') {
+      // Overlapping run of the same task — healthy skip, exit 0 (cron
+      // treats it as a no-op; sync's noop-locked precedent). Greppable.
+      process.stdout.write(
+        `[launch] ${agentName}/${taskId}: skipped — lock held (${result.reason}; lock ${result.lockPath})\n`,
+      );
+      return 0;
+    }
+    if (result.status === 'ok') {
+      process.stdout.write(`[launch] ${agentName}/${taskId}: ok (exit ${result.exitCode})\n`);
+      return 0;
+    } else {
+      process.stderr.write(`[launch] ${agentName}/${taskId}: ${result.status} (exit ${result.exitCode})\n`);
+      return 2;
+    }
+  } catch (err) {
+    process.stderr.write(`[launch] runner: ${err.message}\n`);
+    return err.exitCode ?? 3;
+  }
+}

package/dist/engineering-pa-cli/src/launch/identity.mjs

@@ -0,0 +1,43 @@
+// identity.mjs — pure: load + validate an agent identity from the operator roster.
+// Roster path: <repoRoot>/operator/knowledge/hr/roster/<name>.json
+// Required fields: id, name, roleId, runFolder, status
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const REQUIRED_FIELDS = ['id', 'name', 'roleId', 'runFolder', 'status'];
+
+export async function loadIdentity(repoRoot, agentName) {
+  const path = join(repoRoot, 'operator', 'knowledge', 'hr', 'roster', `${agentName}.json`);
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      const e = new Error(`agent "${agentName}" not found in roster (${path})`);
+      e.exitCode = 2;
+      throw e;
+    }
+    const e = new Error(`could not read roster file for "${agentName}": ${err.message}`);
+    e.exitCode = 3;
+    throw e;
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    const e = new Error(`roster file for "${agentName}" is not valid JSON: ${err.message}`);
+    e.exitCode = 2;
+    throw e;
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!data[field]) {
+      const e = new Error(`identity "${agentName}": missing required field "${field}"`);
+      e.exitCode = 2;
+      throw e;
+    }
+  }
+
+  return data;
+}

package/dist/engineering-pa-cli/src/launch/planner.mjs

@@ -0,0 +1,44 @@
+// planner.mjs — pure: produce a LaunchPlan from loaded identity + task.
+// No I/O. No spawning. Returns a plain object.
+import { join } from 'node:path';
+
+/**
+ * LaunchPlan shape:
+ *   repoRoot        — absolute path to the operator repo
+ *   agent           — { id, name, roleId, runFolder }
+ *   task            — { id, command, workingDirectory, description }
+ *   intakeFolderPath — absolute path to agents/<name>/staging/
+ *   auditLogPath     — absolute path to agents/<name>/runs.jsonl
+ *   lockPath         — absolute path to .cache/launch/<taskId>.lock
+ *                      (per-task: two different tasks may overlap freely;
+ *                      two runs of the SAME task must not. `.cache/` is
+ *                      the platform's gitignored operational-state area —
+ *                      tooling standard §16.)
+ *   lockStaleAfterMs — per-task staleness override in ms, from the task's
+ *                      optional `lockStaleAfterMinutes` field; null means
+ *                      "use the core lock default" (2 h — see
+ *                      packages/core/docs/lock.md for the rationale).
+ */
+export function buildPlan(repoRoot, identity, task) {
+  return {
+    repoRoot,
+    agent: {
+      id: identity.id,
+      name: identity.name,
+      roleId: identity.roleId,
+      runFolder: identity.runFolder,
+    },
+    task: {
+      id: task.id,
+      command: task.command,
+      workingDirectory: task.workingDirectory ?? null,
+      description: task.description ?? null,
+    },
+    intakeFolderPath: join(repoRoot, identity.runFolder, 'staging'),
+    auditLogPath: join(repoRoot, identity.runFolder, 'runs.jsonl'),
+    lockPath: join(repoRoot, '.cache', 'launch', `${task.id}.lock`),
+    lockStaleAfterMs: Number.isFinite(task.lockStaleAfterMinutes) && task.lockStaleAfterMinutes > 0
+      ? task.lockStaleAfterMinutes * 60 * 1000
+      : null,
+  };
+}

package/dist/engineering-pa-cli/src/launch/repo-root.mjs

@@ -0,0 +1,53 @@
+// repo-root.mjs — operator repo root discovery for the launch CLI.
+// Mirrors the pattern in packages/core/src/hq/repo.mjs; own copy avoids
+// cross-package coupling for a pure utility.
+import { stat } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+
+async function pathKind(p) {
+  try {
+    const s = await stat(p);
+    if (s.isDirectory()) return 'dir';
+    if (s.isFile()) return 'file';
+    return 'other';
+  } catch {
+    return 'missing';
+  }
+}
+
+export async function findRepoRoot(start) {
+  let d = start;
+  while (d && d !== dirname(d)) {
+    const k = await pathKind(join(d, '.git'));
+    if (k === 'dir' || k === 'file') return d;
+    d = dirname(d);
+  }
+  return null;
+}
+
+let _cache = null;
+
+export async function getRepoRoot() {
+  if (_cache) return _cache;
+  const envRoot = process.env.DAVE_REPO_ROOT || process.env.PA_REPO_ROOT;
+  if (envRoot) {
+    _cache = resolve(envRoot);
+    return _cache;
+  }
+  const found = await findRepoRoot(process.cwd());
+  if (!found) {
+    const err = new Error(
+      'could not find operator repo root from ' + process.cwd() +
+      ' (no .git ancestor; set DAVE_REPO_ROOT or PA_REPO_ROOT to override)',
+    );
+    err.exitCode = 2;
+    throw err;
+  }
+  _cache = found;
+  return _cache;
+}
+
+// Test seam: reset the cached root between test cases.
+export function _resetRepoRoot() {
+  _cache = null;
+}

package/dist/engineering-pa-cli/src/launch/runner.mjs

@@ -0,0 +1,147 @@
+// runner.mjs — CHOKEPOINT: all file writes outside this module + all process spawn.
+//
+// Discipline: pure modules (identity, task-loader, planner) never touch disk.
+// The runner is the sole module that creates directories, appends audit logs,
+// acquires the per-task lock, and spawns child processes. Tests inject a fake
+// spawner to avoid real I/O.
+//
+// Concurrency lock (default-on): before spawning, the runner acquires the
+// per-task lock at plan.lockPath via the shared core utility
+// (packages/core/docs/lock.md). Two runs of the same task must not overlap —
+// the second run returns `noop-locked` (no spawn, audit record written, the
+// caller exits 0 so cron treats the skip as a healthy no-op, matching sync's
+// precedent). Stale locks (dead pid, or older than the staleness threshold —
+// core default 2 h, per-task override via the task's `lockStaleAfterMinutes`)
+// are broken automatically with a logged warning and the run proceeds. The
+// lock is released on every exit path; a crashed run leaves a dead-pid lock
+// that the next tick breaks.
+//
+// Audit record contract (tooling standard §15):
+//   status — "ok" | "noop-locked" | "fail-exit-<N>" | "fail-spawn"
+//   ts     — RFC-3339 (YYYY-MM-DDTHH:MM:SSZ, no milliseconds)
+import { mkdir, appendFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+// Subpath import (not the bare package) — the engineering-pa dist bundle
+// rewrites cross-package import strings to relative paths, and a bare
+// package import would rewrite to a directory path ESM cannot resolve.
+import { acquireLock } from '../../../engineering-pa-core/src/lock/lock.mjs';
+import { assertNoShellQuoting } from './task-loader.mjs';
+
+function resolveWorkdir(workdir, repoRoot) {
+  if (!workdir) return repoRoot;
+  return workdir
+    .replace(/\$\{DAVE_ROOT\}/g, repoRoot)
+    .replace(/\$\{PA_REPO_ROOT\}/g, repoRoot)
+    .replace(/\$\{DAVE_REPO_ROOT\}/g, repoRoot);
+}
+
+/**
+ * Parse a task command string into { bin, args } suitable for spawn().
+ *
+ * Contract: task commands are STRUCTURED (bin + literal args), not shell
+ * expressions. The string is split on whitespace and passed to spawn()
+ * WITHOUT a shell — no quoting, globbing, expansion, or operators are
+ * honoured. Any single (') or double (") quote character in the command
+ * is a configuration error: rejected via assertNoShellQuoting with
+ * exitCode 2 (task-loader also asserts this at load time so --dry-run
+ * catches it; the check here is the chokepoint guarantee for any caller
+ * that bypasses the loader).
+ *
+ * Why reject instead of parse: silently splitting a quoted command on
+ * whitespace shreds it ("bash -c \"a && b\"" → spawn('bash',
+ * ['-c', '"a', '&&', 'b"']) — bash exits 2, cron mails operator forever).
+ * If you need shell features, put them in a script file and invoke the
+ * script, or move the bash wrapper to the cron entry.
+ *
+ * @param {string} command  command string from schedules/<id>.json
+ * @returns {{ bin: string, args: string[] }}
+ * @throws  {Error & { exitCode: 2 }} on quoted or empty commands
+ */
+function parseCommand(command) {
+  assertNoShellQuoting(command);
+  const parts = command.trim().split(/\s+/);
+  if (!parts[0]) {
+    const e = new Error('command is empty');
+    e.exitCode = 2;
+    throw e;
+  }
+  return { bin: parts[0], args: parts.slice(1) };
+}
+
+async function defaultSpawner(plan) {
+  const { bin, args } = parseCommand(plan.task.command);
+  const cwd = resolveWorkdir(plan.task.workingDirectory, plan.repoRoot);
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { cwd, stdio: 'inherit' });
+    child.on('close', (code) => resolve(code ?? 0));
+    child.on('error', (err) => {
+      const e = new Error(`spawn failed for "${bin}": ${err.message}`);
+      e.exitCode = 3;
+      reject(e);
+    });
+  });
+}
+
+function nowIso() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+async function writeAuditRecord(plan, status, exitCode, extra = {}) {
+  const record = {
+    ts: nowIso(),
+    status,
+    agentId: plan.agent.id,
+    taskId: plan.task.id,
+    exitCode,
+    ...extra,
+  };
+  await appendFile(plan.auditLogPath, JSON.stringify(record) + '\n', 'utf8');
+}
+
+export async function execute(plan, {
+  spawner = defaultSpawner,
+  lockAcquire = acquireLock,
+  stderr = process.stderr,
+} = {}) {
+  await mkdir(plan.intakeFolderPath, { recursive: true });
+
+  // Per-task concurrency lock — default-on. Programmatic callers that hand
+  // the runner a plan without lockPath still get protection: the chokepoint
+  // derives the same per-task path the planner would have chosen.
+  const lockPath = plan.lockPath ?? join(plan.repoRoot, '.cache', 'launch', `${plan.task.id}.lock`);
+  const lockOptions = {};
+  if (Number.isFinite(plan.lockStaleAfterMs) && plan.lockStaleAfterMs > 0) {
+    lockOptions.staleAfterMs = plan.lockStaleAfterMs;
+  }
+  const lock = await lockAcquire(lockPath, lockOptions);
+  if (!lock.acquired) {
+    // Same-task run already in flight — skip cleanly, spawn nothing.
+    await writeAuditRecord(plan, 'noop-locked', 0, { reason: `lock contention: ${lock.reason}` });
+    return { status: 'noop-locked', exitCode: 0, reason: lock.reason, lockPath };
+  }
+  if (lock.stale) {
+    stderr.write(
+      `[launch] warning: broke stale lock at ${lockPath} ` +
+      `(${lock.stale.reason}; pid ${lock.stale.pid ?? 'unknown'}, ` +
+      `acquired ${lock.stale.acquiredAt ?? 'unknown'}) — proceeding\n`,
+    );
+  }
+
+  try {
+    let exitCode;
+    try {
+      exitCode = await spawner(plan);
+    } catch (err) {
+      await writeAuditRecord(plan, 'fail-spawn', -1);
+      throw err;
+    }
+
+    const status = exitCode === 0 ? 'ok' : `fail-exit-${exitCode}`;
+    await writeAuditRecord(plan, status, exitCode);
+
+    return { status, exitCode };
+  } finally {
+    await lock.release();
+  }
+}