@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/teams/worktree.d.ts

@@ -1,109 +1,14 @@
-/**
- * Check if `dir` is inside a git repository (**async, worktree-correct**).
- *
- * Shells out to `git rev-parse --git-dir`, so it returns true from any
- * subdirectory and for linked worktrees. Distinct from the synchronous,
- * root-only `isGitRepo` in `lib/git.ts` (a `.git`-existence check): different
- * semantics, so the two are intentionally **not** merged.
- */
 export declare function isGitRepo(dir: string): Promise<boolean>;
 export declare function getGitRoot(dir: string): Promise<string>;
-/**
- * Check if a worktree directory has uncommitted changes.
- */
 export declare function hasUncommittedChanges(worktreePath: string): Promise<boolean>;
-/**
- * Resolve the repo's default branch name (origin/HEAD → `main`/`master`/…).
- * Refreshes origin/HEAD first so a repo cloned before the default was set resolves.
- * Falls back to `main` when origin/HEAD isn't set.
- */
 export declare function localDefaultBranch(gitRoot: string): Promise<string>;
-/**
- * How many commits the checkout at `repoDir` is behind freshly-fetched
- * `origin/<default>` — the staleness the `teams add` guard checks before pointing
- * a team at a repo.
- *
- * Fetches `origin` FIRST, on purpose: the exact failure this guards (a team
- * pointed at a repo "without fetching first" — a 71-commit-stale s1 checkout in
- * the real incident) leaves the remote-tracking ref itself stale, so a naive
- * `HEAD..origin/<default>` reads 0 and hides the drift. After the fetch the count
- * is against the true remote.
- *
- * Measures the passed checkout's OWN root ({@link getGitRoot} / `--show-toplevel`,
- * worktree-correct) — NOT {@link getMainRepoRoot}: for a `--use-worktree` shared
- * worktree (or a caller standing inside a linked worktree), the teammate runs in
- * THAT worktree, whose HEAD differs from the main checkout's, so folding to the
- * main root would report the wrong tree's staleness. `origin/<default>` resolves
- * from the shared object store regardless of which worktree we stand in. Returns
- * null when `repoDir` isn't a git repo, origin is unreachable, or git errors — the
- * caller treats null as "can't tell, don't block".
- */
 export declare function commitsBehindDefault(repoDir: string): Promise<{
     behind: number;
     base: string;
 } | null>;
-/**
- * Create a new git worktree for a teammate, branched off the freshly-fetched
- * default branch. Fetches `origin` first and bases the branch on
- * `origin/<default>` so a stale local checkout cannot fork teammates off old
- * code. Matches `createRemoteWorktree` — local and remote isolation share one
- * base policy.
- *
- * Resolves the placement root with {@link getMainRepoRoot}, NOT the local
- * `getGitRoot`/`--show-toplevel`, on purpose: when `repoDir` (the caller's
- * ambient cwd) is itself inside another teammate's linked worktree,
- * `--show-toplevel` returns THAT worktree's own root, so the new worktree
- * lands nested inside it (observed: `.../worktrees/A/.agents/worktrees/B`,
- * destroyed along with A's cleanup). `getMainRepoRoot` follows
- * `--git-common-dir`, which always points at the primary checkout's `.git`
- * regardless of which worktree the caller is standing in.
- *
- * @param repoDir - Directory inside the git repository (main checkout or any linked worktree)
- * @param worktreeName - Name for the worktree (used in path and branch)
- * @returns The absolute path to the created worktree
- */
 export declare function createWorktree(repoDir: string, worktreeName: string): Promise<string>;
-/**
- * Remove a git worktree and optionally its branch.
- *
- * Resolves via {@link getMainRepoRoot}, same as {@link createWorktree} — a
- * caller standing inside a DIFFERENT linked worktree (e.g. a `teams stop`
- * run from within another teammate's checkout) must still target the main
- * repo's `.agents/worktrees/<name>`, not `--show-toplevel`'s local answer.
- *
- * @param repoDir - Directory inside the git repository (main checkout or any linked worktree)
- * @param worktreeName - Name of the worktree to remove
- * @param deleteBranch - Whether to delete the associated branch
- */
 export declare function removeWorktree(repoDir: string, worktreeName: string, deleteBranch?: boolean): Promise<void>;
-/**
- * Get the worktree path for a given name.
- */
 export declare function getWorktreePath(gitRoot: string, worktreeName: string): string;
-/**
- * Get the branch name for a worktree.
- */
 export declare function getWorktreeBranch(worktreeName: string): string;
-/**
- * Does the CHECKOUT DIRECTORY for this worktree name exist?
- *
- * Narrower than {@link worktreeExists}, and the difference is load-bearing:
- * `teams add` only ever cleans up after a failed create when there is NO
- * checkout — i.e. when all that can be left is a dangling `agents/<name>`
- * branch ref. That keeps the cleanup incapable of deleting anybody's files,
- * including a concurrent add's freshly-created worktree, whatever the
- * pre-flight probe saw a `git fetch` ago. (RUSH-2356)
- */
 export declare function worktreeCheckoutExists(repoDir: string, worktreeName: string): Promise<boolean>;
-/**
- * Does anything already exist under this worktree name — the checkout directory
- * or its `agents/<name>` branch?
- *
- * Answered from git and the filesystem, never from teammate records: it is asked
- * by `teams add` immediately BEFORE {@link createWorktree}, so that if the create
- * fails the command can tell "the branch ref I half-created" (safe to remove)
- * from "something that was already here" (never remove — `teams stop` deliberately
- * KEEPS a worktree holding uncommitted changes, and its teammate record is
- * terminal by then, so no record-based check can protect it). (RUSH-2356)
- */
 export declare function worktreeExists(repoDir: string, worktreeName: string): Promise<boolean>;

package/dist/lib/teams/worktree.js

@@ -1,9 +1,3 @@
-/**
- * Git worktree utilities for isolated agent execution.
- *
- * Creates/removes temporary worktrees so each teammate can work on
- * its own branch without interfering with others or the main checkout.
- */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as fs from 'fs/promises';
@@ -12,14 +6,6 @@ import { safeJoin } from '../paths.js';
 import { getMainRepoRoot } from '../git.js';
 const execFileAsync = promisify(execFile);
 const WORKTREE_NAME_RE = /^[A-Za-z0-9_-]+$/;
-/**
- * Check if `dir` is inside a git repository (**async, worktree-correct**).
- *
- * Shells out to `git rev-parse --git-dir`, so it returns true from any
- * subdirectory and for linked worktrees. Distinct from the synchronous,
- * root-only `isGitRepo` in `lib/git.ts` (a `.git`-existence check): different
- * semantics, so the two are intentionally **not** merged.
- */
 export async function isGitRepo(dir) {
     try {
         await execFileAsync('git', ['rev-parse', '--git-dir'], { cwd: dir });
@@ -33,9 +19,6 @@ export async function getGitRoot(dir) {
     const { stdout } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], { cwd: dir });
     return stdout.trim();
 }
-/**
- * Check if a worktree directory has uncommitted changes.
- */
 export async function hasUncommittedChanges(worktreePath) {
     try {
         const { stdout } = await execFileAsync('git', ['status', '--porcelain'], { cwd: worktreePath });
@@ -45,17 +28,11 @@ export async function hasUncommittedChanges(worktreePath) {
         return false;
     }
 }
-/**
- * Resolve the repo's default branch name (origin/HEAD → `main`/`master`/…).
- * Refreshes origin/HEAD first so a repo cloned before the default was set resolves.
- * Falls back to `main` when origin/HEAD isn't set.
- */
 export async function localDefaultBranch(gitRoot) {
     try {
         await execFileAsync('git', ['remote', 'set-head', 'origin', '--auto'], { cwd: gitRoot });
     }
     catch {
-        // Offline / no origin — fall through to symbolic-ref or main.
     }
     try {
         const { stdout } = await execFileAsync('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], { cwd: gitRoot });
@@ -64,30 +41,9 @@ export async function localDefaultBranch(gitRoot) {
             return base;
     }
     catch {
-        // no origin/HEAD
     }
     return 'main';
 }
-/**
- * How many commits the checkout at `repoDir` is behind freshly-fetched
- * `origin/<default>` — the staleness the `teams add` guard checks before pointing
- * a team at a repo.
- *
- * Fetches `origin` FIRST, on purpose: the exact failure this guards (a team
- * pointed at a repo "without fetching first" — a 71-commit-stale s1 checkout in
- * the real incident) leaves the remote-tracking ref itself stale, so a naive
- * `HEAD..origin/<default>` reads 0 and hides the drift. After the fetch the count
- * is against the true remote.
- *
- * Measures the passed checkout's OWN root ({@link getGitRoot} / `--show-toplevel`,
- * worktree-correct) — NOT {@link getMainRepoRoot}: for a `--use-worktree` shared
- * worktree (or a caller standing inside a linked worktree), the teammate runs in
- * THAT worktree, whose HEAD differs from the main checkout's, so folding to the
- * main root would report the wrong tree's staleness. `origin/<default>` resolves
- * from the shared object store regardless of which worktree we stand in. Returns
- * null when `repoDir` isn't a git repo, origin is unreachable, or git errors — the
- * caller treats null as "can't tell, don't block".
- */
 export async function commitsBehindDefault(repoDir) {
     const gitRoot = await getGitRoot(repoDir).catch(() => null);
     if (!gitRoot)
@@ -96,7 +52,7 @@ export async function commitsBehindDefault(repoDir) {
         await execFileAsync('git', ['fetch', 'origin'], { cwd: gitRoot });
     }
     catch {
-        return null; // offline / no origin — can't assess staleness, don't block a team.
+        return null;
     }
     const base = await localDefaultBranch(gitRoot);
     try {
@@ -107,29 +63,9 @@ export async function commitsBehindDefault(repoDir) {
         return { behind, base };
     }
     catch {
-        return null; // no origin/<default> tracking ref, detached probe, etc.
+        return null;
     }
 }
-/**
- * Create a new git worktree for a teammate, branched off the freshly-fetched
- * default branch. Fetches `origin` first and bases the branch on
- * `origin/<default>` so a stale local checkout cannot fork teammates off old
- * code. Matches `createRemoteWorktree` — local and remote isolation share one
- * base policy.
- *
- * Resolves the placement root with {@link getMainRepoRoot}, NOT the local
- * `getGitRoot`/`--show-toplevel`, on purpose: when `repoDir` (the caller's
- * ambient cwd) is itself inside another teammate's linked worktree,
- * `--show-toplevel` returns THAT worktree's own root, so the new worktree
- * lands nested inside it (observed: `.../worktrees/A/.agents/worktrees/B`,
- * destroyed along with A's cleanup). `getMainRepoRoot` follows
- * `--git-common-dir`, which always points at the primary checkout's `.git`
- * regardless of which worktree the caller is standing in.
- *
- * @param repoDir - Directory inside the git repository (main checkout or any linked worktree)
- * @param worktreeName - Name for the worktree (used in path and branch)
- * @returns The absolute path to the created worktree
- */
 export async function createWorktree(repoDir, worktreeName) {
     if (!WORKTREE_NAME_RE.test(worktreeName)) {
         throw new Error(`Invalid worktree name: ${worktreeName}`);
@@ -139,9 +75,6 @@ export async function createWorktree(repoDir, worktreeName) {
     const branchName = `agents/${worktreeName}`;
     const base = await localDefaultBranch(gitRoot);
     await fs.mkdir(path.dirname(worktreePath), { recursive: true });
-    // Fetch first so origin/<default> is current. Fail loud on network errors —
-    // silent fallback to HEAD is how swarms write on a days-stale base and only
-    // discover it at merge time.
     try {
         await execFileAsync('git', ['fetch', 'origin'], { cwd: gitRoot });
     }
@@ -154,18 +87,6 @@ export async function createWorktree(repoDir, worktreeName) {
     await execFileAsync('git', ['worktree', 'add', '-b', branchName, worktreePath, `origin/${base}`], { cwd: gitRoot });
     return worktreePath;
 }
-/**
- * Remove a git worktree and optionally its branch.
- *
- * Resolves via {@link getMainRepoRoot}, same as {@link createWorktree} — a
- * caller standing inside a DIFFERENT linked worktree (e.g. a `teams stop`
- * run from within another teammate's checkout) must still target the main
- * repo's `.agents/worktrees/<name>`, not `--show-toplevel`'s local answer.
- *
- * @param repoDir - Directory inside the git repository (main checkout or any linked worktree)
- * @param worktreeName - Name of the worktree to remove
- * @param deleteBranch - Whether to delete the associated branch
- */
 export async function removeWorktree(repoDir, worktreeName, deleteBranch = true) {
     if (!WORKTREE_NAME_RE.test(worktreeName)) {
         throw new Error(`Invalid worktree name: ${worktreeName}`);
@@ -189,35 +110,18 @@ export async function removeWorktree(repoDir, worktreeName, deleteBranch = true)
             await execFileAsync('git', ['branch', '-D', branchName], { cwd: gitRoot });
         }
         catch {
-            // Branch might not exist; ignore
         }
     }
 }
-/**
- * Get the worktree path for a given name.
- */
 export function getWorktreePath(gitRoot, worktreeName) {
     if (!WORKTREE_NAME_RE.test(worktreeName)) {
         throw new Error(`Invalid worktree name: ${worktreeName}`);
     }
     return safeJoin(path.join(gitRoot, '.agents', 'worktrees'), worktreeName);
 }
-/**
- * Get the branch name for a worktree.
- */
 export function getWorktreeBranch(worktreeName) {
     return `agents/${worktreeName}`;
 }
-/**
- * Does the CHECKOUT DIRECTORY for this worktree name exist?
- *
- * Narrower than {@link worktreeExists}, and the difference is load-bearing:
- * `teams add` only ever cleans up after a failed create when there is NO
- * checkout — i.e. when all that can be left is a dangling `agents/<name>`
- * branch ref. That keeps the cleanup incapable of deleting anybody's files,
- * including a concurrent add's freshly-created worktree, whatever the
- * pre-flight probe saw a `git fetch` ago. (RUSH-2356)
- */
 export async function worktreeCheckoutExists(repoDir, worktreeName) {
     if (!WORKTREE_NAME_RE.test(worktreeName)) {
         throw new Error(`Invalid worktree name: ${worktreeName}`);
@@ -226,17 +130,6 @@ export async function worktreeCheckoutExists(repoDir, worktreeName) {
     const dir = safeJoin(path.join(gitRoot, '.agents', 'worktrees'), worktreeName);
     return fs.stat(dir).then(() => true).catch(() => false);
 }
-/**
- * Does anything already exist under this worktree name — the checkout directory
- * or its `agents/<name>` branch?
- *
- * Answered from git and the filesystem, never from teammate records: it is asked
- * by `teams add` immediately BEFORE {@link createWorktree}, so that if the create
- * fails the command can tell "the branch ref I half-created" (safe to remove)
- * from "something that was already here" (never remove — `teams stop` deliberately
- * KEEPS a worktree holding uncommitted changes, and its teammate record is
- * terminal by then, so no record-based check can protect it). (RUSH-2356)
- */
 export async function worktreeExists(repoDir, worktreeName) {
     if (await worktreeCheckoutExists(repoDir, worktreeName))
         return true;
@@ -246,6 +139,6 @@ export async function worktreeExists(repoDir, worktreeName) {
         return true;
     }
     catch {
-        return false; // `--verify` exits non-zero when the ref doesn't exist
+        return false;
     }
 }

package/dist/lib/template.d.ts

@@ -1,25 +1,4 @@
-/**
- * Template resolution utilities.
- * Ported from the legacy agent CLI template helpers.
- *
- * Supports {{artifact.*}} and {{preflight.*}} placeholder patterns used in
- * artifact action input mappings.
- */
-/**
- * Resolve template placeholders with artifact and preflight data.
- * Replaces {{artifact.*}} and {{preflight.*}} patterns.
- *
- * @param tmpl - Template string with placeholders
- * @param artifact - Map of artifact key-value pairs
- * @param preflight - Map of preflight data (can contain strings or string arrays)
- * @returns Resolved template string
- */
 export declare function resolveTemplate(tmpl: string, artifact: Record<string, string>, preflight: Record<string, string | string[] | unknown>): string;
-/**
- * Extract all template variables from a template string.
- * @param tmpl - Template string
- * @returns Object with artifact and preflight variable names
- */
 export declare function extractTemplateVariables(tmpl: string): {
     artifact: string[];
     preflight: string[];

package/dist/lib/template.js

@@ -1,26 +1,8 @@
-/**
- * Template resolution utilities.
- * Ported from the legacy agent CLI template helpers.
- *
- * Supports {{artifact.*}} and {{preflight.*}} placeholder patterns used in
- * artifact action input mappings.
- */
-/**
- * Resolve template placeholders with artifact and preflight data.
- * Replaces {{artifact.*}} and {{preflight.*}} patterns.
- *
- * @param tmpl - Template string with placeholders
- * @param artifact - Map of artifact key-value pairs
- * @param preflight - Map of preflight data (can contain strings or string arrays)
- * @returns Resolved template string
- */
 export function resolveTemplate(tmpl, artifact, preflight) {
     let result = tmpl;
-    // Replace {{artifact.*}}
     result = result.replace(/\{\{artifact\.(\w+)\}\}/g, (_, key) => {
         return artifact[key] ?? '';
     });
-    // Replace {{preflight.*}}
     result = result.replace(/\{\{preflight\.(\w+)\}\}/g, (_, key) => {
         const val = preflight[key];
         if (val === undefined || val === null) {
@@ -36,11 +18,6 @@ export function resolveTemplate(tmpl, artifact, preflight) {
     });
     return result;
 }
-/**
- * Extract all template variables from a template string.
- * @param tmpl - Template string
- * @returns Object with artifact and preflight variable names
- */
 export function extractTemplateVariables(tmpl) {
     const artifact = [];
     const preflight = [];

package/dist/lib/term-client.d.ts

@@ -1,16 +1,9 @@
 export declare const TERM_NOT_INSTALLED_ERROR = "The standalone `term` CLI is not installed. npm i -g @phnx-labs/term-cli";
-/** JSON response envelope from `term`, mirroring the old PTY sidecar's shape. */
 export interface TermResponse {
     ok: boolean;
     error?: string;
     [key: string]: any;
 }
-/**
- * Resolve the `term` binary to exec: `$TERM_BIN` first (exact override, used
- * by tests and by an operator pinning a specific install), else an ordinary
- * PATH lookup. Returns null when neither resolves — the caller must fail loud
- * with {@link TERM_NOT_INSTALLED_ERROR} rather than falling back to anything.
- */
 export declare function resolveTermBin(): string | null;
 export interface TermStartOptions {
     rows?: number;
@@ -18,27 +11,8 @@ export interface TermStartOptions {
     shell?: string;
     cwd?: string;
 }
-/** `term start [-r rows] [-c cols] [-s shell] [-d cwd] --json` → the new session id. */
 export declare function termStart(opts?: TermStartOptions): Promise<TermResponse>;
-/** `term exec <id> <command> --json` — send a command, non-blocking. */
 export declare function termExec(id: string, command: string): Promise<TermResponse>;
-/**
- * `term write <id> <input> --raw --json` — send raw bytes to the session.
- * `--raw` is load-bearing: the caller here always supplies already-literal
- * bytes (e.g. `\x1b[B\r` as real control characters from a JS string), never
- * the `pty write` CLI's `\n`/`\t`/`\e`/`\xHH` textual escape syntax, so `term`
- * must not re-interpret them.
- */
 export declare function termWrite(id: string, input: string): Promise<TermResponse>;
-/** `term screen <id> --json` → `{ screen, exited, cols, rows }`. */
 export declare function termScreen(id: string): Promise<TermResponse>;
-/**
- * `term stop <id>` — end the session and clean up.
- *
- * Unlike every other verb, `stop` has no `--json` mode and prints nothing on
- * success (confirmed against a real built `term` binary — a bare `--json`
- * flag errors `unknown option '--json'`, and success alone leaves stdout
- * empty), so this synthesizes the `{ ok }` envelope from the exit code
- * instead of routing through {@link runTerm}'s stdout-JSON parse.
- */
 export declare function termStop(id: string): Promise<TermResponse>;

package/dist/lib/term-client.js

@@ -1,40 +1,12 @@
-/**
- * `term` client — thin subprocess wrapper over the standalone `term` CLI
- * (published separately as `@phnx-labs/term-cli`), the PTY engine this repo
- * used to own directly (`agents pty`, removed in PHNX-4091). `term` mirrors the
- * old `agents pty` verbs/flags/JSON shapes 1:1 (`start`, `exec`, `read`,
- * `write`, `screen`, `signal`, `resize`, `list`, `stop`, `server start|stop|
- * status`, hidden `_server`) and owns starting/reusing its own background
- * sidecar itself — this client never manages that process, it only shells out
- * to the CLI and parses one line of JSON per call.
- *
- * Resolution order:
- *   1. `$TERM_BIN` — an explicit override (a full path, or a PATH-resolvable
- *      name other than `term`). Sets the exact binary this client execs; the
- *      one legitimate use besides pointing at a real install is a test double.
- *   2. `findInPath('term')` — the ordinary PATH lookup (skips this CLI's own
- *      shims dir, same as every other native-binary resolution in this repo).
- *
- * Neither resolving is the expected state until `@phnx-labs/term-cli` is
- * published and installed — every call fails loud with
- * {@link TERM_NOT_INSTALLED_ERROR} rather than silently no-op'ing.
- */
 import { execFile } from 'node:child_process';
 import { findInPath } from './agent-spec/agents.js';
 export const TERM_NOT_INSTALLED_ERROR = 'The standalone `term` CLI is not installed. npm i -g @phnx-labs/term-cli';
-/**
- * Resolve the `term` binary to exec: `$TERM_BIN` first (exact override, used
- * by tests and by an operator pinning a specific install), else an ordinary
- * PATH lookup. Returns null when neither resolves — the caller must fail loud
- * with {@link TERM_NOT_INSTALLED_ERROR} rather than falling back to anything.
- */
 export function resolveTermBin() {
     const override = process.env.TERM_BIN;
     if (override && override.trim().length > 0)
         return override.trim();
     return findInPath('term');
 }
-/** Run one `term <args>` invocation and parse the trailing JSON line from stdout. */
 function runTerm(args) {
     return new Promise((resolve, reject) => {
         const bin = resolveTermBin();
@@ -48,7 +20,6 @@ function runTerm(args) {
                 reject(new Error(`term ${args[0]} produced no output: ${stderr.toString().trim() || (err ? err.message : 'unknown error')}`));
                 return;
             }
-            // `term` may emit progress on earlier lines; the response is the last line.
             const line = out.split('\n').pop() ?? '';
             try {
                 resolve(JSON.parse(line));
@@ -59,7 +30,6 @@ function runTerm(args) {
         });
     });
 }
-/** `term start [-r rows] [-c cols] [-s shell] [-d cwd] --json` → the new session id. */
 export function termStart(opts = {}) {
     const args = ['start', '--json'];
     if (opts.rows)
@@ -72,33 +42,15 @@ export function termStart(opts = {}) {
         args.push('-d', opts.cwd);
     return runTerm(args);
 }
-/** `term exec <id> <command> --json` — send a command, non-blocking. */
 export function termExec(id, command) {
     return runTerm(['exec', id, command, '--json']);
 }
-/**
- * `term write <id> <input> --raw --json` — send raw bytes to the session.
- * `--raw` is load-bearing: the caller here always supplies already-literal
- * bytes (e.g. `\x1b[B\r` as real control characters from a JS string), never
- * the `pty write` CLI's `\n`/`\t`/`\e`/`\xHH` textual escape syntax, so `term`
- * must not re-interpret them.
- */
 export function termWrite(id, input) {
     return runTerm(['write', id, input, '--raw', '--json']);
 }
-/** `term screen <id> --json` → `{ screen, exited, cols, rows }`. */
 export function termScreen(id) {
     return runTerm(['screen', id, '--json']);
 }
-/**
- * `term stop <id>` — end the session and clean up.
- *
- * Unlike every other verb, `stop` has no `--json` mode and prints nothing on
- * success (confirmed against a real built `term` binary — a bare `--json`
- * flag errors `unknown option '--json'`, and success alone leaves stdout
- * empty), so this synthesizes the `{ ok }` envelope from the exit code
- * instead of routing through {@link runTerm}'s stdout-JSON parse.
- */
 export function termStop(id) {
     return new Promise((resolve, reject) => {
         const bin = resolveTermBin();

package/dist/lib/term-driver.d.ts

@@ -1,4 +1,3 @@
-/** The subset of the `term` CLI a screen-scraping drive loop needs — faked in tests. */
 export interface TermDriver {
     start(opts?: {
         rows?: number;
@@ -12,13 +11,9 @@ export interface TermDriver {
     }>;
     stop(id: string): Promise<void>;
 }
-/** Real driver over the standalone `term` CLI (`./term-client.js`). */
 export declare function defaultTermDriver(): TermDriver;
 export interface DriveOptions {
-    /** Wait after launching before steering / scraping (default 4000ms). */
     initialDelayMs?: number;
-    /** Poll cadence for the scrape loop (default 1000ms). */
     pollMs?: number;
-    /** Overall scrape deadline (default 90000ms). */
     timeoutMs?: number;
 }

package/dist/lib/term-driver.js

@@ -1,12 +1,4 @@
-/**
- * Injectable terminal driver over the standalone `term` CLI.
- *
- * A small seam that lets a flow drive a PTY session — start, exec, write,
- * screen-scrape, stop — through the real `term` CLI in production and a fake in
- * tests. The setup-token mint (`lib/auth-mint.ts`) is the sole consumer today.
- */
 import { termStart, termExec, termWrite, termScreen, termStop } from './term-client.js';
-/** Real driver over the standalone `term` CLI (`./term-client.js`). */
 export function defaultTermDriver() {
     const expectOk = (res, what) => {
         if (!res.ok)

package/dist/lib/terminal/backends/ghostty.d.ts

@@ -1,6 +1,4 @@
 import type { TerminalBackend, SplitDirection } from '../types.js';
-/** AppleScript that opens a Ghostty tab (a window if none is open). */
 export declare function ghosttyTabScript(cwd: string, command: string[]): string;
-/** AppleScript that splits the current Ghostty surface (a window if none is open). */
 export declare function ghosttySplitScript(cwd: string, command: string[], direction: SplitDirection): string;
 export declare const ghosttyBackend: TerminalBackend;

package/dist/lib/terminal/backends/ghostty.js

@@ -1,12 +1,3 @@
-/**
- * Ghostty backend — drives Ghostty (>= 1.3) via AppleScript (`osascript`).
- *
- * Ghostty's `new surface configuration` record carries the working directory and
- * command natively, so no `cd` wrapper is needed. Tab: `new tab` (or a window
- * when none is open). Split: `split <surface> direction right|down`, where the
- * current surface is `focused terminal of selected tab of front window`
- * (verified against Ghostty 1.3.1 — a surface is a "terminal" in its AS model).
- */
 import * as fs from 'fs';
 import { appleScriptStr } from '../quote.js';
 import { execOnly, iLoginShell } from '../shell.js';
@@ -19,7 +10,6 @@ function appExists(p) {
         return false;
     }
 }
-/** Shared prologue: activate + a surface configuration carrying cwd + command. */
 function configPrologue(cwd, command) {
     const cmd = appleScriptStr(iLoginShell(execOnly(command)));
     return [
@@ -30,7 +20,6 @@ function configPrologue(cwd, command) {
         `  set command of cfg to ${cmd}`,
     ];
 }
-/** AppleScript that opens a Ghostty tab (a window if none is open). */
 export function ghosttyTabScript(cwd, command) {
     return [
         ...configPrologue(cwd, command),
@@ -42,7 +31,6 @@ export function ghosttyTabScript(cwd, command) {
         'end tell',
     ].join('\n');
 }
-/** AppleScript that splits the current Ghostty surface (a window if none is open). */
 export function ghosttySplitScript(cwd, command, direction) {
     return [
         ...configPrologue(cwd, command),

package/dist/lib/terminal/backends/index.d.ts

@@ -1,27 +1,10 @@
-/**
- * Backend registry + current-terminal detection.
- */
 import type { Backend, EngineContext, TerminalBackend } from '../types.js';
 import { itermBackend } from './iterm.js';
 import { ghosttyBackend } from './ghostty.js';
 import { tmuxBackend } from './tmux.js';
 import { vscodiumAgentBackend } from './vscodium-agent.js';
 import { terminalAppBackend } from './terminal-app.js';
-/**
- * All known interactive backends, keyed by id.
- *
- * Insertion order is the preference order `availableBackends` returns, and
- * `terminal` (Terminal.app) sits LAST deliberately: it is the every-Mac floor, so
- * a caller that falls back to the first available backend still prefers a real
- * terminal the user chose to install.
- */
 export declare const BACKENDS: Record<Backend, TerminalBackend>;
-/**
- * The backend for the terminal the CLI is currently running in, or null if we
- * can't open a surface into it. tmux wins (via `$TMUX`) because a tmux pane can
- * live inside iTerm/Ghostty; otherwise fall back to `TERM_PROGRAM`.
- */
 export declare function detectCurrentBackend(ctx: EngineContext): Backend | null;
-/** Backends that can actually be driven in this context. */
 export declare function availableBackends(ctx: EngineContext): TerminalBackend[];
 export { itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend, terminalAppBackend };

package/dist/lib/terminal/backends/index.js

@@ -3,14 +3,6 @@ import { ghosttyBackend } from './ghostty.js';
 import { tmuxBackend } from './tmux.js';
 import { vscodiumAgentBackend } from './vscodium-agent.js';
 import { terminalAppBackend } from './terminal-app.js';
-/**
- * All known interactive backends, keyed by id.
- *
- * Insertion order is the preference order `availableBackends` returns, and
- * `terminal` (Terminal.app) sits LAST deliberately: it is the every-Mac floor, so
- * a caller that falls back to the first available backend still prefers a real
- * terminal the user chose to install.
- */
 export const BACKENDS = {
     iterm: itermBackend,
     ghostty: ghosttyBackend,
@@ -18,11 +10,6 @@ export const BACKENDS = {
     'vscodium-agent': vscodiumAgentBackend,
     terminal: terminalAppBackend,
 };
-/**
- * The backend for the terminal the CLI is currently running in, or null if we
- * can't open a surface into it. tmux wins (via `$TMUX`) because a tmux pane can
- * live inside iTerm/Ghostty; otherwise fall back to `TERM_PROGRAM`.
- */
 export function detectCurrentBackend(ctx) {
     if (ctx.env.TMUX)
         return 'tmux';
@@ -31,12 +18,10 @@ export function detectCurrentBackend(ctx) {
         return 'iterm';
     if (term.includes('ghostty'))
         return 'ghostty';
-    // Terminal.app sets TERM_PROGRAM=Apple_Terminal.
     if (term.includes('apple_terminal'))
         return 'terminal';
     return null;
 }
-/** Backends that can actually be driven in this context. */
 export function availableBackends(ctx) {
     return Object.values(BACKENDS).filter((b) => b.isAvailable(ctx));
 }