@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/worktree/held.js

@@ -1,41 +1,13 @@
-/**
- * Surfacing the held set of agent worktrees (PHNX-3520).
- *
- * The nightly `worktree-sweep` routine (PHNX-3503, in phnx-labs/.agents)
- * reclaims merged worktrees and correctly HOLDS anything dirty, unmerged, or
- * undeterminable. That fail-closed bias is right for a destructive job, but it
- * left the held set a silent, growing residue that nothing ever resolves — the
- * sweep prints only a `held=<n>` count. Measured 2026-08-30 the held set is
- * consistently LARGER than the reclaimed set (~800 worktrees fleet-wide), and
- * one bucket inside it — worktrees whose branch carries commits on no remote —
- * is real stranded work (the PHNX-2951 / PHNX-2732 failure class: an agent
- * finished, its commits never reached a remote, and nothing surfaces it).
- *
- * This module is the READ-ONLY surfacing half. It does not remove anything —
- * the destructive reclaim was deliberately reverted from the CLI (3a8d1eb04 →
- * 7e48361f5) and lives as a shell routine. Here we only classify each held
- * worktree into a bucket so the `unmerged-commits` set can be surfaced and,
- * with `pushStrandedBranch`, recovered by publishing the branch — never by
- * deleting anything. Everything fails CLOSED: an unreadable status or an
- * undeterminable merge state is a bucket of its own, never read as "fine".
- */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 const execFileAsync = promisify(execFile);
-/** Worktree dir names are slugs; anything else is refused rather than shelled. */
 const WORKTREE_NAME_RE = /^[A-Za-z0-9._-]+$/;
 async function git(cwd, args) {
     const { stdout } = await execFileAsync('git', args, { cwd, maxBuffer: 8 * 1024 * 1024 });
     return stdout.trim();
 }
-/**
- * Resolve the default branch ref to compare against: `origin/HEAD` when set,
- * else whichever of `origin/main` / `origin/master` exists. Returns null when
- * none resolve, which makes every worktree `merge-state-unknown` rather than
- * silently comparing against nothing.
- */
 export async function resolveDefaultRef(repoRoot) {
     try {
         const head = await git(repoRoot, ['symbolic-ref', '--short', '-q', 'refs/remotes/origin/HEAD']);
@@ -43,7 +15,6 @@ export async function resolveDefaultRef(repoRoot) {
             return head;
     }
     catch {
-        /* fall through to the probes below */
     }
     for (const ref of ['origin/main', 'origin/master']) {
         try {
@@ -51,21 +22,10 @@ export async function resolveDefaultRef(repoRoot) {
             return ref;
         }
         catch {
-            /* try the next candidate */
         }
     }
     return null;
 }
-/**
- * Count commits with no patch-equivalent upstream. Returns -1 when the answer
- * cannot be established, which the classifier treats as `merge-state-unknown`.
- *
- * Patch-id (`git cherry`), NOT ancestry, is load-bearing: this fleet
- * rebase-merges, so a landed branch's SHAs are rewritten and
- * `merge-base --is-ancestor` reports *not merged* for work that fully landed.
- * It also subsumes the unpushed check — an unpushed commit has no upstream
- * equivalent, so it surfaces as unmerged rather than needing a separate probe.
- */
 async function countUnmergedCommits(worktreePath, defaultRef) {
     if (!defaultRef)
         return -1;
@@ -102,43 +62,21 @@ function parseWorktreePorcelain(out) {
         entries.push(cur);
     return entries;
 }
-/**
- * True when `child` is `parent` or sits beneath it, compared on path
- * boundaries. A raw `startsWith` makes `.../fix-1103` look like it is inside
- * `.../fix-110`, so the primary checkout would be mistaken for a neighbour.
- */
 export function isInside(child, parent) {
     const rel = path.relative(parent, child);
     return rel === '' || (rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel));
 }
-/**
- * Decide which bucket a worktree falls into, or null when it is neither stranded
- * nor dirty nor broken (clean and fully upstream — nothing to surface). Pure.
- *
- * Precedence is chosen for SURFACING, not for the sweep's deletion decision:
- * the work-loss signal wins. A determinable `unmerged-commits` is reported as
- * exactly that even when the tree is also dirty, because the recoverable work
- * is the priority — an operator seeing `uncommitted-changes` would push nothing.
- * Only when the merge state itself is unreadable do we fall to `undeterminable`,
- * because then we genuinely cannot tell whether work is stranded.
- */
 export function classifyHeld(facts) {
-    // Fail closed first: if we could not establish the merge state, we cannot
-    // claim the work is safe, so it is undeterminable — never silently "clean".
     if (facts.unmergedCommits < 0)
         return { bucket: 'undeterminable', reason: 'merge-state-unknown' };
-    // The bucket that matters: commits on no upstream. Reported even over a dirty
-    // tree, since the branch carries recoverable work regardless of the worktree.
     if (facts.unmergedCommits > 0)
         return { bucket: 'unmerged-commits', reason: 'unmerged-commits' };
-    // Merge state is clean; now an unreadable status is its own broken-checkout case.
     if (facts.dirtyFiles < 0)
         return { bucket: 'undeterminable', reason: 'status-unreadable' };
     if (facts.dirtyFiles > 0)
         return { bucket: 'uncommitted-changes', reason: 'uncommitted-changes' };
     return null;
 }
-/** Recursively total the byte size of a directory tree; -1 if it can't be read. */
 async function dirSize(dir) {
     let total = 0;
     let entries;
@@ -162,17 +100,10 @@ async function dirSize(dir) {
             }
         }
         catch {
-            /* a file that vanished mid-walk contributes nothing */
         }
     }
     return total;
 }
-/**
- * Classify every worktree registered under one repo and return only the held
- * ones. Read-only — no `git worktree remove`, no `branch -d`, no push. The
- * primary checkout (the first porcelain record, always the repo root) is never
- * a `.agents/worktrees` slug, so it is skipped implicitly.
- */
 export async function collectHeldWorktrees(repoRoot) {
     let porcelain;
     try {
@@ -188,8 +119,6 @@ export async function collectHeldWorktrees(repoRoot) {
     const repoName = path.basename(repoRoot);
     const held = [];
     for (const e of entries) {
-        // Only the PR-bound agent worktrees the sweep governs — not the primary
-        // checkout and not any ad-hoc worktree elsewhere on disk.
         if (!isInside(e.path, wtContainer))
             continue;
         let dirtyFiles = -1;
@@ -239,11 +168,6 @@ export async function collectHeldWorktrees(repoRoot) {
     }
     return held;
 }
-/**
- * Discover repo roots that own a `.agents/worktrees` container beneath
- * `searchHome`. Mirrors the sweep's discovery: match directory SHAPE, prune the
- * heavy dirs so a large home stays fast. Read-only.
- */
 async function discoverWorktreeRepos(searchHome, maxDepth = 7) {
     const PRUNE = new Set([
         'node_modules', '.cache', '.npm', '.bun', 'Library', '.venv', 'dist', 'target', '.git',
@@ -265,7 +189,6 @@ async function discoverWorktreeRepos(searchHome, maxDepth = 7) {
             if (PRUNE.has(e.name))
                 continue;
             const p = path.join(dir, e.name);
-            // A `.agents/worktrees` dir marks its grandparent as a repo root.
             if (e.name === '.agents') {
                 try {
                     const st = await fs.stat(path.join(p, 'worktrees'));
@@ -273,9 +196,8 @@ async function discoverWorktreeRepos(searchHome, maxDepth = 7) {
                         repos.add(dir);
                 }
                 catch {
-                    /* no worktrees container here */
                 }
-                continue; // never descend into a .agents dir
+                continue;
             }
             await walk(p, depth + 1);
         }
@@ -283,7 +205,6 @@ async function discoverWorktreeRepos(searchHome, maxDepth = 7) {
     await walk(searchHome, 0);
     return [...repos].sort();
 }
-/** Discover + classify every held worktree beneath `searchHome`. Read-only. */
 export async function collectHeldWorktreesUnder(searchHome) {
     const repos = await discoverWorktreeRepos(searchHome);
     const all = [];
@@ -297,19 +218,12 @@ const EMPTY_BUCKETS = () => ({
     'uncommitted-changes': [],
     'undeterminable': [],
 });
-/** Group a flat held list into its three buckets. Pure. */
 export function summarizeHeld(held) {
     const buckets = EMPTY_BUCKETS();
     for (const w of held)
         buckets[w.bucket].push(w);
     return { total: held.length, buckets };
 }
-/**
- * Merge several devices' held sets into one fleet roll-up, stamping each entry
- * with its source device so the `unmerged-commits` bucket names where the
- * stranded work lives. Pure — the SSH fan-out that produces the input lives in
- * the command layer.
- */
 export function aggregateHeld(perDevice) {
     const buckets = EMPTY_BUCKETS();
     const devices = [];
@@ -322,28 +236,12 @@ export function aggregateHeld(perDevice) {
     }
     return { total, buckets, devices };
 }
-/**
- * The safe automatic action for the `unmerged-commits` bucket (ticket step 3):
- * PUBLISH the branch so the work becomes visible, never remove anything.
- *
- * Gated hard, fails closed:
- *  - only a worktree whose live classification is still `unmerged-commits`;
- *  - only when the branch does NOT already exist on `origin` — a branch that is
- *    already pushed (including one behind an open PR) needs nothing, and this
- *    also means we never force-update a remote ref;
- *  - a slug-shaped worktree name only, never shelled otherwise.
- *
- * `git push` sets no `--force`: it fast-forwards a new ref or fails loud. A
- * failure is returned, never swallowed.
- */
 export async function pushStrandedBranch(repoRoot, wt) {
     const base = { name: wt.name, branch: wt.branch, pushed: false, reason: '' };
     if (!WORKTREE_NAME_RE.test(wt.name))
         return { ...base, reason: 'unsafe worktree name' };
     if (!wt.branch)
         return { ...base, reason: 'detached HEAD — no branch to push' };
-    // Re-read the facts NOW: the collected snapshot may be stale, and pushing on
-    // a stale "unmerged" verdict is the one thing we must not get wrong.
     const defaultRef = await resolveDefaultRef(repoRoot);
     const unmerged = await countUnmergedCommits(wt.path, defaultRef);
     const fresh = classifyHeld({ branch: wt.branch, dirtyFiles: 0, unmergedCommits: unmerged });

package/dist/lib/wrap.d.ts

@@ -1,33 +1 @@
-/**
- * Terminal word-wrap — one shared helper for the whole CLI.
- *
- * Multi-line word wrapping is the gap the single-line helpers in
- * `session/width.ts` (`truncateToWidth`, `padToWidth`) do not fill. Anywhere that
- * renders variable-length text into a fixed-width terminal wraps through THIS,
- * never a per-field slice.
- *
- * Width is measured with `stringWidth` (from the canonical `session/width.ts`),
- * NOT `String.length`: the text this wraps is routinely ANSI-coloured (chalk /
- * marked-terminal output) and may carry OSC-8 hyperlinks, where `.length`
- * over-counts the invisible escape bytes. Words are split on whitespace, so a
- * wrap boundary always falls between escape sequences, never inside one.
- */
-/**
- * Hard-wrap `text` to `cols` visible columns.
- *
- * - Splits on existing newlines first (each paragraph wraps independently).
- * - Wraps on whitespace; a single word wider than the available width is emitted
- *   on its own line rather than split mid-word (and never mid-escape).
- * - Width is the visible display width via `stringWidth`, so ANSI colour and
- *   OSC-8 hyperlink escapes do not inflate the count.
- * - `hangingIndent` pads every line AFTER the first with that many spaces, so a
- *   labelled value ("Latest  <text>") keeps its continuation lines aligned under
- *   the value. The wrapping width is `cols - indent`.
- * - Floor: when `hangingIndent` is set, the width is floored at 8 so a
- *   pathologically large indent still makes forward progress. With no indent the
- *   floor is 1, so a legitimately small `cols` is respected, never overridden. A
- *   non-finite `cols` degrades to the floor rather than silently disabling wrap.
- *
- * Returns the wrapped lines (never mutates input). An empty string yields [''].
- */
 export declare function wrapToWidth(text: string, cols: number, hangingIndent?: number): string[];

package/dist/lib/wrap.js

@@ -1,36 +1,4 @@
-/**
- * Terminal word-wrap — one shared helper for the whole CLI.
- *
- * Multi-line word wrapping is the gap the single-line helpers in
- * `session/width.ts` (`truncateToWidth`, `padToWidth`) do not fill. Anywhere that
- * renders variable-length text into a fixed-width terminal wraps through THIS,
- * never a per-field slice.
- *
- * Width is measured with `stringWidth` (from the canonical `session/width.ts`),
- * NOT `String.length`: the text this wraps is routinely ANSI-coloured (chalk /
- * marked-terminal output) and may carry OSC-8 hyperlinks, where `.length`
- * over-counts the invisible escape bytes. Words are split on whitespace, so a
- * wrap boundary always falls between escape sequences, never inside one.
- */
 import { stringWidth } from './session/width.js';
-/**
- * Hard-wrap `text` to `cols` visible columns.
- *
- * - Splits on existing newlines first (each paragraph wraps independently).
- * - Wraps on whitespace; a single word wider than the available width is emitted
- *   on its own line rather than split mid-word (and never mid-escape).
- * - Width is the visible display width via `stringWidth`, so ANSI colour and
- *   OSC-8 hyperlink escapes do not inflate the count.
- * - `hangingIndent` pads every line AFTER the first with that many spaces, so a
- *   labelled value ("Latest  <text>") keeps its continuation lines aligned under
- *   the value. The wrapping width is `cols - indent`.
- * - Floor: when `hangingIndent` is set, the width is floored at 8 so a
- *   pathologically large indent still makes forward progress. With no indent the
- *   floor is 1, so a legitimately small `cols` is respected, never overridden. A
- *   non-finite `cols` degrades to the floor rather than silently disabling wrap.
- *
- * Returns the wrapped lines (never mutates input). An empty string yields [''].
- */
 export function wrapToWidth(text, cols, hangingIndent = 0) {
     const indent = Math.max(0, Math.trunc(hangingIndent));
     const floor = indent > 0 ? 8 : 1;

package/dist/lib/yaml-io.d.ts

@@ -1,47 +1,2 @@
 import * as yaml from 'yaml';
-/**
- * The single serialization used by every writer that edits a shared, committed
- * YAML document in place.
- *
- * RUSH-2505 had two halves. The first: the `yaml` emitter pads flow collections
- * by default, so a round trip rewrote
- *
- *     command: [agents, notify, "{message}"]
- * as
- *     command: [ agents, notify, "{message}" ]
- *
- * The second, which outlived the first fix: `agents.yaml` has five in-place
- * writers, and they did not agree on collection style. `state.ts` and
- * `manifest.ts` forced block while `feed.ts`, `activity.ts` and `migrate.ts`
- * took the defaults, so an empty map came out as
- *
- *     mcp:            from two of them, and      mcp: {}
- *       {}                                        from the other three,
- *
- * and each group rewrote the other's output on the next command.
- *
- * Both diffs are semantically no-ops, which is what made them dangerous. The
- * working tree went permanently dirty, then `agents repo pull` refused
- * ("Blocked by local changes") and `git merge --ff-only` refused, so the box
- * silently stopped receiving fleet config. Seven boxes fell 37-52 commits
- * behind and nothing reported it.
- *
- * Two constraints pull in opposite directions, and both are real:
- *
- *  - Forcing `collectionStyle: 'block'` unconditionally flattens a committed
- *    flow sequence into a block list — its own dirtying diff, asserted against
- *    by the RUSH-2505 case in `feed.test.ts`.
- *  - Never forcing it regresses what `state.ts` and `manifest.ts` were guarding:
- *    when the document ROOT is flow (a legacy `{}` or `{a: 1}` file), every
- *    edited node inherits flow, so a `doc.set()` yields
- *    `{a: 1, disabledCommands: [teams]}` instead of a block mapping.
- *
- * So block is forced exactly when the root is flow, which is the only case that
- * needs it, and left alone otherwise. Every writer gets the same rule, so the
- * same document can only produce one result and there is nothing left to
- * oscillate.
- *
- * Caller options merge last, so a writer with a genuine reason to differ still
- * can — but it then owns the drift it causes.
- */
 export declare function stringifyDoc(doc: yaml.Document, options?: yaml.ToStringOptions): string;

package/dist/lib/yaml-io.js

@@ -1,51 +1,4 @@
-/**
- * The single serialization used by every writer that edits a shared, committed
- * YAML document in place.
- *
- * RUSH-2505 had two halves. The first: the `yaml` emitter pads flow collections
- * by default, so a round trip rewrote
- *
- *     command: [agents, notify, "{message}"]
- * as
- *     command: [ agents, notify, "{message}" ]
- *
- * The second, which outlived the first fix: `agents.yaml` has five in-place
- * writers, and they did not agree on collection style. `state.ts` and
- * `manifest.ts` forced block while `feed.ts`, `activity.ts` and `migrate.ts`
- * took the defaults, so an empty map came out as
- *
- *     mcp:            from two of them, and      mcp: {}
- *       {}                                        from the other three,
- *
- * and each group rewrote the other's output on the next command.
- *
- * Both diffs are semantically no-ops, which is what made them dangerous. The
- * working tree went permanently dirty, then `agents repo pull` refused
- * ("Blocked by local changes") and `git merge --ff-only` refused, so the box
- * silently stopped receiving fleet config. Seven boxes fell 37-52 commits
- * behind and nothing reported it.
- *
- * Two constraints pull in opposite directions, and both are real:
- *
- *  - Forcing `collectionStyle: 'block'` unconditionally flattens a committed
- *    flow sequence into a block list — its own dirtying diff, asserted against
- *    by the RUSH-2505 case in `feed.test.ts`.
- *  - Never forcing it regresses what `state.ts` and `manifest.ts` were guarding:
- *    when the document ROOT is flow (a legacy `{}` or `{a: 1}` file), every
- *    edited node inherits flow, so a `doc.set()` yields
- *    `{a: 1, disabledCommands: [teams]}` instead of a block mapping.
- *
- * So block is forced exactly when the root is flow, which is the only case that
- * needs it, and left alone otherwise. Every writer gets the same rule, so the
- * same document can only produce one result and there is nothing left to
- * oscillate.
- *
- * Caller options merge last, so a writer with a genuine reason to differ still
- * can — but it then owns the drift it causes.
- */
 export function stringifyDoc(doc, options = {}) {
-    // A flow root makes every edited node render flow; normalize the whole doc to
-    // block in that case only. `contents.flow` is undefined for a block root.
     const rootIsFlow = doc.contents?.flow === true;
     return doc.toString({
         flowCollectionPadding: false,

package/dist/session-tracker/dist/adapters/claude.js

@@ -2,7 +2,6 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 export const CLAUDE_PROJECTS_ROOT = path.join(os.homedir(), '.claude', 'projects');
-// Mirrors swarmify's workspaceToClaudeFolder: replace / and . with -
 export function claudeWorkspaceFolder(cwd) {
     return cwd.replace(/[\/.]/g, '-');
 }
@@ -37,7 +36,6 @@ export async function awaitNewSession(cwd, before, timeoutMs, pollMs = 50) {
             }
         }
         catch {
-            /* dir may not exist yet */
         }
         await new Promise((r) => setTimeout(r, pollMs));
     }

package/dist/session-tracker/dist/hook.sh

@@ -1,20 +1,4 @@
 #!/usr/bin/env bash
-# Polyglot SessionStart hook.
-#
-# Registered as a SessionStart hook in each agent's native config file.
-# Each agent passes the hook payload differently:
-#   - claude/codex/cursor: JSON on stdin with session_id (+conversation_id for cursor)
-#   - grok: GROK_SESSION_ID and GROK_WORKSPACE_ROOT env vars
-#   - hermes: JSON on stdin (on_session_start payload); best-effort field probe
-#   - gemini/antigravity: best-effort stdin-JSON probe
-#
-# Writes ~/.agents/.cache/terminals/sessions/<PPID>.json with the canonical
-# SessionState schema from src/types.ts. Atomic via mktemp + mv.
-#
-# Invocation:
-#   hook.sh <agent>            # required; selects which payload format to parse
-#
-# Silent on success (SessionStart stdout leaks into the model context).
 
 set -euo pipefail
 
@@ -34,10 +18,7 @@ if [ -z "$AGENT" ]; then
   exit 0
 fi
 
-# Read stdin if any (don't block forever).
-# Use `cat` only when stdin is not a TTY — and rely on hosts (claude, codex,
-# cursor) closing stdin promptly. macOS has no `timeout` in PATH by default,
-# so we don't use it.
+# Stdout enters model context: stay silent, and read hook payload only from non-TTY stdin.
 STDIN_JSON=""
 if [ ! -t 0 ]; then
   STDIN_JSON="$(cat || true)"
@@ -48,7 +29,7 @@ CWD=""
 METHOD="hook-stdin"
 
 extract_stdin_json() {
-  local field_priority="$1"  # space-separated list of JSON keys to try in order
+  local field_priority="$1"
   python3 -c "
 import json, sys
 try:
@@ -79,8 +60,6 @@ case "$AGENT" in
     METHOD="hook-env"
     ;;
   hermes|gemini|antigravity)
-    # Best-effort stdin-JSON probe across the field names these harnesses use.
-    # A miss exits 0 below (no state file) — never a wrong write.
     SID="$(printf '%s' "$STDIN_JSON" | extract_stdin_json 'session_id conversation_id sessionId')"
     CWD="$(printf '%s' "$STDIN_JSON" | extract_stdin_json 'cwd workspace_roots')"
     ;;
@@ -93,8 +72,7 @@ if [ -z "$SID" ]; then
   exit 0
 fi
 
-# The session id becomes two filenames below. Reject path components before
-# either mktemp or mv sees the harness-provided value.
+# Reject path-bearing ids; state filenames are atomic replacements keyed only by the harness's real id.
 case "$SID" in
   *'/'*|*'\'*|'.'|'..') exit 0 ;;
 esac
@@ -128,25 +106,14 @@ PY
 
 mv -f "$TMP" "$STATE_DIR/$PPID.json"
 
-# Prune dead-pid records, zero-byte files, and orphaned temp files left by
-# crashed atomic writes. Keep stdout/stderr silent — it leaks into the model.
 PRUNE_SCRIPT="$SCRIPT_DIR/../dist/prune-state.js"
 if [ -f "$PRUNE_SCRIPT" ]; then
   node "$PRUNE_SCRIPT" >/dev/null 2>&1 || true
 fi
 
-# Persist launch metadata under the harness's real session id. `agents run`
-# exports the EFFECTIVE mode after capability/headless resolution, plus the
-# shared (non-version-home) history directory. Atomic replacement lets a native
-# resume with an explicit --mode become the new mode for the next resume.
+# Persist mode/version/account only after the harness supplies its real session id, so native resume pins origin.
 HISTORY_DIR="${AGENTS_HISTORY_DIR:-}"
 RUN_MODE="${AGENTS_RUN_MODE:-}"
-# The agents-cli version-home id this run launched under. Recorded here (not at
-# spawn) for the same reason as RUN_MODE: the harness coins its real session id
-# only after launch, so it must be joined to that id by this hook. A later native
-# resume pins the exact origin version off it, so a session whose transcript
-# carries no derivable version (codex's `.codex-homes/<version>/` home) still
-# resumes natively instead of degrading to `/continue` (PHNX-3626).
 RUN_VERSION="${AGENTS_RUN_VERSION:-}"
 RUN_ACCOUNT_ID="${AGENTS_RUN_ACCOUNT_ID:-}"
 TMUX_SESSION_NAME="${AGENT_TMUX_SESSION_NAME:-}"

package/dist/session-tracker/dist/index.d.ts

@@ -5,15 +5,8 @@ export * from './writer.js';
 export * from './install-hook.js';
 export { descendantPids, findStateByPid, findStateInTree, findStateByTerminalId, findStateByLaunchId, pruneStaleSessionState, } from './reader.js';
 export interface TrackSpawnOptions {
-    /** Max time to wait for the SessionStart hook to land the state file. Default 5000ms. */
     timeoutMs?: number;
-    /** Poll interval. Default 50ms. */
     pollIntervalMs?: number;
 }
-/**
- * Wait for the polyglot SessionStart hook (src/hook.sh) to drop a state file
- * at stateFilePath(input.agentPid). Resolves as soon as it appears.
- * Returns confidence='low' / sessionId=null on timeout.
- */
 export declare function trackSpawn(input: TrackSpawnInput, opts?: TrackSpawnOptions): Promise<DetectionResult>;
 export declare function getLiveSession(input: LookupInput): Promise<SessionState | null>;

package/dist/session-tracker/dist/index.js

@@ -6,11 +6,6 @@ export * from './state-file.js';
 export * from './writer.js';
 export * from './install-hook.js';
 export { descendantPids, findStateByPid, findStateInTree, findStateByTerminalId, findStateByLaunchId, pruneStaleSessionState, } from './reader.js';
-/**
- * Wait for the polyglot SessionStart hook (src/hook.sh) to drop a state file
- * at stateFilePath(input.agentPid). Resolves as soon as it appears.
- * Returns confidence='low' / sessionId=null on timeout.
- */
 export async function trackSpawn(input, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 5000;
     const pollIntervalMs = opts.pollIntervalMs ?? 50;

package/dist/session-tracker/dist/install-hook.d.ts

@@ -8,12 +8,7 @@ export interface InstallResult {
 export interface InstallOptions {
     dryRun?: boolean;
     hookPathOverride?: string;
-    /** Home directory whose harness-native config should be written. Defaults to
-     *  `os.homedir()` so the live config (usually a symlink into the active
-     *  version home) is updated. */
     home?: string;
 }
-/** Every agent id the hook installer knows — the keys of the compile-time-complete
- *  {@link HOOK_SUPPORT} table (Record<AgentId, …>), so this can never drift from AgentId. */
 export declare const HOOK_AGENTS: AgentId[];
 export declare function installHookFor(agent: AgentId, opts?: InstallOptions): Promise<InstallResult>;

package/dist/session-tracker/dist/install-hook.js

@@ -1,9 +1,3 @@
-// Installs the polyglot src/hook.sh as a SessionStart hook in each agent's
-// native config file. Idempotent — running twice does not double-register.
-//
-// CLI usage:
-//   tsx src/install-hook.ts claude
-//   tsx src/install-hook.ts claude codex cursor
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -17,7 +11,6 @@ function hookCommand(agent, opts) {
     const hook = opts.hookPathOverride ?? HOOK_PATH;
     return `${hook} ${agent}`;
 }
-/** Recognize current registrations and the retired builtin sidecar writer. */
 function isOwnHookCommand(command) {
     const first = command.trim().split(/\s+/)[0];
     return (first.endsWith('hook.sh') && first.includes('session-tracker'))
@@ -45,7 +38,7 @@ async function writeJsonAtomic(p, data) {
         try {
             await fs.promises.unlink(tmp);
         }
-        catch { /* best-effort */ }
+        catch { }
         throw err;
     }
 }
@@ -58,13 +51,11 @@ async function installClaude(opts) {
     const cfg = await readJson(configPath);
     cfg.hooks = cfg.hooks ?? {};
     cfg.hooks.SessionStart = cfg.hooks.SessionStart ?? [];
-    // Remove any prior registration of THIS hook path (idempotency).
     for (const entry of cfg.hooks.SessionStart) {
         if (!entry || !Array.isArray(entry.hooks))
             continue;
         entry.hooks = entry.hooks.filter((h) => !(h && h.command && isOwnHookCommand(h.command)));
     }
-    // Find or create the empty-matcher group and add our hook.
     let group = cfg.hooks.SessionStart.find((e) => e && e.matcher === '');
     if (!group) {
         group = { matcher: '', hooks: [] };
@@ -169,9 +160,6 @@ async function installHermes(opts) {
     const command = hookCommand('hermes', opts);
     if (opts.dryRun)
         return { agent: 'hermes', installed: false, configPath };
-    // Read-modify-write the YAML, preserving every sibling key (mcp_servers, …) —
-    // mirrors the CLI's registerHooksForHermes. Hermes maps SessionStart to the
-    // `on_session_start` event (HERMES_EVENT_MAP in cli/src/lib/hooks/install.ts).
     let cfg = {};
     try {
         const parsed = YAML.parse(await fs.promises.readFile(configPath, 'utf8'));
@@ -207,8 +195,6 @@ const HOOK_SUPPORT = {
     antigravity: { unsupported: 'antigravity has no SessionStart hook event' },
     opencode: { unsupported: 'opencode SessionStart is a generated plugin, not a shell-command hook' },
 };
-/** Every agent id the hook installer knows — the keys of the compile-time-complete
- *  {@link HOOK_SUPPORT} table (Record<AgentId, …>), so this can never drift from AgentId. */
 export const HOOK_AGENTS = Object.keys(HOOK_SUPPORT);
 export async function installHookFor(agent, opts = {}) {
     const support = HOOK_SUPPORT[agent];

package/dist/session-tracker/dist/prune-state.js

@@ -1,7 +1,3 @@
 #!/usr/bin/env node
-// Prune stale entries from the SessionStart hook state directory.
-// Called by hook.sh after a successful write so the directory never accumulates
-// dead-pid records, zero-byte files, or orphaned temp files.
 import { cleanupOrphanedStateFiles } from './state-file.js';
 await cleanupOrphanedStateFiles();
-// Stay silent — stdout from SessionStart hooks leaks into the model context.

package/dist/session-tracker/dist/reader.js

@@ -6,7 +6,6 @@ import { STATE_DIR, parseState, stateFilePath } from './state-file.js';
 const execAsync = promisify(exec);
 const PID_TREE_MAX_DEPTH = 5;
 const PID_TREE_MAX_NODES = 100;
-// macOS `pgrep -P` silently misses children for some pids; `ps -eo` is reliable.
 async function buildChildIndex() {
     const index = new Map();
     try {
@@ -25,7 +24,6 @@ async function buildChildIndex() {
         }
     }
     catch {
-        /* empty index — caller treats as no descendants */
     }
     return index;
 }
@@ -90,7 +88,6 @@ async function scanAllStates() {
                 out.push(s);
         }
         catch {
-            /* skip */
         }
     }
     return out;
@@ -142,7 +139,6 @@ export async function pruneStaleSessionState() {
                     removed++;
                 }
                 catch {
-                    /* best-effort */
                 }
             }
         }

package/dist/session-tracker/dist/state-file.d.ts

@@ -4,7 +4,4 @@ export declare function stateFilePath(pid: number, stateDir?: string): string;
 export declare function serializeState(s: SessionState): string;
 export declare function parseState(raw: string): SessionState | null;
 export declare function writeStateAtomic(state: SessionState, stateDir?: string): Promise<void>;
-/** Remove stale state files: dead-pid records, zero-byte JSON files, and orphaned
- *  temp files left behind by failed atomic writes. Returns the number of files
- *  removed. Best-effort: individual failures are ignored and do not stop the sweep. */
 export declare function cleanupOrphanedStateFiles(stateDir?: string): Promise<number>;