@event4u/agent-config 9.26.0 → 9.28.0

package/src/scripts/_lib/session_register.ts

@@ -0,0 +1,361 @@
+/**
+ * Shared per-session register — so a starting session can see that another
+ * session is already live on this repo, on which branch, and on which roadmap.
+ *
+ * ## Where it lives, and why that needs no new machinery
+ *
+ * `<git-common-dir>/agent-sessions/<session_id>.json`. The common git directory
+ * resolves to the **same** directory from every worktree of a repo, so the
+ * register is shared by construction: no new directory to create, no sync step,
+ * no generator, and never tracked by git. Resolution is
+ * `_lib/git_common_dir.ts` — reused, not re-implemented, because a repo with two
+ * different answers to "where is the common dir" is a bug waiting for a
+ * symlinked parent.
+ *
+ * Runtime state under `agents/runtime/state/` cannot serve this purpose:
+ * concerns run with `CWD = envelope.workspace_root`, so in a worktree that path
+ * is the worktree's own. Measured 2026-08-07 — the main checkout's state
+ * directory was populated and a fresh worktree's did not exist at all. Two
+ * sessions in two worktrees share nothing there.
+ *
+ * ## One file per session — one writer each
+ *
+ * Each session owns exactly one file and is its only writer, so there is no
+ * concurrent-write case to solve: atomicity comes from write-temp + rename
+ * (`_lib/fs_atomic.ts`), the file never grows, compaction does not exist, the
+ * reader does a `readdir` plus N small reads, and cleanup is an `unlink` of
+ * expired files during the `session_start` read.
+ *
+ * The append-only JSONL alternative buys concurrency safety this layout does not
+ * need and pays for it with unbounded growth (one record per turn per session
+ * once heartbeating), a rotation problem (rotating under live appenders loses
+ * heartbeats to the unlinked inode — the classic logrotate defect), and
+ * fold-the-whole-file reads.
+ *
+ * ## Liveness is a heartbeat inside the record — never file mtime
+ *
+ * `last_seen` is rewritten every turn by a hook, and expiry compares that field.
+ * File mtime is explicitly ruled out: `worktree_cleanup_check.ts:65-68` records
+ * the failure — plain `git status` refreshes the on-disk index and bumps the very
+ * mtime being read as liveness, which moved 10 worktrees from safe to live
+ * between two consecutive runs. A field only this concern writes has no such
+ * coupling.
+ *
+ * ## Two accepted limits — declared, not hidden
+ *
+ * 1. **Idle is indistinguishable from crashed.** A session left open over lunch
+ *    stops heartbeating, expires, and releases its claim although the user
+ *    returns. No hook-based heartbeat can tell that apart from a crash. This is
+ *    accepted, and it belongs in user-facing documentation: walking away for
+ *    longer than the TTL means another session may claim your branch.
+ * 2. **This is advisory, not a mutex.** Two sessions can claim in the same
+ *    millisecond. Nothing here provides exclusion, and no later feature may be
+ *    built on it as if it did.
+ *
+ * ## Failure is always open
+ *
+ * Every function here swallows its errors and degrades to "no register": a
+ * session that cannot read or write it still starts, and behaves exactly as
+ * sessions did before this existed.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { write_atomic } from './fs_atomic.js';
+import { git_common_dir } from './git_common_dir.js';
+
+/** Directory name under the common git dir. Never tracked; git ignores unknown
+ *  directories inside `.git` by construction. */
+export const REGISTER_DIRNAME = 'agent-sessions';
+
+/**
+ * Per-host TTL in seconds — how long a record may go without a heartbeat before
+ * a reader treats the session as gone.
+ *
+ * **Derived from data for exactly one host, and honest about the rest.** The
+ * chat-history corpus in this repo holds 71 records across 5 sessions over 24.5
+ * hours, and every one of them is `claude`; 77 % of the gaps come from a single
+ * session. The per-host split the design asked for is **not measurable** from
+ * that, so no interpolated values are shipped for hosts nobody observed. Full
+ * measurement record: `agents/evidence/analysis/parallel-session-register-phase1.md`.
+ *
+ * `claude` is taken from the **raw, unfiltered** p99 (13 705 s) and the raw
+ * user→user max (14 199 s), rounded up to the next hour. Deliberately *not* the
+ * idle-filtered p95: filtering gaps > 30 min characterises turn cadence
+ * correctly and is wrong as an expiry basis, because those gaps occur **inside**
+ * live sessions — 35 % of user→user gaps exceed 30 minutes while the session is
+ * demonstrably still working. A TTL from the filtered p95 would expire a live
+ * claim on roughly a third of turns, which is the collision this register exists
+ * to prevent, re-created by its own mitigation.
+ */
+export const TTL_MEASURED_SECONDS: Readonly<Record<string, number>> = Object.freeze({
+    claude: 14_400, // 4 h — raw p99 13 705 s / raw user→user max 14 199 s, rounded up
+});
+
+/**
+ * TTL for a host with **no** measurements: `3 ×` the one measured p99.
+ *
+ * The name says `MEASURED` above and `DEFAULT` here on purpose (council
+ * 2026-08-07, both members): a map holding one real entry plus a fallback is
+ * honest only if it is *named* as that, rather than presented as a populated
+ * per-host table. Six empty slots would be speculation wearing a data structure.
+ *
+ * The council also moved this number down from a proposed 24 h. The argument
+ * against 24 h: the evidence for a wide spread is that the same host's raw p99
+ * in another project corpus is 53 903 s, i.e. a 4× range — which does not
+ * justify a 6× extrapolation, and a full day makes the register useless on an
+ * unmeasured host, since a crashed session blocks a roadmap claim until
+ * tomorrow. 12 h stays comfortably above every observed live-session gap while
+ * keeping the claim recoverable within a working day.
+ */
+export const TTL_DEFAULT_SECONDS = 43_200; // 12 h
+
+/**
+ * Resolve the TTL for a record, from **the record's own platform** — never the
+ * reader's. Session B on one host reading session A's record must apply A's
+ * cadence, because the TTL describes how often A heartbeats.
+ */
+export function ttl_seconds_for(platform: string | null | undefined): number {
+    const key = String(platform ?? '').trim().toLowerCase();
+    return TTL_MEASURED_SECONDS[key] ?? TTL_DEFAULT_SECONDS;
+}
+
+/** True when this platform's TTL is a measured value rather than the fallback. */
+export function ttl_is_measured(platform: string | null | undefined): boolean {
+    const key = String(platform ?? '').trim().toLowerCase();
+    return Object.prototype.hasOwnProperty.call(TTL_MEASURED_SECONDS, key);
+}
+
+/**
+ * Platforms whose `stop` slot means **the task really ended**, so the register
+ * entry is deleted there instead of merely refreshed.
+ *
+ * The general rule is the opposite and stays the default: `stop` is a *second
+ * heartbeat carrier*, never a deregistration trigger, because on Claude Code the
+ * native `Stop` fires after **every assistant reply** — deregistering there
+ * would kill a live session's own record after its first reply.
+ *
+ * Cline is the one host where that reading is wrong. Its `stop` is mapped from
+ * `TaskCancel` (`hook_manifest.yaml:473`) and is typed `per-event` rather than
+ * `per-turn` (`_lib/obligation_frequency.ts:269-271`), while its `session_end`
+ * is mapped from `TaskComplete` (`:472`). A **cancelled** Cline task therefore
+ * reaches neither deregistration path and leaks its claim until the TTL — and
+ * cancel-and-restart is a routine Cline workflow, not an edge case.
+ *
+ * **This is an explicit allow-list, not a computed condition** (council
+ * 2026-08-07, both members). Deriving it from `slot_frequency(...) ===
+ * 'per-event'` would mean a future platform silently acquires deregistration
+ * behaviour the moment someone types it that way, in a code path where the
+ * failure mode is "a live session deleted its own claim". A human adds a line
+ * here, deliberately, or the platform keeps the safe default.
+ *
+ * The safety model is unchanged either way: TTL remains the correctness basis on
+ * every platform including Cline. This only frees the claim sooner.
+ */
+export const DEREGISTER_ON_STOP_PLATFORMS: ReadonlySet<string> = new Set(['cline']);
+
+/** True when `stop` on this platform means the task ended, not "a reply landed". */
+export function stop_means_session_end(platform: string | null | undefined): boolean {
+    return DEREGISTER_ON_STOP_PLATFORMS.has(String(platform ?? '').trim().toLowerCase());
+}
+
+/**
+ * Platforms where a per-turn heartbeat actually fires today.
+ *
+ * Deliberately **not** derived from the frequency lattice. That instrument
+ * models *slot presence*, and two hosts have a slot that never fires:
+ *
+ * - `cursor` — `user_prompt_submit` and `stop` are **IDE-only**; the CLI fires
+ *   only shell-execution hooks (`hook_manifest.yaml:365-366`,
+ *   `chat-history-platform-hooks.md:214`). The lattice has no IDE/CLI dimension,
+ *   so it reports cursor covered.
+ * - `cowork` — slots are structurally wired but lifecycle events do not fire
+ *   (`hook_manifest.yaml:346-351`).
+ * - `copilot` — no hook surface at all (`hook_manifest.yaml:428-429`), excluded
+ *   from the join by declaration.
+ *
+ * A session on an excluded host still *registers* if a `session_start` reaches
+ * it, and simply stops being visible after its TTL. It is never reported as
+ * covered.
+ */
+export const HEARTBEAT_REACHABLE_PLATFORMS: ReadonlySet<string> = new Set([
+    'claude',
+    'augment', // post-reply `stop` only — sufficient for a liveness stamp
+    'cline', // pre-reply `user_prompt_submit` only
+    'windsurf',
+    'gemini',
+]);
+
+/** One live session, as seen by every other session on the repo. */
+export interface SessionRecord {
+    /** Host-provided session id; also the filename stem. */
+    session_id: string;
+    /** Host platform — decides which TTL applies to THIS record. */
+    platform: string;
+    /** Absolute path of the worktree this session is working in. */
+    worktree: string;
+    /** Branch at the last heartbeat. Re-read every beat; sessions check out. */
+    branch: string | null;
+    /** Roadmap slug this session claims, or null when it has not picked one. */
+    roadmap_slug: string | null;
+    /** ISO-8601 UTC, set once at registration. */
+    started_at: string;
+    /** ISO-8601 UTC, rewritten every heartbeat. The liveness signal. */
+    last_seen: string;
+}
+
+/**
+ * Filename-safe stem for a session id. Path separators and `..` collapse to `_`
+ * so a hostile or merely odd id cannot escape the register directory — the same
+ * traversal guard the dispatcher applies to its feedback directory.
+ *
+ * The fallback fires when the sanitised stem carries **no alphanumeric
+ * character**, not merely when it is empty. `'///'` sanitises to `'___'`, which
+ * is a legal filename and a useless one: it distinguishes nothing, so two
+ * different odd session ids would silently share a record. Requiring one
+ * alphanumeric makes the degenerate case land on the explicit marker instead.
+ */
+export function safe_stem(session_id: string): string {
+    const collapsed = String(session_id ?? '')
+        .replace(/\.\./g, '_')
+        .replace(/[/\\]/g, '_')
+        .replace(/[^A-Za-z0-9._-]/g, '_')
+        .slice(0, 128);
+    return /[A-Za-z0-9]/.test(collapsed) ? collapsed : 'unknown-session';
+}
+
+/**
+ * The register directory for a workspace, or `null` when there is no git common
+ * dir to anchor it to. Does **not** create the directory — writers do.
+ */
+export function register_dir(workspace_root: string): string | null {
+    const common = git_common_dir(workspace_root);
+    return common === null ? null : path.join(common, REGISTER_DIRNAME);
+}
+
+/** ISO-8601 UTC at seconds precision, matching the chat-history stamp format. */
+export function iso_now(now: Date = new Date()): string {
+    return now.toISOString().replace(/\.\d{3}Z$/, '+00:00');
+}
+
+/** Parse an ISO stamp to epoch ms; `null` when unparseable. */
+function epoch_ms(stamp: string | null | undefined): number | null {
+    if (typeof stamp !== 'string' || stamp.length === 0) return null;
+    const ms = Date.parse(stamp);
+    return Number.isFinite(ms) ? ms : null;
+}
+
+/** True when `rec` has not been heard from within its own platform's TTL. */
+export function is_expired(rec: SessionRecord, now: Date = new Date()): boolean {
+    const seen = epoch_ms(rec.last_seen);
+    if (seen === null) return true; // unreadable stamp → not evidence of life
+    const age_s = (now.getTime() - seen) / 1000;
+    return age_s > ttl_seconds_for(rec.platform);
+}
+
+function is_record(v: unknown): v is SessionRecord {
+    if (typeof v !== 'object' || v === null) return false;
+    const o = v as Record<string, unknown>;
+    return typeof o['session_id'] === 'string' && typeof o['last_seen'] === 'string';
+}
+
+/**
+ * Write (or overwrite) this session's own record. Returns `true` on success.
+ * Never throws — a session that cannot write the register still starts.
+ */
+export function write_record(dir: string, rec: SessionRecord): boolean {
+    try {
+        const target = path.join(dir, `${safe_stem(rec.session_id)}.json`);
+        write_atomic(target, `${JSON.stringify(rec, null, 2)}\n`);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** Read this session's own record back, or `null` when it is absent/unreadable. */
+export function read_own_record(dir: string, session_id: string): SessionRecord | null {
+    try {
+        const target = path.join(dir, `${safe_stem(session_id)}.json`);
+        const parsed: unknown = JSON.parse(fs.readFileSync(target, 'utf-8'));
+        return is_record(parsed) ? parsed : null;
+    } catch {
+        return null;
+    }
+}
+
+/** Remove this session's own record. Best-effort; a failure is not an error. */
+export function delete_record(dir: string, session_id: string): boolean {
+    try {
+        fs.unlinkSync(path.join(dir, `${safe_stem(session_id)}.json`));
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export interface ReadLiveOptions {
+    /** Unlink expired records as they are encountered. Default `false`. */
+    prune?: boolean;
+    /** Clock injection for tests. */
+    now?: Date;
+}
+
+/**
+ * Every live record in the register, optionally pruning expired ones as it goes.
+ *
+ * Expiry is evaluated per record against **its own** platform's TTL. A file that
+ * does not parse as a record is treated as expired: it carries no evidence of
+ * life, and leaving it would make the register grow without bound on a host that
+ * writes garbage.
+ *
+ * Returns `[]` on any failure — including "the directory does not exist", which
+ * is the normal state before the first session registers.
+ */
+export function read_live_records(dir: string, options: ReadLiveOptions = {}): SessionRecord[] {
+    const now = options.now ?? new Date();
+    const prune = options.prune === true;
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
+    } catch {
+        return [];
+    }
+    const live: SessionRecord[] = [];
+    for (const name of names) {
+        const full = path.join(dir, name);
+        let rec: SessionRecord | null = null;
+        try {
+            const parsed: unknown = JSON.parse(fs.readFileSync(full, 'utf-8'));
+            rec = is_record(parsed) ? parsed : null;
+        } catch {
+            rec = null;
+        }
+        if (rec === null || is_expired(rec, now)) {
+            if (prune) {
+                try {
+                    fs.unlinkSync(full);
+                } catch {
+                    /* another session may have pruned it first — fine */
+                }
+            }
+            continue;
+        }
+        live.push(rec);
+    }
+    return live;
+}
+
+/**
+ * Live records belonging to sessions other than `session_id` — the set a
+ * starting session actually cares about.
+ */
+export function foreign_live_records(
+    dir: string,
+    session_id: string,
+    options: ReadLiveOptions = {},
+): SessionRecord[] {
+    const own = safe_stem(session_id);
+    return read_live_records(dir, options).filter((r) => safe_stem(r.session_id) !== own);
+}

package/src/scripts/_lib/transcript_entry.ts

@@ -0,0 +1,80 @@
+/**
+ * One reader for a transcript entry's text — the shape half, shared.
+ *
+ * WHY THIS EXISTS, measured rather than anticipated. A Claude Code transcript
+ * carries a user entry's `message.content` in TWO shapes: a bare string, and an
+ * array of content blocks. `conformance_scan` handled both; a second reader
+ * written against the same field handled only the string, and the store says why
+ * that is fatal rather than cosmetic:
+ *
+ *   user entries in one 30-session store:  1 440 string · 23 907 array
+ *   injected skill bodies among them:      0 via string · 41 via array
+ *
+ * So the narrower reader saw **none** of them, and the failure was invisible:
+ * a detector whose loaded-set is empty returns no findings, which is
+ * indistinguishable from compliance. `grep` over the raw JSONL finds the marker
+ * either way — reading raw text is not evidence about the parse path, and that
+ * is the mistake this module removes the opportunity to repeat.
+ *
+ * Scope is deliberately just the shape, plus the sidechain exclusion. Semantic
+ * filters (a `<system-reminder>` is not a chat message, an injected body is not a
+ * user turn) stay with the caller that needs them: they differ per question, and
+ * folding them in here would make one module answer two.
+ */
+
+/** A parsed transcript line. */
+export type TranscriptEntry = Record<string, unknown>;
+
+function _isObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * A subagent's own turns. Excluded by every reader in this tree: a sidechain turn
+ * did not happen in the main thread, so counting it lets a skill loaded in one
+ * context be paired with an act taken in another.
+ */
+export function isSidechain(entry: TranscriptEntry): boolean {
+    return entry['isSidechain'] === true;
+}
+
+/**
+ * Flatten `message.content` to text, whichever shape it arrived in.
+ *
+ * Returns `''` when there is no text (a tool-result-only entry, an unparseable
+ * shape) — never `null`, so a caller cannot forget the second branch.
+ */
+export function entryText(entry: TranscriptEntry): string {
+    const msg = entry['message'];
+    const content = _isObject(msg) ? msg['content'] : undefined;
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (!Array.isArray(content)) {
+        return '';
+    }
+    return content
+        .filter((b) => _isObject(b) && b['type'] === 'text')
+        .map((b) => String((b as Record<string, unknown>)['text'] ?? ''))
+        .join('\n');
+}
+
+/** Tool calls in an entry, flattened to name + input. Both shapes are arrays. */
+export function toolUses(entry: TranscriptEntry): Array<{ name: string; input: Record<string, unknown> }> {
+    const msg = entry['message'];
+    const content = _isObject(msg) ? msg['content'] : undefined;
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    const out: Array<{ name: string; input: Record<string, unknown> }> = [];
+    for (const part of content) {
+        if (!_isObject(part) || part['type'] !== 'tool_use') {
+            continue;
+        }
+        out.push({
+            name: typeof part['name'] === 'string' ? part['name'] : '',
+            input: _isObject(part['input']) ? part['input'] : {},
+        });
+    }
+    return out;
+}