session-orchestrator 5.4.0 → 5.5.0

package/scripts/backfill-abandoned-sessions.mjs

@@ -43,6 +43,7 @@ import { parseArgs } from 'node:util';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
 import { SCAN_CHUNK_BYTES, emitEvent, listEventSourcesNewestFirst } from './lib/events.mjs';
+import { ARCHIVE_DIR_NAME, ROTATION_EVENT } from './lib/events-schema.mjs';
 import { getProjectDir } from './lib/platform.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import { isLockLive, readLock } from './lib/session-lock.mjs';
@@ -52,6 +53,15 @@ const LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
 const SESSION_STARTED = 'orchestrator.session.started';
 const SESSION_ENDED = 'orchestrator.session.ended';
 
+/**
+ * Events-ledger window for the #1401 census (`scripts/lib/events-retention-banner.mjs`):
+ * `null` — {@link planSessions} takes every `session.started` ever written as a
+ * candidate, so no day count bounds it (`DEFAULT_TTL_HOURS` is a minimum AGE,
+ * not a window). A pruned history yields fewer candidates; the run summary says
+ * so as `history_gaps` (#1498).
+ */
+export const REQUIRED_EVENTS_WINDOW_DAYS = null;
+
 /**
  * Default cap on how many candidates may reach the (expensive) shared core in a
  * single run. Only the SessionStart path passes a limit; the CLI stays uncapped.
@@ -59,6 +69,25 @@ const SESSION_ENDED = 'orchestrator.session.ended';
  */
 export const SESSION_START_LIMIT = 25;
 
+/**
+ * Total wall-clock budget, per SessionStart run, for scanning the ROTATED
+ * ledger on behalf of candidates whose events left the active file (#1498).
+ * ONE deadline shared by every candidate; a candidate it leaves unread is
+ * `skipped-history-unread` and retried by the next start — recorded ones drop
+ * out through the sessions.jsonl pre-filter, so the backlog drains.
+ *
+ * Named ceiling (BV-004): at ≈0.55-0.8 ms per MB per candidate (measured
+ * 2026-10-02, see `gatherSessionEvents` in `session-close-backfill.mjs`) a full
+ * default ledger (6 × 10 MB) fits ~10-15 scans per start. Measured the same
+ * day over 58 MB with 25 archived candidates (dry run, load ~5): unbudgeted
+ * 1.41 s; budget 0 — planning and active-file reads only — 0.55 s; budget 500
+ * 0.83-0.84 s, 10 candidates answered and 15 deferred. A single scan longer
+ * than the budget — a ledger past ~600 MB — never completes here; the CLI path
+ * is unbudgeted and still records it. Revisit if `skipped-history-unread`
+ * appears on more than a few consecutive starts of one repo.
+ */
+export const SESSION_START_ARCHIVE_SCAN_BUDGET_MS = 500;
+
 /**
  * Read a JSONL file into parsed objects; MISSING (ENOENT) → `[]` silently,
  * UNREADABLE (EACCES/EISDIR/…) → `[]` with a stderr WARN (#1188); malformed
@@ -126,6 +155,23 @@ function readJsonl(filePath) {
  * @returns {Array<{ sessionId: string, semanticSessionId: string|null }>}
  */
 export function planSessions({ repoRoot }) {
+  return planWithGaps({ repoRoot }).plan;
+}
+
+/**
+ * {@link planSessions} plus the count of rotation tombstones whose archive is
+ * not one of the sources read (#1498). Pruned history used to shrink the plan
+ * silently; non-zero `historyGaps` says the candidate count is a floor.
+ *
+ * The check is `readEventsWithRotations` rule 1 (`scripts/lib/events.mjs`):
+ * resolved by BASENAME against this ledger's own `_archive/` (#1411), and a
+ * file that exists but is not a source (renamed out of `ARCHIVE_NAME_RE`)
+ * counts as a gap too — existence is not reading (#1423).
+ *
+ * @param {{ repoRoot: string }} args
+ * @returns {{ plan: Array<{ sessionId: string, semanticSessionId: string|null }>, historyGaps: number }}
+ */
+function planWithGaps({ repoRoot }) {
   const eventsPath = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
 
   // Two independent UUID -> semantic bridges (#1167). `lock.acquired` is the
@@ -150,9 +196,17 @@ export function planSessions({ repoRoot }) {
   // (`hooks/on-session-start.mjs` → `backfillOnSessionStart`). Reversing the
   // newest-first source list keeps first-seen order chronological, exactly as
   // the single-file read produced it.
-  for (const source of [...listEventSourcesNewestFirst({ filePath: eventsPath })].reverse()) {
+  const sources = listEventSourcesNewestFirst({ filePath: eventsPath });
+  const read = new Set(sources.map((s) => s.path));
+  const archiveDir = path.join(path.dirname(eventsPath), ARCHIVE_DIR_NAME);
+  let historyGaps = 0;
+  for (const source of [...sources].reverse()) {
     forEachJsonlRecord(source.path, (ev) => {
       if (!ev || typeof ev !== 'object') return;
+      if (ev.event === ROTATION_EVENT && typeof ev.archived_as === 'string' && ev.archived_as.length > 0
+        && !read.has(path.join(archiveDir, path.basename(ev.archived_as)))) {
+        historyGaps += 1;
+      }
       if (typeof ev.session_id === 'string' && typeof ev.semantic_session_id === 'string') {
         if (ev.event === LOCK_ACQUIRED) semanticFromLock.set(ev.session_id, ev.semantic_session_id);
         else if (ev.event === SESSION_ENDED) {
@@ -181,7 +235,7 @@ export function planSessions({ repoRoot }) {
       || (semanticSessionId !== null && runningIds.has(semanticSessionId))) continue;
     plan.push({ sessionId, semanticSessionId });
   }
-  return plan;
+  return { plan, historyGaps };
 }
 
 /**
@@ -365,6 +419,10 @@ function cheapRecordId({ sessionId, semanticSessionId }) {
  *   those ancient candidates exhaust the whole budget before the run ever
  *   reaches the genuinely-abandoned recent ones. Measured on a copy of this
  *   repo's live store: first-seen order → backfilled 0, truncated true.
+ * @param {number|null} [args.archiveScanBudgetMs=null]
+ *   #1498 — total budget for rotated-ledger scans across the whole run, turned
+ *   into ONE deadline before the first candidate. Candidates it leaves unread
+ *   count as `skipped.skipped-history-unread`. `null` (CLI default) = unbounded.
  * @returns {Promise<object>} aggregate summary
  */
 export async function runMigration({
@@ -373,13 +431,17 @@ export async function runMigration({
   assumeDeadBeforeMs = null,
   limit = null,
   newestFirst = false,
+  archiveScanBudgetMs = null,
 }) {
-  const planned = planSessions({ repoRoot });
+  const { plan: planned, historyGaps } = planWithGaps({ repoRoot });
   const plan = newestFirst ? [...planned].reverse() : planned;
   const summary = {
     repoRoot,
     mode: apply ? 'apply' : 'dry-run',
     total: plan.length,
+    // #1498: rotated archives the ledger names but no longer holds. Non-zero ⇒
+    // sessions they recorded are not candidates and `total` is a floor.
+    history_gaps: historyGaps,
     backfilled: 0,
     would_backfill: 0,
     dead_by_age: 0,
@@ -397,6 +459,10 @@ export async function runMigration({
   // here so the dry-run total matches what --apply actually writes.
   const projected = new Set();
 
+  const archiveScanDeadlineMs = Number.isFinite(archiveScanBudgetMs)
+    ? Date.now() + archiveScanBudgetMs
+    : null;
+
   for (const item of plan) {
     // -- Cheap pre-filter: already recorded → skip WITHOUT entering the core --
     const known = cheapRecordId(item);
@@ -423,6 +489,7 @@ export async function runMigration({
       dryRun: !apply,
       relaxDeadByAge: true,
       assumeDeadBeforeMs,
+      archiveScanDeadlineMs,
     });
     switch (res.action) {
       case 'backfilled':
@@ -529,16 +596,21 @@ async function emitBackfillCompleted(repoRoot, item, res) {
  * @param {object} args
  * @param {string} args.repoRoot
  * @param {number|null} [args.limit=SESSION_START_LIMIT]
+ * @param {number|null} [args.archiveScanBudgetMs=SESSION_START_ARCHIVE_SCAN_BUDGET_MS]
  * @returns {Promise<object|null>} the summary, or null when disabled/failed
  */
-export async function backfillOnSessionStart({ repoRoot, limit = SESSION_START_LIMIT } = {}) {
+export async function backfillOnSessionStart({
+  repoRoot,
+  limit = SESSION_START_LIMIT,
+  archiveScanBudgetMs = SESSION_START_ARCHIVE_SCAN_BUDGET_MS,
+} = {}) {
   try {
     // Escape hatch for operators who never want ledger writes at session start.
     if (process.env.SO_DISABLE_STARTUP_BACKFILL === '1') return null;
     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).
-    const summary = await runMigration({ repoRoot, apply: true, limit, newestFirst: true });
+    const summary = await runMigration({ repoRoot, apply: true, limit, newestFirst: true, archiveScanBudgetMs });
     // The telemetry flush rides the SAME start-time trigger, for the same reason
     // the backfill does — see flushTelemetryOnSessionStart.
     await flushTelemetryOnSessionStart(repoRoot);
@@ -596,6 +668,9 @@ function renderHuman(summary) {
   lines.push(`Backfill abandoned sessions — ${summary.mode}`);
   lines.push(`  repo:            ${summary.repoRoot}`);
   lines.push(`  sessions seen:   ${summary.total}`);
+  if (summary.history_gaps > 0) {
+    lines.push(`  history gaps:    ${summary.history_gaps} rotated archive(s) no longer readable — sessions seen is a floor`);
+  }
   if (summary.mode === 'apply') {
     lines.push(`  backfilled:      ${summary.backfilled}`);
   } else {

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

@@ -43,8 +43,9 @@
  * a record that never left.
  *
  * Idempotence: dry-run is pure (reads only). `--apply` re-checks store+archive
- * membership per record immediately before appending, so a second `--apply`
- * appends nothing and a later dry-run reports 0 orphans.
+ * membership and appends inside ONE store-lock section (`withLearningsLock`),
+ * so a second `--apply` — sequential or concurrent — appends nothing and a
+ * later dry-run reports 0 orphans.
  *
  * NOTE on discovery: every file here is read through `node:fs`, never grep — a
  * single NUL byte makes a tracked file invisible to grep (silent skip, exit 1,
@@ -70,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, isBackupOf } from './lib/learnings/io.mjs';
+import { appendLearning, isBackupOf, withLearningsLock } from './lib/learnings/io.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_RULES_DIR = '.claude/rules';
@@ -907,28 +908,54 @@ export async function main(argv = [], deps = {}) {
     });
   }
 
-  // ── Apply (append-only, re-checked) ──────────────────────────────────────
+  // ── Apply (append-only, re-checked under the store lock) ─────────────────
   let applied = 0;
   let skippedAlreadyPresent = 0;
   if (apply) {
-    for (const r of records) {
-      if (r.status !== 'orphan' || !r.restorable || !r.record) continue;
-      // Re-check membership at apply time — this is what makes a second
-      // --apply a no-op rather than a duplicate append.
-      if (idsInStore(storeAbs).has(r.learning_id) || idsInStore(archiveAbs).has(r.learning_id)) {
-        skippedAlreadyPresent += 1;
-        r.applied = false;
-        continue;
-      }
-      try {
-        await appendLearning(storeAbs, r.record);
-        applied += 1;
-        r.applied = true;
-      } catch (err) {
-        r.applied = false;
-        r.apply_error = err.message;
-        process.stderr.write(`backfill-learnings-from-vault: append failed for ${r.learning_id}: ${err.message}\n`);
-      }
+    const candidates = records.filter((r) => r.status === 'orphan' && r.restorable && r.record);
+    const failApply = (r, err) => {
+      r.applied = false;
+      r.apply_error = err.message;
+      process.stderr.write(`backfill-learnings-from-vault: append failed for ${r.learning_id}: ${err.message}\n`);
+    };
+    try {
+      // The membership re-check and the append are ONE critical section
+      // (#1487 item 12): checked outside the lock, two concurrent --apply runs
+      // — or one racing a session-end append — both saw "absent" and both
+      // appended. One section for the whole loop, not one per record: a single
+      // acquisition and a single read of store + archive instead of N of each.
+      // Hold time is linear in N small appends — fine for the tens of orphans a
+      // backfill restores; revisit (per-record sections) if a run ever holds
+      // the lock near the 10 s other writers wait. Archive movers (sweep/prune)
+      // also write under this lock, so the archive read is consistent too.
+      // appendLearning() re-enters the held lock (reentrant per async call
+      // chain, io.mjs).
+      await withLearningsLock(storeAbs, async () => {
+        const present = new Set([...idsInStore(storeAbs), ...idsInStore(archiveAbs)]);
+        for (const r of candidates) {
+          // This is what makes a second --apply a no-op rather than a
+          // duplicate append; `present.add` below covers two rules naming one id.
+          if (present.has(r.learning_id)) {
+            skippedAlreadyPresent += 1;
+            r.applied = false;
+            continue;
+          }
+          try {
+            await appendLearning(storeAbs, r.record);
+            applied += 1;
+            r.applied = true;
+            present.add(r.learning_id);
+          } catch (err) {
+            failApply(r, err);
+          }
+        }
+      });
+    } catch (err) {
+      // Lock not acquired (LearningsLockError), its directory not creatable, or
+      // a store read failed inside the section: no candidate still unhandled
+      // was written. Surface it per record, like any other append failure,
+      // instead of reporting a silent success.
+      for (const r of candidates) if (r.applied === undefined) failApply(r, err);
     }
   }
 

package/scripts/codex-install.mjs

@@ -93,6 +93,9 @@ function runCodex(args) {
   const result = spawnSync('codex', args, {
     encoding: 'utf8',
     timeout: CODEX_COMMAND_TIMEOUT_MS,
+    // 'codex plugin list --available --json' exceeds the 1 MiB default once a
+    // few marketplaces are registered (measured 2026-09-22: 2.19 MB → ENOBUFS).
+    maxBuffer: 64 * 1024 * 1024,
   });
 
   if (result.error) {

package/scripts/cursor-install.mjs

@@ -15,7 +15,17 @@
  *   1 — source rules not found, or TARGET is not an existing directory
  */
 
-import { existsSync, mkdirSync, readdirSync, symlinkSync, statSync, lstatSync, writeFileSync } from 'node:fs';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readlinkSync,
+  symlinkSync,
+  statSync,
+  lstatSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -66,7 +76,9 @@ function _isDir(p) {
 function linkPath(source, dest, label) {
   mkdirSync(path.dirname(dest), { recursive: true });
   if (_isSymlink(dest)) {
-    process.stdout.write(`  SKIP: ${label} (symlink exists)\n`);
+    // existsSync follows the link: false means it points at nothing.
+    const state = existsSync(dest) ? 'symlink exists' : 'dangling symlink — not replacing';
+    process.stdout.write(`  SKIP: ${label} (${state})\n`);
     return 'skip';
   }
   if (existsSync(dest)) {
@@ -119,6 +131,38 @@ if (_isDir(SOURCE_SKILLS_DIR)) {
   }
 }
 
+/**
+ * Remove the links an earlier install left for a wrapper this plugin no longer
+ * ships (#1501 item 6: 05c0264f dropped `commands/navigator.md` and
+ * `skills/navigator`, and every installed project kept a dead link). An entry is
+ * removed only when it is a symlink, dangles, AND resolves inside this plugin's
+ * `.cursor/<kind>/` — so it is provably ours. Regular files and live links are
+ * the project's own; a dangling link into another root is not ours to delete
+ * and gets a WARN — unless this plugin ships that name, where linkPath() has
+ * already reported it as dangling.
+ * @param {'rules'|'commands'|'skills'} kind
+ */
+function pruneDeadLinks(kind) {
+  const sourceDir = path.join(SO_ROOT, '.cursor', kind);
+  const targetDir = path.join(TARGET, '.cursor', kind);
+  if (!_isDir(targetDir)) return;
+  for (const name of readdirSync(targetDir)) {
+    const dest = path.join(targetDir, name);
+    if (!_isSymlink(dest) || existsSync(dest)) continue;
+    const pointsTo = path.resolve(path.dirname(dest), readlinkSync(dest));
+    const rel = path.relative(sourceDir, pointsTo);
+    const ours = rel !== '' && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+    if (ours) {
+      unlinkSync(dest);
+      process.stdout.write(`  PRUNE: ${kind}/${name} (dangling link into ${sourceDir})\n`);
+    } else if (!existsSync(path.join(sourceDir, name))) {
+      process.stdout.write(`  WARN: ${kind}/${name} (dangling link outside this plugin, left alone: ${pointsTo})\n`);
+    }
+  }
+}
+
+for (const kind of ['rules', 'commands', 'skills']) pruneDeadLinks(kind);
+
 function renderHooksJson(soRoot) {
   const runNode = shQuote(path.join(soRoot, 'hooks', 'run-node.sh'));
   const bridge = shQuote(path.join(soRoot, 'scripts', 'lib', 'cursor-hook-bridge.mjs'));

package/scripts/emit-session.mjs

@@ -480,9 +480,11 @@ async function main() {
   // explicit `total_tokens` means the caller already rolled up, so nothing is
   // merged. No matching records or a failed read OMITS the fields with a WARN —
   // never a fabricated 0; a null total is omitted rather than written — for
-  // `total_cost_usd` that is any session with an unpriced subagent record
-  // (#1475: unknown model, no model, or no tokens), which the persisted
-  // `cost_records_priced < cost_records_total` then explains.
+  // `total_cost_usd` that is any session with an unpriced cost candidate
+  // (unknown model, no model, no tokens, a started agent without a transcript,
+  // or a v1 agent — the complete list is the `session-token-rollup.mjs` module
+  // doc, #1498), which the persisted `cost_records_priced < cost_records_total`
+  // then explains.
   // match_status explains the omission; diagnostic fields stay out of the record.
   if (ownUuid !== null && !hasOwn('total_tokens')) {
     let rollup = null;

package/scripts/export-hw-learnings.mjs

@@ -60,7 +60,7 @@ import {
   CURRENT_ANONYMIZATION_VERSION,
 } from './lib/learnings.mjs';
 import { withLearningsLock } from './lib/learnings/io.mjs';
-import { findProjectRoot, resolveInstructionFile, expandTilde } from './lib/common.mjs';
+import { findProjectRoot, resolveInstructionFile, expandTilde, redactHomeDir } from './lib/common.mjs';
 import { parseSessionConfig } from './lib/config.mjs';
 import { createSecretValueMasker } from './lib/secret-masker.mjs';
 import { stableHostname, readHostAliases } from './lib/host-identity.mjs';
@@ -85,21 +85,28 @@ const DEFAULT_VAULT_SUBPATH = path.join('01-projects', 'session-orchestrator', '
  *   — forwarded to parseSessionConfig (tests pass `{ env: {}, ownerConfig: undefined }`
  *   for hermetic, owner.yaml-free resolution — issue #653 bleed guard).
  * @returns {string|null} the resolved output path, or null when vault-dir is
- *   unconfigured/unresolvable.
+ *   unconfigured/unresolvable or vault-integration is not enabled.
  */
 export function resolveDefaultOutput({ repoRoot, hostPaths } = {}) {
   const root = repoRoot ?? findProjectRoot();
   const instr = resolveInstructionFile(root);
   if (!instr) return null;
 
-  let vaultDir;
+  let vi;
   try {
     const content = readFileSync(instr.path, 'utf8');
     const config = parseSessionConfig(content, hostPaths ? { hostPaths } : undefined);
-    vaultDir = config?.['vault-integration']?.['vault-dir'];
+    vi = config?.['vault-integration'];
   } catch {
     return null;
   }
+  // #1506.4a: this default target IS the vault, so it obeys the off switch the
+  // other vault writers obey (vault-backfill, board-writer, narrative-mirror:
+  // `enabled !== true` → no vault write), already host-lowered by
+  // parseSessionConfig (env SO_VAULT_INTEGRATION > owner.yaml > committed). An
+  // explicit `--output` is the caller's own path and is not gated.
+  if (vi?.enabled !== true) return null;
+  const vaultDir = vi['vault-dir'];
   if (!vaultDir || typeof vaultDir !== 'string' || vaultDir.trim() === '') return null;
 
   // Expand a `~`-prefixed vault-dir (e.g. the committed Session Config default
@@ -604,7 +611,8 @@ function parseArgs(argv) {
     if (!resolved) {
       process.stderr.write(
         'export-hw-learnings: could not resolve vault-integration.vault-dir for the default ' +
-        '--output path (no CLAUDE.md/AGENTS.md found, or vault-dir is unset). ' +
+        '--output path (no CLAUDE.md/AGENTS.md found, vault-integration.enabled is not true, ' +
+        'or vault-dir is unset). ' +
         'Pass --output <path> explicitly.\n'
       );
       process.exit(1);
@@ -661,7 +669,9 @@ async function promoteHwLearningsUnlocked(opts) {
 
   const flags = [];
   if (malformed.length > 0) {
-    flags.push(`${malformed.length} malformed line(s) in learnings.jsonl were skipped`);
+    // Not promoted, and kept verbatim by the rewrite below (rewriteLearnings
+    // re-reads them under the lock — #1489); a WARN, not a loss.
+    flags.push(`${malformed.length} malformed line(s) in learnings.jsonl were not read (kept verbatim)`);
   }
 
   if (hwPrivate.length === 0) {
@@ -763,7 +773,8 @@ if (isMain) {
   };
 
   run().catch((err) => {
-    process.stderr.write(`export failed: ${err.message}\n`);
+    // The message can carry absolute store/output paths — never print the home dir.
+    process.stderr.write(`export failed: ${redactHomeDir(String(err?.message ?? err))}\n`);
     process.exit(1);
   });
 }

package/scripts/fleet-checkin.mjs

@@ -16,7 +16,15 @@
  * payload `{ session, repo, modus, kandidaten, navigator_state }` — no paths, no
  * quota, no `auftrag_ref`.
  *
- * stdout: one JSON line `{ ok, path, navigator_state, event }`.
+ * stdout: one JSON line
+ * `{ ok, path, navigator_state, navigator_adresse, fallback_due_at, event }`.
+ * `navigator_adresse` is the active lease's `adresse` exactly as
+ * `readNavigatorLease()` validated it (a ListAgents peer name), else `null` — no
+ * active lease, no address in it, or one the validator refused. It is the only
+ * value the caller may address a hint to; an unvalidated string never reaches it.
+ * `fallback_due_at` is `fallbackDueAt(zeit, navigator_state)`: when the
+ * Standard-Auflagen apply if no `auflagen/` file has appeared by then. It is
+ * stdout only — the check-in FILE schema, which the navigator reads, is unchanged.
  *
  * Exit codes:
  *   0 — check-in written (an event failure only WARNs; `event: false` on stdout)
@@ -31,6 +39,7 @@ import path from 'node:path';
 import { emitEvent } from './lib/events.mjs';
 import {
   checkinPath,
+  fallbackDueAt,
   navigatorDir,
   readNavigatorLease,
   utcSecondsTimestamp,
@@ -106,7 +115,12 @@ async function main() {
     return 1;
   }
 
-  const { state: navigatorState } = await readNavigatorLease();
+  const navigator = await readNavigatorLease();
+  const navigatorState = navigator.state;
+  // readNavigatorLease() returns a lease only when it passed validation, its
+  // `adresse` included (an invalid one makes the whole lease `unreadable`).
+  const navigatorAdresse =
+    navigator.state === 'active' && typeof navigator.lease.adresse === 'string' ? navigator.lease.adresse : null;
 
   let event = true;
   try {
@@ -132,7 +146,16 @@ async function main() {
   // Report the path with `~` for the home prefix: stdout lands in transcripts.
   const home = os.homedir();
   const shownPath = target.startsWith(`${home}${path.sep}`) ? `~${target.slice(home.length)}` : target;
-  process.stdout.write(JSON.stringify({ ok: true, path: shownPath, navigator_state: navigatorState, event }) + '\n');
+  process.stdout.write(
+    JSON.stringify({
+      ok: true,
+      path: shownPath,
+      navigator_state: navigatorState,
+      navigator_adresse: navigatorAdresse,
+      fallback_due_at: fallbackDueAt(record.zeit, navigatorState),
+      event,
+    }) + '\n',
+  );
   return 0;
 }
 

package/scripts/lib/autopilot/loop.mjs

@@ -38,6 +38,7 @@ function clampNumber(value, { min, max, fallback }) {
  * @property {string|null} kill_switch @property {string|null} kill_switch_detail @property {string[]} sessions
  * @property {string|null} host_class @property {string|null} resource_verdict_at_start
  * @property {boolean} fallback_to_manual @property {boolean} dry_run @property {number} total_tokens_used
+ * @property {number} tokens_unknown_sessions — #1487 Pkt 4: iterations whose own record carried no token figure; > 0 makes total_tokens_used a lower bound
  * @property {string|null} worktree_path @property {string|null} parent_run_id @property {number} stall_recovery_count
  * @property {number|null} blocked_by_issue — Phase D (#341): issue number this loop was waiting on (OPEN-4 commit-deps); null when not blocked
  * @property {boolean} aborted_by_cohort — Phase D (#341): set by cohort-abort policy (OPEN-5); mutated by W3 P5 orchestration-glue, not by runLoop itself
@@ -138,7 +139,12 @@ export async function runLoop(opts = {}) {
     // totals as `usage`; the accumulator sums them into `total_tokens_used`.
     // Zero or multiple matches throw → FAILED_WAVE, never foreign token usage.
     // CEILING: an own record without token totals adds 0 — the budget
-    // undercounts, it never over-fires.
+    // undercounts, it never over-fires. Such sessions are counted in
+    // `tokens_unknown_sessions` (#1487 Pkt 4), and the switch still fires on the
+    // known lower bound: every fire stays correct, none is lost. Failing closed on
+    // an unknown session instead would stop an armed run on every
+    // coordinator-direct session (no subagents → no rollup totals); revisit if
+    // the session record ever carries the coordinator's own usage.
     max_tokens: opts.maxTokens ?? 0,
     iterations_completed: 0,
     kill_switch: null,
@@ -149,6 +155,9 @@ export async function runLoop(opts = {}) {
     fallback_to_manual: false,
     dry_run: dryRun,
     total_tokens_used: 0,
+    // #1487 Pkt 4 — completed iterations whose own record carried no token
+    // figure; non-zero means `total_tokens_used` is a lower bound.
+    tokens_unknown_sessions: 0,
     // ADR-364 additive fields — forward-compat; callers may omit, defaults are null/0.
     worktree_path: opts.worktreePath ?? null,
     parent_run_id: opts.parentRunId ?? null,
@@ -274,15 +283,21 @@ export async function runLoop(opts = {}) {
     }
     state.iterations_completed += 1;
 
-    // Accumulate own-record output tokens (total_tokens fallback); missing totals
-    // add 0. An unassignable child record already threw → FAILED_WAVE above.
-    if (sessionResult && typeof sessionResult.usage === 'object' && sessionResult.usage !== null) {
-      const outTokens = Number(
-        sessionResult.usage.output_tokens ?? sessionResult.usage.total_tokens
-      );
-      if (Number.isFinite(outTokens) && outTokens > 0) {
-        cumulativeTokens += outTokens;
-      }
+    // Accumulate own-record output tokens (total_tokens fallback). An unassignable
+    // child record already threw → FAILED_WAVE above. An own record carrying
+    // neither figure has UNKNOWN usage, not 0 (#1487 Pkt 4): it adds nothing, so
+    // `total_tokens_used` is a lower bound, and it is counted in
+    // `tokens_unknown_sessions` so the record says how much the sum cannot see.
+    const usage = sessionResult?.usage;
+    const rawTokens = usage !== null && typeof usage === 'object'
+      ? (usage.output_tokens ?? usage.total_tokens)
+      : undefined;
+    // `Number(null)` is 0 — a null figure is a missing one, never a measured 0.
+    const outTokens = rawTokens === null || rawTokens === undefined ? NaN : Number(rawTokens);
+    if (Number.isFinite(outTokens) && outTokens >= 0) {
+      cumulativeTokens += outTokens;
+    } else {
+      state.tokens_unknown_sessions += 1;
     }
     state.total_tokens_used = cumulativeTokens;
 

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

@@ -8,7 +8,8 @@
  *      `hooks/on-stop.mjs` refreshes it at every turn-end and
  *      `hooks/post-tool-batch-wave-signal.mjs` at every tool batch.
  *   2. `autopilot.jsonl` mtime — the legacy marker, used only when no lock path
- *      is supplied or the lock is absent/corrupt/timestamp-less.
+ *      is supplied or the lock is absent/corrupt/heartbeat-less (`started_at`
+ *      is never a stand-in — it does not advance during a run).
  *
  * The header of this module used to claim `autopilot.jsonl` carries "one record
  * per session". It does not: `telemetry.mjs` writes ONE record per /autopilot
@@ -74,11 +75,13 @@ function readHeartbeatMs(sessionLockPath) {
     return null;
   }
   if (typeof lock !== 'object' || lock === null) return null;
-  // Same precedence `session-lock.mjs` uses on read: a v1 lock has no
-  // `last_heartbeat`, and its `started_at` is the best available stand-in.
-  const raw = typeof lock.last_heartbeat === 'string' && lock.last_heartbeat.length > 0
-    ? lock.last_heartbeat
-    : lock.started_at;
+  // `last_heartbeat` only — no `started_at` stand-in, matching `isLockLive()`
+  // since the #595 sunset (2026-10-02). `started_at` never advances during a
+  // run, so a lock without a heartbeat would read as a stall once 600 s passed
+  // (or as fresh within 30 s of its genesis) — a measurement the lock never
+  // made. No heartbeat → `null` → the mtime marker, exactly as for a lock
+  // with no timestamp at all.
+  const raw = lock.last_heartbeat;
   if (typeof raw !== 'string' || raw.length === 0) return null;
   const ms = Date.parse(raw);
   return Number.isFinite(ms) ? ms : null;
@@ -95,9 +98,10 @@ function readHeartbeatMs(sessionLockPath) {
  * @param {string} [opts.autopilotJsonlPath] — path to autopilot.jsonl (default
  *   '.orchestrator/metrics/autopilot.jsonl').
  * @param {string} [opts.sessionLockPath] — path to `session.lock`. When supplied
- *   and readable, its `last_heartbeat` (falling back to `started_at`, the schema
- *   v1 normalisation `session-lock.mjs` applies on read) REPLACES the mtime
- *   marker. Omitted → mtime only, which is what every pre-existing caller gets.
+ *   and readable, its `last_heartbeat` REPLACES the mtime marker. A lock
+ *   without a parsable `last_heartbeat` contributes nothing (no `started_at`
+ *   fallback, as in `session-lock.mjs` `isLockLive()`) and the mtime marker is
+ *   used. Omitted → mtime only, which is what every pre-existing caller gets.
  * @param {number} [opts.stallTimeoutSeconds] — kill-switch threshold (default
  *   600). NOT range-clamped here; caller is responsible for bounds.
  * @param {() => number} [opts.nowMs] — wall-clock supplier (default Date.now).