session-orchestrator 3.24.0 → 4.0.1

package/hooks/post-tool-batch-wave-signal.mjs

@@ -42,6 +42,21 @@
  * under B's identity. `last_batch` stays UNGATED — it is a batch-resolution
  * breadcrumb, not a claim about whose wave lifecycle this is.
  *
+ * DIFF-SIZE MEASUREMENT (#980). The mechanical fallback below persists
+ * `wave_start_sha` (`git rev-parse HEAD`, best-effort) at every wave-OPEN
+ * transition and attaches `files_changed` + `files_changed_source:
+ * 'worktree-vs-wave-start-sha'` to the `orchestrator.wave.completed` it emits
+ * for the wave that sha opened. `files_changed` counts the DEDUPED union of
+ * `git diff --name-only <wave_start_sha>` (working tree vs the wave's start
+ * commit — the coordinator normally commits only at close, so uncommitted
+ * edits must count) and `git ls-files --others --exclude-standard` (untracked).
+ * Every git call is best-effort with a 1.5 s timeout; any failure, or a missing
+ * `wave_start_sha`, OMITS the key — the convergence-monitor reader treats an
+ * absent key as null and the `shrinking_diff` signal simply does not fire.
+ * `wave_start_sha` is written under the SAME ownership gate as the wave keys.
+ * OUT OF SCOPE: `hooks/on-session-end.mjs`'s final-wave `.completed` carries no
+ * `files_changed` — no wave-open transition runs there, so it has no start sha.
+ *
  * MONOTONICITY RULE (#1193 W4c Q3-MED-3). Three writers touch
  * `last_wave_completed` (this hook's explicit branch, this hook's fallback,
  * `hooks/on-session-end.mjs`). Every one of them writes through `maxWave()`,
@@ -51,6 +66,7 @@
  * hooks.json wiring is managed separately (W3-C4 scope).
  */
 
+import { execFileSync } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
@@ -58,7 +74,7 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
 if (!shouldRunHook('post-tool-batch-wave-signal')) process.exit(0);
 
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { findScopeFile } from '../scripts/lib/scope-gate.mjs';
 import { atomicMutateJson } from './_lib/atomic-json.mjs';
@@ -208,6 +224,87 @@ async function resolveWaveNumber(projectDir) {
   }
 }
 
+/**
+ * The only environment variables forwarded to the `git` children below.
+ * Everything else — `GIT_DIR`/`GIT_WORK_TREE`/`GIT_COMMON_DIR` above all — is
+ * dropped, so an ambient redirect cannot make these probes measure a FOREIGN
+ * repository while `cwd` points at this one (`GIT_DIR` outranks `cwd`; that is
+ * exactly the 2026-08-19 redirect incident class).
+ *
+ * Same 6-entry allowlist as `scripts/lib/git-config-drift.mjs:170` and
+ * `check-banner-parity.mjs:63`, COPIED rather than imported on purpose: this is
+ * a live hook, and importing a scripts/lib module for six strings would add an
+ * edge to the hook import graph (`hooks/_lib/hook-import-set.json`) for no
+ * behavioural gain — the constant is cheaper to copy than a shared module is to
+ * maintain (BV-001, the same call git-config-drift.mjs documents).
+ */
+const GIT_ENV_ALLOWLIST = Object.freeze(['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'TZ']);
+
+/** @returns {Record<string,string>} the allowlisted subset of `process.env`. */
+function filteredGitEnv() {
+  /** @type {Record<string,string>} */
+  const out = {};
+  for (const key of GIT_ENV_ALLOWLIST) {
+    const value = process.env[key];
+    if (typeof value === 'string') out[key] = value;
+  }
+  return out;
+}
+
+/** Shared spawn options for the best-effort git probes below (#980). */
+const GIT_OPTS = (projectDir) => ({
+  cwd: projectDir,
+  encoding: 'utf8',
+  timeout: 1_500,
+  stdio: ['ignore', 'pipe', 'ignore'],
+  env: filteredGitEnv(),
+});
+
+/**
+ * `git rev-parse HEAD` in `projectDir`, best-effort (#980).
+ * Returns null on ANY failure — not a git repo, detached/empty HEAD, timeout,
+ * git absent. A null is persisted as null so a STALE sha from the previous wave
+ * can never be mistaken for this wave's start point.
+ *
+ * @param {string} projectDir
+ * @returns {string|null}
+ */
+function readHeadSha(projectDir) {
+  try {
+    const out = execFileSync('git', ['rev-parse', 'HEAD'], GIT_OPTS(projectDir)).trim();
+    return /^[0-9a-f]{40}$/i.test(out) ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Count the files this wave touched: the DEDUPED union of the working tree's
+ * diff against `sha` and the untracked (non-ignored) files (#980).
+ *
+ * Working-tree-vs-sha rather than `sha..HEAD` on purpose: the coordinator
+ * commits at session close, not per wave, so a commit-only diff reads 0 for
+ * every wave of a normal session.
+ *
+ * @param {string} projectDir
+ * @param {unknown} sha  Persisted `wave_start_sha` (may be null/absent).
+ * @returns {number|null} null when unmeasurable — caller OMITS the key.
+ */
+function countFilesChangedSince(projectDir, sha) {
+  if (typeof sha !== 'string' || !/^[0-9a-f]{40}$/i.test(sha)) return null;
+  try {
+    const opts = GIT_OPTS(projectDir);
+    const tracked = execFileSync('git', ['diff', '--name-only', sha], opts);
+    const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard'], opts);
+    const paths = new Set(
+      `${tracked}\n${untracked}`.split('\n').map((l) => l.trim()).filter((l) => l.length > 0),
+    );
+    return paths.size;
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -248,7 +345,7 @@ async function main() {
     ...(waveSignal !== null ? { wave_signal: waveSignal } : {}),
   };
 
-  const sessionFile = path.join(SO_PROJECT_DIR, '.orchestrator', 'current-session.json');
+  const sessionFile = path.join(getProjectDir(), '.orchestrator', 'current-session.json');
 
   const lastBatchResult = await atomicMutateJson(sessionFile, {}, (current) => ({
     ...current,
@@ -277,7 +374,7 @@ async function main() {
     const sessionId = await resolveSessionIdForHeartbeat(input, sessionFile);
     if (typeof sessionId === 'string' && sessionId.length > 0) {
       const { updateHeartbeat } = await import('../scripts/lib/session-lock.mjs');
-      updateHeartbeat({ repoRoot: SO_PROJECT_DIR, sessionId });
+      updateHeartbeat({ repoRoot: getProjectDir(), sessionId });
     }
   } catch { /* best effort — hook must remain non-blocking */ }
 
@@ -357,16 +454,19 @@ async function main() {
     // when an N+1 transition already closed wave N, SessionEnd sees
     // last_wave_completed === last_wave and stays silent.
     try {
-      const wave = await resolveWaveNumber(SO_PROJECT_DIR);
+      const wave = await resolveWaveNumber(getProjectDir());
       if (wave > 0) {
         // Read last_wave from the just-written session file (after the
         // last_batch RMW above, so we observe the latest persisted value).
         let lastWave = 0;
         let lastWaveCompleted = 0;
+        let waveStartSha = null;
         try {
           const raw = await readFile(sessionFile, 'utf8');
           const parsed = JSON.parse(raw);
           if (typeof parsed.last_wave === 'number') lastWave = parsed.last_wave;
+          // #980 — the sha persisted when THIS `last_wave` was opened.
+          if (typeof parsed.wave_start_sha === 'string') waveStartSha = parsed.wave_start_sha;
           // #1193 review F2 — read in the SAME read as `last_wave`: a `/clear`
           // mid-wave already emitted `completed(lastWave)` via SessionEnd, and
           // `on-session-start.mjs` preserves that marker across the restart, so
@@ -383,8 +483,17 @@ async function main() {
           // prior wave is already closed too, and a non-integer marker counts
           // as absent rather than as "different".
           if (lastWave > lastWaveCompleted) {
+            // #980 — measure the closing wave's diff size BEFORE the new wave's
+            // start sha is persisted below. Unmeasurable → both keys omitted.
+            const filesChanged = countFilesChangedSince(getProjectDir(), waveStartSha);
             await emitEvent('orchestrator.wave.completed', {
               wave_number: lastWave,
+              ...(filesChanged !== null
+                ? {
+                  files_changed: filesChanged,
+                  files_changed_source: 'worktree-vs-wave-start-sha',
+                }
+                : {}),
               ...(batchId !== null ? { batch_id: batchId } : {}),
               ...(batchSize !== null ? { batch_size: batchSize } : {}),
             });
@@ -408,8 +517,13 @@ async function main() {
           // that session's own SessionStart takes over the file. Revisit if the
           // ledger shows repeated started{N} for one wave in a shared checkout.
           if (await ownsSessionFile(input, sessionFile)) {
+            // #980 — the OPEN half: stamp the sha this new wave starts from.
+            // Written as null (not omitted) when git is unreadable, so the
+            // PREVIOUS wave's sha can never linger and inflate the next count.
+            const startSha = readHeadSha(getProjectDir());
             const markResult = await atomicMutateJson(sessionFile, {}, (current) => ({
               ...current,
+              wave_start_sha: startSha,
               last_wave: maxWave(current?.last_wave, wave),
               ...(Math.max(lastWave, lastWaveCompleted) > 0
                 ? {

package/hooks/post-tool-failure-corrective-context.mjs

@@ -30,7 +30,7 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
 if (!shouldRunHook('post-tool-failure-corrective-context')) process.exit(0);
 
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { atomicMutateJson } from './_lib/atomic-json.mjs';
 
 // ---------------------------------------------------------------------------
@@ -179,7 +179,7 @@ async function main() {
     exit_code: exitCode,
   };
 
-  const sessionFile = path.join(SO_PROJECT_DIR, '.orchestrator', 'current-session.json');
+  const sessionFile = path.join(getProjectDir(), '.orchestrator', 'current-session.json');
 
   const result = await atomicMutateJson(sessionFile, {}, (current) => {
     const existing = Array.isArray(current.corrective_context)

package/hooks/post-tooluse-frontend-slop.mjs

@@ -29,7 +29,7 @@ if (!shouldRunHook('frontend-slop-hook')) process.exit(0);
 
 import path from 'node:path';
 
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { detectFiles, SCANNABLE_EXTS } from '../scripts/lib/frontend-detect/detect.mjs';
 import { loadFrontendSlopHookConfig } from '../scripts/lib/config/frontend-slop-hook.mjs';
@@ -98,7 +98,7 @@ function resolveSessionId(input) {
  */
 function toRelPath(filePath) {
   try {
-    const rel = path.relative(SO_PROJECT_DIR, filePath);
+    const rel = path.relative(getProjectDir(), filePath);
     if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) return rel;
   } catch { /* fall through */ }
   return path.basename(filePath);
@@ -147,7 +147,7 @@ async function main() {
   if (!SCANNABLE_EXTS.has(ext)) return;
 
   // Session Config gate — OPT-IN (default off).
-  const config = await loadFrontendSlopHookConfig({ repoRoot: SO_PROJECT_DIR });
+  const config = await loadFrontendSlopHookConfig({ repoRoot: getProjectDir() });
   if (config.enabled !== true) return;
 
   // Run the deterministic detector (fail-soft: unreadable files → []).

package/hooks/pre-bash-destructive-guard.mjs

@@ -95,6 +95,8 @@ let blocker = null;
 let readConfigFile;
 let loadEffectivePolicy;
 let isSessionConfigHeading;
+let preprocessBlockLinesNoDash;
+let findUnterminatedComment;
 let emitEvent;
 
 /**
@@ -164,6 +166,7 @@ async function bootstrap() {
       config: { specifier: lib('config.mjs') },
       blockedCommandsPolicy: { specifier: lib('blocked-commands-policy.mjs') },
       sectionExtractor: { specifier: lib('config', 'section-extractor.mjs') },
+      blockPreprocess: { specifier: lib('config', 'block-preprocess.mjs') },
       events: { specifier: lib('events.mjs') },
       blocker: {
         specifier: lib('command-blocker.mjs'),
@@ -192,6 +195,7 @@ async function bootstrap() {
   ({ readConfigFile } = modules.config);
   ({ loadEffectivePolicy } = modules.blockedCommandsPolicy);
   ({ isSessionConfigHeading } = modules.sectionExtractor);
+  ({ findUnterminatedComment, preprocessBlockLinesNoDash } = modules.blockPreprocess);
   ({ emitEvent } = modules.events);
   blocker = modules.blocker;
   degradedLabels = degraded;
@@ -760,19 +764,41 @@ async function main() {
     const mdContent = await readConfigFile(projectDir);
     // Look for "allow-destructive-ops: true" in the Session Config block.
     // Simple line-based scan: find lines under ## Session Config, stop at next ##.
-    const lines = mdContent.split(/\r?\n/);
-    let inConfig = false;
-    for (const line of lines) {
-      // SSOT predicate (#968) — never re-derive this comparison. A local copy
-      // that drifts LOOSER than the extractor silently disagrees with the
-      // runtime about where the config block starts.
-      if (isSessionConfigHeading(line)) { inConfig = true; continue; }
-      if (inConfig && /^## /.test(line)) break;
-      if (inConfig) {
-        const m = line.match(/^\s*(?:-\s+\*\*)?allow-destructive-ops(?::\*\*)?\s*:\s*(\S+)/);
-        if (m && m[1].toLowerCase() === 'true') {
-          process.stderr.write('ℹ destructive-guard bypassed\n');
-          return emitAllow();
+    // W4/F1b — HTML-comment stripping is MANDATORY here (same class as #1162a).
+    // With a raw `split(/\r?\n/)` a COMMENTED-OUT
+    // `<!--\nallow-destructive-ops: true\n-->` under `## Session Config` DISABLED
+    // the whole 14-rule guard for the session: commenting a key out is the most
+    // ordinary way to turn it off and must never turn it ON. `NoDash` (not the
+    // full `preprocessBlockLines`) on purpose — bold-subkey normalisation is not
+    // wanted; the regex below already tolerates `- **key:**` and stays as-is.
+    //
+    // UNTERMINATED `<!--` — the fail-closed direction INVERTS for a bypass scan.
+    // `stripHtmlCommentBlocks` returns the lines UNFILTERED when a comment is
+    // never closed (right for a block PARSER, nothing may silently vanish), which
+    // here would hand the commented-out bypass line back and re-arm the guard's
+    // own off switch. For this scan "I cannot tell where the comments end" must
+    // mean NOT ARMED: the bypass is opt-in, so refusing to grant it is the safe
+    // reading of an ambiguous document. Said out loud on stderr, because a
+    // silently-ignored bypass would look identical to a typo the operator meant.
+    if (findUnterminatedComment(mdContent.split(/\r?\n/)) !== null) {
+      process.stderr.write(
+        'ℹ destructive-guard: unterminated <!-- in CLAUDE.md — bypass ignored\n'
+      );
+    } else {
+      const lines = preprocessBlockLinesNoDash(mdContent);
+      let inConfig = false;
+      for (const line of lines) {
+        // SSOT predicate (#968) — never re-derive this comparison. A local copy
+        // that drifts LOOSER than the extractor silently disagrees with the
+        // runtime about where the config block starts.
+        if (isSessionConfigHeading(line)) { inConfig = true; continue; }
+        if (inConfig && /^## /.test(line)) break;
+        if (inConfig) {
+          const m = line.match(/^\s*(?:-\s+\*\*)?allow-destructive-ops(?::\*\*)?\s*:\s*(\S+)/);
+          if (m && m[1].toLowerCase() === 'true') {
+            process.stderr.write('ℹ destructive-guard bypassed\n');
+            return emitAllow();
+          }
         }
       }
     }

package/hooks/skill-invocation-telemetry.mjs

@@ -33,7 +33,7 @@ import { spawn } from 'node:child_process';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { appendSkillInvocation } from '../scripts/lib/skill-invocations-schema.mjs';
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { shouldDailyFlush } from '../scripts/lib/telemetry/sync.mjs';
 import { resolveConsent, readTelemetryState } from '../scripts/lib/telemetry/consent.mjs';
 import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
@@ -42,9 +42,21 @@ import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
 // Constants
 // ---------------------------------------------------------------------------
 
-const METRICS_DIR = path.join(SO_PROJECT_DIR, '.orchestrator', 'metrics');
+/**
+ * Metrics directory / ledger path. FUNCTIONS, not module-level consts:
+ * `getProjectDir()` walks the filesystem on first call, and this hook must not
+ * pay that at import time (#1153 P5).
+ *
+ * @returns {string}
+ */
+function metricsDirPath() {
+  return path.join(getProjectDir(), '.orchestrator', 'metrics');
+}
 
-const JSONL_PATH = path.join(METRICS_DIR, 'skill-invocations.jsonl');
+/** @returns {string} */
+function jsonlPath() {
+  return path.join(metricsDirPath(), 'skill-invocations.jsonl');
+}
 
 /** Absolute path to the telemetry CLI (carries the hidden `_flush` subcommand). */
 const TELEMETRY_CLI_PATH = path.resolve(
@@ -123,7 +135,7 @@ export function maybeSpawnDailyFlush({
   now = Date.now(),
   statePath,
   queuePath,
-  metricsDir = METRICS_DIR,
+  metricsDir = metricsDirPath(),
 } = {}) {
   try {
     // 1. Cheapest gate: env kill-switches, no file I/O.
@@ -187,7 +199,7 @@ async function main() {
     schema_version: 1,
   };
 
-  await appendSkillInvocation(JSONL_PATH, record);
+  await appendSkillInvocation(jsonlPath(), record);
 
   // Daily-fallback telemetry flush — non-blocking, best-effort, never throws.
   maybeSpawnDailyFlush();

package/hooks/subagent-telemetry.mjs

@@ -84,14 +84,23 @@ if (!shouldRunHook('subagent-telemetry')) process.exit(0);
 import fs from 'node:fs';
 import path from 'node:path';
 import { appendSubagent } from '../scripts/lib/subagents-schema.mjs';
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-const JSONL_PATH = path.join(SO_PROJECT_DIR, '.orchestrator', 'metrics', 'subagents.jsonl');
+/**
+ * Absolute path to the subagent ledger. A FUNCTION, not a module-level const:
+ * `getProjectDir()` walks the filesystem on first call, and this hook must not
+ * pay that at import time (#1153 P5).
+ *
+ * @returns {string}
+ */
+function jsonlPath() {
+  return path.join(getProjectDir(), '.orchestrator', 'metrics', 'subagents.jsonl');
+}
 
 /**
  * Defense-in-depth byte ceiling for transcript reads (#624). The transcript path
@@ -669,7 +678,7 @@ async function main() {
     // duration measurement and the explicit orphan discriminator below.
     // 'unknown' is the agent-id fallback for a payload with no usable id —
     // joining on it would collide across unrelated agents, so never scan for it.
-    const startedAtMs = agentId === 'unknown' ? null : findStartTimestampMs(JSONL_PATH, agentId);
+    const startedAtMs = agentId === 'unknown' ? null : findStartTimestampMs(jsonlPath(), agentId);
 
     // duration_ms (#917): prefer the harness value, else join backwards to this
     // agent's own start record, else null. Never 0 — see resolveDurationMs().
@@ -717,7 +726,7 @@ async function main() {
     record['gen_ai.system'] = 'anthropic';
   }
 
-  await appendSubagent(JSONL_PATH, record);
+  await appendSubagent(jsonlPath(), record);
 }
 
 // Exit 0 always — informational hook must never block Claude.

package/monitors/monitors.json

@@ -2,13 +2,13 @@
   {
     "name": "ecosystem-health",
     "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/lib/ecosystem-health.mjs --watch",
-    "description": "Ecosystem repo health watcher (CI status, branch drift, stale baselines across vault-registered projects). Emits one NDJSON line per detected state change.",
-    "when": "on-skill-invoke:ecosystem-health"
+    "description": "Ecosystem repo health watcher (CI status, branch drift, stale baselines across vault-registered projects). Emits one NDJSON line per detected state change. Hung on session-start because the previous trigger (on-skill-invoke:ecosystem-health) was self-referential: it could only start when the ecosystem-health skill ran, and that skill has 0 recorded invocations fleet-wide, so the watcher never started once.",
+    "when": "on-skill-invoke:session-start"
   },
   {
     "name": "convergence-monitor",
     "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/lib/convergence-monitor.mjs --tail",
-    "description": "Wave convergence telemetry monitor — tails .orchestrator/metrics/events.jsonl + sessions.jsonl, surfaces convergence signals (shrinking diff, pass-rate plateau, velocity).",
+    "description": "Wave convergence telemetry monitor — tails .orchestrator/metrics/events.jsonl (that file only; it never opens sessions.jsonl) and surfaces convergence signals (shrinking diff, pass-rate plateau, velocity).",
     "when": "on-skill-invoke:wave-executor"
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "3.24.0",
+  "version": "4.0.1",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -23,6 +23,7 @@
   },
   "files": [
     ".mcp.json",
+    "AGENTS.md",
     "CHANGELOG.md",
     "pi/",
     "skills/",
@@ -37,11 +38,15 @@
     "assets/",
     ".claude-plugin/",
     ".codex-plugin/",
+    ".cursor-plugin/",
+    ".agents/",
     ".cursor/",
+    ".orchestrator/policy/",
     "docs/*.md",
     "docs/telemetry/telemetry-claims.md",
     "NOTICE",
     "SECURITY.md",
+    "!skills/vault-sync/package-lock.json",
     "!scripts/tests/**",
     "!skills/vault-sync/tests/**",
     "!**/node_modules/**",
@@ -66,9 +71,12 @@
     "ajv": "^8.17.1",
     "js-yaml": "^4.3.1",
     "mdast-util-to-string": "^4.0.0",
+    "picomatch": "^4.0.4",
     "remark": "^15.0.0",
     "remark-parse": "^11.0.0",
     "unified": "^11.0.0",
+    "yaml": "^2.9.0",
+    "zod": "^3.25.76",
     "zx": "^8.1.0"
   },
   "devDependencies": {

package/pi/prompts/session.md

@@ -1,6 +1,6 @@
 ---
-description: Start a development session (housekeeping, feature, deep)
-argument-hint: "[housekeeping|feature|deep]"
+description: Start a development session (housekeeping, feature, deep; ultradeep = deep + profile)
+argument-hint: "[housekeeping|feature|deep|ultradeep]"
 ---
 
 # /session

package/scripts/backfill-abandoned-sessions.mjs

@@ -43,7 +43,7 @@ import { fileURLToPath } from 'node:url';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
 import { emitEvent } from './lib/events.mjs';
-import { SO_PROJECT_DIR } from './lib/platform.mjs';
+import { getProjectDir } from './lib/platform.mjs';
 
 const LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
 const SESSION_STARTED = 'orchestrator.session.started';
@@ -382,13 +382,59 @@ export async function backfillOnSessionStart({ repoRoot, limit = SESSION_START_L
     if (typeof repoRoot !== 'string' || repoRoot.length === 0) return null;
     // newestFirst is mandatory here — see runMigration's param docs for the
     // measured failure (budget burned on ancient already-recorded candidates).
-    return await runMigration({ repoRoot, apply: true, limit, newestFirst: true });
+    const summary = await runMigration({ repoRoot, apply: true, limit, newestFirst: true });
+    // The telemetry flush rides the SAME start-time trigger, for the same reason
+    // the backfill does — see flushTelemetryOnSessionStart.
+    await flushTelemetryOnSessionStart(repoRoot);
+    return summary;
   } catch {
     // Swallowed by contract — see the docblock. The hook is informational-only.
     return null;
   }
 }
 
+/** POST budget for the start-time telemetry drain (ms). Deliberately tighter than
+ *  the close-time budget: a session START must not wait on the network. Expiry is
+ *  LOSSLESS — flush() routes a timed-out batch into the offline queue. */
+const STARTUP_FLUSH_TIMEOUT_MS = 1500;
+
+/**
+ * SECOND FLUSH TRIGGER (GitLab #1234) — drain the PREVIOUS session's telemetry
+ * queue at the NEXT session's start.
+ *
+ * THE BUG THIS FIXES: the mechanical flush (#1138) lives only in
+ * `hooks/on-session-end.mjs`, which fires on a REGULAR close. Measured 2026-09-06
+ * over 90 fleet days, the real close rate is 21,3 % (429 clean closes / 2.016
+ * distinct `session.started` ids) — so roughly four sessions in five never reach
+ * the only code path that sends. This is the exact argument
+ * `backfillOnSessionStart` already makes for the ledger, applied to the ping:
+ * SessionStart is the trigger that survives whatever killed the last session.
+ *
+ * Three properties make this safe to run on the hot start path:
+ *  - LAZY IMPORT. `sync.mjs` is pulled in at CALL time, not module load. Loading
+ *    it statically would put the whole telemetry subtree onto the SessionStart
+ *    hook's import graph — the graph `tests/hooks/on-stop.test.mjs` guards for
+ *    bare specifiers, and the cost would be paid on every start whether or not
+ *    telemetry is even consented to.
+ *  - GATED, ALWAYS. `flush()` opens with `resolveConsent()`; with no consent it
+ *    returns before any network, queue write, or anon-ID mint.
+ *  - NEVER THROWS, NEVER BLOCKS A START. Every failure is swallowed, and the POST
+ *    is bounded at STARTUP_FLUSH_TIMEOUT_MS; a timeout queues the batch rather
+ *    than losing it.
+ *
+ * @param {string} repoRoot
+ * @returns {Promise<void>}
+ */
+async function flushTelemetryOnSessionStart(repoRoot) {
+  try {
+    const { flush } = await import('./lib/telemetry/sync.mjs');
+    await flush({
+      metricsDir: path.join(repoRoot, '.orchestrator', 'metrics'),
+      timeoutMs: STARTUP_FLUSH_TIMEOUT_MS,
+    });
+  } catch { /* fire-and-forget by contract */ }
+}
+
 function renderHuman(summary) {
   const lines = [];
   lines.push(`Backfill abandoned sessions — ${summary.mode}`);
@@ -441,7 +487,7 @@ async function main() {
         '  --dry-run             preview only (DEFAULT — nothing is written)\n' +
         '  --apply               synthesize + append abandoned-session stubs\n' +
         '  --json                emit the summary as JSON to stdout\n' +
-        '  --repo-root           override the project root (default: resolved SO_PROJECT_DIR)\n' +
+        '  --repo-root           override the project root (default: resolved project dir)\n' +
         '  --assume-dead-before  ISO-8601 cutoff; a candidate whose last known event\n' +
         '                        predates it bypasses a live foreign session.lock\n' +
         'Exit codes: 0 ok, 1 arg error, 2 system error\n'
@@ -451,7 +497,7 @@ async function main() {
 
   // --apply is an explicit opt-in; absent it (or with --dry-run) we never write.
   const apply = values.apply === true && values['dry-run'] !== true;
-  const repoRoot = values['repo-root'] || SO_PROJECT_DIR;
+  const repoRoot = values['repo-root'] || getProjectDir();
 
   let assumeDeadBeforeMs = null;
   if (typeof values['assume-dead-before'] === 'string' && values['assume-dead-before'].length > 0) {

package/scripts/backfill-learnings-from-vault.mjs

@@ -71,7 +71,7 @@ import { parseSessionConfig } from './lib/config.mjs';
 import { subjectToSlug, parseFrontmatter } from './lib/vault-mirror/utils.mjs';
 import { kebab } from './lib/learnings/kebab.mjs';
 import { validateLearning } from './lib/learnings/schema.mjs';
-import { appendLearning } from './lib/learnings/io.mjs';
+import { appendLearning, isBackupOf } from './lib/learnings/io.mjs';
 
 const DEFAULT_RULES_DIR = '.claude/rules';
 const DEFAULT_STORE = '.orchestrator/metrics/learnings.jsonl';
@@ -620,7 +620,13 @@ function idsInStore(filePath) {
   return ids;
 }
 
-/** List `<store>.bak-*` siblings (a verbatim original beats any reconstruction). */
+/**
+ * List `<store>.bak[-.]*` siblings (a verbatim original beats any
+ * reconstruction). Both delimiter forms count — the legacy dot form
+ * (`learnings.jsonl.bak.evolve-<ts>`) is still on disk in consumer repos and
+ * was silently skipped here, i.e. a backup that exists and is not found in the
+ * one case it is for (#1173).
+ */
 function backupPaths(storePath) {
   const dir = dirname(storePath);
   const base = basename(storePath);
@@ -633,7 +639,7 @@ function backupPaths(storePath) {
     return [];
   }
   return names
-    .filter((n) => n.startsWith(`${base}.bak-`))
+    .filter((n) => isBackupOf(base, n))
     .sort()
     .map((n) => join(dir, n));
 }