@ravefox/space 0.0.0-stage → 0.2.1

package/src/lib/first-output-watchdog.js

@@ -0,0 +1,191 @@
+/**
+ * First-output watchdog for a seat's model CLI spawn.
+ *
+ * On 2026-10-30 every launchd seat's `claude -p` turn parked while the Mac's
+ * console was locked: no transcript row, no stdout, no stderr, for the full
+ * 45-minute run timeout. Each one held its delivery the whole time, the retry
+ * respawned it into the same hang, and the log said only "claude timed out
+ * after 2700000ms", which names nothing.
+ *
+ * The signal is not stdout. A seat runs `claude -p --output-format text`,
+ * which writes stdout once, at the end, so a healthy 20-minute turn has zero
+ * stdout bytes for 20 minutes. What a healthy turn does write is its session
+ * transcript: measured on the dart seat, the first row landed 0.7 s after the
+ * spawn, and the hung spawns that night wrote no row at all. So a spawn counts
+ * as started when it writes any stdout or stderr byte OR its transcript grows.
+ * A spawn that does neither inside the window is killed with a reason. When
+ * the transcript is missing altogether, the path may simply be wrong, so the
+ * spawn is killed only if the console is also locked.
+ *
+ * That is the rule for a plain-text spawn. A stream-json spawn (TASK-710) counts
+ * only model events on stdout; see `modelStream` on watchFirstOutput.
+ */
+import { realpathSync, statSync } from 'fs';
+import { readProcess } from '@commonlyai/seats/process-group';
+
+export const DEFAULT_FIRST_OUTPUT_WINDOW_MS = 180_000;
+
+// 0 turns the watchdog off; anything unparseable keeps the default.
+export const firstOutputWindowMs = (env = process.env) => {
+  const raw = env?.COMMONLY_FIRST_OUTPUT_WINDOW_MS;
+  if (raw === undefined || raw === '') return DEFAULT_FIRST_OUTPUT_WINDOW_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_FIRST_OUTPUT_WINDOW_MS;
+};
+
+export const SPAWN_STALLED_CODE = 'spawn_stalled';
+
+// The message carries the class word spawn-retry.js matches, so the stall gets
+// its own backoff rather than RUNTIME's 5-second retry.
+export const spawnStalledError = ({ label, windowMs, reason }) => {
+  const error = new Error(
+    `${label} produced no output in ${Math.round(windowMs / 1000)}s (${reason}); killed before the run timeout`,
+  );
+  error.code = SPAWN_STALLED_CODE;
+  error.stallReason = reason;
+  return error;
+};
+
+// `ioreg -n Root -d1` prints `"IOConsoleLocked" = Yes` while the screen is
+// locked. True, false, or null when it cannot tell (not darwin, ioreg failed).
+// child_process is loaded on demand: suites that mock it with only `spawn`
+// would otherwise fail to import every adapter that uses this module.
+export const consoleLocked = async ({ platform = process.platform, execFileImpl } = {}) => {
+  if (platform !== 'darwin') return null;
+  const run = execFileImpl || (await import('child_process')).execFile;
+  if (typeof run !== 'function') return null;
+  return new Promise((resolve) => {
+    run('/usr/sbin/ioreg', ['-n', 'Root', '-d1'], { timeout: 5000 }, (error, stdout) => {
+      if (error) return resolve(null);
+      const match = String(stdout).match(/"IOConsoleLocked"\s*=\s*(Yes|No)/);
+      return resolve(match ? match[1] === 'Yes' : null);
+    });
+  });
+};
+
+// Claude names its project folder after process.cwd(), which on macOS is the
+// physical path (/tmp is /private/tmp), so the transcript is looked for there.
+export const physicalPath = (dir) => {
+  if (!dir) return dir;
+  try {
+    return realpathSync(dir);
+  } catch {
+    return dir;
+  }
+};
+
+// How long a stalled spawn gets to exit after SIGTERM before SIGKILL.
+export const STALL_KILL_GRACE_MS = 10_000;
+
+// The boot line for a claude seat. This watchdog is the stall guard a claude
+// turn runs: the seats supervisor's stall window is off for claude
+// (STALL_DEFAULTS_MS in supervised-turn.js), and its package default of 120 s
+// was once read as this one's (the G6 walk, 2026-11-01).
+export const describeFirstOutputWatch = (env = process.env) => {
+  const windowMs = firstOutputWindowMs(env);
+  if (!windowMs) return 'first-output watchdog OFF for claude (COMMONLY_FIRST_OUTPUT_WINDOW_MS=0)';
+  return `first-output watchdog ON for claude: a turn with no model output in ${windowMs}ms is killed `
+    + `(SIGTERM, then SIGKILL ${STALL_KILL_GRACE_MS}ms later if it is still alive)`;
+};
+
+/**
+ * SIGKILL each snapshotted descendant of a stalled spawn that is still alive
+ * once the spawn itself has exited. Its parent may have exited, so it may now
+ * belong to launchd: only the pid and start time are matched, which still
+ * rules out a reused pid. Returns the pids signalled.
+ */
+export const killStallSurvivors = (snapshot, { read = readProcess, kill = process.kill.bind(process) } = {}) => {
+  const killed = [];
+  for (const row of snapshot || []) {
+    const now = read(row.pid);
+    if (!now || now.started !== row.started) continue;
+    try { kill(row.pid, 'SIGKILL'); killed.push(row.pid); } catch { /* gone */ }
+  }
+  return killed;
+};
+
+const sizeOf = (file) => {
+  if (!file) return -1;
+  try {
+    return statSync(file).size;
+  } catch {
+    return -1;
+  }
+};
+
+// A stream-json line is model progress when it is an event other than `system`.
+// The `system` events are `init` (written before any model call) and
+// `api_retry` (a provider failing and retrying). Counting either would keep a
+// hung provider looking alive until the run timeout.
+export const isModelProgressLine = (line) => {
+  try {
+    const event = JSON.parse(line);
+    return !!event && typeof event === 'object' && event.type !== 'system';
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Watch `proc` for its first sign of life. Returns `{ stop }`; call it when the
+ * process closes. `onStall(reason)` fires at most once, after the caller should
+ * kill the process.
+ *
+ * With `modelStream`, the spawn writes stream-json events. Only model output
+ * counts as life there. A transcript row does not, because claude writes its
+ * first row about a second after spawn, before any model reply. Stderr does
+ * not either: claude prints warnings at spawn (an unrecognised model, a
+ * connector notice) whatever the provider does next.
+ */
+export const watchFirstOutput = ({
+  proc,
+  windowMs,
+  transcriptPath = null,
+  modelStream = false,
+  onStall,
+  lockProbe = consoleLocked,
+  setTimeoutImpl = setTimeout,
+  clearTimeoutImpl = clearTimeout,
+}) => {
+  if (!windowMs) return { stop: () => {} };
+  let started = false;
+  let stopped = false;
+  let partial = '';
+  const markStarted = () => { started = true; };
+  if (modelStream) {
+    proc.stdout?.on('data', (chunk) => {
+      const lines = (partial + chunk.toString()).split('\n');
+      partial = lines.pop();
+      if (lines.some(isModelProgressLine)) markStarted();
+    });
+  } else {
+    proc.stdout?.on('data', markStarted);
+    proc.stderr?.on('data', markStarted);
+  }
+  // A missing file counts as empty, so creating an empty one is not growth.
+  const baseline = Math.max(0, sizeOf(transcriptPath));
+  const timer = setTimeoutImpl(async () => {
+    const size = sizeOf(transcriptPath);
+    if (started || (!modelStream && size > baseline)) return;
+    const locked = await lockProbe().catch(() => null);
+    // Output can arrive while the probe runs (ps or ioreg may take a second).
+    if (stopped || started) return;
+    if (modelStream) {
+      // The model signal does not read the transcript, so a missing path cannot
+      // hide a hung provider here.
+      onStall(locked ? 'console locked' : 'stuck: no model output inside the window');
+      return;
+    }
+    // No transcript where one was expected may only mean the path is wrong, so
+    // that alone never kills a turn: it takes a locked console as well.
+    if (size < 0 && locked !== true) return;
+    onStall(locked ? 'console locked' : 'no transcript, stdout or stderr');
+  }, windowMs);
+  timer?.unref?.();
+  return {
+    stop: () => {
+      stopped = true;
+      clearTimeoutImpl(timer);
+    },
+  };
+};

package/src/lib/git-readonly-server.js

@@ -0,0 +1,138 @@
+/**
+ * The `workspace_git` MCP server: one tool, `git`, for a workspace-trust seat
+ * (TASK-294). The claude adapter spawns it as
+ *
+ *   node git-readonly-server.js --root <workspace> --git <binary>
+ *
+ * and the model sees it as `mcp__workspace_git__git`. It speaks the MCP stdio
+ * transport (newline-delimited JSON-RPC 2.0) and hands every call to
+ * runReadonlyGit, which refuses anything that is not read-only and runs the
+ * rest with execFile in the workspace.
+ */
+import { realpathSync, statSync } from 'fs';
+import { isAbsolute } from 'path';
+import { createInterface } from 'readline';
+import { fileURLToPath } from 'url';
+import { READONLY_GIT_SUBCOMMANDS, runReadonlyGit } from './git-readonly.js';
+
+export const SERVER_NAME = 'workspace_git';
+export const TOOL_NAME = 'git';
+const SERVER_VERSION = '1.0.0';
+
+// The tool surface is the same in each of these, so the server answers in the
+// version the client asked for when it is one of them.
+const SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(['2024-11-05', '2025-03-26', '2025-06-18']);
+
+export const GIT_TOOL = Object.freeze({
+  name: TOOL_NAME,
+  description: `Run read-only git in your workspace: ${READONLY_GIT_SUBCOMMANDS.join(', ')}. `
+    + 'Pass the subcommand and its arguments separately, one argument per array entry, '
+    + "e.g. { subcommand: 'log', args: ['-n', '5', '--oneline'] }. "
+    + 'Options that write a file, run a program, or read outside the workspace are refused with the reason, '
+    + 'and paths must stay inside the workspace. For log, diff and show, put paths after \'--\' '
+    + "(e.g. ['-p', '--', 'src/app.js']). .env files are left out of every result. "
+    + 'This is the only git available to you.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      subcommand: { type: 'string', enum: [...READONLY_GIT_SUBCOMMANDS] },
+      args: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Arguments after the subcommand, one per entry.',
+      },
+    },
+    required: ['subcommand'],
+    additionalProperties: false,
+  },
+});
+
+const reply = (id, result) => ({ jsonrpc: '2.0', id, result });
+const fail = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+/**
+ * A handler for one parsed JSON-RPC message. Resolves the response, or null
+ * for a notification (a message with no id), which gets none.
+ */
+export const createGitServerHandler = ({
+  root, git = 'git', baseEnv = process.env, run = runReadonlyGit,
+}) => async (message) => {
+  if (!message || typeof message !== 'object' || Array.isArray(message) || typeof message.method !== 'string') {
+    return fail(message?.id ?? null, -32600, 'Invalid Request');
+  }
+  const { id, method, params } = message;
+  if (id === undefined) return null;
+  if (method === 'initialize') {
+    const asked = params?.protocolVersion;
+    return reply(id, {
+      protocolVersion: SUPPORTED_PROTOCOL_VERSIONS.includes(asked) ? asked : SUPPORTED_PROTOCOL_VERSIONS[0],
+      capabilities: { tools: {} },
+      serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+    });
+  }
+  if (method === 'ping') return reply(id, {});
+  if (method === 'tools/list') return reply(id, { tools: [GIT_TOOL] });
+  if (method === 'tools/call') {
+    if (params?.name !== TOOL_NAME) return fail(id, -32602, `Unknown tool: ${params?.name}`);
+    const { subcommand, args = [] } = params.arguments || {};
+    const { ok, text } = await run({
+      subcommand, args, root, git, baseEnv,
+    });
+    return reply(id, { content: [{ type: 'text', text }], isError: !ok });
+  }
+  return fail(id, -32601, `Method not found: ${method}`);
+};
+
+/** `--root <dir> --git <binary>`; the root must be an existing directory. */
+export const parseServerArgs = (argv) => {
+  const value = (flag) => {
+    const at = argv.indexOf(flag);
+    return at === -1 ? undefined : argv[at + 1];
+  };
+  const root = value('--root');
+  if (typeof root !== 'string' || !isAbsolute(root)) throw new Error('--root <absolute workspace path> is required');
+  const real = realpathSync(root);
+  if (!statSync(real).isDirectory()) throw new Error(`--root ${root} is not a directory`);
+  return { root: real, git: value('--git') || 'git' };
+};
+
+export const serve = ({
+  root, git, input = process.stdin, output = process.stdout, baseEnv = process.env,
+}) => {
+  const handle = createGitServerHandler({ root, git, baseEnv });
+  // A closed pipe on the client side is the client leaving, not an error.
+  output.on('error', () => {});
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  lines.on('line', async (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      output.write(`${JSON.stringify(fail(null, -32700, 'Parse error'))}\n`);
+      return;
+    }
+    const response = await handle(message);
+    if (response) output.write(`${JSON.stringify(response)}\n`);
+  });
+  return lines;
+};
+
+const runAsMain = () => {
+  try {
+    return Boolean(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+};
+
+if (runAsMain()) {
+  let options;
+  try {
+    options = parseServerArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`${SERVER_NAME}: ${err.message}\n`);
+    process.exit(2);
+  }
+  serve(options);
+}