@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/overdue.js

@@ -1,49 +1,14 @@
-/**
- * Overdue routine detection.
- *
- * When the daemon was not running (laptop off, reboot, daemon crash) at the
- * time a job was supposed to fire, the missed schedule is lost — croner only
- * schedules forward from "now." This module compares each enabled job's
- * most-recent expected fire time (from its cron expression) with the start
- * time of its most-recent recorded run; jobs whose latest run is older than
- * their most-recent expected fire are flagged as overdue.
- *
- * Surfaced two ways: a desktop notification on daemon startup, and a
- * `agents routines catchup` command that runs them on demand.
- */
 import * as fs from 'fs';
 import { Cron } from 'croner';
 import { alignedSlotForFire, listJobs, getLatestRun, resolveJobFilePath, isPastEndAt, isOneShotRoutine, jobRunsOnThisDevice } from './scheduling/routines.js';
 import { notifyDesktop } from './menubar/notify-desktop.js';
-// Tolerance between "expected fire" and "recorded run start" — accounts for
-// the small gap between the cron tick and when the runner writes meta.json.
 const GRACE_MS = 60_000;
-/** Compute the most recent fire of `pattern` at or before `now`. Delegates to
- *  {@link alignedSlotForFire} so overdue detection (`missedRunId`) and the live
- *  forward-timer dispatch (`slotRunId`) key on the SAME occurrence identity — a
- *  missed fire and its live twin for one UTC slot then collide by construction
- *  (SING-15). */
 function previousExpectedFire(cron, now) {
     return alignedSlotForFire(cron, now);
 }
-/**
- * When a routine started existing, and therefore the earliest fire it can
- * sensibly be judged against.
- *
- * `createdAt` is stamped by `writeJob`. Routines written before that field
- * existed have none, so the file's own mtime stands in — it is the closest
- * honest answer available on disk, and it only ever moves the floor later,
- * never earlier, so it cannot manufacture a false "overdue".
- *
- * Returns null when neither is available, which leaves the routine unfloored
- * (previous behaviour) rather than silently skipping it.
- */
 export function routineEffectiveStart(job, now = new Date()) {
     if (job.createdAt) {
         const stamped = new Date(job.createdAt);
-        // Clamp a future stamp (clock skew, a hand-edited year) to now. Left
-        // unclamped it sits after every possible expected fire, so the routine can
-        // never be flagged overdue until wall-clock time catches up.
         if (!isNaN(stamped.getTime())) {
             return stamped.getTime() > now.getTime() ? now : stamped;
         }
@@ -58,31 +23,17 @@ export function routineEffectiveStart(job, now = new Date()) {
         return null;
     }
 }
-/** Return every enabled, recurring job whose most recent expected fire was
- *  missed. One-shot jobs are excluded — they fire at most once. */
 export function detectOverdueJobs(now = new Date()) {
     const overdue = [];
     for (const job of listJobs()) {
         if (!job.enabled)
             continue;
-        // One-shot: fires at most once, so a missed slot is not a backlog to replay.
-        // Use the same predicate the scheduler does — the raw `runOnce` flag alone
-        // missed a one-shot-LIKE schedule (a fixed minute/hour/day/month) that never
-        // carried the flag.
         if (isOneShotRoutine(job))
             continue;
-        // Past its configured end: catch-up must not resurrect a routine the author
-        // already retired. The scheduler only auto-disables lazily, inside a live
-        // cron tick, so a routine whose endAt elapsed while the daemon was down is
-        // still enabled on disk when the catch-up pass runs.
         if (isPastEndAt(job, now))
             continue;
-        // Trigger-only jobs (no cron schedule) never have an expected fire time.
         if (!job.schedule)
             continue;
-        // A job pinned to another device is that device's to run, notify, and
-        // catch up — flagging it here would make every machine in the fleet nag
-        // (and `catchup` fire) for a job that must not run locally.
         if (!jobRunsOnThisDevice(job))
             continue;
         let expected = null;
@@ -95,15 +46,10 @@ export function detectOverdueJobs(now = new Date()) {
             cron.stop();
         }
         catch {
-            // Invalid cron expression — skip rather than crash the daemon.
             continue;
         }
         if (!expected)
             continue;
-        // A fire that predates the routine never could have happened, so it is not
-        // a miss. Without this, any newly created routine on a daily/weekly cron is
-        // instantly "overdue" for the previous occurrence — and with auto-catchup
-        // that means `agents routines add` runs the routine once, immediately.
         const start = routineEffectiveStart(job, now);
         if (start && expected.getTime() < start.getTime())
             continue;
@@ -116,12 +62,6 @@ export function detectOverdueJobs(now = new Date()) {
     }
     return overdue;
 }
-/**
- * Fire a branded desktop notification listing the overdue jobs. Routed through
- * the MenubarHelper companion (notify-desktop.ts) so it carries the agents-cli
- * mark; clicking opens the runs folder (~/.agents/.history/runs). Best-effort —
- * a missing notifier or absent display is swallowed and never crashes the daemon.
- */
 export function notifyOverdue(jobs) {
     if (jobs.length === 0)
         return;

package/dist/lib/owner-message.d.ts

@@ -1,29 +1,9 @@
 import type { SinkMessageFormat } from './sink-format.js';
 interface OwnerMessageOptions {
-    /** Scannable subject line, when the caller has one (feed post does; notify does not). */
     title?: string;
-    /** Explicit session id (`--session`); otherwise resolved from the run environment. */
     sessionId?: string;
-    /**
-     * Rendering vocabulary for this body (PHNX-3698). Slack `mrkdwn` linkifies the
-     * ticket keys and the session crumb as `<url|label>`; `plain` (the default)
-     * keeps the human sentence with no URLs, for iMessage / owner-scoped rush.
-     * The owner fan-out passes one format per destination.
-     */
     format?: SinkMessageFormat;
 }
-/**
- * Shape a raw owner-send body into the composed broadcast message. `format`
- * decides how links surface — `plain` (default) for iMessage / owner-scoped rush,
- * `mrkdwn` for a Slack owner destination (PHNX-3698).
- */
 export declare function composeOwnerMessage(rawText: string, opts?: OwnerMessageOptions): string;
-/**
- * A per-format composer bound to ONE resolved context — the shape the owner
- * fan-out wants (PHNX-3698). `agents send --to owner` build
- * this once, use `compose('plain')` for the envelope's display body, and hand
- * `compose` to `sendToOwner` so each policy destination re-renders in its own
- * format without re-walking the pid registry.
- */
 export declare function ownerMessageComposer(rawText: string, opts?: OwnerMessageOptions): (format: SinkMessageFormat) => string;
 export {};

package/dist/lib/owner-message.js

@@ -1,36 +1,9 @@
-/**
- * Compose an owner-bound phone ping through the SAME shaper `agents feed post`
- * uses, so `agents send --to owner` stop shipping a raw body
- * dump (PHNX-3698).
- *
- * Before this, an owner send delivered the body verbatim: a long wall of prose,
- * a `TEAM-N` key iMessage renders as dead text, and no way back to the session.
- * Routing the body through {@link composeBroadcastMessage} makes an owner ping
- * identical to an important feed post of the same event — short-shaped body,
- * every ticket key linkified to its Linear URL, and the current session's
- * `…/console/sessions/<id>` page as a tappable crumb.
- *
- * The session/agent/host are resolved the same way a feed post resolves them
- * ({@link resolvePostIdentity} — the pid-registry / env walk), so a `notify`
- * run inside an agent session inherits that session with no flag. Outside a
- * session (a human at a shell) identity is undefined: the ping still gets
- * short-shaping and ticket linkification, just no session crumb.
- */
 import { composeBroadcastMessage } from './feed-broadcast.js';
 import { resolvePostIdentity } from './feed-post.js';
 import { getSessionById, resolveFullSessionId } from './session/db.js';
-import { linearIssueUrl } from './session/linear.js';
-/**
- * Resolve the run identity into the broadcast context an owner ping is built
- * from — the shared shape a `feed post` uses. Pure except for the identity/index
- * reads that {@link resolvePostIdentity} / {@link getSessionById} already perform
- * for feed posts. Built ONCE so the owner fan-out can render it in more than one
- * format (Slack vs iMessage) without re-walking the pid registry per destination.
- */
+import { linearIssueUrl } from '@phnx-labs/sessions-cli/reader';
 function ownerMessageContext(rawText, opts = {}) {
     const identity = resolvePostIdentity({ sessionId: opts.sessionId });
-    // A footer crumb that would 404 (an 8-char short id) is upgraded to the full
-    // indexed id so the console URL resolves; a full/native id passes through.
     const session = resolveFullSessionId(identity?.sessionId);
     const ticket = session ? getSessionById(session)?.ticketId : undefined;
     return {
@@ -43,21 +16,9 @@ function ownerMessageContext(rawText, opts = {}) {
         ...(session ? { session } : {}),
     };
 }
-/**
- * Shape a raw owner-send body into the composed broadcast message. `format`
- * decides how links surface — `plain` (default) for iMessage / owner-scoped rush,
- * `mrkdwn` for a Slack owner destination (PHNX-3698).
- */
 export function composeOwnerMessage(rawText, opts = {}) {
     return composeBroadcastMessage(ownerMessageContext(rawText, opts), opts.format ?? 'plain');
 }
-/**
- * A per-format composer bound to ONE resolved context — the shape the owner
- * fan-out wants (PHNX-3698). `agents send --to owner` build
- * this once, use `compose('plain')` for the envelope's display body, and hand
- * `compose` to `sendToOwner` so each policy destination re-renders in its own
- * format without re-walking the pid registry.
- */
 export function ownerMessageComposer(rawText, opts = {}) {
     const ctx = ownerMessageContext(rawText, opts);
     return (format) => composeBroadcastMessage(ctx, format);

package/dist/lib/packages/output-home.d.ts

@@ -1,37 +1,9 @@
-/** The three harness homes a portable schema-v3 package can be materialized into. */
 export declare const PORTABLE_HARNESSES: readonly ["claude", "codex", "opencode"];
 type PortableHarness = (typeof PORTABLE_HARNESSES)[number];
-/** Thrown for a bad front-door argument (harness / version / output home). Never `process.exit`. */
 export declare class MaterializeGuardError extends Error {
     constructor(message: string);
 }
-/** Reject a harness that is not one of the three portable homes, with a message naming it. */
 export declare function assertPortableHarness(harness: string): PortableHarness;
-/** Reject a non-exact harness version (empty, malformed, or `@latest`). */
 export declare function assertExactHarnessVersion(version: string): string;
-/**
- * Resolve `--output-home` to an absolute path, refusing a target that climbs out
- * of cwd (relative), uses a `..` segment, IS the live home root, or targets (or
- * sits inside) an existing live Claude/Codex/OpenCode home — after canonicalizing
- * symlinks in the existing ancestors so a symlinked target/ancestor can't alias
- * `$HOME`. Every rejection carries a `Path escape:` prefix so callers surface one
- * consistent reason.
- *
- * If any protected home is instead a DANGLING symlink or chain, the function
- * fails closed and refuses EVERY output home (via {@link assertNoDanglingLiveHome}),
- * because the absent target it points at has no canonical spelling to compare a
- * candidate against and the materializer's first `mkdir -p` would follow the link
- * and re-create the operator's live home there (PHNX-3838). The existing-home
- * comparison uses a byte-exact `===` / `startsWith` on two `realpath`-canonical
- * paths, which is exact filesystem identity — no approximation of the volume's
- * case/Unicode collation, which an independent macOS review showed cannot be
- * reproduced in JS from the path text.
- *
- * This is a front-door convenience guard. The load-bearing containment invariant
- * (that no per-resource write/delete escapes the output home — including through
- * a symlink planted at the harness-config-dir join point, which this function
- * cannot see because the materializer forms that child itself) is enforced in
- * `materializeAgentPackage`, so a direct (non-CLI) caller is protected too.
- */
 export declare function resolveOutputHome(raw: string, cwd?: string, home?: string): string;
 export {};

package/dist/lib/packages/output-home.js

@@ -1,84 +1,33 @@
-/**
- * Front-door safety guard for `agents packages materialize` (PHNX-3838).
- *
- * The canonical materializer ({@link materializeAgentPackage} in
- * `agent-spec/materialize.ts`) writes into whatever `outputHome` it is handed —
- * that is its job, and it must stay destination-agnostic so Factory / Prix Cloud
- * can point it at any ephemeral home. Refusing a *dangerous* destination is a
- * CLI-front-door concern, not a materializer concern, so it lives here:
- *
- *   - the target may not climb out of cwd (relative) or carry a `..` segment;
- *   - if any protected live harness home (`~/.claude`, `~/.codex`, `~/.opencode`)
- *     is a DANGLING symlink or dangling chain, EVERY output home is refused —
- *     fail closed (see {@link assertNoDanglingLiveHome});
- *   - the target may not be the operator's live home ROOT, nor — or sit inside —
- *     an EXISTING live `~/.claude`, `~/.codex`, or `~/.opencode` home;
- *   - the harness must be one of the three portable homes;
- *   - the harness version must be an exact version, never `@latest`.
- *
- * The live-home ROOT refusal is load-bearing: the materializer appends the
- * harness config dir (`.claude`/`.codex`/`.opencode`) to `outputHome`, so an
- * `outputHome` of `$HOME` itself would land straight in the operator's live
- * `~/.claude`. And because a symlink (`outputHome` itself, or any ancestor)
- * pointing at `$HOME` re-opens the same hole — `path.resolve` normalizes `..`
- * but never follows links — the check canonicalizes the existing ancestors with
- * `realpath` before comparing.
- *
- * Kept beside the command (not inside it) so the live-home refusal is
- * unit-testable without spawning the whole CLI.
- */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { assertWithin, realpathExistingPrefix } from '../paths.js';
 import { VERSION_RE } from '../agent-spec/primitives.js';
-/** The three harness homes a portable schema-v3 package can be materialized into. */
 export const PORTABLE_HARNESSES = ['claude', 'codex', 'opencode'];
 function isPortableHarness(value) {
     return PORTABLE_HARNESSES.includes(value);
 }
-/** Thrown for a bad front-door argument (harness / version / output home). Never `process.exit`. */
 export class MaterializeGuardError extends Error {
     constructor(message) {
         super(message);
         this.name = 'MaterializeGuardError';
     }
 }
-/** Reject a harness that is not one of the three portable homes, with a message naming it. */
 export function assertPortableHarness(harness) {
     if (!isPortableHarness(harness)) {
         throw new MaterializeGuardError(`Unsupported capability: '${harness}' is not a portable-agent harness (${PORTABLE_HARNESSES.join(', ')}).`);
     }
     return harness;
 }
-/** Reject a non-exact harness version (empty, malformed, or `@latest`). */
 export function assertExactHarnessVersion(version) {
     if (!version || version === 'latest' || !VERSION_RE.test(version)) {
         throw new MaterializeGuardError(`Invalid harness version '${version}'. Pass an exact harness version (not @latest).`);
     }
     return version;
 }
-/** True when `raw` still contains a `..` segment after splitting on both separators. */
 function outputHomeHasDotDot(raw) {
     return raw.split(/[\\/]/).includes('..');
 }
-/**
- * The absolute path a DANGLING symlink chain ultimately points at, or `null`
- * when `p` is not a symlink or its chain resolves to an existing file.
- *
- * `realpathExistingPrefix` deliberately does NOT follow a dangling LEAF link — it
- * resolves the link's parent and re-appends the basename — so `~/.claude` → an
- * absent target canonicalizes to the literal `~/.claude`, and the target itself
- * sails past every containment compare. Yet the materializer's very first act is
- * `fs.mkdirSync(outputHome, { recursive: true })`, which FOLLOWS that link and
- * creates the target, re-pointing the operator's live `~/.claude` at the
- * materialized tree. So the guard treats a dangling protected home as a fail-
- * closed condition (see {@link assertNoDanglingLiveHome}). A live symlink (its
- * target exists) resolves cleanly through `realpathExistingPrefix`, hence the
- * `!fs.existsSync` gate returns `null` for it. Relative links resolve against
- * each hop's own directory; a bounded hop budget defuses a symlink cycle
- * (returning the best-effort endpoint, which still reads as dangling → refused).
- */
 function danglingLinkChainTarget(p) {
     let current = path.resolve(p);
     let followed = false;
@@ -95,28 +44,6 @@ function danglingLinkChainTarget(p) {
     }
     return current;
 }
-/**
- * Fail CLOSED when any protected live harness home (`~/.claude`, `~/.codex`,
- * `~/.opencode`) is a DANGLING symlink or dangling symlink chain — refusing
- * EVERY output home, not merely one that aliases the dangling target.
- *
- * Why refuse the whole operation instead of the aliasing path alone: the
- * materializer's first act is `fs.mkdirSync(outputHome, { recursive: true })`,
- * which FOLLOWS the link and creates its absent target, re-pointing the
- * operator's live `~/.<harness>` at the materialized tree. To refuse only the
- * aliasing output home we would have to decide whether the requested path and
- * the dangling target name the SAME file — but the target does not exist, so it
- * cannot be `realpath`'d, and its identity then depends on the destination
- * volume's own case/Unicode collation, which is per-volume and NOT knowable from
- * the path text. An independent macOS review confirmed this directly: NFC +
- * `toLowerCase` is not APFS case folding (APFS treats e.g. U+017F ſ and ASCII `s`
- * as identical, which `toLowerCase` does not), and an OS-derived case-sensitivity
- * flag is wrong for per-volume semantics. Rather than approximate an unknowable
- * collation, the guard refuses outright until the operator repairs the dangling
- * home. A dangling protected home is an abnormal state, so this over-rejects
- * nothing a healthy environment relies on; the EXISTING-home comparison stays
- * exact because `realpath` gives it a trustworthy canonical spelling.
- */
 function assertNoDanglingLiveHome(realHome) {
     for (const name of PORTABLE_HARNESSES) {
         if (danglingLinkChainTarget(path.join(realHome, `.${name}`)) !== null) {
@@ -125,49 +52,12 @@ function assertNoDanglingLiveHome(realHome) {
         }
     }
 }
-/**
- * The canonical EXISTING live harness home to forbid, per harness: the
- * `realpathExistingPrefix` of each `~/.<harness>`. For a live symlink this is the
- * real on-disk target (so `--output-home ~/.claude` and its resolved dir both
- * match); for a plain dir, or a home that does not exist at all, it is the
- * literal `~/.<harness>` path. Because both this and the candidate output home
- * are canonicalized with `realpath`, a byte-exact compare is exact filesystem
- * identity — `realpath` returns the volume's own on-disk spelling, so two paths
- * naming the same file collapse to the same string with no need to approximate
- * the volume's case/Unicode collation. A DANGLING `~/.<harness>` never reaches
- * here: {@link assertNoDanglingLiveHome} fails closed first, precisely because
- * its absent target has no realpath-canonical spelling to compare against.
- */
 function liveHarnessHomes(realHome) {
     return PORTABLE_HARNESSES.map((name) => ({
         harness: name,
         live: realpathExistingPrefix(path.join(realHome, `.${name}`)),
     }));
 }
-/**
- * Resolve `--output-home` to an absolute path, refusing a target that climbs out
- * of cwd (relative), uses a `..` segment, IS the live home root, or targets (or
- * sits inside) an existing live Claude/Codex/OpenCode home — after canonicalizing
- * symlinks in the existing ancestors so a symlinked target/ancestor can't alias
- * `$HOME`. Every rejection carries a `Path escape:` prefix so callers surface one
- * consistent reason.
- *
- * If any protected home is instead a DANGLING symlink or chain, the function
- * fails closed and refuses EVERY output home (via {@link assertNoDanglingLiveHome}),
- * because the absent target it points at has no canonical spelling to compare a
- * candidate against and the materializer's first `mkdir -p` would follow the link
- * and re-create the operator's live home there (PHNX-3838). The existing-home
- * comparison uses a byte-exact `===` / `startsWith` on two `realpath`-canonical
- * paths, which is exact filesystem identity — no approximation of the volume's
- * case/Unicode collation, which an independent macOS review showed cannot be
- * reproduced in JS from the path text.
- *
- * This is a front-door convenience guard. The load-bearing containment invariant
- * (that no per-resource write/delete escapes the output home — including through
- * a symlink planted at the harness-config-dir join point, which this function
- * cannot see because the materializer forms that child itself) is enforced in
- * `materializeAgentPackage`, so a direct (non-CLI) caller is protected too.
- */
 export function resolveOutputHome(raw, cwd = process.cwd(), home = os.homedir()) {
     if (!raw || raw.includes('\0')) {
         throw new MaterializeGuardError('Path escape: output home is empty or contains a null byte');
@@ -186,11 +76,7 @@ export function resolveOutputHome(raw, cwd = process.cwd(), home = os.homedir())
     }
     const canonical = realpathExistingPrefix(resolved);
     const realHome = realpathExistingPrefix(home);
-    // Fail closed first: a dangling protected home makes EVERY output home unsafe,
-    // and its absent target has no realpath-canonical spelling to compare against.
     assertNoDanglingLiveHome(realHome);
-    // The materializer appends the harness config dir to outputHome, so the live
-    // home ROOT would write straight into ~/.claude etc.
     if (canonical === realHome) {
         throw new MaterializeGuardError('Path escape: output home must not be the live home directory');
     }

package/dist/lib/paths.d.ts

@@ -1,30 +1,4 @@
-/**
- * Canonicalize `target` by `realpath`-resolving its longest EXISTING ancestor and
- * re-appending the not-yet-created tail. A plain `realpathSync(target)` throws when
- * `target` (a fresh output dir, a not-yet-written file) does not exist — but any
- * symlink in the part that DOES exist (the target itself, or an ancestor) is
- * exactly the escape hatch a containment check must resolve before comparing.
- * Unlike `path.resolve` (which only normalizes `..`), this follows links.
- */
 export declare function realpathExistingPrefix(target: string): string;
-/**
- * True when `name` is a safe single path segment: non-empty, not '.'/'..',
- * free of path separators and null bytes, and within the filename length limit.
- * Dot-prefixed names like '.env.example' are allowed.
- */
 export declare function isSafeSegmentName(name: string): boolean;
-/**
- * Resolve base + name while preventing path-traversal attacks.
- * Rejects path separators, null bytes, '.' and '..', and any resolved path
- * that escapes the base directory. Dot-prefixed names like '.env.example'
- * are allowed — actual traversal is caught by the containment check below.
- * Allows spaces, unicode, and other common filename characters.
- */
 export declare function safeJoin(base: string, name: string): string;
-/**
- * Assert that `target` (which may legitimately contain path separators, e.g. a
- * multi-segment relative key) stays within `root` after normalization. Use this
- * where a caller must accept nested relative paths but the input is untrusted —
- * `safeJoin` is stricter and only allows single segments.
- */
 export declare function assertWithin(root: string, target: string): string;

package/dist/lib/paths.js

@@ -1,13 +1,5 @@
 import * as fs from 'fs';
 import * as path from 'path';
-/**
- * Canonicalize `target` by `realpath`-resolving its longest EXISTING ancestor and
- * re-appending the not-yet-created tail. A plain `realpathSync(target)` throws when
- * `target` (a fresh output dir, a not-yet-written file) does not exist — but any
- * symlink in the part that DOES exist (the target itself, or an ancestor) is
- * exactly the escape hatch a containment check must resolve before comparing.
- * Unlike `path.resolve` (which only normalizes `..`), this follows links.
- */
 export function realpathExistingPrefix(target) {
     let current = path.resolve(target);
     const tail = [];
@@ -19,30 +11,18 @@ export function realpathExistingPrefix(target) {
         catch {
             const parent = path.dirname(current);
             if (parent === current)
-                return path.resolve(target); // nothing on this path exists
+                return path.resolve(target);
             tail.push(path.basename(current));
             current = parent;
         }
     }
 }
-/**
- * True when `name` is a safe single path segment: non-empty, not '.'/'..',
- * free of path separators and null bytes, and within the filename length limit.
- * Dot-prefixed names like '.env.example' are allowed.
- */
 export function isSafeSegmentName(name) {
     return (!!name &&
         name !== '.' && name !== '..' &&
         !/[\/\\\x00]/.test(name) &&
         name.length <= 255);
 }
-/**
- * Resolve base + name while preventing path-traversal attacks.
- * Rejects path separators, null bytes, '.' and '..', and any resolved path
- * that escapes the base directory. Dot-prefixed names like '.env.example'
- * are allowed — actual traversal is caught by the containment check below.
- * Allows spaces, unicode, and other common filename characters.
- */
 export function safeJoin(base, name) {
     if (!isSafeSegmentName(name)) {
         throw new Error(`Invalid name: ${name}`);
@@ -52,12 +32,6 @@ export function safeJoin(base, name) {
         throw new Error(`Path escape: ${name}`);
     return resolved;
 }
-/**
- * Assert that `target` (which may legitimately contain path separators, e.g. a
- * multi-segment relative key) stays within `root` after normalization. Use this
- * where a caller must accept nested relative paths but the input is untrusted —
- * `safeJoin` is stricter and only allows single segments.
- */
 export function assertWithin(root, target) {
     const base = path.resolve(root);
     const resolved = path.resolve(target);

package/dist/lib/percentile.d.ts

@@ -1,12 +1 @@
-/**
- * Percentile of a sorted-ascending array, linear interpolation. p in [0,100].
- *
- * Deliberately its own file with zero imports: `perf/db.ts` (the SQLite
- * warehouse), `hooks/profile.ts` (the legacy JSONL hook profile), and
- * `routines.ts` (routineStats) all need this exact formula, but `routines.ts`
- * and `hooks/profile.ts` must NOT pull in `perf/db.ts`'s `../sqlite.js`
- * dependency just to round a percentile — sqlite is a heavier, perf-warehouse-
- * specific dependency that has no business loading into every routines- or
- * hooks-touching code path.
- */
 export declare function percentile(sorted: number[], p: number): number;

package/dist/lib/percentile.js

@@ -1,14 +1,3 @@
-/**
- * Percentile of a sorted-ascending array, linear interpolation. p in [0,100].
- *
- * Deliberately its own file with zero imports: `perf/db.ts` (the SQLite
- * warehouse), `hooks/profile.ts` (the legacy JSONL hook profile), and
- * `routines.ts` (routineStats) all need this exact formula, but `routines.ts`
- * and `hooks/profile.ts` must NOT pull in `perf/db.ts`'s `../sqlite.js`
- * dependency just to round a percentile — sqlite is a heavier, perf-warehouse-
- * specific dependency that has no business loading into every routines- or
- * hooks-touching code path.
- */
 export function percentile(sorted, p) {
     if (sorted.length === 0)
         return 0;

package/dist/lib/perf/db.d.ts

@@ -1,27 +1,11 @@
-/**
- * Disposable performance warehouse — SQLite under ~/.agents/.cache/perf/.
- *
- * Opened only by `agents insights perf` / `hooks profile` (read path). Writers use
- * {@link recordSample} in `./spool.ts` (NDJSON, no SQLite).
- */
 import Database from '../sqlite.js';
 import type { AggregateOptions, PerfAggregateRow } from './types.js';
 export type { AggregateOptions, PerfAggregateRow, PerfPhaseStat, PerfSample } from './types.js';
 export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
 export { percentile } from '../percentile.js';
 export declare const DEFAULT_RETENTION_DAYS = 30;
-/** Test seam — redirect the warehouse path (like AGENTS_EVENTS_PATH). */
 export declare function _resetPerfDbForTest(overridePath?: string | null): void;
-/** Drain the NDJSON spool into samples. Idempotent; truncates on success. */
 export declare function drainSpool(db?: Database.Database): number;
-/**
- * Aggregate samples by (kind, label) with p50/p95/p99. Drains the spool first.
- *
- * `opts.project` scopes the query to samples whose recorded `cwd` resolves to
- * that project key (see project-key.ts) — resolution runs per unique cwd
- * (memoized) rather than per row, since `resolveProjectKey` does a filesystem
- * walk and a warehouse query can carry many rows sharing the same cwd.
- */
 export declare function aggregateSamples(opts?: AggregateOptions): PerfAggregateRow[];
 export declare function perfDbPath(): string;
 export declare function perfSpoolPath(): string;

package/dist/lib/perf/db.js

@@ -1,9 +1,3 @@
-/**
- * Disposable performance warehouse — SQLite under ~/.agents/.cache/perf/.
- *
- * Opened only by `agents insights perf` / `hooks profile` (read path). Writers use
- * {@link recordSample} in `./spool.ts` (NDJSON, no SQLite).
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import Database from '../sqlite.js';
@@ -12,11 +6,6 @@ import { localMachineId } from '../origin-machine.js';
 import { resolveProjectKey } from '../project-key.js';
 import { percentile } from '../percentile.js';
 import { resolveSpoolPath, shortSessionId, _resetPerfSpoolForTest } from './spool.js';
-/**
- * Parse the `phases` map from a sample's meta_json. Fail-soft: a row with no
- * meta_json, malformed JSON, or a non-numeric phase value contributes nothing
- * rather than throwing (the warehouse must survive any writer's shape).
- */
 function parsePhases(metaJson) {
     if (!metaJson)
         return undefined;
@@ -74,13 +63,12 @@ CREATE TABLE IF NOT EXISTS meta (
 let _db = null;
 let _dbPath = null;
 let _disabled = false;
-/** Test seam — redirect the warehouse path (like AGENTS_EVENTS_PATH). */
 export function _resetPerfDbForTest(overridePath) {
     if (_db) {
         try {
             _db.close();
         }
-        catch { /* ignore */ }
+        catch { }
     }
     _db = null;
     _dbPath = overridePath === undefined ? null : overridePath;
@@ -111,7 +99,7 @@ function openDb() {
         try {
             _db.close();
         }
-        catch { /* ignore */ }
+        catch { }
         _db = null;
     }
     try {
@@ -136,7 +124,6 @@ function openDb() {
         return null;
     }
 }
-/** Drain the NDJSON spool into samples. Idempotent; truncates on success. */
 export function drainSpool(db) {
     const spool = resolveSpoolPath();
     if (!fs.existsSync(spool))
@@ -152,7 +139,7 @@ export function drainSpool(db) {
         try {
             fs.writeFileSync(spool, '');
         }
-        catch { /* ignore */ }
+        catch { }
         return 0;
     }
     const target = db ?? openDb();
@@ -210,17 +197,8 @@ function maybeRetain(db) {
         db.prepare(`INSERT OR REPLACE INTO meta(key, value) VALUES ('last_retain_ms', ?)`).run(String(now));
     }
     catch {
-        // ignore
     }
 }
-/**
- * Aggregate samples by (kind, label) with p50/p95/p99. Drains the spool first.
- *
- * `opts.project` scopes the query to samples whose recorded `cwd` resolves to
- * that project key (see project-key.ts) — resolution runs per unique cwd
- * (memoized) rather than per row, since `resolveProjectKey` does a filesystem
- * walk and a warehouse query can carry many rows sharing the same cwd.
- */
 export function aggregateSamples(opts = {}) {
     const db = openDb();
     if (!db)
@@ -249,8 +227,6 @@ export function aggregateSamples(opts = {}) {
     }
     const rows = db.prepare(`SELECT kind, label, duration_ms, cache, exit_code, status, cwd, meta_json
      FROM samples WHERE ${clauses.join(' AND ')}`).all(...params);
-    // Memoize cwd -> project key: resolveProjectKey walks the filesystem for
-    // a repo root, and many rows in one warehouse query share the same cwd.
     const projectCache = new Map();
     const projectForCwd = (cwd) => {
         if (!cwd)
@@ -290,11 +266,6 @@ export function aggregateSamples(opts = {}) {
             b.stale++;
         else if (r.cache === 'miss' || r.cache === 'none')
             b.misses++;
-        // Exit classes (Claude/Codex PreToolUse convention):
-        //   0 → allowed
-        //   2 → intentional deny/block (not a crash)
-        //   1 / other nonzero → real error
-        // Timeouts are recorded via status, not exit_code, so they don't double-count.
         if (r.status === 'timeout')
             b.timeouts++;
         else if (typeof r.exit_code === 'number') {