@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/linear-projects.d.ts

@@ -1,42 +1,11 @@
-/** The minimal Linear project shape the link flow needs (id + name + url). */
 export interface LinearProjectLite {
     id: string;
     name: string;
-    /** Project URL, when the `linear` CLI JSON carries one. Never fabricated. */
     url?: string;
 }
-/**
- * Collapse a Linear name / repo slug / folder path to one comparison key:
- * lowercase, keep only the last path segment, strip separators.
- *   "Agents CLI"            -> "agentscli"
- *   "phnx-labs/agents-cli"  -> "agentscli"
- *   "~/src/.../agents-cli"  -> "agentscli"
- */
 export declare function normalizeProjectKey(s: string): string;
-/**
- * Find the Linear project that best matches a repo slug or folder name.
- * Exact normalized match first, then a containment fallback (either direction),
- * so "agents-cli-web" still suggests "Agents CLI" when no exact peer exists.
- *
- * Kept for parity with the Factory original — the `link` command uses
- * {@link pickLinearProject} instead: this one returns the FIRST match (silent
- * on duplicate names), which is fine for a UI suggestion but never for a write
- * path.
- */
 export declare function matchLinearProject(slugOrName: string, projects: LinearProjectLite[]): LinearProjectLite | undefined;
-/**
- * Find the local checkout directory a Linear project name refers to, on EXACT
- * key equality only — never containment. `matchLinearProject`'s containment
- * fallback is right for suggesting a link a human then confirms; this backs
- * `projects import --from-linear`, which writes `root`/`repo` with nobody
- * looking, and "Agents CLI" must not silently bind `agents-cli-web`.
- *
- * Returns `undefined` when nothing matches, and also when SEVERAL dirs key to
- * the same value (`agents-cli` and `agents_cli`) — an ambiguous match is not a
- * match.
- */
 export declare function matchLocalCheckoutExact(name: string, dirNames: string[]): string | undefined;
-/** The outcome of picking one Linear project out of the workspace list. */
 export type LinearPick = {
     kind: 'match';
     project: LinearProjectLite;
@@ -46,39 +15,8 @@ export type LinearPick = {
 } | {
     kind: 'none';
 };
-/**
- * Pick the Linear project a query refers to. An exact id or exact normalized
- * name match is confident enough to write; anything weaker (several exact-name
- * peers, or only containment matches) comes back as a candidate LIST for the
- * user to disambiguate — the link command never guesses on a weak signal.
- */
 export declare function pickLinearProject(query: string, projects: LinearProjectLite[]): LinearPick;
-/**
- * List the workspace's Linear projects via the `linear` CLI on PATH. Throws a
- * clear error when the binary is missing, errors, or returns a shape we can't
- * use — this backs an explicit user command, so a silent empty list would send
- * the user down a wrong "no matches" path.
- */
 export declare function listLinearProjects(): LinearProjectLite[];
-/**
- * The `linear` block a def should carry after binding it to `project`.
- *
- * Pure so the write rule is testable without a `linear` CLI or a filesystem —
- * `agents projects link` is the only caller and does nothing else to the field.
- *
- * Two rules, both learned from real drift:
- *
- * - `name` is REFRESHED, never merely preserved. It used to be written by
- *   spreading `prior`, so a project renamed on the board kept its old label in
- *   the YAML forever — and that label is what the status card, the AGI EXT
- *   Fleet panel (`linearProjectName`), and agents naming the work all read.
- * - `url` is dropped when the projectId CHANGES and the incoming row has none.
- *   Carrying it over would leave a def pointing at the previous project's page
- *   beside the new project's name, and the status card prefers `url` over the
- *   id — so the one field a reader clicks would go to the wrong project.
- *   Re-linking the SAME id keeps a previously stored url, since the CLI's list
- *   row omitting `url` says nothing about whether the project has one.
- */
 export declare function nextLinearLink(prior: {
     projectId?: string;
     url?: string;

package/dist/lib/linear-projects.js

@@ -1,38 +1,8 @@
-// Linear project matching for `agents projects link --linear`.
-//
-// A project's identity shows up three ways — a Linear project name ("Agents CLI"),
-// a GitHub repo slug ("phnx-labs/agents-cli"), and a filesystem folder
-// (".../agents-cli"). normalizeProjectKey() collapses all three to one comparison
-// key so they compare equal, and matchLinearProject() binds a repo/folder to the
-// Linear project the user most likely means.
-//
-// Ported from apps/ext/src/core/linearProjects.ts (no cross-package imports —
-// repo rule); keep the two in sync. The matcher half is PURE so it unit-tests
-// without a live `linear` binary; the `linear projects --json` shell-out lives at
-// the bottom (listLinearProjects) and fails LOUD — it's behind an explicit user
-// command, not a best-effort card enrichment.
 import { execFileSync } from 'child_process';
-/**
- * Collapse a Linear name / repo slug / folder path to one comparison key:
- * lowercase, keep only the last path segment, strip separators.
- *   "Agents CLI"            -> "agentscli"
- *   "phnx-labs/agents-cli"  -> "agentscli"
- *   "~/src/.../agents-cli"  -> "agentscli"
- */
 export function normalizeProjectKey(s) {
     const last = s.toLowerCase().split('/').filter(Boolean).pop() ?? '';
     return last.replace(/[-_\s.]/g, '');
 }
-/**
- * Find the Linear project that best matches a repo slug or folder name.
- * Exact normalized match first, then a containment fallback (either direction),
- * so "agents-cli-web" still suggests "Agents CLI" when no exact peer exists.
- *
- * Kept for parity with the Factory original — the `link` command uses
- * {@link pickLinearProject} instead: this one returns the FIRST match (silent
- * on duplicate names), which is fine for a UI suggestion but never for a write
- * path.
- */
 export function matchLinearProject(slugOrName, projects) {
     const key = normalizeProjectKey(slugOrName);
     if (!key)
@@ -45,29 +15,9 @@ export function matchLinearProject(slugOrName, projects) {
         return pk.length > 0 && (pk.includes(key) || key.includes(pk));
     });
 }
-/**
- * Collapse a Linear **display name** or a directory basename to one comparison
- * key. Deliberately NOT `normalizeProjectKey`: that one keeps only the segment
- * after the last `/`, which is right for an `owner/repo` slug or a filesystem
- * path and wrong for a display name, where `/` is ordinary punctuation. Keying
- * "Rush / Web" the path way yields `web`, which exact-matches an unrelated
- * `web/` checkout — the precise silent mis-binding this whole match path exists
- * to prevent.
- */
 function checkoutMatchKey(s) {
     return s.toLowerCase().replace(/[^a-z0-9]+/g, '');
 }
-/**
- * Find the local checkout directory a Linear project name refers to, on EXACT
- * key equality only — never containment. `matchLinearProject`'s containment
- * fallback is right for suggesting a link a human then confirms; this backs
- * `projects import --from-linear`, which writes `root`/`repo` with nobody
- * looking, and "Agents CLI" must not silently bind `agents-cli-web`.
- *
- * Returns `undefined` when nothing matches, and also when SEVERAL dirs key to
- * the same value (`agents-cli` and `agents_cli`) — an ambiguous match is not a
- * match.
- */
 export function matchLocalCheckoutExact(name, dirNames) {
     const key = checkoutMatchKey(name);
     if (!key)
@@ -75,12 +25,6 @@ export function matchLocalCheckoutExact(name, dirNames) {
     const hits = dirNames.filter((d) => checkoutMatchKey(d) === key);
     return hits.length === 1 ? hits[0] : undefined;
 }
-/**
- * Pick the Linear project a query refers to. An exact id or exact normalized
- * name match is confident enough to write; anything weaker (several exact-name
- * peers, or only containment matches) comes back as a candidate LIST for the
- * user to disambiguate — the link command never guesses on a weak signal.
- */
 export function pickLinearProject(query, projects) {
     const q = query.trim();
     if (!q)
@@ -102,12 +46,6 @@ export function pickLinearProject(query, projects) {
     });
     return containment.length > 0 ? { kind: 'candidates', projects: containment } : { kind: 'none' };
 }
-/**
- * List the workspace's Linear projects via the `linear` CLI on PATH. Throws a
- * clear error when the binary is missing, errors, or returns a shape we can't
- * use — this backs an explicit user command, so a silent empty list would send
- * the user down a wrong "no matches" path.
- */
 export function listLinearProjects() {
     let out;
     try {
@@ -142,31 +80,8 @@ export function listLinearProjects() {
         return [];
     });
 }
-/**
- * The `linear` block a def should carry after binding it to `project`.
- *
- * Pure so the write rule is testable without a `linear` CLI or a filesystem —
- * `agents projects link` is the only caller and does nothing else to the field.
- *
- * Two rules, both learned from real drift:
- *
- * - `name` is REFRESHED, never merely preserved. It used to be written by
- *   spreading `prior`, so a project renamed on the board kept its old label in
- *   the YAML forever — and that label is what the status card, the AGI EXT
- *   Fleet panel (`linearProjectName`), and agents naming the work all read.
- * - `url` is dropped when the projectId CHANGES and the incoming row has none.
- *   Carrying it over would leave a def pointing at the previous project's page
- *   beside the new project's name, and the status card prefers `url` over the
- *   id — so the one field a reader clicks would go to the wrong project.
- *   Re-linking the SAME id keeps a previously stored url, since the CLI's list
- *   row omitting `url` says nothing about whether the project has one.
- */
 export function nextLinearLink(prior, project) {
     const next = { projectId: project.id, name: project.name };
-    // A stored url is kept ONLY when the prior block names the same project. Not
-    // `prior.projectId && prior.projectId !== id`: `projects add --linear <url>`
-    // writes `{ url }` with no projectId at all, and treating that as "same
-    // project" carried a url belonging to whatever the user had pasted.
     const url = project.url ?? (prior?.projectId === project.id ? prior?.url : undefined);
     if (url)
         next.url = url;

package/dist/lib/linear-rate-limit.d.ts

@@ -1,26 +1,5 @@
-/** One hour, the window Linear's request quota is measured over. */
 export declare const LINEAR_RATE_WINDOW_MS: number;
-/**
- * The shared proactive budget, one key's requests per rolling hour. Deliberately
- * under Linear's hard 2500/hr so it leaves headroom for a human using the key and
- * absorbs the concurrent check-then-create overshoot (at most N-1 for N racing
- * agents) without ever reaching a real 429.
- */
 export declare const LINEAR_HOURLY_REQUEST_BUDGET = 2400;
 export declare function setLinearRateLimitDirForTest(dir: string | null): string | null;
-/**
- * Count this key's requests inside the rolling window, sweeping elapsed stamp
- * files as it goes (they can only accumulate at the rate requests are issued, and
- * this is the one place that already lists them). Pure read otherwise.
- */
 export declare function linearRequestsInWindow(apiKey: string, nowMs?: number): number;
-/**
- * Try to reserve one Linear request against the shared hourly budget.
- *
- * Returns `true` and records the reservation when there is room, `false` when the
- * budget is exhausted — the caller then serves the cache instead of spending a
- * request that would 429. The write is a single empty file whose NAME carries the
- * whole record, so a concurrent reserver can neither clobber it nor be clobbered
- * by it.
- */
 export declare function reserveLinearRequest(apiKey: string, nowMs?: number): boolean;

package/dist/lib/linear-rate-limit.js

@@ -1,73 +1,9 @@
-/**
- * A shared, cross-process request budget for the Linear API — the proactive half
- * of the frugality story `linear-cache.ts` started.
- *
- * Linear meters requests per API KEY at 2500/hr (complexity is 99.999% untouched,
- * so requests are the only budget that binds — see `linear-cache.ts`). The
- * failure this exists to stop: this box routinely runs ~13 agent sessions on ONE
- * key, each a separate short-lived process, and nothing coordinated their
- * spending. `linear-cache.ts` already caches reads and backs off AFTER a 429
- * lands (`isRateLimited`/`noteRateLimited`), but that is reactive — by the time
- * the 429 arrives the budget is already gone and every agent's status update is
- * throttled fleet-wide (PHNX-2310). This adds the missing PROACTIVE gate: before
- * a request goes out, it must fit inside a shared hourly budget, so the N agents
- * degrade to serving the (stale) cache instead of collectively blowing the limit.
- *
- * ## The budget lives in the FILENAMES, and that is the whole design
- *
- * State is on disk, not in memory, because the spenders are separate processes.
- * The obvious shape — one JSON document holding a counter — is read-modify-write,
- * and without a lock two agents reserving at once both read the old count and let
- * the lower write land last, silently under-counting. That is not theoretical
- * here: the triggering condition is a burst of concurrent agents, which is
- * exactly what a fleet drain issues. This is the same race `usage-backoff.ts`
- * documents, and the answer is the same: no shared mutable document.
- *
- * Each reserved request is its own empty file, `<createdMs>.<pid>.<seq>`, and the
- * count is `readdir().length` after elapsed files (older than the window) are
- * swept. Two concurrent writers create two DIFFERENT files and neither can erase
- * the other, so the count can only be under-read by an in-flight peer that has
- * not yet created its file — never corrupted, and never over-counted. A sliding
- * one-hour window of stamp files is a token bucket whose tokens refill as the
- * oldest requests age out, with no lock on a path every reservation touches.
- *
- * The budget is set BELOW Linear's hard 2500/hr ({@link LINEAR_HOURLY_REQUEST_BUDGET}).
- * Two reasons: it leaves headroom for a human running `projects status` by hand
- * (the CLI is not the only caller of the key), and it absorbs the small
- * check-then-create race — N agents reserving in the same instant can each read
- * `count < budget` and all create, overshooting by at most (N-1). Bounding the
- * budget under the real ceiling keeps that overshoot from ever reaching a real 429.
- *
- * State is per KEY (hashed, so the raw key never lands on disk), because the
- * 2500/hr quota is per key: two different keys spend independently.
- *
- * Scope is per MACHINE. The state lives under `getCacheDir()`
- * (`~/.agents/.cache/`), which is machine-local and NOT fleet-synced — so this
- * budgets the many concurrent agent processes on one box against each other, the
- * case that actually exhausted the key (~13 sessions on one machine). Two
- * different boxes sharing the same key each keep their own budget, so their
- * aggregate can still exceed 2500/hr; coordinating the budget across devices
- * (a synced or served counter) is a known limitation, not yet built.
- */
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
-/** One hour, the window Linear's request quota is measured over. */
 export const LINEAR_RATE_WINDOW_MS = 60 * 60 * 1000;
-/**
- * The shared proactive budget, one key's requests per rolling hour. Deliberately
- * under Linear's hard 2500/hr so it leaves headroom for a human using the key and
- * absorbs the concurrent check-then-create overshoot (at most N-1 for N racing
- * agents) without ever reaching a real 429.
- */
 export const LINEAR_HOURLY_REQUEST_BUDGET = 2400;
-/**
- * Test seam, mirroring `setUsageBackoffDirForTest`. The cache dir resolves `HOME`
- * once at import time, so a test that swaps `process.env.HOME` afterwards would
- * otherwise read and WRITE the developer's real cache and throttle their own
- * Linear reads. Returns the previous value so a test can restore it.
- */
 let rateLimitDirOverride = null;
 export function setLinearRateLimitDirForTest(dir) {
     const prev = rateLimitDirOverride;
@@ -77,16 +13,10 @@ export function setLinearRateLimitDirForTest(dir) {
 function rateLimitRoot() {
     return rateLimitDirOverride ?? path.join(getCacheDir(), 'linear-rate-limit');
 }
-/**
- * Per-key directory. The key is hashed so the raw credential never touches disk;
- * a short hex prefix is collision-safe enough for the handful of keys one fleet
- * uses and keeps the path short.
- */
 function keyDir(apiKey) {
     const hash = crypto.createHash('sha256').update(apiKey).digest('hex').slice(0, 16);
     return path.join(rateLimitRoot(), hash);
 }
-/** Parse `<createdMs>.<pid>.<seq>` back to its creation instant, or null if it is not one of ours. */
 function createdMsOf(name) {
     const first = name.indexOf('.');
     if (first <= 0)
@@ -97,11 +27,6 @@ function createdMsOf(name) {
     const n = Number(head);
     return Number.isFinite(n) ? n : null;
 }
-/**
- * Count this key's requests inside the rolling window, sweeping elapsed stamp
- * files as it goes (they can only accumulate at the rate requests are issued, and
- * this is the one place that already lists them). Pure read otherwise.
- */
 export function linearRequestsInWindow(apiKey, nowMs = Date.now()) {
     const dir = keyDir(apiKey);
     let names;
@@ -109,7 +34,7 @@ export function linearRequestsInWindow(apiKey, nowMs = Date.now()) {
         names = fs.readdirSync(dir);
     }
     catch {
-        return 0; // no directory yet — nothing spent
+        return 0;
     }
     const cutoff = nowMs - LINEAR_RATE_WINDOW_MS;
     let live = 0;
@@ -122,7 +47,6 @@ export function linearRequestsInWindow(apiKey, nowMs = Date.now()) {
                 fs.rmSync(path.join(dir, name), { force: true });
             }
             catch {
-                /* another process may have swept it already */
             }
         }
         else {
@@ -132,32 +56,16 @@ export function linearRequestsInWindow(apiKey, nowMs = Date.now()) {
     return live;
 }
 let reserveSeq = 0;
-/**
- * Try to reserve one Linear request against the shared hourly budget.
- *
- * Returns `true` and records the reservation when there is room, `false` when the
- * budget is exhausted — the caller then serves the cache instead of spending a
- * request that would 429. The write is a single empty file whose NAME carries the
- * whole record, so a concurrent reserver can neither clobber it nor be clobbered
- * by it.
- */
 export function reserveLinearRequest(apiKey, nowMs = Date.now()) {
     if (linearRequestsInWindow(apiKey, nowMs) >= LINEAR_HOURLY_REQUEST_BUDGET)
         return false;
     const dir = keyDir(apiKey);
     try {
         fs.mkdirSync(dir, { recursive: true });
-        // `<createdMs>.<pid>.<seq>`: pid separates processes, the in-process counter
-        // separates two reservations in the same millisecond, so the name is unique
-        // without a lock or a random token. Empty contents — the name is the record.
         fs.writeFileSync(path.join(dir, `${nowMs}.${process.pid}.${reserveSeq++}`), '');
         return true;
     }
     catch {
-        // An unwritable cache dir costs the cross-process budget, not correctness: if
-        // we cannot record the reservation we still let the request through rather
-        // than blocking a caller on a broken cache dir. The reactive 429 backoff in
-        // linear-cache.ts remains the backstop.
         return true;
     }
 }

package/dist/lib/linux-userns.d.ts

@@ -1,57 +1,16 @@
-/** Path of the AppArmor knob that gates unprivileged userns on Ubuntu 23.10+. */
 export declare const APPARMOR_USERNS_SYSCTL_PATH = "/proc/sys/kernel/apparmor_restrict_unprivileged_userns";
-export type UsernsState = 
-/** A new user namespace with a uid map can be created — Codex's sandbox works. */
-'ok'
-/** Unprivileged userns is restricted — Codex's bwrap sandbox cannot start. */
- | 'blocked'
-/** Could not determine (non-Linux, or the probe could not run). */
- | 'unknown';
+export type UsernsState = 'ok' | 'blocked' | 'unknown';
 export interface UsernsStatus {
     state: UsernsState;
-    /** One-line human reason, present when `blocked` or `unknown`. */
     reason?: string;
 }
-/** The raw signals the pure interpreter reasons over. */
 interface UsernsInputs {
     platform: NodeJS.Platform;
-    /**
-     * Contents of {@link APPARMOR_USERNS_SYSCTL_PATH} trimmed, or null when the
-     * file is absent (older kernels / no AppArmor userns mediation).
-     */
     apparmorRestrict: string | null;
-    /**
-     * Result of actually attempting to create a user namespace with a uid map:
-     *   - 'ok'      → the probe created the namespace and mapped root.
-     *   - 'denied'  → the kernel refused the uid_map write (the restricted case).
-     *   - 'no-tool' → the probe binary (`unshare`) was missing or failed to spawn.
-     */
     unshareProbe: 'ok' | 'denied' | 'no-tool';
 }
-/**
- * Decide userns availability from raw signals. Pure — no I/O.
- *
- * The definitive signal is the actual probe: if we successfully created a userns
- * and wrote a uid map, the sandbox works regardless of the sysctl (an AppArmor
- * profile may grant a specific binary `userns` even while the global knob is 1).
- * A denied probe is a hard `blocked`. When the probe tool is missing we fall back
- * to the sysctl: `1` → `blocked`, `0`/absent → `unknown` (we could not prove it,
- * and refuse to claim `ok` we did not observe).
- */
 export declare function interpretUsernsInputs(inputs: UsernsInputs): UsernsStatus;
-/** Read the AppArmor userns sysctl, or null when the file is absent. */
 export declare function readApparmorRestrict(sysctlPath?: string): string | null;
-/**
- * Actually try to create a user namespace and map root inside it — the same
- * operation bwrap performs (`unshare --user --map-root-user`). This is the ground
- * truth: it observes exactly what the kernel/AppArmor policy permits for *this*
- * process, rather than inferring from the sysctl alone.
- */
 export declare function probeUnshare(): 'ok' | 'denied' | 'no-tool';
-/**
- * Resolve whether an unprivileged user namespace can be created on this host,
- * cached for the process (the answer is a stable property of the box). Non-Linux
- * short-circuits to `ok` without spawning anything.
- */
 export declare function probeUnprivilegedUserns(platform?: NodeJS.Platform): UsernsStatus;
 export {};

package/dist/lib/linux-userns.js

@@ -1,38 +1,6 @@
-/**
- * Unprivileged user-namespace availability on Linux — the capability Codex's
- * Linux sandbox needs, and the one Ubuntu 23.10+ restricts by default.
- *
- * Codex ≥0.146 implements its `read-only` and `workspace-write` sandbox modes on
- * Linux with a bundled **bubblewrap** (`bwrap`), extracted per-run to
- * `$CODEX_HOME/tmp/arg0/codex-XXXX/` and exec'd from a memfd. bwrap sets up its
- * mounts inside a fresh **unprivileged user namespace** (`--unshare-user`, then a
- * write to `/proc/self/uid_map`). Ubuntu 24.04 ships
- * `kernel.apparmor_restrict_unprivileged_userns=1`, which denies that to an
- * unconfined binary — so bwrap dies with `bwrap: setting up uid map: Permission
- * denied` and a headless Codex run lands zero tools (no file writes, no shell).
- * `danger-full-access` (our `skip` mode) drops the sandbox and is the only mode
- * that avoids bwrap; the legacy Landlock backend is gone (`use_linux_sandbox_bwrap`
- * is `removed`, `use_legacy_landlock` panics under the permission-profile model).
- *
- * This module is the single detector. It is pure at its core
- * ({@link interpretUsernsInputs}) so the decision is unit-testable without a
- * shell, and {@link probeUnprivilegedUserns} gathers the real inputs once per
- * process. See PHNX-3285.
- */
 import { execFileSync } from 'child_process';
 import * as fs from 'fs';
-/** Path of the AppArmor knob that gates unprivileged userns on Ubuntu 23.10+. */
 export const APPARMOR_USERNS_SYSCTL_PATH = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns';
-/**
- * Decide userns availability from raw signals. Pure — no I/O.
- *
- * The definitive signal is the actual probe: if we successfully created a userns
- * and wrote a uid map, the sandbox works regardless of the sysctl (an AppArmor
- * profile may grant a specific binary `userns` even while the global knob is 1).
- * A denied probe is a hard `blocked`. When the probe tool is missing we fall back
- * to the sysctl: `1` → `blocked`, `0`/absent → `unknown` (we could not prove it,
- * and refuse to claim `ok` we did not observe).
- */
 export function interpretUsernsInputs(inputs) {
     if (inputs.platform !== 'linux')
         return { state: 'ok' };
@@ -47,7 +15,6 @@ export function interpretUsernsInputs(inputs) {
             reason: `the kernel denied creating an unprivileged user namespace${via}`,
         };
     }
-    // Probe tool unavailable — lean on the AppArmor knob.
     if (inputs.apparmorRestrict === '1') {
         return {
             state: 'blocked',
@@ -60,7 +27,6 @@ export function interpretUsernsInputs(inputs) {
         reason: '`unshare` was not available to probe user-namespace support',
     };
 }
-/** Read the AppArmor userns sysctl, or null when the file is absent. */
 export function readApparmorRestrict(sysctlPath = APPARMOR_USERNS_SYSCTL_PATH) {
     try {
         return fs.readFileSync(sysctlPath, 'utf8').trim();
@@ -69,12 +35,6 @@ export function readApparmorRestrict(sysctlPath = APPARMOR_USERNS_SYSCTL_PATH) {
         return null;
     }
 }
-/**
- * Actually try to create a user namespace and map root inside it — the same
- * operation bwrap performs (`unshare --user --map-root-user`). This is the ground
- * truth: it observes exactly what the kernel/AppArmor policy permits for *this*
- * process, rather than inferring from the sysctl alone.
- */
 export function probeUnshare() {
     try {
         execFileSync('unshare', ['--user', '--map-root-user', 'true'], {
@@ -84,8 +44,6 @@ export function probeUnshare() {
         return 'ok';
     }
     catch (err) {
-        // ENOENT / spawn failure → the tool isn't here; anything else (nonzero exit
-        // from the denied uid_map write) is the restricted case.
         const code = err?.code;
         if (code === 'ENOENT')
             return 'no-tool';
@@ -93,11 +51,6 @@ export function probeUnshare() {
     }
 }
 let cached = null;
-/**
- * Resolve whether an unprivileged user namespace can be created on this host,
- * cached for the process (the answer is a stable property of the box). Non-Linux
- * short-circuits to `ok` without spawning anything.
- */
 export function probeUnprivilegedUserns(platform = process.platform) {
     if (platform !== 'linux')
         return { state: 'ok' };

package/dist/lib/lock-compromise.d.ts

@@ -1,8 +1 @@
-/**
- * proper-lockfile invokes this callback from its background refresh timer.
- * Its default is to throw there, outside the caller's promise chain, which can
- * terminate the daemon. These leases are advisory serialization barriers: log
- * a broken lease and let the owning operation finish instead of crashing the
- * shared process.
- */
 export declare function logAndContinueOnLockCompromised(scope: string): (err: Error) => void;

package/dist/lib/lock-compromise.js

@@ -1,10 +1,3 @@
-/**
- * proper-lockfile invokes this callback from its background refresh timer.
- * Its default is to throw there, outside the caller's promise chain, which can
- * terminate the daemon. These leases are advisory serialization barriers: log
- * a broken lease and let the owning operation finish instead of crashing the
- * shared process.
- */
 export function logAndContinueOnLockCompromised(scope) {
     return (err) => {
         console.warn(`[agents ${scope}] Lock was compromised; continuing without crashing: ${err.message}`);

package/dist/lib/log-follow.d.ts

@@ -1,7 +1,5 @@
 export interface FollowOptions {
-    /** Poll interval in milliseconds (default 500). */
     intervalMs?: number;
-    /** Start at the current end of file (skip existing content). Default false. */
     fromEnd?: boolean;
 }
 export declare function followFile(filePath: string, onChunk: (text: string) => void, opts?: FollowOptions): () => void;

package/dist/lib/log-follow.js

@@ -1,13 +1,3 @@
-/**
- * Cross-platform `tail -f`.
- *
- * Replaces spawning the POSIX `tail` binary (absent on Windows) with a poll-based
- * follower that behaves identically on every platform and needs no external
- * dependency. Reads bytes appended since the last position every `intervalMs`;
- * resets to 0 if the file shrinks (truncation / log rotation). The active timer
- * keeps the event loop alive, so callers just register a SIGINT handler that
- * calls the returned stop().
- */
 import * as fs from 'fs';
 export function followFile(filePath, onChunk, opts = {}) {
     const intervalMs = opts.intervalMs ?? 500;
@@ -27,7 +17,7 @@ export function followFile(filePath, onChunk, opts = {}) {
                 onChunk(initial.toString('utf-8'));
             pos = initial.length;
         }
-        catch { /* file may not exist yet — start at 0 and wait for it to appear */ }
+        catch { }
     }
     const poll = () => {
         let size;
@@ -35,10 +25,10 @@ export function followFile(filePath, onChunk, opts = {}) {
             size = fs.statSync(filePath).size;
         }
         catch {
-            return; /* gone / not yet created */
+            return;
         }
         if (size < pos)
-            pos = 0; // truncated or rotated — re-read from the top
+            pos = 0;
         if (size <= pos)
             return;
         let fd;
@@ -50,13 +40,13 @@ export function followFile(filePath, onChunk, opts = {}) {
             if (bytes > 0)
                 onChunk(buf.subarray(0, bytes).toString('utf-8'));
         }
-        catch { /* transient read error — retry next tick */ }
+        catch { }
         finally {
             if (fd !== undefined) {
                 try {
                     fs.closeSync(fd);
                 }
-                catch { /* noop */ }
+                catch { }
             }
         }
     };