session-orchestrator 3.22.0 → 3.24.0

package/hooks/_lib/atomic-json.mjs

@@ -0,0 +1,111 @@
+/**
+ * atomic-json.mjs — shared atomic read-modify-write helper for JSON hook state.
+ *
+ * Extracted (issue #1197) from four byte-identical private copies of
+ * `atomicMutateJson` that had accumulated independently in
+ * `hooks/cwd-change-restore.mjs`, `hooks/on-session-end.mjs`,
+ * `hooks/post-tool-batch-wave-signal.mjs`, and
+ * `hooks/post-tool-failure-corrective-context.mjs` (measured 2026-09-02 @
+ * a019d5a4 via `rg -n "function atomicMutateJson" hooks/` — 4 hits, one per
+ * file, logic byte-identical modulo the per-file tmp-suffix and the
+ * `fs.`-namespace-vs-named-import style `on-session-end.mjs` uses).
+ *
+ * F-H fix (W3-reviewer finding, #1197): the pre-extraction copies treated
+ * EVERY read/parse failure as "file absent" and silently fell back to
+ * `defaultValue` — so an unparsable file, `EISDIR`, `EACCES`, or a file
+ * truncated mid-write by a concurrent writer was overwritten with
+ * `defaultValue`-derived content instead of being left alone. Only `ENOENT`
+ * (file genuinely does not exist yet) is a legitimate "start fresh" case;
+ * every other failure now aborts BEFORE the tmp-write/rename stage and
+ * reports `{ ok: false, reason }` — the original file is never touched.
+ *
+ * Return-object over throw (deliberate — see #1197 task note): all four
+ * callers already run under `main().catch(() => {}).finally(() =>
+ * process.exit(0))` — informational, never-deny hooks (verified 2026-09-02:
+ * none of the four match a deny/block pattern) — so a thrown error would be
+ * swallowed safely too. But in `post-tool-batch-wave-signal.mjs` a throw at
+ * the FIRST call site (line ~278, the `last_batch` write) would abort
+ * `main()` before it reaches the independent heartbeat-refresh block that
+ * follows — a real behavioural loss the thrown-error path would introduce
+ * silently. A result object lets every caller decide locally whether an RMW
+ * failure should short-circuit the rest of `main()` or just get logged and
+ * ignored, so no caller loses unrelated post-call behaviour by construction.
+ *
+ * NAMED CEILING (BV-004): tmp-file + rename makes each individual write
+ * atomic, but not the full read-modify-write — two concurrent callers can
+ * still interleave (both read the same `current`, both compute an update
+ * from it, the second rename wins and silently drops the first mutation).
+ * This module does not defend against that race. Revisit with a per-file
+ * lock (e.g. an flock-style sidecar or `session-lock.mjs`'s lease pattern)
+ * if `.orchestrator/current-session.json` writes start dropping fields
+ * under concurrent-session load — no such loss has been measured yet.
+ *
+ * @module hooks/_lib/atomic-json
+ */
+
+import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Atomic read-modify-write of a JSON file via temp-file + rename.
+ *
+ * Reads the existing file and parses it as JSON. When the file does not
+ * exist (`ENOENT`), starts from `defaultValue` — the only case in which
+ * "file absent" is legitimate. Any OTHER read or parse failure (directory
+ * at `filePath`, permission denied, truncated/corrupt JSON, …) aborts
+ * WITHOUT calling `mutate` and WITHOUT writing anything — the original file
+ * (if any) is left exactly as it was.
+ *
+ * On success, applies the synchronous `mutate` transformer, writes the
+ * result to a `${filePath}.tmp-<suffix>-<pid>-<ts>` sibling, then renames it
+ * over `filePath` (atomic on POSIX same-filesystem rename; best-effort on
+ * Windows). If the write/rename stage itself fails, the tmp file is
+ * best-effort unlinked so a failure never leaves an orphaned `.tmp-*`
+ * artifact behind.
+ *
+ * @param {string} filePath — absolute path to the JSON file.
+ * @param {object} defaultValue — starting value used ONLY when the file does
+ *   not exist yet (`ENOENT`). Never applied on top of an unreadable-but-
+ *   present file.
+ * @param {function(object): object} mutate — pure synchronous transformer;
+ *   receives the parsed current value (or `defaultValue`), returns the next
+ *   value to persist.
+ * @param {string} [tmpTag] — short tag folded into the tmp filename so
+ *   concurrent callers targeting the same `filePath` from different hooks
+ *   don't collide on the same tmp path (mirrors the per-caller suffixes the
+ *   four pre-extraction copies used: `-cwd-`, `-ose-`, `-ptb-`, `-ptf-`).
+ * @returns {Promise<{ ok: true, value: object } | { ok: false, reason: string }>}
+ */
+export async function atomicMutateJson(filePath, defaultValue, mutate, tmpTag = 'ajs') {
+  let current = defaultValue;
+  try {
+    const raw = await readFile(filePath, 'utf8');
+    current = JSON.parse(raw);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      // File genuinely does not exist yet — the only legitimate "fresh
+      // file" case. `current` already holds `defaultValue`.
+    } else {
+      // EISDIR, EACCES, a JSON.parse SyntaxError (unparsable/truncated
+      // content), or anything else — never silently treat as "absent".
+      // Abort before mutate/write; the original file is untouched.
+      return { ok: false, reason: (err && err.code) || 'parse-error' };
+    }
+  }
+
+  const updated = mutate(current);
+  const tmp = `${filePath}.tmp-${tmpTag}-${process.pid}-${Date.now()}`;
+  try {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(tmp, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+    await rename(tmp, filePath);
+  } catch (err) {
+    try {
+      await unlink(tmp);
+    } catch {
+      // tmp was never created, or is already gone — nothing to clean up.
+    }
+    return { ok: false, reason: (err && err.code) || 'write-error' };
+  }
+  return { ok: true, value: updated };
+}

package/hooks/_lib/lock-bootstrap.mjs

@@ -89,8 +89,9 @@ export async function bootstrapLock({
   }
 
   // Step 1: try to acquire. If a fresh acquire succeeds, we are done.
-  // If a stale-PID-dead/-alive lock exists, force-overwrite it (the prior
-  // session has died; the current raw owner can take the worktree).
+  // If a stale-heartbeat lock exists, force-overwrite it (the prior session
+  // stopped heartbeating past its ttl; the current raw owner can take the
+  // worktree).
   // Only an exact match of the existing physical raw sessionId permits the
   // same-session force-refresh. semantic_session_id, STATE.md `session`, and
   // an owner proof never make a different raw id the same owner.
@@ -107,8 +108,11 @@ export async function bootstrapLock({
 
   const shouldForce =
     acquireResult.ok !== true && (
-      acquireResult.reason === 'stale-pid-dead' ||
-      acquireResult.reason === 'stale-pid-alive' ||
+      // #1137: 'stale-heartbeat' replaced the former 'stale-pid-dead' /
+      // 'stale-pid-alive' pair. Both legacy spellings are gone from
+      // session-lock.mjs; matching only the new one keeps this force-branch
+      // reachable.
+      acquireResult.reason === 'stale-heartbeat' ||
       (acquireResult.reason === 'active' &&
         acquireResult.existingLock &&
         acquireResult.existingLock.session_id === sessionId)

package/hooks/_lib/subagent-paths.mjs

@@ -0,0 +1,143 @@
+/**
+ * subagent-paths.mjs — consolidated subagent sidecar-path derivation (#1196).
+ *
+ * Four call sites independently derived the SAME shape — the stopping
+ * subagent's own `agent-<id>.jsonl` transcript + `agent-<id>.meta.json`
+ * sidecar, from the PARENT transcript path the harness sends on stdin — and
+ * diverged on strictness. Measured 2026-09-02 @ a019d5a4 (this consolidation):
+ *
+ * | copy (file:line)                                          | honours `agent_transcript_path` | id bound        | rejects `'unknown'` | containment check |
+ * |------------------------------------------------------------|:---:|:---:|:---:|:---:|
+ * | hooks/subagent-telemetry.mjs:513 `resolveSubagentTranscriptPath` | no  | unbounded (`+`) | yes (:517) | n/a (no override) |
+ * | hooks/on-stop.mjs:666 `resolveSidecarBase`                       | no  | `{1,64}` (:566) | **no** | n/a (no override) |
+ * | hooks/post-subagent-discovery-validator.mjs:538 `resolveAgentTranscriptPath` | yes (:539) | `{1,64}` (:547) | yes (:549) | **no** — `explicit` returned unchecked (:539) |
+ * | scripts/lib/wave-transcript-tail.mjs:610 `readAgentType`         | no  | **none** | no | n/a (no override) |
+ *
+ * `resolveSubagentSidecar()` below applies the STRICTEST rule found in ANY
+ * copy to every caller: the `{1,64}` bound, the `'unknown'` rejection (closes
+ * the on-stop.mjs / wave-transcript-tail.mjs gap), AND a path-containment
+ * check on the `agentTranscriptPath` override that NONE of the four copies
+ * performed — post-subagent-discovery-validator.mjs returned the harness
+ * override completely unvalidated. That containment check is a NEW rule this
+ * consolidation introduces, not a preserved behaviour.
+ *
+ * @module hooks/_lib/subagent-paths
+ */
+
+import path from 'node:path';
+
+/**
+ * Real agent ids are hex-ish tokens (e.g. `a60348a01ca982b4c`); anything else
+ * is rejected, not sanitised, so no payload value can traverse out of the
+ * `subagents/` directory. `{1,64}` is the strictest bound found across the
+ * four prior copies (hooks/subagent-telemetry.mjs used an unbounded `+`;
+ * scripts/lib/wave-transcript-tail.mjs applied no charset check at all).
+ */
+export const AGENT_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/**
+ * Validate a candidate agent id against the strictest rule of the four prior
+ * copies: the `{1,64}` charset+length bound, AND explicit rejection of the
+ * literal `'unknown'` — the no-usable-id fallback value that several callers
+ * (`firstNonEmptyString(..., 'unknown')`) substitute when the harness sends no
+ * id at all. `'unknown'` matches `AGENT_ID_RE` (it's plain lowercase letters),
+ * so a charset check alone does not catch it — hooks/on-stop.mjs's
+ * `resolveSidecarBase()` had exactly this gap (AGENT_ID_RE-only, no explicit
+ * `'unknown'` rejection) before this consolidation.
+ *
+ * @param {unknown} agentId
+ * @returns {agentId is string}
+ */
+export function isValidAgentId(agentId) {
+  return typeof agentId === 'string' && AGENT_ID_RE.test(agentId) && agentId !== 'unknown';
+}
+
+/**
+ * Resolve the sidecar pair (`.jsonl` transcript + `.meta.json`) for a stopping
+ * subagent (#949, #1190, #1191, #1196).
+ *
+ * Two paths to the same result:
+ *  - **Override.** `agentTranscriptPath` (the harness's `agent_transcript_path`,
+ *    honoured today only by hooks/post-subagent-discovery-validator.mjs:539)
+ *    wins when present — but ONLY when, after `path.resolve`, it sits inside
+ *    `dirname(transcriptPath)`. An override outside that tree is REJECTED
+ *    (returns null), never silently accepted and never falls through to
+ *    derivation — a bad override must not resolve to an unrelated agent's
+ *    sidecar.
+ *  - **Derivation.** `<dir>/<base>/subagents/agent-<agentId>` from the PARENT
+ *    transcript path — the shape all four prior copies agree on
+ *    (subagent-telemetry.mjs:513, on-stop.mjs:666,
+ *    post-subagent-discovery-validator.mjs:552-553, and the subagentsDir
+ *    scripts/lib/wave-transcript-tail.mjs's tailLoop() already builds by hand).
+ *
+ * Returns null — never a guessed or partial path — on ANY invalid input: an
+ * empty/non-string `transcriptPath`, an `agentId` failing `isValidAgentId()`
+ * (only checked in the derivation branch — the override branch does not need
+ * a valid agentId, matching all four prior copies' precedence), or an override
+ * that fails containment.
+ *
+ * NAMED CEILING (BV-004): the meta path is always derived as
+ * `transcript.replace(/\.jsonl$/i, '.meta.json')` (or `${transcript}.meta.json`
+ * when the transcript has no `.jsonl` suffix to replace — an override the
+ * harness contract says never happens; see the header comments of
+ * hooks/post-subagent-discovery-validator.mjs). REVISIT TRIGGER: if a real
+ * override without a `.jsonl` suffix is ever observed, this needs its own
+ * validation branch instead of the current always-well-formed assumption.
+ *
+ * NAMED CEILING (BV-004, LOW, qa review): the override's containment check
+ * (`path.relative(resolvedDir, resolvedOverride)` below) is LEXICAL, not
+ * filesystem-real — it runs on `path.resolve()`'d strings, never on
+ * `fs.realpathSync()`'d ones. A symlink SITTING INSIDE `dirname(transcriptPath)`
+ * whose TARGET points outside that tree therefore passes containment: the
+ * lexical path looks contained, the file it actually resolves to is not.
+ * Deliberately not fixed with a realpath call here — every current consumer
+ * of this override branch (hooks/post-subagent-discovery-validator.mjs) only
+ * READS the resulting sidecar files, and `agentTranscriptPath` is a value the
+ * HARNESS itself supplies on stdin, not one an untrusted external actor can
+ * inject — so the realpath syscalls would buy nothing against the live
+ * threat model. REVISIT TRIGGER: if `agentTranscriptPath` (or any future
+ * override this module accepts) is ever sourced from a producer this repo
+ * does NOT trust as much as the harness's own stdin payload, resolve both
+ * `resolvedOverride` and `resolvedDir` through `fs.realpathSync()` before the
+ * `path.relative()` comparison, so a symlink cannot smuggle the effective
+ * path outside the allowed tree.
+ *
+ * @param {object} args
+ * @param {string|undefined|null} args.transcriptPath — parent transcript path
+ *   (stdin `transcript_path`, or an equivalent parent-transcript path)
+ * @param {string|undefined|null} args.agentId
+ * @param {string|undefined|null} [args.agentTranscriptPath] — harness override
+ *   (`agent_transcript_path`); takes precedence over derivation when present
+ *   and contained under `dirname(transcriptPath)`
+ * @returns {{base: string, transcript: string, meta: string}|null}
+ */
+export function resolveSubagentSidecar({ transcriptPath, agentId, agentTranscriptPath = null }) {
+  if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) return null;
+
+  const dir = path.dirname(transcriptPath);
+  const base = path.basename(transcriptPath).replace(/\.jsonl$/i, '');
+  if (!base || base === '.' || base === '..') return null;
+
+  let transcript;
+  if (typeof agentTranscriptPath === 'string' && agentTranscriptPath.trim()) {
+    const resolvedOverride = path.resolve(agentTranscriptPath);
+    const resolvedDir = path.resolve(dir);
+    const rel = path.relative(resolvedDir, resolvedOverride);
+    const contained = rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+    if (!contained) return null;
+    transcript = resolvedOverride;
+  } else {
+    if (!isValidAgentId(agentId)) return null;
+    transcript = path.join(dir, base, 'subagents', `agent-${agentId}.jsonl`);
+  }
+
+  const meta = /\.jsonl$/i.test(transcript)
+    ? transcript.replace(/\.jsonl$/i, '.meta.json')
+    : `${transcript}.meta.json`;
+
+  return {
+    base: transcript.replace(/\.jsonl$/i, ''),
+    transcript,
+    meta,
+  };
+}