session-orchestrator 3.16.0

package/scripts/lib/coordinator-snapshot.mjs

@@ -0,0 +1,371 @@
+// @ts-check
+/**
+ * coordinator-snapshot.mjs — pre-dispatch coordinator snapshot helpers for session-orchestrator.
+ *
+ * Saves git stash-format commit objects under refs/so-snapshots/<sessionId>/wave-<N>-<label>
+ * without touching the working tree, using `git update-ref` to persist them.
+ *
+ * `git stash create` alone captures only tracked modifications. It silently ignores
+ * `-u`/`--include-untracked` on git 2.53 (the flag is accepted but has no effect on
+ * `create` — only `push` and `save` honor it), so any new untracked files produced
+ * during a wave were dropped from the snapshot. Fix (#221): after building the
+ * tracked stash commit we also build an untracked-tree commit from a temp index and
+ * attach it as a third parent, matching git-stash's 3-parent format so
+ * `git stash apply` restores both tracked and untracked content on recovery.
+ *
+ * Part of v3.1.0 env-aware sessions (issue #196).
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+import { $, nothrow } from 'zx';
+
+// Do not spam stdout/stderr with git command echoes.
+$.verbose = false;
+$.quiet = true;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+const MODULE = 'coordinator-snapshot';
+const REF_PREFIX = 'refs/so-snapshots/';
+
+/**
+ * Sanitize a session ID for use in a git ref namespace.
+ * Replaces any character outside [A-Za-z0-9._-] with '-'.
+ *
+ * @param {string} sessionId
+ * @returns {string}
+ */
+function _sanitizeSessionId(sessionId) {
+  return sessionId.replace(/[^A-Za-z0-9._-]/g, '-');
+}
+
+/**
+ * Build the full ref name for a snapshot.
+ *
+ * @param {string} sanitizedSessionId
+ * @param {number} waveN
+ * @param {string} label
+ * @returns {string}
+ */
+function _refName(sanitizedSessionId, waveN, label) {
+  return `${REF_PREFIX}${sanitizedSessionId}/wave-${waveN}-${label}`;
+}
+
+/**
+ * Build a snapshot commit that captures both tracked changes and untracked files.
+ *
+ * Strategy:
+ *   1. `git stash create` produces a 2-parent commit over tracked/index changes.
+ *   2. `_buildUntrackedParent` produces an optional commit whose tree is the set
+ *      of untracked, non-gitignored files (done via a temp GIT_INDEX_FILE).
+ *   3. If both are present, we splice the untracked commit in as a third parent
+ *      of the stash — matching the format `git stash push -u` writes, so
+ *      `git stash apply` can restore both tracked and untracked content.
+ *   4. If only one is present, return that SHA; if neither, return empty string.
+ *
+ * @param {ReturnType<typeof $>} git
+ * @param {string} cwd
+ * @param {string} stashMessage
+ * @returns {Promise<string>} snapshot commit SHA or '' if nothing to capture
+ */
+async function _buildSnapshotCommit(git, cwd, stashMessage) {
+  const stashResult = await git`git stash create ${stashMessage}`;
+  const trackedSha = stashResult.stdout.trim();
+  const untrackedSha = await _buildUntrackedParent(git, cwd, stashMessage);
+
+  if (!trackedSha && !untrackedSha) return '';
+  if (!untrackedSha) return trackedSha;
+  if (!trackedSha) return untrackedSha;
+
+  // Splice untracked commit as a 3rd parent of the tracked stash commit.
+  const trackedTree = (await git`git rev-parse ${trackedSha + '^{tree}'}`).stdout.trim();
+  const parentsRaw = (await git`git rev-list --parents -n 1 ${trackedSha}`).stdout.trim().split(' ');
+  const [, ...stashParents] = parentsRaw;
+  const parentArgs = [];
+  for (const p of stashParents) parentArgs.push('-p', p);
+  parentArgs.push('-p', untrackedSha);
+  const combined = await git`git commit-tree ${trackedTree} ${parentArgs} -m ${stashMessage}`;
+  return combined.stdout.trim();
+}
+
+/**
+ * Build a commit object whose tree contains only the current untracked,
+ * non-gitignored files. Returns '' when the tree has no such files.
+ *
+ * Uses a temporary GIT_INDEX_FILE so the real index and working tree are never
+ * touched. The commit has HEAD as its sole parent, matching git-stash's
+ * "untracked files on ..." conventions.
+ *
+ * @param {ReturnType<typeof $>} git
+ * @param {string} cwd
+ * @param {string} stashMessage — reused as commit subject for provenance
+ * @returns {Promise<string>} untracked-commit SHA, or '' if no untracked files
+ */
+async function _buildUntrackedParent(git, cwd, stashMessage) {
+  const lsRes = await git`git ls-files --others --exclude-standard -z`;
+  const paths = lsRes.stdout.split('\0').filter(Boolean);
+  if (paths.length === 0) return '';
+
+  const tempIndex = path.join(
+    os.tmpdir(),
+    `so-snap-untracked-${process.pid}-${Date.now()}`,
+  );
+  const gitIdx = $({
+    cwd,
+    env: { ...process.env, GIT_INDEX_FILE: tempIndex },
+  });
+  gitIdx.verbose = false;
+  gitIdx.quiet = true;
+
+  try {
+    // `read-tree --empty` initializes the temp index file.
+    await gitIdx`git read-tree --empty`;
+    await gitIdx`git update-index --add -- ${paths}`;
+    const treeSha = (await gitIdx`git write-tree`).stdout.trim();
+    if (!treeSha) return '';
+    const head = (await git`git rev-parse HEAD`).stdout.trim();
+    const subject = `untracked files on ${stashMessage}`;
+    const commitRes = await git`git commit-tree ${treeSha} -p ${head} -m ${subject}`;
+    return commitRes.stdout.trim();
+  } finally {
+    try {
+      await fs.unlink(tempIndex);
+    } catch {
+      // Temp index may never have been created if read-tree failed — ignore.
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// saveSnapshot
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a git-stash commit object and save it under refs/so-snapshots/<sessionId>/wave-<N>-<label>.
+ * No-op when working tree is clean (no uncommitted changes). Does NOT touch the working tree
+ * (uses `git stash create -u` which produces a commit object including untracked files
+ * without modifying files). The `-u` flag is load-bearing — without it, untracked files
+ * generated between waves (e.g. new test files) are silently dropped from the snapshot
+ * and cannot be recovered on crash resume (#221).
+ *
+ * @param {Object} opts
+ * @param {string} opts.sessionId — session identifier (sanitized for ref namespace)
+ * @param {number} opts.waveN — wave number, 1-indexed
+ * @param {string} [opts.label='pre'] — short suffix for the ref (e.g. 'pre-dispatch', 'post-impl')
+ * @returns {Promise<{ok: boolean, ref: string|null, sha: string|null, skipped?: true, error?: string}>}
+ */
+export async function saveSnapshot({ sessionId, waveN, label = 'pre' }) {
+  if (!sessionId || sessionId.trim() === '') {
+    return { ok: false, ref: null, sha: null, error: `${MODULE}: sessionId must not be empty` };
+  }
+
+  const cwd = process.cwd();
+  const git = $({ cwd });
+
+  try {
+    // Step 1: Check if working tree is clean.
+    const statusResult = await git`git status --porcelain`;
+    if (statusResult.stdout.trim() === '') {
+      return { ok: true, ref: null, sha: null, skipped: true };
+    }
+
+    // Step 2: Build the snapshot commit without modifying the working tree.
+    // Tracked changes come from `git stash create`; untracked files are attached
+    // via a third parent commit built from a temp index (see _buildUntrackedParent).
+    const sanitized = _sanitizeSessionId(sessionId);
+    const stashMessage = `so-snapshot ${sessionId} wave ${waveN} ${label}`;
+    const sha = await _buildSnapshotCommit(git, cwd, stashMessage);
+
+    if (!sha) {
+      // Race condition guard: status showed changes but git stash create produced
+      // nothing and there are no untracked files — treat as clean.
+      return { ok: true, ref: null, sha: null, skipped: true };
+    }
+
+    // Step 3: Persist the stash commit object under our custom ref namespace.
+    const ref = _refName(sanitized, waveN, label);
+    await git`git update-ref ${ref} ${sha}`;
+
+    return { ok: true, ref, sha };
+  } catch (err) {
+    const msg = err && typeof err === 'object' && 'stderr' in err
+      ? /** @type {any} */ (err).stderr.trim()
+      : String(err);
+    return { ok: false, ref: null, sha: null, error: `${MODULE}: saveSnapshot failed — ${msg}` };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// listSnapshots
+// ---------------------------------------------------------------------------
+
+/**
+ * List all coordinator snapshot refs, optionally filtered by sessionId.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.sessionId] — if set, only return this session's snapshots
+ * @returns {Promise<Array<{ref: string, sha: string, sessionId: string, waveN: number, label: string, createdAt: string}>>}
+ *   Sorted by waveN DESC (most recent wave first).
+ */
+export async function listSnapshots({ sessionId } = {}) {
+  const cwd = process.cwd();
+  const git = $({ cwd });
+
+  let output;
+  try {
+    // zx interpolates each template-literal word as a separate argv entry, so the
+    // format string must be a single interpolated value to stay as one --format arg.
+    const fmt = '%(refname) %(objectname) %(committerdate:iso8601)';
+    const result = await nothrow(
+      git`git for-each-ref --format=${fmt} ${REF_PREFIX}`
+    );
+    output = result.stdout;
+  } catch {
+    return [];
+  }
+
+  /** @type {Array<{ref: string, sha: string, sessionId: string, waveN: number, label: string, createdAt: string}>} */
+  const snapshots = [];
+
+  for (const rawLine of output.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    // Format: "<refname> <sha> <iso8601-date> <iso8601-time> <iso8601-offset>"
+    // The date portion from --format=%(committerdate:iso8601) looks like:
+    //   "refs/so-snapshots/sess/wave-1-pre abc123 2026-04-21 10:00:00 +0200"
+    // We split on the first two spaces to get refname and sha, then take the rest as date.
+    const spaceIdx1 = line.indexOf(' ');
+    if (spaceIdx1 === -1) continue;
+    const spaceIdx2 = line.indexOf(' ', spaceIdx1 + 1);
+    if (spaceIdx2 === -1) continue;
+
+    const ref = line.slice(0, spaceIdx1);
+    const sha = line.slice(spaceIdx1 + 1, spaceIdx2);
+    const dateStr = line.slice(spaceIdx2 + 1).trim();
+
+    // Parse ref: strip prefix, then split on '/' to get sessionId and wave part.
+    if (!ref.startsWith(REF_PREFIX)) continue;
+    const remainder = ref.slice(REF_PREFIX.length);
+    // remainder is "<sessionId>/wave-<N>-<label>"
+    const slashIdx = remainder.indexOf('/');
+    if (slashIdx === -1) {
+      console.error(`${MODULE}: listSnapshots — unexpected ref format (no slash after sessionId): ${ref}`);
+      continue;
+    }
+
+    const refSessionId = remainder.slice(0, slashIdx);
+    const wavePart = remainder.slice(slashIdx + 1);
+
+    // wavePart must match wave-<int>-<label>
+    const waveMatch = wavePart.match(/^wave-(\d+)-(.+)$/);
+    if (!waveMatch) {
+      console.error(`${MODULE}: listSnapshots — skipping ref with unexpected wave format: ${ref}`);
+      continue;
+    }
+
+    const waveN = parseInt(waveMatch[1], 10);
+    const label = waveMatch[2];
+
+    // Convert "2026-04-21 10:00:00 +0200" to ISO 8601 with T separator.
+    const createdAt = dateStr.replace(' ', 'T').replace(' ', '');
+
+    snapshots.push({ ref, sha, sessionId: refSessionId, waveN, label, createdAt });
+  }
+
+  snapshots.sort((a, b) => b.waveN - a.waveN);
+
+  if (sessionId) {
+    const sanitized = _sanitizeSessionId(sessionId);
+    return snapshots.filter((s) => s.sessionId === sanitized);
+  }
+
+  return snapshots;
+}
+
+// ---------------------------------------------------------------------------
+// deleteSnapshot
+// ---------------------------------------------------------------------------
+
+/**
+ * Delete a single snapshot ref. Idempotent (returns ok:true if ref already gone).
+ *
+ * @param {Object} opts
+ * @param {string} opts.refName — full ref name, e.g. "refs/so-snapshots/sess-123/wave-2-pre"
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+export async function deleteSnapshot({ refName }) {
+  const cwd = process.cwd();
+  const git = $({ cwd });
+
+  try {
+    // git update-ref -d exits 0 whether or not the ref existed.
+    await git`git update-ref -d ${refName}`;
+    return { ok: true };
+  } catch (err) {
+    const msg = err && typeof err === 'object' && 'stderr' in err
+      ? /** @type {any} */ (err).stderr.trim()
+      : String(err);
+    return { ok: false, error: `${MODULE}: deleteSnapshot failed for '${refName}' — ${msg}` };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// gcSnapshots
+// ---------------------------------------------------------------------------
+
+/**
+ * Delete all snapshots whose commit committer-date is older than olderThanDays.
+ * Non-throwing; errors per-ref are logged to stderr but don't abort.
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.olderThanDays=14]
+ * @returns {Promise<{ok: boolean, deletedCount: number, scanned: number, error?: string}>}
+ */
+export async function gcSnapshots({ olderThanDays = 14 } = {}) {
+  let snapshots;
+  try {
+    snapshots = await listSnapshots();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, deletedCount: 0, scanned: 0, error: `${MODULE}: gcSnapshots — listSnapshots failed: ${msg}` };
+  }
+
+  const scanned = snapshots.length;
+  let deletedCount = 0;
+  const now = Date.now();
+  const msPerDay = 24 * 60 * 60 * 1000;
+
+  for (const snapshot of snapshots) {
+    let ageMs;
+    try {
+      ageMs = now - new Date(snapshot.createdAt).getTime();
+    } catch {
+      // Unparseable date — skip this snapshot.
+      console.error(`${MODULE}: gcSnapshots — could not parse createdAt '${snapshot.createdAt}' for ref ${snapshot.ref}, skipping`);
+      continue;
+    }
+
+    if (isNaN(ageMs)) {
+      console.error(`${MODULE}: gcSnapshots — invalid date for ref ${snapshot.ref}, skipping`);
+      continue;
+    }
+
+    const ageDays = ageMs / msPerDay;
+    if (ageDays > olderThanDays) {
+      const result = await deleteSnapshot({ refName: snapshot.ref });
+      if (result.ok) {
+        deletedCount++;
+      } else {
+        console.error(`${MODULE}: gcSnapshots — failed to delete ${snapshot.ref}: ${result.error}`);
+      }
+    }
+  }
+
+  return { ok: true, deletedCount, scanned };
+}

package/scripts/lib/crypto-digest-utils.mjs

@@ -0,0 +1,91 @@
+/**
+ * crypto-digest-utils.mjs — Shared SHA-256 digest helpers.
+ *
+ * Replaces inline `createHash('sha256')...` patterns in 6 modules.
+ * Pure functions, no side effects, no async.
+ *
+ * Exports:
+ *   digestSha256Short(input, options?)       → string (truncated hex, default 8 chars)
+ *   digestSha256(input, options?)            → string (full hex digest)
+ *   digestSha256WithSalt(value, options)     → string (salt + \x00 + value pattern)
+ *   digestMultiBufferSha256(buffers, options?) → string (sequential multi-buffer update)
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Compute a SHA-256 digest of `input` and return a truncated hex string.
+ * The most common pattern: an 8-character hex prefix suitable as a stable
+ * short identifier (e.g. schema hash, task dedup key).
+ *
+ * @param {string|Buffer} input  - Value to hash; coerced to string when not a Buffer.
+ * @param {{ length?: number, encoding?: string }} [options]
+ *   - `length`   Number of leading characters to return (default 8).
+ *   - `encoding` Digest encoding passed to `hash.digest()` (default 'hex').
+ * @returns {string} Truncated digest string.
+ */
+export function digestSha256Short(input, options = {}) {
+  const length = options.length ?? 8;
+  const encoding = options.encoding ?? 'hex';
+  return createHash('sha256').update(String(input ?? '')).digest(encoding).slice(0, length);
+}
+
+/**
+ * Compute the full SHA-256 digest of `input` without truncation.
+ *
+ * @param {string|Buffer} input  - Value to hash; coerced to string when not a Buffer.
+ * @param {{ encoding?: string }} [options]
+ *   - `encoding` Digest encoding passed to `hash.digest()` (default 'hex').
+ * @returns {string} Full digest string.
+ */
+export function digestSha256(input, options = {}) {
+  const encoding = options.encoding ?? 'hex';
+  return createHash('sha256').update(String(input ?? '')).digest(encoding);
+}
+
+/**
+ * Compute a SHA-256 digest using the `salt + \x00 + value` pattern.
+ * Used for hostname hashing where a per-installation salt prevents
+ * cross-installation correlation without knowing the salt.
+ *
+ * @param {string} value  - The value to hash (e.g. hostname).
+ * @param {{ salt: string, encoding?: string }} options
+ *   - `salt`     Required. The salt string prepended before a NUL separator.
+ *   - `encoding` Digest encoding passed to `hash.digest()` (default 'hex').
+ * @returns {string} Full digest string.
+ * @throws {TypeError} When `options.salt` is not a string.
+ */
+export function digestSha256WithSalt(value, options) {
+  if (!options || typeof options.salt !== 'string') {
+    throw new TypeError('digestSha256WithSalt requires options.salt (string)');
+  }
+  const encoding = options.encoding ?? 'hex';
+  return createHash('sha256')
+    .update(options.salt)
+    .update('\x00')
+    .update(String(value ?? ''))
+    .digest(encoding);
+}
+
+/**
+ * Compute a SHA-256 digest by sequentially updating over an array of
+ * buffers or strings. Preserves the exact update order of the original
+ * multi-step `hash.update(a).update(b)...` patterns.
+ *
+ * @param {Array<string|Buffer>} buffers  - Ordered list of values to feed into the hash.
+ * @param {{ encoding?: string }} [options]
+ *   - `encoding` Digest encoding passed to `hash.digest()` (default 'hex').
+ * @returns {string} Full digest string.
+ * @throws {TypeError} When `buffers` is not an array.
+ */
+export function digestMultiBufferSha256(buffers, options = {}) {
+  if (!Array.isArray(buffers)) {
+    throw new TypeError('digestMultiBufferSha256 requires buffers (array)');
+  }
+  const encoding = options.encoding ?? 'hex';
+  const h = createHash('sha256');
+  for (const b of buffers) {
+    h.update(b);
+  }
+  return h.digest(encoding);
+}

package/scripts/lib/discovery/helpers.mjs

@@ -0,0 +1,127 @@
+/**
+ * discovery-helpers.mjs — Shared utilities for /discovery and /test --since filtering.
+ *
+ * Pure ESM, Node stdlib only. No shell injection: uses execFile throughout.
+ *
+ * Exports:
+ *   changedFilesSince(ref) → Promise<string[]>
+ *
+ * Part of the Clawpatch Borrow Cluster (issue #420).
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Input validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Characters that should never appear in a git ref passed to execFile args.
+ *
+ * NOTE — layered defence: `execFile` is the primary injection guard (it passes
+ * args directly to the OS without invoking a shell, so none of these characters
+ * can trigger shell interpretation).  This regex is a secondary sanity-check
+ * that catches clearly-malformed refs early, before the process is spawned, and
+ * provides a human-readable error message.  Do NOT rely on this regex as the
+ * sole injection barrier.
+ *
+ * Includes `\n` and `\r` to reject pathological env-injected refs that contain
+ * embedded newlines (can occur in certain CI variable-expansion scenarios).
+ *
+ * @type {RegExp}
+ */
+const UNSAFE_REF_CHARS = /[;|&`$<>\\\n\r]/;
+
+/**
+ * Validate that `ref` does not contain shell-injection-relevant characters.
+ * Throws a TypeError if the ref is invalid.
+ *
+ * @param {string} ref
+ */
+function validateRef(ref) {
+  if (UNSAFE_REF_CHARS.test(ref)) {
+    throw new TypeError(
+      `Invalid ref '${ref}': contains shell-unsafe characters (;|&\`$<>\\, newlines). ` +
+        `Use a plain git ref like HEAD~3, a commit hash, or a branch name.`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the list of files changed between `ref` and HEAD.
+ *
+ * Resolution:
+ *   1. Validates the ref with git rev-parse (confirms it is resolvable).
+ *   2. Runs git diff --name-only <ref>..HEAD.
+ *   3. Returns sorted, de-duplicated relative paths (no leading ./ or /).
+ *
+ * Empty result (no files changed) → returns [] — the CALLER decides whether
+ * to skip or proceed with a full scan.
+ *
+ * @param {string} ref - Git ref (commit hash, branch name, tag, HEAD~N, …).
+ * @returns {Promise<string[]>} Sorted array of relative file paths.
+ * @throws {Error} If the ref cannot be resolved or git is unavailable.
+ */
+export async function changedFilesSince(ref) {
+  if (!ref || typeof ref !== 'string' || !ref.trim()) {
+    throw new TypeError(`changedFilesSince: ref must be a non-empty string, got: ${JSON.stringify(ref)}`);
+  }
+
+  const trimmedRef = ref.trim();
+  validateRef(trimmedRef);
+
+  // Step 1: verify the ref is resolvable.
+  try {
+    await execFileAsync('git', ['rev-parse', '--verify', trimmedRef], {
+      encoding: 'utf8',
+      // No shell — args are passed directly to git.
+    });
+  } catch (err) {
+    const detail = err.stderr ? err.stderr.trim() : String(err);
+    throw new Error(
+      `Cannot resolve ref '${trimmedRef}'. Common causes: shallow clone ` +
+        `(run 'git fetch --unshallow'), local-only refs that have not been ` +
+        `fetched, or a typo. Use HEAD~N or 'git log --oneline' to list ` +
+        `available refs. Original error: ${detail}`,
+      { cause: err },
+    );
+  }
+
+  // Step 2: compute changed files.
+  let rawOutput;
+  try {
+    const result = await execFileAsync('git', ['diff', '--name-only', `${trimmedRef}..HEAD`], {
+      encoding: 'utf8',
+    });
+    rawOutput = result.stdout ?? result;
+  } catch (err) {
+    // A non-zero exit from git diff --name-only is unusual (the ref already
+    // validated above) but surface as a clear error.
+    const detail = err.stderr ? err.stderr.trim() : String(err);
+    throw new Error(
+      `git diff --name-only ${trimmedRef}..HEAD failed: ${detail}`,
+      { cause: err },
+    );
+  }
+
+  // Step 3: normalise paths.
+  const paths = String(rawOutput)
+    .split('\n')
+    .map((p) => p.trim())
+    // Remove empty lines (trailing newline, etc.).
+    .filter(Boolean)
+    // Strip leading ./ if somehow present.
+    .map((p) => (p.startsWith('./') ? p.slice(2) : p))
+    // Strip leading / if somehow present (safety net).
+    .map((p) => (p.startsWith('/') ? p.slice(1) : p));
+
+  // Deduplicate + sort alphabetically.
+  return [...new Set(paths)].sort();
+}