session-orchestrator 5.11.0 → 5.13.0

package/scripts/lib/auto-dream.mjs

@@ -26,8 +26,18 @@ import { existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { atomicWriteText, envelopeToError } from './io.mjs';
 
-import { readCanonicalSessions } from './sessions-canonical.mjs';
-import { filterRealSessions } from './session-schema.mjs';
+import { readCanonicalSessions, isMeasuredSession } from './sessions-canonical.mjs';
+import { resolveEventsLedgerRoot } from './platform.mjs';
+
+/**
+ * Tolerated skew (ms) between the system clock (`generated_at`) and filesystem
+ * timestamps (MEMORY.md mtime) in the #788 drift check. Windows was measured
+ * stamping mtimes up to 1 ms AFTER the clock reading that preceded the write.
+ * Ceiling (BV-004): a real MEMORY.md write within this window after the sidecar
+ * is indistinguishable from skew and is not refused. Revisit if a measured skew
+ * above the tolerance appears or a writer needs sub-5-ms freshness.
+ */
+const CLOCK_SKEW_TOLERANCE_MS = 5;
 
 // ---------------------------------------------------------------------------
 // Signal reader — MEMORY.md size + sessions-since-last-cleanup
@@ -53,7 +63,7 @@ import { filterRealSessions } from './session-schema.mjs';
  */
 export async function readDreamSignals({ repoRoot, memoryDir }) {
   const memoryPath = path.join(memoryDir, 'MEMORY.md');
-  const sessionsFilePath = path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl');
+  const sessionsFilePath = path.join(resolveEventsLedgerRoot(repoRoot), '.orchestrator', 'metrics', 'sessions.jsonl');
 
   // 1. Line count of MEMORY.md (missing → 0)
   let memoryLines = 0;
@@ -80,13 +90,10 @@ export async function readDreamSignals({ repoRoot, memoryDir }) {
 
   const entries = readCanonicalSessions({ filePath: sessionsFilePath });
 
-  // Abandoned-session filter (#834): sessions.jsonl carries phantom
-  // `status: 'abandoned'` stubs (session-close-backfill records for
-  // sessions that ended without a real close). They are legitimate DATA
-  // but not legitimate SIGNAL — a burst of abandoned stubs must not fire
-  // /memory-cleanup off zero real work. filterRealSessions() is the
-  // shared, tested implementation (scripts/lib/session-schema/filters.mjs).
-  const realEntries = filterRealSessions(entries);
+  // Count only canonical measured work (#1584), including legacy waves and
+  // known non-synthetic abandoned sessions; synthetic completed stubs do not
+  // advance maintenance cadence or supply a cleanup anchor.
+  const realEntries = entries.filter(isMeasuredSession);
 
   // Find the most recent memory_cleanup_at timestamp across all REAL entries.
   for (const entry of realEntries) {
@@ -438,12 +445,13 @@ export async function applyPendingDream({ repoRoot, memoryDir, maxAgeDays = 14 }
       // (nanosecond) precision on APFS/ext4. Comparing them raw makes a
       // MEMORY.md written in the SAME millisecond as the sidecar (mtimeMs
       // fractionally > the floored generatedMs) look like drift. Floor mtimeMs
-      // to the resolution `generated_at` actually has, then apply strict `>`
-      // (mirrors `ageDays > maxAgeDays`): same-millisecond = clock-resolution
-      // noise, not a drift signal; a later write (≥1ms) is a real signal.
+      // to the resolution `generated_at` actually has. The system clock and
+      // the filesystem clock can also disagree by a millisecond (Windows), so
+      // drift is signalled only beyond CLOCK_SKEW_TOLERANCE_MS: up to the
+      // tolerance = clock noise, tolerance + 1 ms or later = a real write.
       if (existsSync(memoryPath)) {
         const memoryMtimeMs = statSync(memoryPath).mtimeMs;
-        if (Math.floor(memoryMtimeMs) > generatedMs) {
+        if (Math.floor(memoryMtimeMs) > generatedMs + CLOCK_SKEW_TOLERANCE_MS) {
           return { applied: false, reason: 'stale-index', driftMs: Math.round(memoryMtimeMs - generatedMs) };
         }
       }

package/scripts/lib/autopilot/loop.mjs

@@ -21,6 +21,7 @@ import {
 } from './telemetry.mjs';
 import { durableCommit } from './durable-telemetry.mjs';
 import { getStateDir } from '../platform.mjs';
+import { resolveLedgerPath } from '../ledger-path.mjs';
 
 // Internal clamp — mirrors flags.mjs internal; not re-exported there.
 function clampNumber(value, { min, max, fallback }) {
@@ -91,7 +92,7 @@ export async function runLoop(opts = {}) {
   const nowMs = typeof opts.nowMs === 'function' ? opts.nowMs : () => Date.now();
   const jsonlPath = typeof opts.jsonlPath === 'string' && opts.jsonlPath.length > 0
     ? opts.jsonlPath
-    : DEFAULT_JSONL_PATH;
+    : resolveLedgerPath(DEFAULT_JSONL_PATH, process.cwd()); // #1722: linked worktree → main checkout when ignored
   const peerAbortThreshold = typeof opts.peerAbortThreshold === 'number'
     ? opts.peerAbortThreshold
     : DEFAULT_PEER_ABORT_THRESHOLD;
@@ -342,6 +343,7 @@ export async function runLoop(opts = {}) {
     sessionId: state.autopilot_run_id,
     files: [
       jsonlPath.replace(process.cwd() + '/', ''),
+      // ledger-root: durableCommit file list (disabled), not a sink
       '.orchestrator/metrics/sessions.jsonl',
       `${getStateDir()}/STATE.md`,
     ],

package/scripts/lib/autopilot/recent-runs.mjs

@@ -43,12 +43,14 @@
  *   - Corrupt lines are SKIPPED (not fatal): one malformed JSON line does not
  *     discard the rest of the history.
  *
- * No imports beyond node builtins. ESM. eslint-clean (eqeqeq, no-throw).
+ * Imports node builtins plus the #1722 ledger resolver. ESM. eslint-clean (eqeqeq, no-throw).
  */
 
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 
+import { resolveLedgerPath } from '../ledger-path.mjs';
+
 /** Canonical per-repo autopilot telemetry path (relative to repoRoot). */
 const AUTOPILOT_JSONL_RELPATH = path.join('.orchestrator', 'metrics', 'autopilot.jsonl');
 
@@ -80,7 +82,7 @@ export function readRecentAutopilotRuns({ repoRoot, limit = DEFAULT_LIMIT } = {}
 
   let raw;
   try {
-    raw = readFileSync(path.join(repoRoot, AUTOPILOT_JSONL_RELPATH), 'utf8');
+    raw = readFileSync(resolveLedgerPath(AUTOPILOT_JSONL_RELPATH, repoRoot), 'utf8');
   } catch {
     // Missing / unreadable file ⇒ no history ⇒ [] (G2 gate omitted with a warning).
     return [];

package/scripts/lib/autopilot/stall-sampler.mjs

@@ -36,6 +36,7 @@
  */
 
 import { readFileSync, statSync } from 'node:fs';
+import { resolveLedgerPath } from '../ledger-path.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -114,7 +115,7 @@ function readHeartbeatMs(sessionLockPath) {
  * }}
  */
 export function sampleProgress(opts = {}) {
-  const autopilotJsonlPath = opts.autopilotJsonlPath ?? DEFAULT_AUTOPILOT_JSONL;
+  const autopilotJsonlPath = opts.autopilotJsonlPath ?? resolveLedgerPath(DEFAULT_AUTOPILOT_JSONL, process.cwd());
   // stallTimeoutSeconds is currently informational — the caller decides if
   // stallSeconds exceeds threshold. We read it (with default) so the signature
   // stays stable when (future) clamp logic moves here. Underscore prefix marks

package/scripts/lib/autopilot/telemetry.mjs

@@ -21,6 +21,7 @@ import { mkdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { atomicWriteWithBackup, envelopeToError } from '../io.mjs';
+import { resolveLedgerPath } from '../ledger-path.mjs';
 
 // ---------------------------------------------------------------------------
 // Schema version
@@ -183,7 +184,10 @@ const DEFAULT_AUTOPILOT_JSONL = '.orchestrator/metrics/autopilot.jsonl';
  * @param {string}   [jsonlPath]            - defaults to .orchestrator/metrics/autopilot.jsonl
  * @returns {void}
  */
-export function writeMultiStoryCoordinatorEntry(entry, jsonlPath = DEFAULT_AUTOPILOT_JSONL) {
+export function writeMultiStoryCoordinatorEntry(
+  entry,
+  jsonlPath = resolveLedgerPath(DEFAULT_AUTOPILOT_JSONL, process.cwd()),
+) {
   // Defensive: ensure metrics directory exists
   const dir = path.dirname(jsonlPath);
   try { mkdirSync(dir, { recursive: true }); } catch { /* idempotent — directory may already exist */ }

package/scripts/lib/autopilot/worktree-pipeline.mjs

@@ -21,9 +21,9 @@
 //   - scripts/lib/worktree/lifecycle.mjs (substrate: validateWorkspacePath)
 
 // NOTE: zx is imported LAZILY inside functions that need it (see lazyZx() helper).
-// Top-level `import { $ as realZx } from 'zx'` caused fork-pool fragility — when this
+// Top-level `import { $ as realZx } from '../zx.mjs'` caused fork-pool fragility — when this
 // module is loaded in a worker fork before tests like tests/lib/worktree/constants.test.mjs
-// run, vi.mock('zx', ...) factories in those test files cannot re-route the cached
+// run, vi.mock('@lib/zx.mjs', ...) factories in those test files cannot re-route the cached
 // import. Pipeline 3848 (commit 1347c7a) failed for this reason. Lazy import preserves
 // module-load order isolation. Pattern matches deep-2 #367 DI-seam migration.
 import path from 'node:path';
@@ -200,7 +200,7 @@ export async function setupWorktree(context, opts = {}) {
     worktreeRoot = WORKTREE_ROOT_DEFAULT,
   } = context;
 
-  const exec = opts.$ ?? (await import('zx')).$;
+  const exec = opts.$ ?? (await import('../zx.mjs')).$;
 
   // CWE-59 hardening (#375): resolve symlinks in worktreeRoot ONCE so that
   // validateWorkspacePath comparisons use a fully-resolved parent path.
@@ -748,7 +748,7 @@ function writePromotionMarker({ wtPath, sourceRoot, sessionId, branch }) {
  *   recorded verbatim in the `orchestrator.session.root_left` payload. Only used
  *   when `rawSessionId` is given.
  * @param {object} [opts]
- * @param {Function} [opts.$]       - zx-like template-tag executor (DI seam); falls back to lazy `await import('zx')`.
+ * @param {Function} [opts.$]       - zx-like template-tag executor (DI seam); falls back to lazy `await import('../zx.mjs')`.
  * Every freshly created worktree also gets a `.orchestrator/promoted-from.json`
  * marker (see {@link PROMOTION_MARKER_RELPATH}) so session-end Phase 4a can
  * still recognise it after the #1069 process boundary hands the worktree to a
@@ -817,7 +817,7 @@ export async function enterWorktree({
   // -------------------------------------------------------------------------
   // Step 2: Lazy zx DI (Pipeline 3848 commit 1347c7a — mandatory for vi.mock).
   // -------------------------------------------------------------------------
-  const exec = opts.$ ?? (await import('zx')).$;
+  const exec = opts.$ ?? (await import('../zx.mjs')).$;
 
   // -------------------------------------------------------------------------
   // Step 3: Path resolution + boundary check (mirrors setupWorktree lines 154-187).

package/scripts/lib/baseline-archetypes.mjs

@@ -71,7 +71,11 @@ export function validateBaselineContract(value) {
     check(typeof item.id === 'string' && ID.test(item.id));
     check(Number.isSafeInteger(item.order) && item.order >= 1);
     relative(item.templatePath); check(item.templatePath === `templates/${item.id}`);
-    for (const key of ['runtimes', 'packageManagers']) array(item[key], (runtime) => { shape(runtime, ['name', 'version']); text(runtime.name); text(runtime.version); }, 1);
+    // projects-baseline docs/ARCHETYPE-CONTRACT.md: "`pkm-vault` is the only archetype
+    // allowed to have empty runtime and package-manager arrays" (#1607). Every other
+    // archetype still needs at least one entry.
+    const runtimeMinimum = item.id === 'pkm-vault' ? 0 : 1;
+    for (const key of ['runtimes', 'packageManagers']) array(item[key], (runtime) => { shape(runtime, ['name', 'version']); text(runtime.name); text(runtime.version); }, runtimeMinimum);
     shape(item.ui, ['mode', 'framework', 'tailwind']); text(item.ui.mode); text(item.ui.framework); check(typeof item.ui.tailwind === 'boolean');
     shape(item.api, ['mode', 'framework']); text(item.api.mode); text(item.api.framework);
     shape(item.deploy, ['default', 'alternatives']); text(item.deploy.default); strings(item.deploy.alternatives);
@@ -136,10 +140,14 @@ export function baselineSourcePath(root, source, directory = false, { missingRea
   try { realRoot = realpathSync(root); } catch { fail('unsafe-source'); }
   let current = root;
   let stat;
-  for (const component of source.split('/')) {
+  const components = source.split('/');
+  for (const [index, component] of components.entries()) {
     current = path.join(current, component);
     try { stat = lstatSync(current); } catch (error) { fail(error?.code === 'ENOENT' ? missingReason : 'unsafe-source'); }
     if (stat.isSymbolicLink()) fail('unsafe-source');
+    // A path below a non-directory is unsafe on every platform: POSIX lstat
+    // throws ENOTDIR, Windows ENOENT (which would read as "missing").
+    if (index < components.length - 1 && !stat.isDirectory()) fail('unsafe-source');
   }
   if (directory ? !stat.isDirectory() : !stat.isFile()) fail('unsafe-source');
   let real;

package/scripts/lib/blocked-commands-policy.mjs

@@ -19,9 +19,10 @@
  * `{}`, `{"rules":[]}`, malformed JSON, and a missing file) — every overlay
  * failure mode fails TO THE FLOOR, not open.
  *
- * All exported functions are TOTAL: they never throw. The consuming hook keeps
- * its documented `main().catch → exit 0` fail-open for internal errors, so any
- * throw here would silently disarm the guard — totality is load-bearing.
+ * All exported functions are TOTAL: they never throw. The consuming hook now
+ * DENIES on an error inside main() (fail-closed, #1671); only a module-load
+ * failure stays fail-open (#992). A throw here would therefore block every Bash
+ * call instead of disarming the guard — totality is still load-bearing.
  */
 
 import { existsSync, promises as fsp } from 'node:fs';

package/scripts/lib/build-live-signals.mjs

@@ -17,10 +17,11 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { parseStateMd, parseRecommendations, resolveStateMdPath } from './state-md.mjs';
-import { normalizeSession, tailRealSessions } from './session-schema.mjs';
+import { normalizeSession } from './session-schema.mjs';
 import { parseBootstrapLock } from './bootstrap-lock-freshness.mjs';
 import { scanBacklog, DEFAULT_BACKLOG_LIMIT } from './backlog-scan.mjs';
-import { readCanonicalSessions } from './sessions-canonical.mjs';
+import { isMeasuredSession, readCanonicalSessions } from './sessions-canonical.mjs';
+import { resolveEventsLedgerRoot } from './platform.mjs';
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -65,7 +66,7 @@ export async function buildLiveSignals(opts = {}) {
     ? resolve(repoRoot, opts.statePath)
     : resolveStateMdPath(repoRoot);
   const sessionsPath = resolve(
-    repoRoot,
+    typeof opts.sessionsPath === 'string' ? repoRoot : resolveEventsLedgerRoot(repoRoot),
     typeof opts.sessionsPath === 'string'
       ? opts.sessionsPath
       : '.orchestrator/metrics/sessions.jsonl'
@@ -129,12 +130,15 @@ export async function buildLiveSignals(opts = {}) {
     // handling (ENOENT vs EACCES/EISDIR, #1188) is delegated to the shared
     // reader; both still degrade to `[]` here, matching Branch 3's contract.
     const canonical = readCanonicalSessions({ filePath: sessionsPath });
-    const parsed = canonical.map((obj) => normalizeSession(obj));
-    // #834: `status: 'abandoned'` phantom stubs must still be filtered out
-    // BEFORE the tail is taken, or sessionTailN silently means "last N LINES"
-    // instead of "last N REAL sessions". tailRealSessions() does the filter +
-    // tail.
-    recentSessions = tailRealSessions(parsed, sessionTailN);
+    // Audit E1: drop synthetic backfill stubs (incl. non-abandoned
+    // `state-md-completed` ones `isRealSession` lets through) BEFORE normalizing
+    // — they would otherwise count toward the mode-selector's session-type
+    // history. Filtered on the raw record so normalization cannot mask markers.
+    const parsed = canonical.filter(isMeasuredSession).map((obj) => normalizeSession(obj));
+    // Take the tail AFTER measured filtering, using the same population as
+    // site-numbers and dispatcher; a status-only filter would narrow it again.
+    recentSessions = Number.isFinite(sessionTailN) && sessionTailN > 0
+      ? parsed.slice(-Math.floor(sessionTailN)) : [];
   } catch {
     // Branch 3: file unreadable — recentSessions stays [] (readCanonicalSessions
     // itself never throws, but the graceful-null contract is kept as a backstop).