@promptctl/cc-candybar 1.17.3 → 1.17.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.17.3",
+  "version": "1.17.5",
   "description": "Statusline renderer for Claude Code — a JSON5-configurable DSL with daemon-cached data sources, byte-clean palette-aware composition, and OSC8 click verbs.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -24,6 +24,10 @@
     "test:coverage": "jest --coverage",
     "demo": "tsx src/demo/dsl.ts",
     "benchmark:timing": "scripts/benchmark_timing.sh",
+    "preloadtest": "pnpm build",
+    "loadtest": "node --import tsx scripts/daemon-load-harness.ts",
+    "preloadtest:gate": "pnpm build",
+    "loadtest:gate": "node --import tsx scripts/daemon-load-harness.ts --sessions 25 --interval 300 --duration 20 --churn --transcript-lines 5000",
     "check:protocol": "node scripts/check-protocol.mjs",
     "gen:schema": "tsx scripts/gen-schema.ts",
     "check:schema": "tsx scripts/check-schema.ts",
@@ -91,10 +95,10 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.17.3",
-    "@promptctl/cc-candybar-darwin-x64": "1.17.3",
-    "@promptctl/cc-candybar-linux-x64": "1.17.3",
-    "@promptctl/cc-candybar-linux-arm64": "1.17.3"
+    "@promptctl/cc-candybar-darwin-arm64": "1.17.5",
+    "@promptctl/cc-candybar-darwin-x64": "1.17.5",
+    "@promptctl/cc-candybar-linux-x64": "1.17.5",
+    "@promptctl/cc-candybar-linux-arm64": "1.17.5"
   },
   "pnpm": {
     "supportedArchitectures": {

package/src/daemon/cache/session-usage-store.ts

@@ -1,23 +1,26 @@
-import fs from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 import {
-  SessionProvider,
   type SessionInfo,
-  type SessionUsage,
   type UsageInfo,
   type TokenBreakdown,
 } from "../../segments/session";
+import { PricingService } from "../../segments/pricing";
 import {
   getClaudePaths,
   findProjectPaths,
+  findAgentTranscripts,
+  readAppendedEntries,
   type ClaudeHookData,
+  type ParsedEntry,
+  type TranscriptCursor,
 } from "../../utils/claude";
 // [LAW:single-enforcer] The once-per-day seed's directory walk shares the same
 // in-flight-I/O budget (gn4.2) as every other transcript scan.
 import {
   readdir as gatedReaddir,
   stat as gatedStat,
+  statMtimeMs,
 } from "../../utils/transcript-fs";
 import { SingleFlight } from "../../utils/single-flight";
 import { ABSENT, failed, ok, type Outcome } from "../../utils/outcome";
@@ -105,6 +108,10 @@ interface DayUsage {
 }
 
 interface SessionRecord {
+  // [LAW:one-source-of-truth] `files` is canonical (main transcript + agent
+  // sidechains, each its own incremental FileFold); `sessionInfo`/`days` are
+  // derived from mergeFolds and re-synced on every ingest — the single writer.
+  files: Map<string, FileFold>;
   sessionInfo: SessionInfo;
   days: Map<string, DayUsage>;
   transcriptMtime: number;
@@ -152,33 +159,119 @@ function seedCutoffMs(): number {
   return d.getTime();
 }
 
-function statMtimeMs(filePath: string | undefined): number {
-  if (!filePath) return 0;
-  try {
-    return fs.statSync(filePath).mtimeMs;
-  } catch {
-    return 0;
-  }
+function emptyBreakdown(): TokenBreakdown {
+  return { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 };
+}
+
+// [LAW:one-source-of-truth] The incremental fold of ONE append-only transcript
+// file (a session's main transcript or one agent sidechain). `cursor` marks the
+// bytes already folded; the sums run over every usage-bearing entry seen so far.
+// The session aggregate is the MERGE of its files' folds (mergeFolds), so a file
+// rewritten by /compact re-folds in isolation without disturbing the others.
+interface FileFold {
+  cursor: TranscriptCursor;
+  entries: number; // usage-bearing entries folded (0 ⇒ empty session, all-null)
+  cost: number;
+  breakdown: TokenBreakdown;
+  days: Map<string, DayUsage>; // keys >= seed cutoff only (pruned on fold)
 }
 
-// dayKey strings sort lexically == chronologically, so "keep recent" is a
-// string comparison against yesterday's key.
-function bucketByDay(usage: SessionUsage): Map<string, DayUsage> {
+// [LAW:effects-at-boundaries] Pure fold of NEW entries onto a prior file fold.
+// Returns a FRESH FileFold (prior is never mutated) so two concurrent refolds
+// sharing one prior snapshot can't corrupt each other. `reset` (file rewritten)
+// discards the prior sums and folds `entries` — the whole new file — from zero.
+//
+// [LAW:one-source-of-truth] Session cost and day cost use the SAME priced value:
+// an entry lacking costUSD is priced once (PricingService) and that figure feeds
+// BOTH the session total and its day bucket. This matches the old path exactly —
+// it mutated entry.costUSD to the priced cost before bucketByDay read it — so
+// `today` is not silently under-counted for un-costed entries.
+async function foldFile(
+  prior: FileFold | undefined,
+  reset: boolean,
+  entries: readonly ParsedEntry[],
+  cursor: TranscriptCursor,
+): Promise<FileFold> {
+  // dayKey strings sort lexically == chronologically, so "keep recent" is a
+  // string comparison against yesterday's key.
   const keep = dayKey(new Date(seedCutoffMs()));
+  const base = prior && !reset ? prior : undefined;
+  let count = base?.entries ?? 0;
+  let cost = base?.cost ?? 0;
+  const breakdown = base ? { ...base.breakdown } : emptyBreakdown();
   const days = new Map<string, DayUsage>();
-  for (const entry of usage.entries) {
+  if (base) {
+    for (const [k, v] of base.days) if (k >= keep) days.set(k, { ...v });
+  }
+  for (const entry of entries) {
+    const u = entry.message?.usage;
+    if (!u) continue;
+    count++;
+    const priced =
+      entry.costUSD ?? (await PricingService.calculateCostForEntry(entry.raw));
+    cost += priced;
+    breakdown.input += u.input_tokens || 0;
+    breakdown.output += u.output_tokens || 0;
+    breakdown.cacheCreation += u.cache_creation_input_tokens || 0;
+    breakdown.cacheRead += u.cache_read_input_tokens || 0;
     const key = dayKey(new Date(entry.timestamp));
     if (key < keep) continue;
     const d = days.get(key) ?? { ...EMPTY_DAY };
-    const u = entry.message.usage;
-    d.cost += entry.costUSD ?? 0;
+    // [LAW:one-source-of-truth] Day cost uses the PRICED value, same as session
+    // cost — the old path mutated entry.costUSD to the priced cost before
+    // bucketByDay read it, so an un-costed entry contributed its priced value to
+    // `today`, not 0. Using `priced` here preserves that (session and day agree).
+    d.cost += priced;
     d.input += u.input_tokens || 0;
     d.output += u.output_tokens || 0;
     d.cacheCreation += u.cache_creation_input_tokens || 0;
     d.cacheRead += u.cache_read_input_tokens || 0;
     days.set(key, d);
   }
-  return days;
+  return { cursor, entries: count, cost, breakdown, days };
+}
+
+// [LAW:effects-at-boundaries] Pure merge of a session's file folds into the
+// derived record shape the read path serves. `entries === 0` across all files is
+// the empty session (all-null SessionInfo, whose fields the payload drops) — the
+// same distinction the old `entries.length === 0` arm carried.
+function mergeFolds(files: ReadonlyMap<string, FileFold>): {
+  sessionInfo: SessionInfo;
+  days: Map<string, DayUsage>;
+} {
+  let count = 0;
+  let cost = 0;
+  const bd = emptyBreakdown();
+  const days = new Map<string, DayUsage>();
+  for (const f of files.values()) {
+    count += f.entries;
+    cost += f.cost;
+    bd.input += f.breakdown.input;
+    bd.output += f.breakdown.output;
+    bd.cacheCreation += f.breakdown.cacheCreation;
+    bd.cacheRead += f.breakdown.cacheRead;
+    for (const [k, v] of f.days) {
+      const d = days.get(k) ?? { ...EMPTY_DAY };
+      d.cost += v.cost;
+      d.input += v.input;
+      d.output += v.output;
+      d.cacheCreation += v.cacheCreation;
+      d.cacheRead += v.cacheRead;
+      days.set(k, d);
+    }
+  }
+  if (count === 0) return { sessionInfo: EMPTY_SESSION_INFO, days };
+  const tokens = bd.input + bd.output + bd.cacheCreation + bd.cacheRead;
+  return {
+    sessionInfo: {
+      cost,
+      calculatedCost: cost,
+      officialCost: null,
+      tokens,
+      tokenBreakdown: bd,
+    },
+    days,
+  };
 }
 
 // Bounded-concurrency fan-out for the seed: at most `limit` parses in flight.
@@ -201,7 +294,6 @@ async function mapPool<T>(
 }
 
 export class SessionUsageStore {
-  private readonly sessions = new SessionProvider();
   private readonly entries = new Map<string, SessionRecord>();
   // [LAW:one-source-of-truth] Coalesces concurrent MISSES for the same
   // (session, observed mtime) onto one parse; cleared on settle (a coalescer,
@@ -424,15 +516,49 @@ export class SessionUsageStore {
     if (!transcriptPath) return existing ? ok(existing) : ABSENT;
 
     this.misses++;
-    const aggregate = await this.flight.run(`${sessionId}:${mtime}`, () =>
-      this.aggregate(sessionId, transcriptPath),
-    );
-    if (aggregate.kind !== "ok") return aggregate;
-    // Tag with the mtime observed AFTER the read so the next render that sees
-    // the same mtime is a safe hit.
+    // [LAW:no-ambient-temporal-coupling] The flight thunk snapshots the prior
+    // record when it RUNS (first caller); coalesced callers share that one
+    // refold. Two concurrent DIFFERENT-mtime refolds each read the same prior and
+    // last-writer-wins. This is safe — and specifically NOT a double-count —
+    // because `refold` writes the byte cursor and the fold as ONE atomic pair
+    // (both from a single refold result), and the fold always covers exactly
+    // [0, cursor). A losing writer's fold is discarded WITH its cursor, not left
+    // beside a stale one. So even when last-writer-wins rewinds the stored cursor,
+    // it rewinds the paired fold with it; the next refold folds [cursor, end) onto
+    // a fold that lacks those bytes — each byte folded once. `foldFile` is pure
+    // (fresh FileFold, prior never mutated), so the shared prior can't corrupt.
+    // Pinned by the concurrency test in test/transcript-incremental.test.ts.
+    // The prior is read when the thunk RUNS. If evictIfNeeded dropped this
+    // session between thunk creation and run, prior is undefined and refold does
+    // one whole-file re-fold — still correct, just non-incremental that once.
+    // (Eviction only fires after a successful write, so this can bite only on a
+    // first miss under cap pressure.)
+    // [LAW:no-silent-failure] ingest MUST stay total — every caller reads
+    // `.kind`, so a rejected promise (e.g. PricingService.calculateCostForEntry
+    // throwing on a bad rate table or network hiccup inside foldFile) would
+    // escape the Outcome contract entirely. The deleted getSessionUsageFromPath
+    // wrapped this; keep that guarantee by mapping any throw to `failed`.
+    let outcome: Outcome<{
+      files: Map<string, FileFold>;
+      sessionInfo: SessionInfo;
+      days: Map<string, DayUsage>;
+      mainMtime: number;
+    }>;
+    try {
+      outcome = await this.flight.run(`${sessionId}:${mtime}`, () =>
+        this.refold(sessionId, transcriptPath, this.entries.get(sessionId)),
+      );
+    } catch (error) {
+      return failed(
+        `usage refold (${sessionId}): ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    if (outcome.kind !== "ok") return outcome;
     const record: SessionRecord = {
-      ...aggregate.value,
-      transcriptMtime: statMtimeMs(transcriptPath),
+      files: outcome.value.files,
+      sessionInfo: outcome.value.sessionInfo,
+      days: outcome.value.days,
+      transcriptMtime: outcome.value.mainMtime,
       transcriptPath,
       lastSeenAt: Date.now(),
     };
@@ -442,23 +568,54 @@ export class SessionUsageStore {
     return ok(record);
   }
 
-  private async aggregate(
+  // [LAW:dataflow-not-control-flow] Re-fold ONLY the bytes appended since the
+  // prior record — the transcript (and each agent sidechain) is append-only, so
+  // per-render work is O(new bytes), not O(file). The whole-file case (cold
+  // record, or a first-ever read) is the same path with an empty prior: the
+  // reader yields the whole file from offset 0. A `failed` read on any file
+  // fails the fold (the boundary logs it); an `absent` file (not yet written /
+  // agent removed) keeps its prior fold and contributes nothing new.
+  private async refold(
     sessionId: string,
     transcriptPath: string,
+    prior: SessionRecord | undefined,
   ): Promise<
-    Outcome<{ sessionInfo: SessionInfo; days: Map<string, DayUsage> }>
+    Outcome<{
+      files: Map<string, FileFold>;
+      sessionInfo: SessionInfo;
+      days: Map<string, DayUsage>;
+      mainMtime: number;
+    }>
   > {
-    const usage = await this.sessions.getSessionUsageFromPath(
+    // File set for this fold: the main transcript plus the session's current
+    // agent sidechains. Files no longer in the set (a removed sidechain) drop
+    // out of `newFiles`, so a rewritten/renamed file cannot linger in the merge.
+    // Pass the prior file set so already-verified agent sidechains skip their
+    // first-line re-read — per-render agent discovery is O(new sidechains).
+    const agentPaths = await findAgentTranscripts(
       sessionId,
-      transcriptPath,
+      dirname(transcriptPath),
+      prior === undefined ? undefined : new Set(prior.files.keys()),
     );
-    // getSessionUsageFromPath never produces absent (an empty transcript is a
-    // real zero-entry usage); failed passes through to the boundary.
-    if (usage.kind !== "ok") return usage;
-    return ok({
-      sessionInfo: this.sessions.toSessionInfo(usage.value),
-      days: bucketByDay(usage.value),
-    });
+    const newFiles = new Map<string, FileFold>();
+    let mainMtime = 0;
+    for (const filePath of [transcriptPath, ...agentPaths]) {
+      const priorFold = prior?.files.get(filePath);
+      const read = await readAppendedEntries(filePath, priorFold?.cursor);
+      if (read.kind === "failed") return read;
+      if (read.kind === "absent") {
+        // The file has no bytes yet (fresh main) or vanished (removed agent
+        // sidechain). Carry a prior fold forward; otherwise it contributes
+        // nothing. The main transcript's absence leaves mainMtime 0, so the next
+        // render's mtime gate re-attempts rather than caching an empty read.
+        if (priorFold) newFiles.set(filePath, priorFold);
+        continue;
+      }
+      const { entries, cursor, reset } = read.value;
+      newFiles.set(filePath, await foldFile(priorFold, reset, entries, cursor));
+      if (filePath === transcriptPath) mainMtime = cursor.mtimeMs;
+    }
+    return ok({ files: newFiles, ...mergeFolds(newFiles), mainMtime });
   }
 
   private ensureSeeded(day: string): Promise<void> {

package/src/daemon/process-fingerprint.ts

@@ -0,0 +1,135 @@
+import { launchSync, type LaunchOpts, type LaunchResult } from "../proc/launch";
+
+// ─── Process start-time fingerprint ──────────────────────────────────────────
+//
+// [FRAMING:representation] A bare pid is an under-constrained identity: the
+// kernel recycles pids, so "a process with pid 989 exists" does NOT prove "989
+// is the same process that wrote this lease". A crashed daemon whose pid the OS
+// later hands to an unrelated long-lived process reads `alive` on every
+// subsequent start, so no daemon ever comes up (brandon-daemon-lifecycle-2b3.4
+// RESIDUAL 1 — the inverse of the socket-theft storm). The kernel ALSO stamps
+// each process with a start-time it never rewinds within that pid's life;
+// (pid, start-time) is the pair that actually IS a process identity, so a
+// recycled pid is provably a DIFFERENT process (different start-time).
+//
+// [LAW:one-source-of-truth] The authority is the kernel's process identity, not
+// a bare pid. `ps -o lstart=` exposes the start-time on every Unix we ship to
+// (darwin + linux). The reported token is treated as OPAQUE — compared by string
+// equality, never parsed — so there is no date-format representation to drift
+// [FRAMING:representation]: a producer/consumer parse mismatch is unrepresentable
+// when neither side parses. That opaque-equality invariant holds ONLY if the
+// GENERATOR is deterministic. `ps -o lstart=` is strftime-formatted (locale) via
+// `localtime()` (timezone), so the SAME process renders different tokens across a
+// locale change OR a timezone change (TZ env, DST, tzdata update). We pin BOTH on
+// the `ps` subprocess — `LC_ALL=C` (dominates any ambient LC_TIME/LC_ALL) and
+// `TZ=UTC` — so the token is a locale- and timezone-invariant UTC rendering of
+// the start instant, and equality is sound.
+
+// A read of a pid's kernel start-time. Only TWO outcomes, because nothing
+// derivable from a `ps` exit code can SOUNDLY prove a process is dead — a
+// non-zero exit means "no start-time to report", which conflates a genuinely
+// absent pid with an access failure (hardened `/proc`/`hidepid`, a
+// permission-denied read of a live process). A `gone` state produced from that
+// would be an over-claim ([LAW:types-are-the-program]) that could false-dead a
+// live owner and reclaim its socket. So:
+//   start       — the pid is live and this is its start-time token (the ONLY
+//                 thing `ps` can assert soundly: it printed a row).
+//   unavailable — `ps` reported no start-time (absent OR unreadable OR errored).
+//                 Callers defer to kill(pid,0), the sound liveness test, which
+//                 correctly reclaims a truly-dead pid and spares a live one.
+// The fingerprint's unique contribution is the `start`+mismatch case (a recycled
+// pid whose live start-time differs from the lease); everything else falls back
+// to kill, no worse than before the fingerprint existed.
+export type StartTimeRead =
+  | { kind: "start"; token: string }
+  | { kind: "unavailable"; detail: string };
+
+// The subprocess boundary, injected so the parse/branch logic is exercised by
+// input enumeration with a fake launcher while the real path runs the real `ps`.
+export type Launcher = (opts: LaunchOpts) => LaunchResult;
+
+// [LAW:effects-at-boundaries][LAW:single-enforcer] The sole effect (spawning
+// `ps`) goes through the one subprocess enforcer, `launchSync`. The ONLY sound
+// signal `ps` gives is a printed start-time row (a live pid we could read);
+// [LAW:no-silent-failure] every other outcome — absent pid, access failure,
+// spawn-error, timeout — is `unavailable`, deferring the alive/dead call to
+// kill(pid,0) rather than risk declaring a live owner dead from a `ps` exit
+// code that cannot distinguish "gone" from "cannot read".
+export function readStartTime(
+  pid: number,
+  launch: Launcher = launchSync,
+): StartTimeRead {
+  const res = launch({
+    bin: "ps",
+    args: ["-o", "lstart=", "-p", String(pid)],
+    category: "process-fingerprint",
+    timeoutMs: 2000,
+    // [FRAMING:representation] Pin BOTH locale and timezone so the token is
+    // deterministic across daemons — the writer and reader must render the same
+    // process identically for opaque string equality to be sound. LC_ALL=C fixes
+    // the strftime format; TZ=UTC fixes localtime(), so DST / TZ / tzdata changes
+    // can't make one live process render two different start-time strings.
+    env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+  });
+  if (res.ok) {
+    const token = res.stdout.trim();
+    if (token.length > 0) return { kind: "start", token };
+    // Exit 0 with empty output is anomalous (a live pid always lists) — don't
+    // mint an empty-string fingerprint; defer to kill.
+    return { kind: "unavailable", detail: "ps produced no start-time" };
+  }
+  const detail =
+    res.reason === "spawn-error"
+      ? (res.error ?? "ps spawn failed")
+      : `ps ${res.reason} (exit ${res.exitCode})`;
+  return { kind: "unavailable", detail };
+}
+
+export interface LivenessDeps {
+  readStartTime: (pid: number) => StartTimeRead;
+  pidAlive: (pid: number) => boolean;
+}
+
+// [LAW:dataflow-not-control-flow] The liveness verdict is a pure fold over the
+// start-time read + the lease's recorded token. Full input space:
+//   read=start + token matches lease   → true  (same process still alive)
+//   read=start + token differs         → false (a DIFFERENT process holds the
+//                                        pid — a recycle, or a restarted daemon)
+//   read=unavailable                   → kill(pid,0) fallback (the sound
+//                                        alive/dead test: a truly-dead pid →
+//                                        false → reclaim; a live pid ps couldn't
+//                                        read → true → spared)
+//   lease token = null (unfingerprinted at write, e.g. a host without `ps`) →
+//                                        kill(pid,0) fallback for the same reason
+//
+// [LAW:no-silent-failure] Only the `start`+mismatch case comes from the
+// fingerprint; every ambiguous `ps` outcome defers to kill, so the DANGEROUS
+// direction (declaring a live daemon dead → stealing its socket, the storm this
+// epic fights) never happens merely because `ps` could not answer. The only
+// thing forfeited when `ps` cannot answer is detecting a recycled pid.
+export function sameLiveProcess(
+  pid: number,
+  leaseToken: string | null,
+  deps: LivenessDeps,
+): boolean {
+  if (leaseToken === null) return deps.pidAlive(pid);
+  const read = deps.readStartTime(pid);
+  switch (read.kind) {
+    case "start":
+      return read.token === leaseToken;
+    case "unavailable":
+      return deps.pidAlive(pid);
+  }
+}
+
+// Read THIS process's own start-time to stamp into its lease. `unavailable`
+// (no `ps`) collapses to `null` — the lease records "unfingerprinted", and every
+// reader of it falls back to kill(pid,0) via sameLiveProcess. A dead result is
+// impossible for our own live pid; if it somehow occurs we also record null.
+export function readOwnStartTime(
+  pid: number,
+  read: (pid: number) => StartTimeRead = readStartTime,
+): string | null {
+  const r = read(pid);
+  return r.kind === "start" ? r.token : null;
+}

package/src/daemon/server.ts

@@ -22,6 +22,11 @@ import {
   readSocketIdentity,
   type SocketIdentity,
 } from "./socket-ownership";
+import {
+  readStartTime,
+  readOwnStartTime,
+  sameLiveProcess,
+} from "./process-fingerprint";
 import { dlog, closeLog } from "./log";
 import {
   PROTOCOL_VERSION,
@@ -127,8 +132,16 @@ const BIN_CHECK_INTERVAL_MS = 60 * 1000;
 // connection. Any uncaught error exits non-zero; the next client obtains a
 // fresh daemon via obtainDaemonKick() (fire-and-forget caller) or
 // obtainDaemon() (caller waits for readiness) in src/daemon/acquire.ts.
+// [LAW:one-source-of-truth] Our own kernel start-time, read once at startup and
+// stamped into our lease so a future daemon's arbitration can prove whether our
+// pid still names THIS process or a recycled ghost (process-fingerprint.ts).
+// null when this host cannot fingerprint (no `ps`) — readers then fall back to
+// kill(pid,0), no worse than before the fingerprint existed.
+let myStartTime: string | null = null;
+
 export function runDaemon(): void {
   fs.mkdirSync(daemonDir(), { recursive: true });
+  myStartTime = readOwnStartTime(process.pid);
   // [LAW:single-enforcer] Verify the socket parent is uid==me + mode 0700 +
   // not a symlink before we bind. Without this check, a same-host attacker
   // could pre-create the predictable `/tmp/cc-candybar-<uid>` directory and
@@ -236,7 +249,11 @@ function handleAddressInUse(server: net.Server, sockPath: string): void {
   // [LAW:one-source-of-truth] Derive the lease from the SAME sockPath threaded
   // through unlink + rebind below, not the re-derived global — one identity
   // source for the whole arbitration.
-  const decision = arbitrateSocket(readLease(leasePathFor(sockPath)), pidAlive);
+  const decision = arbitrateSocket(
+    readLease(leasePathFor(sockPath)),
+    (pid, startTime) =>
+      sameLiveProcess(pid, startTime, { readStartTime, pidAlive }),
+  );
   if (decision.kind === "attach-and-exit") {
     dlog("info", `EADDRINUSE: ${decision.reason} — exiting`);
     process.exit(0);
@@ -280,20 +297,19 @@ function onListening(sockPath: string): void {
   // the FD yields no path-comparable identity. stat(path), taken as close to the
   // bind as possible, is the only path-comparable truth available.
   //
-  // [FRAMING:representation] Be honest about the ONE window this capture cannot
-  // close. It catches an absent/unreadable path (below): we could not form a
-  // fingerprint, so we have no proof of ownership and exit toward the SAFE
-  // direction (a false-displaced daemon just lets whoever holds the path serve —
-  // no orphan) WITHOUT writing a lease that would stomp a thief's. It does NOT
-  // catch a path that is present but already holds a THIEF's socket — if a second
-  // daemon completed its full EADDRINUSE → read-lease → unlink → rebind cycle in
-  // the single event-loop tick between bind() and this 'listening' callback, we
-  // fingerprint the thief's identity and the self-check reads `owned` forever
-  // (the orphan this module exists to kill). That race is irreducible at this
-  // layer (no race-free handle on our own socket's path-identity exists) and
-  // vanishingly narrow; fully closing it needs the lock-based liveness the epic
-  // deferred (a flock/start-time fingerprint) — the same residual sibling .1's
-  // arbitrateSocket documents for its false-alive direction.
+  // [FRAMING:representation] This inode capture still cannot close the capture
+  // race on its own: if a second daemon completed its full EADDRINUSE →
+  // read-lease → unlink → rebind cycle in the single event-loop tick between
+  // bind() and this 'listening' callback, we stat the path and capture the
+  // THIEF's inode as "ours". No race-free handle on our own socket's path
+  // identity exists (an AF_UNIX listener's fstat is a different namespace's
+  // inode), so the captured inode cannot be made trustworthy. But that is no
+  // longer the immortal orphan it was (brandon-daemon-lifecycle-2b3.4 RESIDUAL
+  // 2): the ownership self-check now ALSO requires the lease to still name us,
+  // and a real thief writes its own pid into the lease — so a displaced daemon
+  // drains within a bounded number of intervals instead of reading `owned`
+  // forever (see checkOwnership). The absent/unreadable case below still exits
+  // toward the SAFE direction without writing a lease that would stomp a thief's.
   const boundRead = readSocketIdentity(sockPath);
   if (boundRead.kind !== "present") {
     dlog(
@@ -330,15 +346,20 @@ function onListening(sockPath: string): void {
 // --- socket-ownership self-check ---
 //
 // [LAW:single-enforcer] The sole enforcer of "serving implies owning the socket
-// path over time" (brandon-daemon-lifecycle-2b3.2). Periodically re-stats the
-// path; if its kernel identity no longer matches what we bound, we were
-// displaced (its socket unlinked + rebound by a reclaimer) and drain through the
-// SAME shutdown funnel as signals, the RSS backstop, and the watchdog — no
-// parallel exit path.
+// path over time" (brandon-daemon-lifecycle-2b3.2). Each interval it re-reads
+// BOTH representations a displacer can touch — the path's kernel identity (still
+// the inode we bound?) and the lease (still names our pid?) — and drains through
+// the SAME shutdown funnel as signals, the RSS backstop, and the watchdog on
+// either mismatch. The lease arm closes the capture race (RESIDUAL 2): a thief
+// that stole our socket inside the bind→listening tick, which the inode arm
+// cannot see because we captured the thief's inode, is caught the moment the
+// thief writes its own pid into the lease. No parallel exit path.
 function armOwnershipWatch(sockPath: string, bound: SocketIdentity): void {
   makeOwnershipWatch({
     bound,
+    myPid: process.pid,
     readIdentity: () => readSocketIdentity(sockPath),
+    readLease: () => readLease(leasePathFor(sockPath)),
     shutdown: (code) => shutdown(code),
     log: dlog,
   }).arm();
@@ -418,7 +439,7 @@ function writeLeaseFile(sockPath: string): void {
     pid: process.pid,
     version: PROTOCOL_VERSION,
     binPath: process.argv[1],
-    startedAt: new Date().toISOString(),
+    startTime: myStartTime,
   });
   if (reason !== null) dlog("warn", `lease write failed: ${reason}`);
 }