@pareto4/pp-core 1.22.0 → 1.23.1

package/scripts/live-runs/driver.cjs

@@ -0,0 +1,326 @@
+'use strict';
+
+/**
+ * driver.cjs - Phase 44 REACH-02 turn driver (D-01, D-04).
+ *
+ * One user turn is one `claude -p <turn> --output-format stream-json --verbose`
+ * process. Later turns resume the conversation with `--resume <session_id>` taken
+ * from the previous turn's result event. The child runs as the operator (login
+ * needs HOME) inside a scratch project. What the harness narrows here:
+ *   - the env is an allow list (ENV_ALLOW): tokens, cloud keys, the SSH agent,
+ *     ANTHROPIC_MODEL, GSD_* test switches and GIT_DIR-style variables never reach (gsd-allow-legacy-name: runtime env contract)
+ *     the child, and the parent session's markers are gone;
+ *   - the operator's user settings and MCP servers are left out, but the deny rules
+ *     in their user settings.json are carried over through --disallowedTools;
+ *   - the tools that reach the network, schedule work or push (DENIED_TOOLS) are
+ *     denied, next to the auto-approved working set (ALLOWED_TOOLS);
+ *   - every turn has a wall-time kill and a dollar cap.
+ * What it does not do: it is not a sandbox. Bash, Write and Edit are auto-approved,
+ * so a model that ignores the scenario can still run any other command as the
+ * operator. The scrub (scrub.cjs) is the last line before evidence is written.
+ *
+ * Never passes --model (the run gets the CLI's default model, D-04) or --bare
+ * (it needs an API key and skips the installed commands). The spawn is an argv
+ * array with no shell: the user turn is data.
+ *
+ * The binary comes from PP_LIVE_CLAUDE_BIN (a script path runs through node), so the
+ * offline tests drive a fake. Nothing here is required by `npm test` except that
+ * test (D-02).
+ */
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** The parent Claude Code session's markers. A child that inherits them refuses to start. */
+const CLAUDE_ENV_SCRUB_RE = /^CLAUDE_CODE_|^CLAUDECODE$|^CLAUDE_PID$|^CLAUDE_EFFORT$/;
+
+/**
+ * The only env keys a child session inherits: what the CLI needs to start, log in and
+ * reach the API. Everything else (GH_TOKEN, AWS_*, SSH_AUTH_SOCK, NPM_TOKEN,
+ * ANTHROPIC_MODEL, GSD_*, GIT_DIR, ...) is dropped. ANTHROPIC_API_KEY stays because it (gsd-allow-legacy-name)
+ * is a login path; the scrub removes its value from any evidence.
+ */
+const ENV_ALLOW = Object.freeze([
+  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM', 'TMPDIR', 'TZ',
+  'CLAUDE_CONFIG_DIR', 'ANTHROPIC_API_KEY',
+  'HTTPS_PROXY', 'HTTP_PROXY', 'NO_PROXY', 'https_proxy', 'http_proxy', 'no_proxy', 'NODE_EXTRA_CA_CERTS',
+  'SYSTEMROOT', 'SystemRoot', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'PATHEXT', 'COMSPEC', 'ComSpec',
+]);
+
+/** The offline fake CLI is driven by these; they never exist in a real run. */
+const ENV_ALLOW_PREFIX_RE = /^PP_FAKE_CLAUDE_/;
+
+/** An explicit allow list replaces bypass mode; Agent is there so a workflow can spawn pp-core agents. */
+const ALLOWED_TOOLS = 'Bash Read Write Edit Glob Grep Agent';
+
+/**
+ * Denied outright: tools that reach the network, schedule or trigger work outside the
+ * turn, or notify a person, and the shell commands that push, call remote services or
+ * read credential folders. A deny rule wins over an auto-approval.
+ */
+const DENIED_TOOLS = Object.freeze([
+  'WebFetch', 'WebSearch', 'RemoteTrigger', 'CronCreate', 'CronDelete', 'CronList', 'ScheduleWakeup', 'PushNotification',
+  'Bash(git push *)', 'Bash(gh *)', 'Bash(ssh *)', 'Bash(scp *)', 'Bash(curl *)', 'Bash(wget *)',
+  'Read(~/.ssh/**)', 'Read(~/.aws/**)', 'Read(~/.config/gh/**)', 'Read(~/.npmrc)',
+]);
+
+/**
+ * The deny rules from the operator's user settings.json (`permissions.deny`). The child
+ * runs with --setting-sources project,local, which leaves that file out, so its deny
+ * rules are passed on explicitly. A missing or unreadable file gives [].
+ */
+function userDenyRules(env = process.env) {
+  const configDir = env.CLAUDE_CONFIG_DIR || (env.HOME ? path.join(env.HOME, '.claude') : null);
+  if (!configDir) return [];
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(configDir, 'settings.json'), 'utf8'));
+    const deny = data && data.permissions && data.permissions.deny;
+    return Array.isArray(deny) ? deny.filter((r) => typeof r === 'string' && r.trim() !== '') : [];
+  } catch {
+    return [];
+  }
+}
+
+/** The throwaway identity every scratch repo and child process commits under. */
+const GIT_IDENTITY = Object.freeze({ name: 'Live Run', email: 'live-run@example.invalid' });
+
+const MAX_BUFFER = 256 * 1024 * 1024;
+/** The process-group guard every turn runs under (WR-06), and its timings. */
+const TURN_GUARD = path.join(__dirname, 'turn-guard.cjs');
+const KILL_GRACE_MS = 5000;
+const GUARD_MARGIN_MS = 10000;
+const VERSION_TIMEOUT_MS = 30000;
+const DETAIL_MAX = 300;
+const SCRIPT_EXTENSIONS = new Set(['.cjs', '.js', '.mjs']);
+
+/**
+ * Env keys that point git at another repository. Inherited from a git hook or other
+ * tooling they would make the scratch repo's git calls act on the operator's repo.
+ */
+const GIT_REPO_ENV_KEYS = Object.freeze([
+  'GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_COMMON_DIR', 'GIT_CEILING_DIRECTORIES', 'GIT_NAMESPACE', 'GIT_PREFIX',
+]);
+
+/** A copy of `env` without the GIT_REPO_ENV_KEYS. */
+function withoutGitRepoEnv(env = process.env) {
+  const out = { ...env };
+  for (const key of GIT_REPO_ENV_KEYS) delete out[key];
+  return out;
+}
+
+function gitIdentityEnv() {
+  return {
+    GIT_AUTHOR_NAME: GIT_IDENTITY.name,
+    GIT_AUTHOR_EMAIL: GIT_IDENTITY.email,
+    GIT_COMMITTER_NAME: GIT_IDENTITY.name,
+    GIT_COMMITTER_EMAIL: GIT_IDENTITY.email,
+  };
+}
+
+/** Which binary to run: PP_LIVE_CLAUDE_BIN when set (a script path runs through node), else `claude`. */
+function resolveBin(env = process.env) {
+  const bin = env && env.PP_LIVE_CLAUDE_BIN;
+  if (!bin) return { command: 'claude', prefixArgs: [] };
+  if (SCRIPT_EXTENSIONS.has(path.extname(bin))) return { command: process.execPath, prefixArgs: [bin] };
+  return { command: bin, prefixArgs: [] };
+}
+
+/**
+ * The env a child session gets: only the ENV_ALLOW keys of `baseEnv` (HOME stays, login
+ * needs it). `personHome` becomes the person home (where person.json lives); `audience`
+ * null leaves PP_AUDIENCE unset so a walk can test the person-file path instead of the
+ * variable.
+ */
+function childEnv(baseEnv, { personHome, audience = 'business' } = {}) {
+  const env = {};
+  for (const [key, value] of Object.entries(baseEnv || {})) {
+    if (value === undefined || CLAUDE_ENV_SCRUB_RE.test(key)) continue;
+    if (ENV_ALLOW.includes(key) || ENV_ALLOW_PREFIX_RE.test(key)) env[key] = value;
+  }
+  env.GSD_HOME = personHome;
+  if (audience !== null) env.PP_AUDIENCE = audience;
+  return { ...env, ...gitIdentityEnv() };
+}
+
+/** The exact argv for one turn. `extraDeny` adds deny rules (the operator's own, see userDenyRules). */
+function buildArgs({ prompt, sessionId, budgetUsd, extraDeny = [] }) {
+  const deny = [...new Set([...DENIED_TOOLS, ...extraDeny])].join(' ');
+  const args = [
+    '-p', prompt,
+    '--output-format', 'stream-json',
+    '--verbose',
+    '--setting-sources', 'project,local',
+    '--strict-mcp-config',
+    '--permission-mode', 'acceptEdits',
+    '--allowedTools', ALLOWED_TOOLS,
+    '--disallowedTools', deny,
+    '--max-budget-usd', String(budgetUsd),
+  ];
+  if (sessionId) args.push('--resume', sessionId);
+  return args;
+}
+
+/** The guard's report from fd 3, or null when it did not write one. */
+function guardReport(res) {
+  const raw = res && Array.isArray(res.output) ? String(res.output[3] || '') : '';
+  const last = raw.split('\n').filter((l) => l.trim() !== '').pop();
+  if (!last) return null;
+  try {
+    const r = JSON.parse(last);
+    return r && typeof r === 'object' ? r : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run one turn. Never throws for a CLI problem: the caller classifies the result
+ * (`classifyTurn`) and records "not run" with the reason (D-03). The CLI runs under
+ * turn-guard.cjs, which kills its whole process group at the wall time and when it
+ * exits; the spawnSync timeout here is only a backstop for the guard itself.
+ */
+function runTurn({ cwd, personHome, prompt, sessionId, wallMs, budgetUsd, env = process.env, audience = 'business' }) {
+  const { command, prefixArgs } = resolveBin(env);
+  const args = [...prefixArgs, ...buildArgs({ prompt, sessionId, budgetUsd, extraDeny: userDenyRules(env) })];
+  const started = Date.now();
+  const res = spawnSync(process.execPath, [TURN_GUARD, String(wallMs), String(KILL_GRACE_MS), command, ...args], {
+    cwd,
+    env: childEnv(env, { personHome, audience }),
+    encoding: 'utf8',
+    timeout: wallMs + KILL_GRACE_MS + GUARD_MARGIN_MS,
+    killSignal: 'SIGKILL',
+    maxBuffer: MAX_BUFFER,
+    stdio: ['ignore', 'pipe', 'pipe', 'pipe'],
+  });
+  const report = guardReport(res);
+  let status;
+  let signal;
+  let timedOut;
+  let spawnError = null;
+  if (report) {
+    status = report.status === undefined ? null : report.status;
+    signal = report.signal === undefined ? null : report.signal;
+    timedOut = report.timedOut === true;
+    spawnError = report.spawnError || null;
+  } else {
+    status = res.status;
+    signal = res.signal;
+    timedOut = Boolean(res.error && res.error.code === 'ETIMEDOUT');
+    if (res.error && !timedOut) spawnError = res.error.code || res.error.message;
+  }
+  return {
+    status,
+    signal,
+    timedOut,
+    spawnError,
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+    durationMs: Date.now() - started,
+    args,
+  };
+}
+
+/** Split stream-json stdout into events; a line that is not JSON is reported, not thrown. */
+function parseLines(stdout) {
+  const events = [];
+  const parseErrors = [];
+  for (const raw of String(stdout || '').split('\n')) {
+    if (raw.trim() === '') continue;
+    try {
+      events.push(JSON.parse(raw));
+    } catch (err) {
+      parseErrors.push({ line: raw, error: err.message });
+    }
+  }
+  return { events, parseErrors };
+}
+
+/** The session id the next turn resumes: the result event's, else the last event that carries one. */
+function sessionIdOf(events) {
+  const withId = (events || []).filter((e) => e && typeof e.session_id === 'string' && e.session_id !== '');
+  const result = [...withId].reverse().find((e) => e.type === 'result');
+  if (result) return result.session_id;
+  return withId.length > 0 ? withId.at(-1).session_id : null;
+}
+
+const AUTH_RE = /not logged in|please run \/login|invalid api key|authentication_error|oauth token (?:has )?expired|expired oauth/i;
+const LAUNCH_REFUSED_RE = /cannot be launched inside another claude code session|nested (?:claude code )?session/i;
+
+const cut = (s) => String(s).trim().slice(0, DETAIL_MAX);
+const firstMatchingLine = (text, re) => String(text).split('\n').find((l) => re.test(l)) || '';
+
+/** Text a login problem would show: stderr, an error result, or a stdout line that is not an event. */
+function authEvidence(turn, events) {
+  const parts = [turn.stderr || ''];
+  for (const e of events) {
+    if (e && e.type === 'result' && e.is_error === true) parts.push(String(e.result || ''));
+  }
+  if (events.length === 0) parts.push(turn.stdout || '');
+  return parts.join('\n');
+}
+
+/**
+ * Decide what became of a turn, in a fixed order: the CLI is missing, it ran out of
+ * wall time, the login failed, the account is rate limited, the CLI refused a nested
+ * launch, it crashed, or it is fine. `detail` is the matching line, cut to 300 characters.
+ */
+function classifyTurn(turn, events = []) {
+  if (turn.spawnError === 'ENOENT') return { kind: 'cli_missing', detail: cut('the claude binary was not found') };
+  if (turn.timedOut) return { kind: 'timeout', detail: cut('the turn ran past its wall time and was killed') };
+
+  const auth = authEvidence(turn, events);
+  if (AUTH_RE.test(auth)) return { kind: 'auth', detail: cut(firstMatchingLine(auth, AUTH_RE)) };
+
+  const limited = events.find((e) => {
+    if (!e || e.type !== 'rate_limit_event') return false;
+    const status = e.rate_limit_info && e.rate_limit_info.status;
+    return typeof status === 'string' && !status.startsWith('allowed');
+  });
+  if (limited) return { kind: 'rate_limited', detail: cut(JSON.stringify(limited.rate_limit_info)) };
+
+  const err = turn.stderr || '';
+  if (LAUNCH_REFUSED_RE.test(err)) return { kind: 'launch_refused', detail: cut(firstMatchingLine(err, LAUNCH_REFUSED_RE)) };
+
+  const hasResult = events.some((e) => e && e.type === 'result');
+  if (turn.spawnError || turn.status !== 0 || !hasResult) {
+    const why = turn.spawnError || (err.trim() !== '' ? err : `exit ${turn.status === null ? 'by signal ' + turn.signal : turn.status} with no result event`);
+    return { kind: 'crashed', detail: cut(why) };
+  }
+  return { kind: 'ok', detail: '' };
+}
+
+/** The CLI's version string, or null when it cannot run. */
+function cliVersion({ env = process.env } = {}) {
+  const { command, prefixArgs } = resolveBin(env);
+  const res = spawnSync(command, [...prefixArgs, '--version'], {
+    env,
+    encoding: 'utf8',
+    timeout: VERSION_TIMEOUT_MS,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (res.error || res.status !== 0) return null;
+  const out = String(res.stdout || '').trim();
+  return out === '' ? null : out;
+}
+
+module.exports = {
+  CLAUDE_ENV_SCRUB_RE,
+  ENV_ALLOW,
+  ALLOWED_TOOLS,
+  DENIED_TOOLS,
+  GIT_IDENTITY,
+  GIT_REPO_ENV_KEYS,
+  withoutGitRepoEnv,
+  gitIdentityEnv,
+  resolveBin,
+  userDenyRules,
+  childEnv,
+  buildArgs,
+  runTurn,
+  parseLines,
+  sessionIdOf,
+  classifyTurn,
+  cliVersion,
+};