session-orchestrator 5.12.0 → 5.13.0

package/hooks/pre-bash-staging-fence.mjs

@@ -43,7 +43,7 @@
  *   G1  tool filter — Bash only
  *   G2  command must be a non-empty string
  *   G3  cheap regex PRE-FILTER — skip the tokenizer for plainly unrelated
- *       commands (see GIT_ADD_REGEX; it does not decide the question)
+ *       commands (see mayStage; it does not decide the question)
  *   G4  context gate — isWaveAgentContext(); exit 0 immediately for
  *       coordinator/manual commits (AC5 safe-default no-op)
  *   G4b tokenize + extract path operands; exit 0 when no `git add` statement
@@ -67,7 +67,8 @@
 
 import { readStdin, emitAllow, writeJsonAtomicSync } from '../scripts/lib/io.mjs';
 import { isWaveAgentContext } from '../scripts/lib/wave-context.mjs';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
@@ -87,16 +88,38 @@ import { dotGitAncestor, launchDirFromEnv } from '../scripts/lib/platform.mjs';
  * command?" — since #1404 that verdict belongs to {@link extractStagedPaths},
  * which resolves the verb and subcommand properly.
  *
- * `git` and `add` must sit in the same statement (the negated class stops at
- * `;`, `&`, `|` and newline) within 120 characters of each other, so global
- * flags between them are tolerated: `git -C sub add x` reaches the extractor,
- * where `\bgit\s+add\b` used to drop it silently. `\badd\b` keeps
- * `git addremote` out.
+ * The words `git` and `add` must both occur — anywhere, in any order. Global
+ * flags between them are therefore tolerated at any length: `git -C sub add x`
+ * reaches the extractor, where `\bgit\s+add\b` used to drop it silently.
+ * `\badd\b` keeps `git addremote` out.
+ *
+ * Why not "same statement, within N characters" (#1670 item 6): the previous
+ * `\bgit\b[^;&|\n]{0,120}\badd\b` let `git -C <long path> -c k=v … add x`, a
+ * quoted `;`/`&`/`|` in a `-c` value, and a `\`-newline continuation pass
+ * UNFENCED — this pre-filter is the fence's only early exit, so every miss
+ * fails OPEN. Dropping the bound (`[^;&|\n]*`) is not an option either: it
+ * backtracks once per `git` occurrence, quadratic on attacker-influenced text
+ * (measured 2026-10-18: 200 kB of `git ` → 6220 ms, past the 5 s hook budget;
+ * two independent word tests → 0.16 ms). Two `\b` tests are linear.
  *
  * False positives are cheap AND inert: `git commit -m "add x"` matches here,
  * resolves to no `git add` statement, and writes nothing (G4b).
+ *
+ * `stage` is git's built-in synonym for `add` (#1671 item 5).
+ *
+ * NAMED CEILING (BV-004, #1671 item 5): a subcommand spelled with shell quoting
+ * or escaping — `git a\dd x`, `git a''dd x` — misses both this pre-filter and
+ * the extractor's unquoted-subcommand check, so that staging is not recorded.
+ * The fence only RECORDS (it never blocks), so the loss is a collision entry,
+ * not a bypassed denial. REVISIT TRIGGER: a wave agent observed staging with a
+ * quoted/escaped subcommand, or the fence starting to block.
+ *
+ * @param {string} command
+ * @returns {boolean}
  */
-const GIT_ADD_REGEX = /\bgit\b[^;&|\n]{0,120}\badd\b/;
+function mayStage(command) {
+  return /\b(?:add|stage)\b/.test(command) && /\bgit\b/.test(command);
+}
 
 /**
  * Recorded in place of a path list when the staging command names NO explicit
@@ -114,6 +137,9 @@ const GIT_GLOBAL_VALUE_FLAGS = new Set([
   '-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env',
 ]);
 
+/** `git add` and its built-in synonym `git stage` (#1671 item 5). */
+const GIT_ADD_SUBCOMMANDS = new Set(['add', 'stage']);
+
 /** `git add` flags that consume the NEXT token as their value. */
 const GIT_ADD_VALUE_FLAGS = new Set(['--chmod']);
 
@@ -211,7 +237,7 @@ function normalizeStagedPath(raw) {
  *    blocked commit, which the hook's fail-safe posture forbids. This is also
  *    why a blanket "pre-filter hit but nothing resolved → `paths: ['*']`"
  *    floor was REJECTED at the 2026-09-20 fix: `git commit -m "add x"` matches
- *    {@link GIT_ADD_REGEX}, and the marker overlaps EVERY staged path, so that
+ *    {@link mayStage}, and the marker overlaps EVERY staged path, so that
  *    floor manufactures a collision for a command that stages nothing.
  *  - A staging command a shell never executes locally is not recorded, and
  *    should not be: `ssh host 'git add x'` stages a REMOTE index, and
@@ -311,7 +337,7 @@ function scanForStagedPaths(command, lib, paths, state, depth) {
         // The G3 pre-filter again, on the payload: same cheap question, same
         // tolerated false positives, and it keeps an unrelated `-c` operand
         // from paying for a second tokenize.
-        if (typeof payload === 'string' && GIT_ADD_REGEX.test(payload)) {
+        if (typeof payload === 'string' && mayStage(payload)) {
           scanForStagedPaths(payload, lib, paths, state, depth + 1);
         }
       }
@@ -335,7 +361,7 @@ function scanForStagedPaths(command, lib, paths, state, depth) {
       i += 1; // boolean global flag, or attached `--git-dir=<p>`
     }
 
-    if (i >= segment.length || segment[i].quoted || segment[i].text !== 'add') continue;
+    if (i >= segment.length || segment[i].quoted || !GIT_ADD_SUBCOMMANDS.has(segment[i].text)) continue;
     state.recognised = true;
     i += 1;
 
@@ -485,6 +511,218 @@ function appendIntent({ fenceFile, agentId, command, paths }) {
   return writeJsonAtomicSync(fenceFile, body, { tmpPrefix: '.fence.tmp' });
 }
 
+// ---------------------------------------------------------------------------
+// Work-tree recorder (#1659)
+// ---------------------------------------------------------------------------
+
+/**
+ * Cheap PRE-FILTER for the work-tree recorder — same shape and same role as
+ * {@link mayStage}, for the same reasons (#1670 item 6: a bounded lookahead
+ * silently skipped `git -C <long path> -c … commit`): only a hit pays for the
+ * tokenizer and a git spawn. False positives (`echo "git commit"`) resolve to
+ * no commit statement and record nothing.
+ *
+ * @param {string} command
+ * @returns {boolean}
+ */
+function mayCommit(command) {
+  return /\bcommit\b/.test(command) && /\bgit\b/.test(command);
+}
+
+/** Timeout for the one `git rev-parse` per commit tree (hook budget is 5 s). */
+const RECORDER_GIT_TIMEOUT_MS = 2000;
+
+/** Directory-changing verbs whose effect the walker does not model (#1659). */
+const DIR_UNKNOWN_VERBS = new Set(['pushd', 'popd', 'chdir']);
+/** Builtins that change the directory when invoked as `builtin <name>` (#1659). */
+const DIR_CHANGE_BUILTINS = new Set(['cd', 'pushd', 'popd', 'chdir']);
+
+/**
+ * Expand a `cd`/`-C` operand against the current directory. Returns null when
+ * the operand cannot be resolved without a shell (`$VAR`, `~user`, `-`), so
+ * the caller records nothing rather than a guessed tree.
+ *
+ * @param {string} base - absolute current directory
+ * @param {string} operand
+ * @returns {string|null}
+ */
+function resolveDirOperand(base, operand) {
+  if (operand === '~') return os.homedir();
+  if (operand.startsWith('~/')) return path.join(os.homedir(), operand.slice(2));
+  if (operand === '-' || operand.startsWith('~') || operand.includes('$') || operand.includes('`')) return null;
+  return path.resolve(base, operand);
+}
+
+/**
+ * Effective directories of every `git commit` statement in a command.
+ *
+ * Walks the chain segments in order, tracking the directory the shell would be
+ * in: a `cd <dir>` statement moves it (relative to the previous one), and each
+ * `-C <dir>` global flag of the commit statement composes on top, as git does.
+ * A `cd` whose operand is unresolvable (`cd "$WT"`) makes the directory
+ * UNKNOWN for the rest of the command — later commits are not recorded rather
+ * than misattributed to the launch tree. So does any directory change the
+ * walker does not model (`pushd`, `popd`, `chdir`, `builtin cd`).
+ *
+ * NAMED CEILINGS (BV-004): subshell scope is not modelled — `(cd x && git
+ * commit); git commit` attributes the second commit to `x` too; a commit nested
+ * in `bash -c "…"` is not recorded. REVISIT if a session's commits are found
+ * missing from `orchestrator.session.work_tree` for one of these shapes.
+ *
+ * @param {string} command
+ * @param {string} startDir - absolute directory the command starts in
+ * @param {{ tokenizeCommand: Function, splitChainSegments: Function,
+ *           resolveSegmentVerb: Function }} lib
+ * @returns {string[]} distinct absolute directories
+ */
+function commitDirs(command, startDir, lib) {
+  const out = new Set();
+  let cwd = startDir;
+  const tokens = lib.tokenizeCommand(command);
+  // No paren stripping here: since #1667 the shared tokenizer turns subshell
+  // parens into statement breaks and appends `$( )`/backtick bodies as their
+  // own statements. A hand strip on top only ever changed `((git commit))`
+  // — arithmetic, not a commit — into a recorded commit (#1670).
+  //
+  // Those hoisted bodies sit AFTER every outer statement, behind the first
+  // `operator: 'substitution'` separator, so walking them in stream order would
+  // judge `cd sub && echo $(git commit); cd ../other` against `other`. Walk the
+  // outer statements first; the bodies then run in the start directory only
+  // when no outer statement moved it, and in an UNKNOWN directory otherwise
+  // (not recorded rather than misattributed).
+  const cut = tokens.findIndex((t) => t.operator === 'substitution');
+  const outer = cut < 0 ? tokens : tokens.slice(0, cut);
+  const hoistedSegments = cut < 0 ? [] : lib.splitChainSegments(tokens.slice(cut));
+  const outerSegments = lib.splitChainSegments(outer);
+  let moved = false;
+  const segments = [...outerSegments, null, ...hoistedSegments];
+  for (const segment of segments) {
+    if (segment === null) {
+      // Boundary between the outer statements and the hoisted bodies.
+      cwd = moved ? null : startDir;
+      continue;
+    }
+    if (segment.length === 0) continue;
+    const { verb, index } = lib.resolveSegmentVerb(segment);
+    if (index < 0) continue;
+
+    // A directory change the walker does not model (`pushd`, `popd`, zsh's
+    // `chdir`, `builtin cd …`) makes the directory UNKNOWN, like an
+    // unresolvable `cd` operand — never misattributed to the old tree (#1659).
+    if (!segment[index].quoted && (DIR_UNKNOWN_VERBS.has(verb)
+      || (verb === 'builtin' && index + 1 < segment.length && DIR_CHANGE_BUILTINS.has(segment[index + 1].text)))) {
+      cwd = null;
+      moved = true;
+      continue;
+    }
+
+    if (verb === 'cd' && !segment[index].quoted) {
+      moved = true;
+      if (cwd === null) continue;
+      let operand = null;
+      for (let j = index + 1; j < segment.length; j++) {
+        const t = segment[j];
+        if (!t.quoted && t.text.startsWith('-') && t.text !== '-') continue; // -P / -L
+        operand = t.text;
+        break;
+      }
+      cwd = operand === null ? os.homedir() : resolveDirOperand(cwd, operand);
+      continue;
+    }
+
+    if (verb !== 'git' || cwd === null) continue;
+    let dir = cwd;
+    let i = index + 1;
+    while (i < segment.length) {
+      const tok = segment[i];
+      if (tok.quoted || !tok.text.startsWith('-') || tok.text === '-') break;
+      if (GIT_GLOBAL_VALUE_FLAGS.has(tok.text)) {
+        if (tok.text === '-C' && i + 1 < segment.length && dir !== null) {
+          dir = resolveDirOperand(dir, segment[i + 1].text);
+        }
+        i += 2;
+        continue;
+      }
+      i += 1;
+    }
+    if (i < segment.length && !segment[i].quoted && segment[i].text === 'commit' && dir !== null) {
+      out.add(dir);
+    }
+  }
+  return [...out];
+}
+
+/**
+ * Record `(tree, start_ref)` for every tree a `git commit` in this command
+ * targets, as an `orchestrator.session.work_tree` event (#1659).
+ *
+ * Runs for EVERY session context (coordinator and wave agents alike), before
+ * the fence gates. Best-effort and side-effect-only: it never throws, never
+ * blocks, and never touches the hook's decision — the caller emits the same
+ * allow either way. One record per commit; the READER dedupes (first record
+ * per tree wins), so no ledger read happens on this path.
+ *
+ * Cost on a command without a commit: one or two linear word tests.
+ *
+ * @param {object} input - the hook payload
+ * @param {string} command
+ * @returns {Promise<void>}
+ */
+async function recordWorkTrees(input, command) {
+  try {
+    if (!mayCommit(command)) return;
+    const sessionId = typeof input?.session_id === 'string' ? input.session_id.trim() : '';
+    if (sessionId === '') return;
+    const payloadCwd = typeof input?.cwd === 'string' ? input.cwd.trim() : '';
+    const startDir = path.isAbsolute(payloadCwd) ? payloadCwd : process.cwd();
+
+    const lib = await import('../scripts/lib/command-blocker.mjs');
+    const dirs = commitDirs(command, startDir, lib);
+    if (dirs.length === 0) return;
+
+    const pairs = new Map();
+    for (const dir of dirs) {
+      let lines;
+      try {
+        lines = execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel', 'HEAD'], {
+          encoding: 'utf8',
+          timeout: RECORDER_GIT_TIMEOUT_MS,
+          stdio: ['ignore', 'pipe', 'ignore'],
+        }).split('\n');
+      } catch {
+        continue; // not a repo, dir gone, or unborn HEAD — nothing to anchor on
+      }
+      const top = (lines[0] || '').trim();
+      const head = (lines[1] || '').trim();
+      if (top === '' || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(head)) continue;
+      let tree = top;
+      try { tree = realpathSync(top); } catch { /* keep git's spelling */ }
+      if (!pairs.has(tree)) pairs.set(tree, head);
+    }
+    if (pairs.size === 0) return;
+
+    const { emitEvent } = await import('../scripts/lib/events.mjs');
+    const { SESSION_WORK_TREE_EVENT } = await import('../scripts/lib/events-schema.mjs');
+    for (const [tree, startRef] of pairs) {
+      try {
+        await emitEvent(SESSION_WORK_TREE_EVENT, {
+          session_id: sessionId,
+          tree,
+          start_ref: startRef,
+        });
+      } catch (err) {
+        process.stderr.write(
+          `⚠ pre-bash-staging-fence: work-tree record not written — ${err?.message || err}\n`,
+        );
+      }
+    }
+  } catch (err) {
+    process.stderr.write(
+      `⚠ pre-bash-staging-fence: work-tree recorder failed — ${err?.message || err}\n`,
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -500,9 +738,13 @@ async function main() {
   const command = input?.tool_input?.command;
   if (typeof command !== 'string' || command.length === 0) return emitAllow();
 
+  // #1659 — record (tree, start_ref) before any `git commit`, in every session
+  // context. Side effect only: it cannot change the decision below.
+  await recordWorkTrees(input, command);
+
   // G3 — cheap regex PRE-FILTER. Commands that cannot possibly be a staging
   // command pass through without loading the tokenizer.
-  if (!GIT_ADD_REGEX.test(command)) return emitAllow();
+  if (!mayStage(command)) return emitAllow();
 
   // G4 — context gate. Coordinator/manual commits are not fenced.
   if (!isWaveAgentContext()) return emitAllow();
@@ -541,8 +783,10 @@ if (isMainModule(import.meta.url)) {
   if (!shouldRunHook('pre-bash-staging-fence')) process.exit(0);
 
   // Top-level error handler — never let exit 1 leak. Fail-open on internal
-  // errors to avoid blocking legitimate work (mirrors the destructive-guard
-  // posture).
+  // errors on purpose (#1679 point 3): this hook only LOGS staging intent and
+  // never blocks (G6); the commit guard reconciles. Unlike the destructive
+  // guard, which denies on an internal error since #1671, a deny here would turn
+  // the logger into a gate. Revisit if a fence record is missed because of one.
   main().catch((e) => {
     process.stderr.write(
       `⚠ pre-bash-staging-fence: internal error — ${e?.message || e}\n`,

package/hooks/pre-bash-templates-first.mjs

@@ -38,8 +38,9 @@
  */
 
 import { readStdin, emitAllow, emitDeny } from '../scripts/lib/io.mjs';
-import { resolveProjectDir, resolvePluginRoot } from '../scripts/lib/platform.mjs';
+import { resolveProjectDir, resolvePluginRoot, resolveEventsLedgerRoot } from '../scripts/lib/platform.mjs';
 import { readJson } from '../scripts/lib/common.mjs';
+import { readProcessLocalSessionIds } from '../scripts/lib/session-identity/own-session.mjs';
 import { hasReadInSession } from './_lib/transcript-history.mjs';
 import { resolveHost, matchesBypass } from './_lib/vcs-create-matcher.mjs';
 
@@ -219,7 +220,8 @@ function resolvePolicyPath(projectDir) {
  *
  *   { "<session_id>": { "acknowledgedAt": "<ISO timestamp>" } }
  *
- * A future /templates-ack command writes this file; the hook only reads it.
+ * The `/templates-ack` command (commands/templates-ack.md, #1589/#1591) writes
+ * this file; the hook only reads it.
  *
  * @param {string} ackFilePath
  * @param {string|null} sessionId
@@ -239,29 +241,25 @@ async function isAcknowledged(ackFilePath, sessionId) {
 }
 
 /**
- * Pull the session_id from the hook stdin payload, with a single fallback
- * to the persisted file written by on-session-start.mjs. Returns null when
- * neither source yields a string.
+ * Require this invocation's ID for acknowledgement identity. Missing, malformed
+ * or conflicting IDs cannot fall back to env. Parent IDs and shared checkout
+ * state never establish an acknowledgement identity.
  *
  * @param {object|null} input
- * @param {string|null} projectDir
- * @returns {Promise<string|null>}
+ * @returns {string|null}
  */
-async function resolveSessionId(input, projectDir) {
-  const fromStdin = input?.session_id ?? input?.sessionId ?? null;
-  if (typeof fromStdin === 'string' && fromStdin.length > 0) return fromStdin;
-
-  if (!projectDir) return null;
-  const persisted = path.join(projectDir, '.orchestrator', 'current-session.json');
-  if (!existsSync(persisted)) return null;
-  try {
-    const data = await readJson(persisted);
-    if (data && typeof data === 'object') {
-      const sid = data.session_id ?? data.sessionId ?? null;
-      if (typeof sid === 'string' && sid.length > 0) return sid;
-    }
-  } catch {
-    // ignore — null below
+function resolveSessionId(input) {
+  const keys = ['session_id', 'sessionId'].filter((key) =>
+    Object.hasOwn(input ?? {}, key),
+  );
+  if (keys.length > 0) {
+    const ids = keys.map((key) => input[key]);
+    if (ids.some((id) => typeof id !== 'string' || !id.trim())) return null;
+    const trimmed = ids.map((id) => id.trim());
+    if (new Set(trimmed).size !== 1) return null;
+    // Pass only the invocation ID: the helper's parent/env union is not an
+    // acknowledgement identity and must not grant a peer's bypass.
+    return readProcessLocalSessionIds({ env: {}, hookInput: { session_id: trimmed[0] } })[0] ?? null;
   }
   return null;
 }
@@ -330,12 +328,15 @@ async function main() {
     typeof policy.acknowledgement_file === 'string' && policy.acknowledgement_file.length > 0
       ? policy.acknowledgement_file
       : DEFAULT_ACK_PATH;
+  // A relative ack file is runtime state, not a tracked file: resolve it under
+  // the MAIN checkout for a linked worktree, the same root `/templates-ack`
+  // writes to — otherwise the two sides split across roots (sweep of #1729).
   const ackFile = path.isAbsolute(ackRel)
     ? ackRel
-    : path.join(projectDir || process.cwd(), ackRel);
+    : path.join(resolveEventsLedgerRoot(projectDir || process.cwd()), ackRel);
 
   // G6 — acknowledgement-file check.
-  const sessionId = await resolveSessionId(input, projectDir);
+  const sessionId = resolveSessionId(input);
   if (await isAcknowledged(ackFile, sessionId)) {
     return emitAllow();
   }
@@ -430,9 +431,9 @@ if (isMainModule(import.meta.url)) {
   // per session.
   if (!shouldRunHook('pre-bash-templates-first')) process.exit(0);
 
-  // Top-level error handler — never let exit 1 leak. Same posture as
-  // pre-bash-destructive-guard.mjs: fail-open on internal errors to avoid
-  // blocking legitimate work.
+  // Top-level error handler — never let exit 1 leak. This hook is advisory, so
+  // it fails open on internal errors to avoid blocking legitimate work (unlike
+  // pre-bash-destructive-guard.mjs, which denies on a main() error, #1671).
   main().catch((e) => {
     process.stderr.write(
       `⚠ pre-bash-templates-first: internal error — ${e?.message || e}\n`,

package/hooks/run-node.sh

@@ -66,7 +66,7 @@ if [ -n "$expired" ]; then
     echo "session-orchestrator: 'node' not found on the hook PATH — plugin hooks are skipped."
     echo "  Fix: install Node.js 24+, expose it on the harness PATH, or set SO_NODE_BIN=/abs/path/to/node."
     echo "  (Hook shells do not source ~/.zshrc — Homebrew/nvm/volta installs can be invisible here."
-    echo "   Rate-limited to once per 6h. See README.md § Troubleshooting.)"
+    echo "   Rate-limited to once per 6h. See docs/USER-GUIDE.md § Node is missing from the hook PATH.)"
   } >&2
 fi
 exit 0

package/hooks/skill-invocation-telemetry.mjs

@@ -33,7 +33,8 @@ import { spawn } from 'node:child_process';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { appendSkillInvocation } from '../scripts/lib/skill-invocations-schema.mjs';
-import { getProjectDir } from '../scripts/lib/platform.mjs';
+import { resolveEventsLedgerRoot } from '../scripts/lib/platform.mjs';
+import { resolveLedgerPath } from '../scripts/lib/ledger-path.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';
@@ -44,19 +45,25 @@ import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 // ---------------------------------------------------------------------------
 
 /**
- * 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).
+ * Ledger paths. FUNCTIONS, not module-level consts: resolving the project dir
+ * walks the filesystem on first call, and this hook must not pay that at
+ * import time (#1153 P5).
+ *
+ * The two resolve independently (#1722): `skill-invocations.jsonl` goes
+ * through {@link resolveLedgerPath} (the main checkout's copy only when the
+ * launch dir is a linked worktree that gitignores it), while the metrics dir
+ * holding `sessions.jsonl` maps unconditionally via resolveEventsLedgerRoot
+ * (#1514/#1584).
  *
  * @returns {string}
  */
-function metricsDirPath() {
-  return path.join(getProjectDir(), '.orchestrator', 'metrics');
+function sessionsMetricsDirPath() {
+  return path.join(resolveEventsLedgerRoot(), '.orchestrator', 'metrics');
 }
 
 /** @returns {string} */
 function jsonlPath() {
-  return path.join(metricsDirPath(), 'skill-invocations.jsonl');
+  return resolveLedgerPath('.orchestrator/metrics/skill-invocations.jsonl');
 }
 
 /** Absolute path to the telemetry CLI (carries the hidden `_flush` subcommand). */
@@ -136,7 +143,7 @@ export function maybeSpawnDailyFlush({
   now = Date.now(),
   statePath,
   queuePath,
-  metricsDir = metricsDirPath(),
+  metricsDir = sessionsMetricsDirPath(),
 } = {}) {
   try {
     // 1. Cheapest gate: env kill-switches, no file I/O.

package/hooks/subagent-telemetry.mjs

@@ -108,12 +108,14 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import fs from 'node:fs';
-import path from 'node:path';
 import { appendSubagent } from '../scripts/lib/subagents-schema.mjs';
 import { getProjectDir } from '../scripts/lib/platform.mjs';
+import { resolveLedgerPath } from '../scripts/lib/ledger-path.mjs';
 import { resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 import { readTailWindow } from '../scripts/lib/tail-window.mjs';
 import { COST_BASIS } from '../scripts/lib/telemetry/pricing.mjs';
+import { setLifecycle } from '../scripts/lib/agent-status.mjs';
+import { rawPayloadSessionId, resolveOwnLockRoot } from './_lib/hook-root.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -127,7 +129,9 @@ import { COST_BASIS } from '../scripts/lib/telemetry/pricing.mjs';
  * @returns {string}
  */
 function jsonlPath() {
-  return path.join(getProjectDir(), '.orchestrator', 'metrics', 'subagents.jsonl');
+  // #1722: the main checkout's copy when the launch dir is a linked worktree
+  // that gitignores the ledger (emit-session.mjs reads it there).
+  return resolveLedgerPath('.orchestrator/metrics/subagents.jsonl');
 }
 
 /**
@@ -650,7 +654,9 @@ function resolveSubagentTranscriptPath(parentTranscriptPath, agentId) {
 
 /**
  * Scan the tail of the ledger backwards for the most recent 'start' record with
- * the given agent_id and return its timestamp in epoch-ms (#917).
+ * the given agent_id and return its timestamp in epoch-ms (#917) plus its
+ * `agent_type` (#1617), so a stop whose payload carries no type can inherit it
+ * from the same single tail read — no second scan on the hot path.
  *
  * Reads only the last START_JOIN_TAIL_BYTES rather than the whole file — see that
  * constant for the measured sizing rationale. Scanning backwards means the FIRST
@@ -658,20 +664,22 @@ function resolveSubagentTranscriptPath(parentTranscriptPath, agentId) {
  * reused across sessions (measured 2026-07-30: 22 of 1420 distinct start ids
  * appeared more than once).
  *
- * NEVER throws. Any failure (missing file, unreadable, no match, unparseable
- * timestamp) yields null so the caller falls back to an honest "unknown".
+ * NEVER throws. Any failure (missing file, unreadable, no match) yields
+ * `{ startedAtMs: null, agentType: null }` so the caller falls back to an honest
+ * "unknown". An unparseable start timestamp nulls only `startedAtMs`.
  *
  * @param {string} filePath — ledger path
  * @param {string} agentId — the stopping agent's id
- * @returns {number|null} epoch-ms of the matching start, or null
+ * @returns {{ startedAtMs: number|null, agentType: string|null }}
  */
-function findStartTimestampMs(filePath, agentId) {
+function findStartRecord(filePath, agentId) {
+  const none = { startedAtMs: null, agentType: null };
   try {
-    if (typeof agentId !== 'string' || !agentId.trim()) return null;
-    if (!fs.existsSync(filePath)) return null;
+    if (typeof agentId !== 'string' || !agentId.trim()) return none;
+    if (!fs.existsSync(filePath)) return none;
 
     const window = readTailWindow(filePath, START_JOIN_TAIL_BYTES);
-    if (window.size === 0) return null;
+    if (window.size === 0) return none;
 
     const lines = window.text.split('\n');
     // When the window does not cover the whole file, the first element is a
@@ -692,11 +700,13 @@ function findStartTimestampMs(filePath, agentId) {
       }
       if (!obj || obj.event !== 'start' || obj.agent_id !== agentId) continue;
       const ms = Date.parse(obj.timestamp);
-      return Number.isFinite(ms) ? ms : null;
+      const agentType =
+        typeof obj.agent_type === 'string' && obj.agent_type.trim() ? obj.agent_type : null;
+      return { startedAtMs: Number.isFinite(ms) ? ms : null, agentType };
     }
-    return null;
+    return none;
   } catch {
-    return null;
+    return none;
   }
 }
 
@@ -798,7 +808,23 @@ 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(jsonlPath(), agentId);
+    const startJoin = agentId === 'unknown'
+      ? { startedAtMs: null, agentType: null }
+      : findStartRecord(jsonlPath(), agentId);
+    const { startedAtMs } = startJoin;
+
+    // agent_type inheritance (#1617): the stop payload does not always carry the
+    // type, while the start record for the same agent_id does. Payload wins when
+    // present; otherwise take it from the start record found by the join above.
+    // CEILING: this cannot type the phantom class (#939/#949) — those stops have
+    // no start record at all. Almost all type-less stop records are phantom
+    // stops (subagent_transcript_found: false), which this join cannot type;
+    // records from before #949 carry no flag at all. It closes the class for
+    // real agents whose stop payload omits the type.
+    // Readers counting by type must still filter on subagent_transcript_found.
+    if (agentType === null && startJoin.agentType !== null) {
+      record.agent_type = startJoin.agentType;
+    }
 
     // duration_ms (#917): prefer the harness value, else join backwards to this
     // agent's own start record, else null. Never 0 — see resolveDurationMs().
@@ -884,6 +910,43 @@ async function main() {
   }
 
   await appendSubagent(jsonlPath(), record);
+  await writeLiveMap(input, record);
+}
+
+/**
+ * Keep the HUD's agent live-map current from the lifecycle hooks (#1580).
+ * Before this, only wave-executor self-reports reached
+ * `.orchestrator/runtime/agent-status-current.json`, and those carry no session
+ * binding, so so-hud showed 0 agents while subagents ran.
+ *
+ * Writes into the root that holds THIS session's lock (#1605), so a session
+ * working in a worktree feeds the map the HUD reads beside that lock. A stop is
+ * written only when its start record was found: the phantom-stop class
+ * (#939/#949) has no start and a fresh agent_id per firing, and would otherwise
+ * add one `done` entry per firing. Best-effort: a short lock timeout and every
+ * failure swallowed, so agent dispatch is never delayed beyond it.
+ *
+ * @param {object} input   Hook payload.
+ * @param {object} record  The ledger record just written.
+ * @returns {Promise<void>}
+ */
+async function writeLiveMap(input, record) {
+  try {
+    if (record.agent_id === 'unknown') return;
+    if (record.event === 'stop' && record.start_record_found !== true) return;
+    const sessionId = rawPayloadSessionId({ session_id: record.parent_session_id });
+    if (sessionId === null) return;
+    const repoRoot = resolveOwnLockRoot({ session_id: sessionId, cwd: input?.cwd }, getProjectDir());
+    await setLifecycle(
+      record.agent_id,
+      { status: record.event === 'start' ? 'running' : 'done', sessionId, agentType: record.agent_type ?? null },
+      // The event's own time, not the time after transcript parsing: a stop stamped late can overtake a
+      // quickly resumed agent's next start and show it as done.
+      { repoRoot, timeoutMs: 1000, now: Number.isFinite(Date.parse(record.timestamp)) ? Date.parse(record.timestamp) : Date.now() },
+    );
+  } catch {
+    /* best-effort: the live-map never blocks or fails the hook */
+  }
 }
 
 // Entry guard (#1393): run only as the node script the harness execs — a bare