session-orchestrator 3.16.0

package/scripts/lib/state-md-peer-guard.mjs

@@ -0,0 +1,232 @@
+/**
+ * state-md-peer-guard.mjs — Issue #588 (STATE.md peer-guard)
+ *
+ * Belt-and-suspenders defense for session-start Phase 1b.
+ *
+ * Even with parallel-aware-preamble (Phase 0.5) and session-lock acquire
+ * (Phase 1.2) in place, a session can miss an active peer when:
+ *   - The peer's session.lock was force-deleted (stale-PID sweep) but
+ *     STATE.md still shows status:active.
+ *   - A registry entry was orphaned but not yet swept.
+ *
+ * `checkPeerStateMd` reads the repo's STATE.md frontmatter and reports
+ * whether a *different* active session currently owns it.  Callers
+ * (session-start Phase 1b, skill body) use the result to decide whether to
+ * fire the Worktree-Promotion AUQ before overwriting STATE.md.
+ *
+ * Never throws — all errors are surfaced via the `reason` field with value
+ * `'malformed-state-md'` so callers can always act on the return value.
+ *
+ * @module state-md-peer-guard
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseStateMd } from './state-md.mjs';
+
+// ---------------------------------------------------------------------------
+// Canonical STATE.md path candidates (same order as frontmatter-mutators.mjs)
+// ---------------------------------------------------------------------------
+
+const STATE_MD_CANDIDATES = ['.claude/STATE.md', '.codex/STATE.md', '.cursor/STATE.md', '.pi/STATE.md'];
+
+function preferredStateMdCandidate() {
+  switch (process.env.SO_PLATFORM) {
+    case 'codex': return '.codex/STATE.md';
+    case 'cursor': return '.cursor/STATE.md';
+    case 'pi': return '.pi/STATE.md';
+    default: return '.claude/STATE.md';
+  }
+}
+
+function orderedStateMdCandidates() {
+  const preferred = preferredStateMdCandidate();
+  return [
+    preferred,
+    ...STATE_MD_CANDIDATES.filter((candidate) => candidate !== preferred),
+  ];
+}
+
+/**
+ * Resolve the first existing STATE.md path under repoRoot, checking the active
+ * platform first. Falls back to the active platform path when none exist.
+ *
+ * @param {string} repoRoot
+ * @returns {string}  Absolute path (may not exist on disk).
+ */
+function _resolveStateMdPath(repoRoot) {
+  const candidates = orderedStateMdCandidates();
+  for (const candidate of candidates) {
+    const abs = join(repoRoot, candidate);
+    if (existsSync(abs)) return abs;
+  }
+  return join(repoRoot, candidates[0]);
+}
+
+// ---------------------------------------------------------------------------
+// Age calculation helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Return age in decimal hours from an ISO-8601 `started_at` string to now.
+ * Returns Infinity on unparseable input so callers treat malformed dates as
+ * "very old" (safe-side: allow overwrite).
+ *
+ * DIVERGENCE NOTE: `_ageHoursFrom` in peer-discovery.mjs returns undefined on
+ * unparseable input so callers can omit the ageHours field rather than emit a
+ * misleading number. This function returns Infinity instead — a fail-safe
+ * semantics: a malformed date is treated as "infinitely old/definitely-stale"
+ * which permits the overwrite rather than blocking on an indeterminate age.
+ * The divergence is intentional: peer-guard needs a conservative yes/no
+ * decision, so Infinity is the correct safe default; peer-discovery emits
+ * structured data, so undefined (field omission) is correct. Do NOT merge
+ * or unify these helpers.
+ *
+ * @param {string|null|undefined} startedAt
+ * @returns {number}  Hours elapsed (may be Infinity).
+ */
+function _ageHoursFromStartedAt(startedAt) {
+  if (typeof startedAt !== 'string' || startedAt.trim() === '') return Infinity;
+  const ms = Date.now() - new Date(startedAt).getTime();
+  if (!Number.isFinite(ms)) return Infinity;
+  return ms / (1000 * 60 * 60);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect whether a peer session owns the current repo's STATE.md.
+ *
+ * Decision tree:
+ *  1. File missing            → { peer: null, reason: 'no STATE.md' }
+ *  2. Malformed frontmatter   → { peer: null, reason: 'malformed-state-md' }
+ *  3. status completed|idle   → { peer: null, reason: 'status: <X>' }
+ *  4. status active + session === mySessionId
+ *                             → { peer: null, reason: 'own session' }
+ *  5. status active + different session + age > maxAgeHours
+ *                             → { peer: null, reason: 'ABANDONED (age > maxAgeHours)' }
+ *  6. status active + different session + age ≤ maxAgeHours
+ *                             → { peer: { sessionId, startedAt, currentWave, mode, ageHours },
+ *                                  reason: 'ACTIVE peer detected' }
+ *
+ * @param {string}      repoRoot     Absolute path to the repository root.
+ * @param {string|null} mySessionId  Current session's id (UUID or semantic);
+ *                                   null means "no session yet" — any active
+ *                                   session counts as a peer.
+ * @param {object}      [opts]
+ * @param {number}      [opts.maxAgeHours=4]  STATE.md older than this is
+ *                                             treated as abandoned (allow overwrite).
+ * @returns {{
+ *   peer: {
+ *     sessionId:   string,
+ *     startedAt:   string,
+ *     currentWave: number,
+ *     mode:        string|null,
+ *     ageHours:    number
+ *   } | null,
+ *   reason: string | null
+ * }}
+ */
+export function checkPeerStateMd(repoRoot, mySessionId, opts = {}) {
+  const maxAgeHours =
+    typeof opts.maxAgeHours === 'number' && opts.maxAgeHours > 0 ? opts.maxAgeHours : 4;
+
+  // ------------------------------------------------------------------
+  // Step 1: resolve + read STATE.md
+  // ------------------------------------------------------------------
+  const stateMdPath = _resolveStateMdPath(repoRoot);
+
+  let raw;
+  try {
+    raw = readFileSync(stateMdPath, 'utf8');
+  } catch (err) {
+    // ENOENT is expected for fresh repos; other FS errors also treated as
+    // "no STATE.md" — fail-open (allow overwrite) rather than blocking.
+    if (err.code === 'ENOENT') {
+      return { peer: null, reason: 'no STATE.md' };
+    }
+    return { peer: null, reason: 'no STATE.md' };
+  }
+
+  // ------------------------------------------------------------------
+  // Step 2: parse frontmatter (parseStateMd never throws per its contract)
+  // ------------------------------------------------------------------
+  let parsed;
+  try {
+    parsed = parseStateMd(raw);
+  } catch {
+    return { peer: null, reason: 'malformed-state-md' };
+  }
+
+  if (parsed === null || parsed.frontmatter === null) {
+    return { peer: null, reason: 'malformed-state-md' };
+  }
+
+  const fm = parsed.frontmatter;
+
+  // ------------------------------------------------------------------
+  // Step 3: check status field
+  // ------------------------------------------------------------------
+  const status = typeof fm.status === 'string' ? fm.status.toLowerCase().trim() : '';
+
+  if (status === 'completed' || status === 'idle') {
+    return { peer: null, reason: `status: ${status}` };
+  }
+
+  // Any non-active value (missing, unknown) → treat as non-blocking.
+  if (status !== 'active') {
+    return { peer: null, reason: `status: ${status || 'unknown'}` };
+  }
+
+  // ------------------------------------------------------------------
+  // Step 4: check session identity
+  // ------------------------------------------------------------------
+  // PRECONDITION (invariant): `mySessionId` and `fm.session` MUST be expressed
+  // in the SAME id-space (both semantic OR both UUID). The equality check below
+  // is plain string-equality — a semantic-vs-UUID mismatch for the SAME logical
+  // session would be misclassified as a foreign peer (fail-safe: extra AUQ, never
+  // a missed peer). When `mySessionId === null` ("no session yet"), the ownership
+  // short-circuit is skipped and any active session with a `session` field counts
+  // as a peer.
+  const sessionField = typeof fm.session === 'string' ? fm.session : null;
+
+  // No session field → cannot identify a peer; allow overwrite.
+  if (sessionField === null) {
+    return { peer: null, reason: 'no session field' };
+  }
+
+  // Session matches ours → we own STATE.md already.
+  if (mySessionId !== null && sessionField === mySessionId) {
+    return { peer: null, reason: 'own session' };
+  }
+
+  // ------------------------------------------------------------------
+  // Step 5: check age of the active entry
+  // ------------------------------------------------------------------
+  const startedAt = typeof fm['started_at'] === 'string' ? fm['started_at'] : null;
+  const ageHours = _ageHoursFromStartedAt(startedAt);
+
+  if (ageHours > maxAgeHours) {
+    return { peer: null, reason: 'ABANDONED (age > maxAgeHours)' };
+  }
+
+  // ------------------------------------------------------------------
+  // Step 6: active peer detected
+  // ------------------------------------------------------------------
+  const currentWave = typeof fm['current-wave'] === 'number' ? fm['current-wave'] : 0;
+  // `session-type` is the frontmatter key used for mode (e.g. 'deep', 'feature').
+  const mode = typeof fm['session-type'] === 'string' ? fm['session-type'] : null;
+
+  return {
+    peer: {
+      sessionId: sessionField,
+      startedAt: startedAt ?? '',
+      currentWave,
+      mode,
+      ageHours,
+    },
+    reason: 'ACTIVE peer detected',
+  };
+}

package/scripts/lib/state-md.mjs

@@ -0,0 +1,53 @@
+/**
+ * STATE.md helpers (issue #184).
+ *
+ * Thin barrel — re-exports all 25 public symbols from the split submodules.
+ * Implementation lives in scripts/lib/state-md/*.mjs.
+ *
+ * @see scripts/lib/state-md/yaml-parser.mjs        parseStateMd, serializeStateMd
+ * @see scripts/lib/state-md/frontmatter-mutators.mjs touchUpdatedField, updateFrontmatterFields
+ * @see scripts/lib/state-md/body-sections.mjs       readCurrentTask, appendDeviation, markExpressPathComplete, appendWhatNotToRetry, readWhatNotToRetry, readOpenQuestions, appendOpenQuestion, markOpenQuestionAnswered
+ * @see scripts/lib/state-md/mission-status.mjs      parseMissionStatus, writeMissionStatus, setMissionStatus, readMissionStatus
+ * @see scripts/lib/state-md/recommendations.mjs     parseRecommendations
+ */
+
+export { parseStateMd, serializeStateMd } from './state-md/yaml-parser.mjs';
+
+export {
+  touchUpdatedField,
+  updateFrontmatterFields,
+  resolveStateMdPath,
+  writeStateMd,
+  updateFrontmatterFieldsOnDisk,
+  touchUpdatedFieldOnDisk,
+} from './state-md/frontmatter-mutators.mjs';
+
+export {
+  readCurrentTask,
+  appendDeviation,
+  markExpressPathComplete,
+  recordAutoCommit,
+  appendDeviationOnDisk,
+  recordAutoCommitOnDisk,
+  markExpressPathCompleteOnDisk,
+  appendWhatNotToRetry,
+  readWhatNotToRetry,
+  appendWhatNotToRetryOnDisk,
+  readOpenQuestions,
+  appendOpenQuestion,
+  markOpenQuestionAnswered,
+  appendOpenQuestionOnDisk,
+  markOpenQuestionAnsweredOnDisk,
+  MAX_OPEN_QUESTIONS_STORED,
+} from './state-md/body-sections.mjs';
+
+export {
+  parseMissionStatus,
+  writeMissionStatus,
+  setMissionStatus,
+  readMissionStatus,
+  writeMissionStatusOnDisk,
+  setMissionStatusOnDisk,
+} from './state-md/mission-status.mjs';
+
+export { parseRecommendations } from './state-md/recommendations.mjs';

package/scripts/lib/subagents-schema.mjs

@@ -0,0 +1,309 @@
+/**
+ * subagents-schema.mjs — schema module for subagent lifecycle records.
+ *
+ * Mirrors learnings.mjs style: Zod-free, custom ValidationError, validate /
+ * normalize / migrate / append / read functions. No top-level side effects.
+ *
+ * Part of issue #342 (PostToolUseFailure + PostToolBatch + SubagentStart/Stop
+ * hook handlers). W1-Part1 scope: schema module only.
+ *
+ * Canonical schema (schema_version: 1):
+ *   timestamp         ISO 8601 string — when the event occurred
+ *   event             'start' | 'stop' — lifecycle event type
+ *   agent_id          string — unique identifier for the subagent instance
+ *   schema_version    1 (integer)
+ *
+ * Required for event='stop':
+ *   duration_ms       positive integer — wall-clock time from start to stop
+ *
+ * Optional:
+ *   agent_type        string | null — e.g. 'explore', 'writer', 'test-writer'
+ *   parent_session_id string | null — session that spawned this subagent
+ *   token_input       integer | null — prompt token count for this subagent
+ *   token_output      integer | null — completion token count for this subagent
+ *   total_cost_usd    number  | null — native total cost in USD (#624, fractional,
+ *                                      best-effort: null when the harness does not
+ *                                      expose it; no rate table is applied)
+ *
+ * OTel aliases (optional, stop-only, additive — #411, schema_version=1 backwards-compat):
+ *   gen_ai.usage.input_tokens   integer | null — alias of token_input
+ *   gen_ai.usage.output_tokens  integer | null — alias of token_output
+ *   gen_ai.system               'anthropic'    — AI provider identifier
+ */
+
+import { readFile, appendFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Current subagent-record schema version. */
+export const CURRENT_SCHEMA_VERSION = 1;
+
+/** Allowed event values. */
+export const VALID_EVENTS = Object.freeze(['start', 'stop']);
+
+// ---------------------------------------------------------------------------
+// ValidationError
+// ---------------------------------------------------------------------------
+
+export class ValidationError extends Error {
+  /**
+   * @param {string} message
+   * @param {string|undefined} field — optional field name that triggered the error
+   */
+  constructor(message, field) {
+    super(message);
+    this.name = 'ValidationError';
+    this.field = field;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Validate
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a subagent record. Throws ValidationError on any constraint
+ * violation. Does NOT mutate the input.
+ *
+ * Required fields: timestamp, event, agent_id, schema_version.
+ * Additional requirement when event='stop': duration_ms (positive integer).
+ * Optional: agent_type, parent_session_id, token_input, token_output.
+ *
+ * @param {object} entry
+ * @returns {object} the entry (unchanged) — validation is side-effect-free
+ * @throws {ValidationError}
+ */
+export function validateSubagent(entry) {
+  if (!entry || typeof entry !== 'object') {
+    throw new ValidationError('subagent record must be a non-null object');
+  }
+
+  // schema_version
+  if (entry.schema_version !== CURRENT_SCHEMA_VERSION) {
+    throw new ValidationError(
+      `schema_version must be ${CURRENT_SCHEMA_VERSION}, got: ${entry.schema_version}`,
+      'schema_version',
+    );
+  }
+
+  // timestamp
+  if (typeof entry.timestamp !== 'string' || !entry.timestamp.trim()) {
+    throw new ValidationError('timestamp must be a non-empty ISO 8601 string', 'timestamp');
+  }
+  if (Number.isNaN(Date.parse(entry.timestamp))) {
+    throw new ValidationError(
+      `timestamp is not a valid ISO 8601 date: ${entry.timestamp}`,
+      'timestamp',
+    );
+  }
+
+  // event
+  if (!VALID_EVENTS.includes(entry.event)) {
+    throw new ValidationError(
+      `event must be one of ${VALID_EVENTS.join('|')}, got: ${entry.event}`,
+      'event',
+    );
+  }
+
+  // agent_id
+  if (typeof entry.agent_id !== 'string' || !entry.agent_id.trim()) {
+    throw new ValidationError('agent_id must be a non-empty string', 'agent_id');
+  }
+
+  // duration_ms — required for stop events
+  if (entry.event === 'stop') {
+    if (
+      typeof entry.duration_ms !== 'number' ||
+      !Number.isInteger(entry.duration_ms) ||
+      entry.duration_ms < 0
+    ) {
+      throw new ValidationError(
+        'duration_ms must be a non-negative integer when event=stop',
+        'duration_ms',
+      );
+    }
+  }
+
+  // agent_type (optional)
+  if (entry.agent_type !== undefined && entry.agent_type !== null && typeof entry.agent_type !== 'string') {
+    throw new ValidationError('agent_type must be a string or null', 'agent_type');
+  }
+
+  // parent_session_id (optional)
+  if (
+    entry.parent_session_id !== undefined &&
+    entry.parent_session_id !== null &&
+    typeof entry.parent_session_id !== 'string'
+  ) {
+    throw new ValidationError('parent_session_id must be a string or null', 'parent_session_id');
+  }
+
+  // token_input (optional)
+  if (entry.token_input !== undefined && entry.token_input !== null) {
+    if (typeof entry.token_input !== 'number' || !Number.isInteger(entry.token_input) || entry.token_input < 0) {
+      throw new ValidationError('token_input must be a non-negative integer or null', 'token_input');
+    }
+  }
+
+  // token_output (optional)
+  if (entry.token_output !== undefined && entry.token_output !== null) {
+    if (typeof entry.token_output !== 'number' || !Number.isInteger(entry.token_output) || entry.token_output < 0) {
+      throw new ValidationError('token_output must be a non-negative integer or null', 'token_output');
+    }
+  }
+
+  // total_cost_usd (optional, #624) — fractional number (not integer), best-effort.
+  if (entry.total_cost_usd !== undefined && entry.total_cost_usd !== null) {
+    if (typeof entry.total_cost_usd !== 'number' || !Number.isFinite(entry.total_cost_usd) || entry.total_cost_usd < 0) {
+      throw new ValidationError('total_cost_usd must be a non-negative number or null', 'total_cost_usd');
+    }
+  }
+
+  // OTel alias — #411 additive, schema_version=1 backwards-compat
+  const otelInputTokens = entry['gen_ai.usage.input_tokens'];
+  if (otelInputTokens !== undefined && otelInputTokens !== null) {
+    if (typeof otelInputTokens !== 'number' || !Number.isInteger(otelInputTokens) || otelInputTokens < 0) {
+      throw new ValidationError('gen_ai.usage.input_tokens must be a non-negative integer or null', 'gen_ai.usage.input_tokens');
+    }
+  }
+
+  // OTel alias — #411 additive, schema_version=1 backwards-compat
+  const otelOutputTokens = entry['gen_ai.usage.output_tokens'];
+  if (otelOutputTokens !== undefined && otelOutputTokens !== null) {
+    if (typeof otelOutputTokens !== 'number' || !Number.isInteger(otelOutputTokens) || otelOutputTokens < 0) {
+      throw new ValidationError('gen_ai.usage.output_tokens must be a non-negative integer or null', 'gen_ai.usage.output_tokens');
+    }
+  }
+
+  // OTel alias — #411 additive, schema_version=1 backwards-compat
+  if (entry['gen_ai.system'] !== undefined && entry['gen_ai.system'] !== null) {
+    if (typeof entry['gen_ai.system'] !== 'string') {
+      throw new ValidationError('gen_ai.system must be a string or null', 'gen_ai.system');
+    }
+  }
+
+  return entry;
+}
+
+// ---------------------------------------------------------------------------
+// Normalize
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a subagent record read from disk. Applies defaults for optional
+ * fields so callers can treat legacy and new entries uniformly.
+ * Does NOT throw — malformed entries are passed through unchanged.
+ *
+ * @param {object} entry
+ * @returns {object} entry with optional fields defaulted to null / CURRENT_SCHEMA_VERSION
+ */
+export function normalizeSubagent(entry) {
+  if (!entry || typeof entry !== 'object') return entry;
+  return {
+    ...entry,
+    schema_version: entry.schema_version ?? CURRENT_SCHEMA_VERSION,
+    agent_type: entry.agent_type ?? null,
+    parent_session_id: entry.parent_session_id ?? null,
+    token_input: entry.token_input ?? null,
+    token_output: entry.token_output ?? null,
+    // total_cost_usd — #624 additive, best-effort native cost (null when absent)
+    total_cost_usd: entry.total_cost_usd ?? null,
+    // OTel alias — #411 additive, schema_version=1 backwards-compat
+    'gen_ai.usage.input_tokens': entry['gen_ai.usage.input_tokens'] ?? null,
+    'gen_ai.usage.output_tokens': entry['gen_ai.usage.output_tokens'] ?? null,
+    'gen_ai.system': entry['gen_ai.system'] ?? null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Migrate
+// ---------------------------------------------------------------------------
+
+/**
+ * Migrate a legacy / partial subagent record to the canonical v1 shape.
+ * Idempotent — calling it on an already-canonical record is a safe no-op.
+ * No-op for v1; reserved for future schema bumps.
+ *
+ * The caller MUST still run validateSubagent() on the result before writing.
+ *
+ * @param {object} entry
+ * @returns {object} record with schema_version stamped
+ */
+export function migrateLegacySubagent(entry) {
+  if (!entry || typeof entry !== 'object') return entry;
+  const out = { ...entry };
+  if (out.schema_version === undefined || out.schema_version === null) {
+    out.schema_version = CURRENT_SCHEMA_VERSION;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Append
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a single subagent record to a JSONL file.
+ *
+ * Steps:
+ *   1. Stamp schema_version if missing.
+ *   2. Normalize (apply optional-field defaults).
+ *   3. Validate — throws ValidationError on bad input.
+ *   4. Serialize to JSON + newline.
+ *   5. mkdir(dirname, recursive: true).
+ *   6. appendFile (POSIX append ≤ PIPE_BUF is atomic for typical JSONL lines).
+ *
+ * @param {string} filePath — absolute path to target .jsonl file
+ * @param {object} entry — candidate subagent record
+ * @returns {Promise<object>} the validated + normalized entry that was written
+ * @throws {ValidationError} when the entry fails schema validation
+ */
+export async function appendSubagent(filePath, entry) {
+  const stamped = {
+    ...entry,
+    schema_version: entry?.schema_version ?? CURRENT_SCHEMA_VERSION,
+  };
+  const normalized = normalizeSubagent(stamped);
+  const validated = validateSubagent(normalized);
+  const line = JSON.stringify(validated) + '\n';
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await appendFile(filePath, line, 'utf8');
+  return validated;
+}
+
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+
+/**
+ * Read all valid subagent records from a JSONL file. Malformed lines are
+ * skipped with a stderr warning — never throws.
+ *
+ * @param {string} filePath — absolute path to target .jsonl file
+ * @returns {Promise<object[]>} array of normalized subagent records
+ */
+export async function readSubagents(filePath) {
+  if (!existsSync(filePath)) return [];
+  let raw;
+  try {
+    raw = await readFile(filePath, 'utf8');
+  } catch (err) {
+    process.stderr.write(`[subagents-schema] WARN: could not read ${filePath}: ${err?.message ?? err}\n`);
+    return [];
+  }
+  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+  const entries = [];
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      entries.push(normalizeSubagent(parsed));
+    } catch {
+      process.stderr.write(`[subagents-schema] WARN: skipping malformed JSONL line: ${line.slice(0, 120)}\n`);
+    }
+  }
+  return entries;
+}