session-orchestrator 3.16.0

package/scripts/lifecycle-sim-v6.mjs

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+/**
+ * scripts/lifecycle-sim-v6.mjs — Lifecycle simulation v6
+ *
+ * Issue #86 — measure the interaction between SO's enforcement layer and the
+ * downstream Claude Code agent layer. Real telemetry (GL#84) is still blocked,
+ * so v6 falls back to a discrete-event simulation parameterised from
+ * directional intuition codified in the issue and the existing v3.2 docs.
+ *
+ * The sim does NOT claim statistical authority. It produces a directional
+ * comparison between `enforcement: warn` and `enforcement: strict` over N
+ * synthetic sessions with a fixed RNG seed. The output is meant to seed a
+ * follow-up real-run experiment, not to drive a policy flip on its own.
+ *
+ * Usage:
+ *   node scripts/lifecycle-sim-v6.mjs [--enforcement warn|strict|both]
+ *                                     [--sessions N] [--seed K]
+ *                                     [--json]
+ *
+ * Defaults: --enforcement both --sessions 100 --seed 42
+ *
+ * Exit codes (per cli-design.md):
+ *   0  — sim ran successfully
+ *   1  — bad CLI args
+ *   2  — internal error
+ */
+
+import { parseArgs } from 'node:util';
+
+// -----------------------------------------------------------------------------
+// Deterministic RNG — mulberry32 (small, well-known, seedable)
+// -----------------------------------------------------------------------------
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function rng() {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Box-Muller normal sample, clamped to [min, max], rounded to int. */
+function gaussianInt(rng, mean, stddev, min, max) {
+  // two uniforms → standard normal
+  let u1 = rng();
+  if (u1 < 1e-9) u1 = 1e-9;
+  const u2 = rng();
+  const z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+  const value = Math.round(mean + z * stddev);
+  return Math.max(min, Math.min(max, value));
+}
+
+// -----------------------------------------------------------------------------
+// Simulation parameters (kept as an explicit object so the report can echo them)
+// -----------------------------------------------------------------------------
+const PARAMS = Object.freeze({
+  // Per-session planned issues sampled from a clipped Gaussian.
+  plannedMean: 12,
+  plannedStddev: 5,
+  plannedMin: 5,
+  plannedMax: 25,
+
+  // Base completion rate (fraction of planned issues an idealised session
+  // completes when nothing is blocked). Per-session jitter applied on top.
+  baseCompletion: 0.78,
+  completionJitter: 0.08, // ±8 percentage points
+
+  // Probability that a planned issue triggers a scope-friction event during
+  // its first edit attempt. Independent of enforcement level — the friction
+  // exists regardless; what differs is what the harness *does* about it.
+  scopeFrictionProb: 0.12,
+
+  // Carryover into next session: fraction of unfinished issues that roll over.
+  // 1.0 = everything carries over; lower values model dropped scope.
+  carryoverFraction: 1.0,
+
+  // Stagnation threshold: a session is "stagnant" when carryover_ratio > this.
+  stagnationCarryoverRatio: 0.5,
+
+  // Stagnation streak length triggering the "stagnant streak" bucket.
+  stagnationStreakLength: 3,
+
+  // Enforcement-mode-specific multipliers — see the report for the rationale
+  // and limits of these values.
+  modes: {
+    warn: {
+      // warn: friction is logged but the agent is allowed to retry, often
+      // converging on a partial solution. Friction events drag completion
+      // down moderately (each event costs ~1.5% completion) and a small
+      // fraction of friction events become permanent blocks.
+      frictionCompletionPenalty: 0.015,
+      blockConversionRate: 0.18,
+    },
+    strict: {
+      // strict: every scope-violation hard-aborts the agent's current step.
+      // The agent has to re-plan. This hurts completion more per event but
+      // converts fewer events into permanent blocks because the agent never
+      // produces partial-but-wrong output.
+      frictionCompletionPenalty: 0.025,
+      blockConversionRate: 0.08,
+    },
+  },
+});
+
+// -----------------------------------------------------------------------------
+// Single-mode simulation
+// -----------------------------------------------------------------------------
+function simulateMode({ mode, sessions, seed }) {
+  if (!PARAMS.modes[mode]) {
+    throw new Error(`Unknown enforcement mode: ${mode}`);
+  }
+  const { frictionCompletionPenalty, blockConversionRate } = PARAMS.modes[mode];
+
+  // Seed each mode independently of the other so order doesn't matter, but
+  // derive the seed from the user seed so re-runs with the same --seed are
+  // identical.
+  const modeSeed = seed ^ (mode === 'warn' ? 0xa5a5a5a5 : 0x5a5a5a5a);
+  const rng = mulberry32(modeSeed);
+
+  let carryoverIssues = 0;
+  let stagnationStreak = 0;
+  let longestStagnationStreak = 0;
+  let stagnantSessionCount = 0;
+  let totalPlanned = 0;
+  let totalCompleted = 0;
+  let totalBlocked = 0;
+  const carryoverRatios = [];
+
+  for (let i = 0; i < sessions; i++) {
+    const fresh = gaussianInt(
+      rng,
+      PARAMS.plannedMean,
+      PARAMS.plannedStddev,
+      PARAMS.plannedMin,
+      PARAMS.plannedMax,
+    );
+    const planned = fresh + carryoverIssues;
+    totalPlanned += planned;
+
+    // Friction events: one Bernoulli draw per planned issue.
+    let frictionEvents = 0;
+    let permanentBlocks = 0;
+    for (let j = 0; j < planned; j++) {
+      if (rng() < PARAMS.scopeFrictionProb) {
+        frictionEvents += 1;
+        if (rng() < blockConversionRate) {
+          permanentBlocks += 1;
+        }
+      }
+    }
+
+    // Effective completion rate — base, jitter, friction penalty.
+    const jitter = (rng() * 2 - 1) * PARAMS.completionJitter;
+    let completionRate = PARAMS.baseCompletion + jitter;
+    completionRate -= frictionEvents * frictionCompletionPenalty;
+    completionRate = Math.max(0, Math.min(1, completionRate));
+
+    const completable = planned - permanentBlocks;
+    const completed = Math.min(completable, Math.round(completable * completionRate));
+    totalCompleted += completed;
+    totalBlocked += permanentBlocks;
+
+    const unfinished = planned - completed;
+    const carryoverRatio = planned === 0 ? 0 : unfinished / planned;
+    carryoverRatios.push(carryoverRatio);
+
+    if (carryoverRatio > PARAMS.stagnationCarryoverRatio) {
+      stagnationStreak += 1;
+      if (stagnationStreak >= PARAMS.stagnationStreakLength) {
+        stagnantSessionCount += 1;
+      }
+      if (stagnationStreak > longestStagnationStreak) {
+        longestStagnationStreak = stagnationStreak;
+      }
+    } else {
+      stagnationStreak = 0;
+    }
+
+    carryoverIssues = Math.round(unfinished * PARAMS.carryoverFraction);
+  }
+
+  carryoverRatios.sort((a, b) => a - b);
+  const meanCarryover =
+    carryoverRatios.reduce((s, v) => s + v, 0) / carryoverRatios.length;
+  const p95Index = Math.min(
+    carryoverRatios.length - 1,
+    Math.floor(0.95 * carryoverRatios.length),
+  );
+  const p95Carryover = carryoverRatios[p95Index];
+
+  return {
+    mode,
+    sessions,
+    totals: {
+      planned: totalPlanned,
+      completed: totalCompleted,
+      blocked: totalBlocked,
+    },
+    completionRatio: totalPlanned === 0 ? 0 : totalCompleted / totalPlanned,
+    carryover: {
+      meanRatio: meanCarryover,
+      p95Ratio: p95Carryover,
+    },
+    stagnation: {
+      streakThreshold: PARAMS.stagnationStreakLength,
+      carryoverThreshold: PARAMS.stagnationCarryoverRatio,
+      stagnantSessions: stagnantSessionCount,
+      stagnationRate: stagnantSessionCount / sessions,
+      longestStreak: longestStagnationStreak,
+    },
+  };
+}
+
+// -----------------------------------------------------------------------------
+// CLI
+// -----------------------------------------------------------------------------
+function parseCli(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      enforcement: { type: 'string', default: 'both' },
+      sessions: { type: 'string', default: '100' },
+      seed: { type: 'string', default: '42' },
+      json: { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+    allowPositionals: false,
+  });
+  return values;
+}
+
+const HELP = `lifecycle-sim-v6 — issue #86 directional simulation
+
+Usage:
+  node scripts/lifecycle-sim-v6.mjs [--enforcement warn|strict|both]
+                                    [--sessions N] [--seed K]
+                                    [--json]
+
+Options:
+  --enforcement   warn | strict | both  (default: both)
+  --sessions N    number of simulated sessions per mode  (default: 100)
+  --seed K        RNG seed for reproducibility           (default: 42)
+  --json          emit JSON to stdout (default: human text)
+  -h, --help      show this help
+
+Exit codes:
+  0  success
+  1  bad arguments
+  2  internal error
+`;
+
+function humanReport(results, opts) {
+  const lines = [];
+  lines.push('lifecycle-sim-v6 — directional results (NOT statistical)');
+  lines.push(`seed=${opts.seed} sessions=${opts.sessions} per mode`);
+  lines.push('');
+  for (const r of results) {
+    lines.push(`mode: ${r.mode}`);
+    lines.push(`  planned issues:        ${r.totals.planned}`);
+    lines.push(`  completed:             ${r.totals.completed}`);
+    lines.push(`  permanently blocked:   ${r.totals.blocked}`);
+    lines.push(`  completion ratio:      ${r.completionRatio.toFixed(3)}`);
+    lines.push(`  mean carryover ratio:  ${r.carryover.meanRatio.toFixed(3)}`);
+    lines.push(`  p95 carryover ratio:   ${r.carryover.p95Ratio.toFixed(3)}`);
+    lines.push(
+      `  stagnant sessions:     ${r.stagnation.stagnantSessions} ` +
+        `(rate ${r.stagnation.stagnationRate.toFixed(3)})`,
+    );
+    lines.push(`  longest streak:        ${r.stagnation.longestStreak}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function main() {
+  let opts;
+  try {
+    opts = parseCli(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`bad args: ${err.message}\n`);
+    return 1;
+  }
+  if (opts.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  const sessions = Number.parseInt(opts.sessions, 10);
+  const seed = Number.parseInt(opts.seed, 10);
+  if (!Number.isFinite(sessions) || sessions <= 0) {
+    process.stderr.write('--sessions must be a positive integer\n');
+    return 1;
+  }
+  if (!Number.isFinite(seed)) {
+    process.stderr.write('--seed must be an integer\n');
+    return 1;
+  }
+
+  let modes;
+  if (opts.enforcement === 'both') {
+    modes = ['warn', 'strict'];
+  } else if (opts.enforcement === 'warn' || opts.enforcement === 'strict') {
+    modes = [opts.enforcement];
+  } else {
+    process.stderr.write(`--enforcement must be warn|strict|both\n`);
+    return 1;
+  }
+
+  let results;
+  try {
+    results = modes.map((mode) => simulateMode({ mode, sessions, seed }));
+  } catch (err) {
+    process.stderr.write(`sim error: ${err.message}\n`);
+    return 2;
+  }
+
+  if (opts.json) {
+    const out = {
+      seed,
+      sessions,
+      params: PARAMS,
+      results,
+    };
+    process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+  } else {
+    process.stdout.write(humanReport(results, { sessions, seed }));
+  }
+  return 0;
+}
+
+// Entry point — only run when invoked as a script (not when imported by tests).
+const isDirectRun = (() => {
+  try {
+    const argv1 = process.argv[1] ? new URL(`file://${process.argv[1]}`).href : '';
+    return import.meta.url === argv1;
+  } catch {
+    return false;
+  }
+})();
+
+if (isDirectRun) {
+  process.exit(main());
+}
+
+// Named exports for tests.
+export { mulberry32, gaussianInt, simulateMode, PARAMS, parseCli, main };

package/scripts/lock-reaper.mjs

@@ -0,0 +1,185 @@
+/**
+ * lock-reaper.mjs — CLI: reconcile orphaned session.lock leases across the fleet.
+ *
+ * Host-wide reconciliation for `session.lock` leases left behind by crashed or
+ * abandoned sessions (Epic #724 C7). Wraps scripts/lib/lock-reaper.mjs
+ * reapStaleLocks(); default mode is --dry-run (classify only). Pass --apply to
+ * archive-move dead-lease locks.
+ *
+ * SAFETY: reaping only ever touches OWN-HOST leases whose heartbeat is past TTL
+ * and whose recorded PID is dead. Live leases and cross-host leases are never
+ * reaped — see the lib's HARD SAFETY INVARIANTS. Every reap is an archive-move
+ * (a copy is written to <repo>/.orchestrator/tmp/reaped-locks/ before the
+ * original is removed), never an unlink-only.
+ *
+ * DO NOT run --apply against the real ~/Projects while parallel sessions are
+ * active unless you understand the invariants — the live-lock guard protects
+ * them, but --dry-run first is the safe habit.
+ *
+ * Exit codes: 0 success · 1 user/input error (bad flags) · 2 system error.
+ *
+ * Exports (for unit tests): main.
+ */
+
+import { reapStaleLocks } from './lib/lock-reaper.mjs';
+
+// ---------------------------------------------------------------------------
+// Human-readable output
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {number|null} ageHours
+ * @returns {string}
+ */
+function formatAge(ageHours) {
+  if (ageHours === null || ageHours === undefined) return 'unknown age';
+  if (ageHours >= 24) return `${(ageHours / 24).toFixed(1)}d stale`;
+  return `${ageHours.toFixed(1)}h stale`;
+}
+
+/**
+ * Print a human-readable summary to stdout.
+ *
+ * @param {{ scanned:number, candidates:object[], reaped:object[], skipped:object[], dryRun:boolean }} result
+ */
+function printHuman(result) {
+  const { scanned, candidates, reaped, skipped, dryRun } = result;
+
+  process.stdout.write(`Scanned ${scanned} repo(s).\n`);
+
+  if (candidates.length > 0) {
+    const label = dryRun ? 'REAP CANDIDATES' : 'REAPED';
+    process.stdout.write(`  ${label} (${candidates.length}):\n`);
+    for (const c of candidates) {
+      const archived = c.archivePath ? ` → ${c.archivePath}` : '';
+      process.stdout.write(`    ${c.repoName ?? c.repo} — session ${c.sessionId}, ${formatAge(c.ageHours)}${archived}\n`);
+    }
+  }
+
+  if (skipped.length > 0) {
+    process.stdout.write(`  SKIPPED (${skipped.length}):\n`);
+    for (const s of skipped) {
+      process.stdout.write(`    ${s.repo} — ${s.reason}\n`);
+    }
+  }
+
+  if (dryRun) {
+    process.stdout.write(
+      `\nDry-run mode. Use --apply to archive-move the ${candidates.length} candidate(s).\n`,
+    );
+  } else {
+    process.stdout.write(`\nApplied. Archived ${reaped.length} orphaned lease(s).\n`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse argv, run the reconciliation, print the result.
+ *
+ * @param {object} [opts]
+ * @param {string[]} [opts.argv]     — override process.argv.slice(2) (tests).
+ * @param {string} [opts.startDir]   — override scan root (tests + --start-dir).
+ * @param {object} [opts.deps]       — forwarded to reapStaleLocks (tests).
+ * @returns {Promise<0|1|2>} exit code.
+ */
+export async function main(opts = {}) {
+  const argv = opts.argv ?? process.argv.slice(2);
+
+  let flagDryRun = false;
+  let flagApply = false;
+  let flagJson = false;
+  let flagHelp = false;
+  let startDir = opts.startDir;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--dry-run':
+        flagDryRun = true;
+        break;
+      case '--apply':
+        flagApply = true;
+        break;
+      case '--json':
+        flagJson = true;
+        break;
+      case '--start-dir':
+        startDir = argv[++i];
+        if (typeof startDir !== 'string' || startDir.length === 0) {
+          process.stderr.write('lock-reaper: --start-dir requires a path argument.\n');
+          return 1;
+        }
+        break;
+      case '--help':
+      case '-h':
+        flagHelp = true;
+        break;
+      default:
+        process.stderr.write(`lock-reaper: unknown argument: ${arg}\n`);
+        process.stderr.write('Run with --help for usage.\n');
+        return 1;
+    }
+  }
+
+  if (flagHelp) {
+    process.stdout.write(`lock-reaper.mjs — reconcile orphaned session.lock leases across the fleet
+
+USAGE
+  node scripts/lock-reaper.mjs [--dry-run] [--apply] [--json] [--start-dir <path>] [--help]
+
+FLAGS
+  --dry-run          (default) Classify orphaned leases; no filesystem mutations.
+  --apply            Archive-move own-host dead-lease locks. Requires explicit opt-in.
+  --json             Emit machine-readable JSON to stdout.
+  --start-dir <path> Override the scan root (defaults to the confinement root).
+  -h, --help         Show this help text and exit.
+
+SAFETY
+  Only own-host leases whose heartbeat is past TTL AND whose recorded PID is
+  dead are reaped. Live leases and cross-host leases are never reaped — they are
+  listed for an operator. Every reap is an archive-move to
+  <repo>/.orchestrator/tmp/reaped-locks/, never an unlink-only.
+
+EXIT CODES
+  0 — success
+  1 — user/input error (bad flags)
+  2 — system error (unexpected exception)
+`);
+    return 0;
+  }
+
+  if (flagApply && flagDryRun) {
+    process.stderr.write('lock-reaper: --apply and --dry-run are mutually exclusive.\n');
+    process.stderr.write('Run with --help for usage.\n');
+    return 1;
+  }
+
+  // Default: dry-run unless --apply was given.
+  const dryRun = !flagApply;
+
+  const result = await reapStaleLocks({ startDir, dryRun, deps: opts.deps });
+
+  if (flagJson) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    printHuman(result);
+  }
+
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// CLI guard — prevents execution during test-time imports.
+// ---------------------------------------------------------------------------
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      process.stderr.write(`lock-reaper: unexpected error: ${err?.stack ?? err}\n`);
+      process.exit(2);
+    });
+}