@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/teams/pr-watch.d.ts

@@ -1,19 +1,9 @@
-/**
- * A CI check result. Shaped after `gh pr checks <pr> --json name,state,link,workflow`,
- * where `state` is one of SUCCESS | FAILURE | PENDING | ERROR | CANCELLED | SKIPPING | ...
- *
- * Note on identity: `gh pr checks` exposes NO stable check-run id — `link` is the
- * per-run URL, which changes every time a workflow re-runs. So dedupe keys off the
- * check NAME (stable across re-runs), not the link (see `checkDedupeKey`). `link`
- * is retained only for the human-facing prompt and for scraping run logs.
- */
 export interface PrCheck {
     name: string;
     state: string;
     link?: string;
     workflow?: string;
 }
-/** A PR review comment. Shaped after GitHub's `repos/{owner}/{repo}/pulls/{n}/comments`. */
 export interface PrReviewComment {
     id: number;
     body: string;
@@ -21,35 +11,19 @@ export interface PrReviewComment {
     path?: string;
     html_url?: string;
 }
-/** One PR under watch, with its current CI + comment snapshot. */
 export interface PrSnapshot {
-    /** The PR URL (https://github.com/{owner}/{repo}/pull/{n}). */
     prUrl: string;
-    /**
-     * Name of the teammate whose work opened this PR — the `--after` anchor the
-     * spawned fix/bugfix teammate links to. Null when the PR can't be traced to a
-     * named teammate (the reaction still fires, just without a dependency edge).
-     */
     sourceTeammate: string | null;
     checks: PrCheck[];
     comments: PrReviewComment[];
 }
-/**
- * Default cap on how many fix/bugfix waves pr-watch spawns for a single PR before
- * it gives up and escalates to a human. A persistently-RED PR re-runs CI on every
- * follow-up commit; without a cap the loop would spawn teammates without bound
- * (issue #338). Configurable via `--max-waves`.
- */
 export declare const DEFAULT_MAX_WAVES = 3;
-/** A decision to spawn a follow-up teammate. Pure output of `decidePrActions`. */
 export type PrWatchAction = {
     kind: 'ci-fix';
     prUrl: string;
     sourceTeammate: string | null;
     check: PrCheck;
-    /** Idempotency key — record it in `handled` once acted on so it never re-fires. */
     dedupeKey: string;
-    /** 1-based wave number for this PR (used to name the spawned teammate uniquely). */
     wave: number;
 } | {
     kind: 'review-fix';
@@ -59,108 +33,42 @@ export type PrWatchAction = {
     dedupeKey: string;
     wave: number;
 } | {
-    /**
-     * The per-PR wave budget is exhausted — stop spawning, escalate to a human.
-     * Emitted once per PR (deduped via `needsHumanKey`) instead of an N+1th fix.
-     */
     kind: 'needs-human';
     prUrl: string;
     sourceTeammate: string | null;
-    /** What triggered the escalation (e.g. `CI check "test"`). */
     subject: string;
-    /** Waves already spent on this PR when the cap was hit. */
     waves: number;
     dedupeKey: string;
 };
-/** The spawnable subset of actions — everything except the `needs-human` escalation. */
 export type PrWatchSpawnAction = Extract<PrWatchAction, {
     kind: 'ci-fix' | 'review-fix';
 }>;
-/** True when a check is in a terminal failing state. */
 export declare function isFailedCheck(check: PrCheck): boolean;
-/**
- * Idempotency key for a failed check on a PR — dedupe by check NAME.
- *
- * The name is the ONLY identity that's stable across re-runs: when a fixer pushes
- * a follow-up commit, GitHub creates a fresh workflow run with a new `link` URL but
- * the SAME check name. Keying off `link` (as an earlier draft did) would treat every
- * re-run as a brand-new failure and spawn an unbounded chain of fixers (issue #338).
- * Keying off the name means a re-run of the same check is recognised as the same
- * logical failure; the per-PR wave counter then bounds how many times we retry it.
- */
 export declare function checkDedupeKey(prUrl: string, check: PrCheck): string;
-/** Idempotency key for a review comment on a PR — dedupe by comment id. */
 export declare function commentDedupeKey(prUrl: string, comment: PrReviewComment): string;
-/** Idempotency key for the one-shot "needs human" escalation on a PR. */
 export declare function needsHumanKey(prUrl: string): string;
-/**
- * The pure heart of pr-watch: given a PR snapshot, the set of dedupe keys already
- * acted on, and how many fix waves each PR has already spent, decide which
- * follow-up teammates to spawn. Emits:
- *   - one `ci-fix` action per NEW failed check (dedup by check NAME)
- *   - one `review-fix` action per NEW review comment (dedup by comment id)
- *   - a single `needs-human` action (per PR) once the wave budget is exhausted,
- *     INSTEAD of spawning — so a persistently-failing PR escalates rather than
- *     spawning teammates without bound (issue #338).
- *
- * `waves` maps a PR URL to the number of fix/bugfix teammates already spawned for
- * it; once that reaches `maxWaves`, no further spawns are emitted for that PR.
- * Both the CI-fix and comment-routing paths draw from the SAME per-PR budget, so
- * neither can loop unboundedly.
- *
- * No network, no side effects, no reference to state beyond the passed
- * `handled` / `waves` — so the same failure never spawns twice and the caller
- * stays in control of when a wave is "spent".
- */
 export declare function decidePrActions(snapshot: PrSnapshot, handled: ReadonlySet<string>, waves?: ReadonlyMap<string, number>, maxWaves?: number): PrWatchAction[];
-/**
- * Build the task prompt for a CI-fix teammate. Pure so it's unit-testable: the
- * failing check + the fetched logs are injected as data.
- */
 export declare function buildCiFixPrompt(action: Extract<PrWatchAction, {
     kind: 'ci-fix';
 }>, logs: string): string;
-/**
- * Build the task prompt for a review-comment bugfix teammate. Pure so it's
- * unit-testable: the review comment is injected as data.
- */
 export declare function buildReviewFixPrompt(action: Extract<PrWatchAction, {
     kind: 'review-fix';
 }>): string;
-/** Parse an owner/repo/number triple out of a GitHub PR URL. Returns null when it doesn't match. */
 export declare function parsePrUrl(prUrl: string): {
     owner: string;
     repo: string;
     number: number;
 } | null;
-/** A PR to watch, paired with the teammate that opened it. */
 export interface WatchTarget {
     prUrl: string;
     sourceTeammate: string | null;
 }
 interface PrWatchDeps {
-    /** Discover which PRs to watch this pass (teammates may open PRs mid-run). */
     resolveTargets: () => Promise<WatchTarget[]>;
-    /** Snapshot one PR's CI + review comments. Defaults to `pollPrSnapshot`. */
     pollSnapshot?: (prUrl: string, sourceTeammate: string | null) => Promise<PrSnapshot>;
-    /** Fetch CI failure logs for a ci-fix action. Defaults to `fetchCiFailureLogs`. */
     fetchLogs?: (check: PrCheck) => Promise<string>;
-    /**
-     * React to one decided spawn action: spawn the fix/bugfix teammate. The prompt
-     * is pre-built with logs/comment injected. Return the spawned teammate label for
-     * logging, or null if the spawn was skipped. `needs-human` actions never reach
-     * here — they surface as a `needs-human` event instead.
-     */
     react: (action: PrWatchSpawnAction, prompt: string) => Promise<string | null>;
-    /**
-     * True when a previously-spawned reaction has finished. Once its fixer settles,
-     * the dedupe guard for that check clears so a check that is STILL red can spawn
-     * its next (budget-bounded) wave; without this, a check would only ever get one
-     * fix attempt per pr-watch run. Optional — when omitted, a check gets a single
-     * wave until pr-watch restarts.
-     */
     reactionSettled?: (label: string) => Promise<boolean>;
-    /** Progress sink — one call per notable event (poll, spawn, escalate, error). */
     onEvent?: (event: PrWatchEvent) => void;
 }
 export type PrWatchEvent = {
@@ -186,34 +94,19 @@ export type PrWatchEvent = {
 };
 interface PrWatchOptions {
     intervalMs?: number;
-    /** Stop after this many polls (0 / undefined = run until signalled). */
     maxPolls?: number;
-    /** Seed of already-handled dedupe keys (e.g. restored from disk). */
     handled?: Set<string>;
-    /** Per-PR fix-wave counts, carried across restarts so the budget survives a restart. */
     waves?: Map<string, number>;
-    /** Cap on fix waves per PR before escalating to a human. Defaults to DEFAULT_MAX_WAVES. */
     maxWaves?: number;
-    /** Abort signal — resolves the loop at the next interval boundary. */
     shouldStop?: () => boolean;
 }
 interface PrWatchResult {
     polls: number;
     spawned: number;
-    /** How many PRs escalated to a human (wave budget exhausted). */
     neededHuman: number;
     handled: Set<string>;
     waves: Map<string, number>;
     stoppedBy: 'max-polls' | 'signal';
 }
-/**
- * Run the pr-watch poll loop. Each pass: retire the dedupe guards of any fixers
- * that have finished (so a still-red check can spawn its next wave), resolve watch
- * targets, snapshot each PR, decide actions against the running `handled` set and
- * per-PR `waves` budget, then react — spawning fresh fixers, or emitting a
- * one-shot `needs-human` event once a PR's wave budget is spent. Every acted-on
- * dedupe key is recorded so a failure/comment never spawns twice within a wave,
- * and `waves` hard-caps the total spawns per PR (issue #338).
- */
 export declare function runPrWatch(deps: PrWatchDeps, opts?: PrWatchOptions): Promise<PrWatchResult>;
 export {};

package/dist/lib/teams/pr-watch.js

@@ -1,39 +1,7 @@
-/**
- * Autonomous PR lifecycle for teams (issue #338).
- *
- * A team's teammates open PRs. This module watches those PRs and reacts:
- *   - RED CI  -> spawn a fresh fix wave (a teammate --after the one that failed,
- *                with the CI failure logs injected) that pushes a follow-up commit.
- *   - NEW REVIEW COMMENT -> route it to a `bugfix` teammate (--after the source),
- *                with the comment body injected.
- *
- * The DECISION logic here is a pure function (`decidePrActions`) over a snapshot
- * of check results + review comments + a set of already-handled ids. It never
- * touches the network — the poll-based collector (`pollPrSnapshot`, backed by the
- * `gh` CLI) and the orchestrator (`runPrWatch`) sit on top and feed it data. That
- * split keeps the spawn-or-not-spawn logic fully unit-testable (see
- * pr-watch.test.ts) and dedupe-correct.
- *
- * Follow-up (deferred, not required here): replace the poll loop with the
- * event-driven webhook receiver from #331 — `pollPrSnapshot` is the seam where a
- * `check_run` / `pull_request_review_comment` webhook payload would plug in,
- * producing the same PrSnapshot the pure decider already consumes.
- */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 const execFileAsync = promisify(execFile);
-/**
- * Default cap on how many fix/bugfix waves pr-watch spawns for a single PR before
- * it gives up and escalates to a human. A persistently-RED PR re-runs CI on every
- * follow-up commit; without a cap the loop would spawn teammates without bound
- * (issue #338). Configurable via `--max-waves`.
- */
 export const DEFAULT_MAX_WAVES = 3;
-/**
- * Check states that count as a RED CI failure worth spawning a fix wave for.
- * PENDING / SUCCESS / SKIPPING / NEUTRAL are deliberately excluded — a fix wave
- * only fires on a genuine, terminal failure.
- */
 const FAILED_STATES = new Set([
     'FAILURE',
     'ERROR',
@@ -42,55 +10,21 @@ const FAILED_STATES = new Set([
     'ACTION_REQUIRED',
     'STARTUP_FAILURE',
 ]);
-/** True when a check is in a terminal failing state. */
 export function isFailedCheck(check) {
     return FAILED_STATES.has((check.state || '').trim().toUpperCase());
 }
-/**
- * Idempotency key for a failed check on a PR — dedupe by check NAME.
- *
- * The name is the ONLY identity that's stable across re-runs: when a fixer pushes
- * a follow-up commit, GitHub creates a fresh workflow run with a new `link` URL but
- * the SAME check name. Keying off `link` (as an earlier draft did) would treat every
- * re-run as a brand-new failure and spawn an unbounded chain of fixers (issue #338).
- * Keying off the name means a re-run of the same check is recognised as the same
- * logical failure; the per-PR wave counter then bounds how many times we retry it.
- */
 export function checkDedupeKey(prUrl, check) {
     return `ci:${prUrl}:${check.name}`;
 }
-/** Idempotency key for a review comment on a PR — dedupe by comment id. */
 export function commentDedupeKey(prUrl, comment) {
     return `review:${prUrl}:${comment.id}`;
 }
-/** Idempotency key for the one-shot "needs human" escalation on a PR. */
 export function needsHumanKey(prUrl) {
     return `needs-human:${prUrl}`;
 }
-/**
- * The pure heart of pr-watch: given a PR snapshot, the set of dedupe keys already
- * acted on, and how many fix waves each PR has already spent, decide which
- * follow-up teammates to spawn. Emits:
- *   - one `ci-fix` action per NEW failed check (dedup by check NAME)
- *   - one `review-fix` action per NEW review comment (dedup by comment id)
- *   - a single `needs-human` action (per PR) once the wave budget is exhausted,
- *     INSTEAD of spawning — so a persistently-failing PR escalates rather than
- *     spawning teammates without bound (issue #338).
- *
- * `waves` maps a PR URL to the number of fix/bugfix teammates already spawned for
- * it; once that reaches `maxWaves`, no further spawns are emitted for that PR.
- * Both the CI-fix and comment-routing paths draw from the SAME per-PR budget, so
- * neither can loop unboundedly.
- *
- * No network, no side effects, no reference to state beyond the passed
- * `handled` / `waves` — so the same failure never spawns twice and the caller
- * stays in control of when a wave is "spent".
- */
 export function decidePrActions(snapshot, handled, waves = new Map(), maxWaves = DEFAULT_MAX_WAVES) {
     const actions = [];
     const { prUrl } = snapshot;
-    // Waves already spent, plus the ones we're about to emit in THIS pass — so a
-    // single pass with several fresh failures can't blow past the budget.
     let projected = waves.get(prUrl) ?? 0;
     let escalated = false;
     const escalate = (subject) => {
@@ -98,7 +32,7 @@ export function decidePrActions(snapshot, handled, waves = new Map(), maxWaves =
             return;
         const dedupeKey = needsHumanKey(prUrl);
         if (handled.has(dedupeKey))
-            return; // already escalated this PR — stay silent
+            return;
         escalated = true;
         actions.push({
             kind: 'needs-human',
@@ -149,10 +83,6 @@ export function decidePrActions(snapshot, handled, waves = new Map(), maxWaves =
     }
     return actions;
 }
-/**
- * Build the task prompt for a CI-fix teammate. Pure so it's unit-testable: the
- * failing check + the fetched logs are injected as data.
- */
 export function buildCiFixPrompt(action, logs) {
     const logsBlock = logs.trim()
         ? `\n\nCI failure logs:\n\`\`\`\n${logs.trim()}\n\`\`\``
@@ -165,10 +95,6 @@ export function buildCiFixPrompt(action, logs) {
         `Do not open a new PR — push to the existing branch so this PR goes green.` +
         logsBlock);
 }
-/**
- * Build the task prompt for a review-comment bugfix teammate. Pure so it's
- * unit-testable: the review comment is injected as data.
- */
 export function buildReviewFixPrompt(action) {
     const c = action.comment;
     const where = c.path ? ` on \`${c.path}\`` : '';
@@ -180,20 +106,12 @@ export function buildReviewFixPrompt(action) {
         `Review comment:\n${c.body}` +
         (c.html_url ? `\n\n(thread: ${c.html_url})` : ''));
 }
-/** Parse an owner/repo/number triple out of a GitHub PR URL. Returns null when it doesn't match. */
 export function parsePrUrl(prUrl) {
     const m = prUrl.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
     if (!m)
         return null;
     return { owner: m[1], repo: m[2], number: Number(m[3]) };
 }
-// ---------------------------------------------------------------------------
-// Impure collectors — thin `gh` CLI wrappers. Kept out of the pure decider so
-// tests never hit the network. These are the seam the #331 webhook receiver
-// would replace: a webhook payload can synthesize the same PrCheck /
-// PrReviewComment shapes and hand them straight to decidePrActions.
-// ---------------------------------------------------------------------------
-/** Fetch the current CI checks for a PR via `gh pr checks`. Returns [] on any gh error. */
 async function fetchPrChecks(prUrl) {
     try {
         const { stdout } = await execFileAsync('gh', ['pr', 'checks', prUrl, '--json', 'name,state,link,workflow'], { maxBuffer: 8 * 1024 * 1024 });
@@ -206,13 +124,9 @@ async function fetchPrChecks(prUrl) {
         }));
     }
     catch {
-        // `gh pr checks` exits non-zero when checks are failing OR when none are
-        // configured. Both surface as a throw here; treat "can't read" as "nothing
-        // to act on" rather than crashing the watch loop.
         return [];
     }
 }
-/** Fetch review comments for a PR via `gh api`. Returns [] on any gh error. */
 async function fetchPrReviewComments(prUrl) {
     const parsed = parsePrUrl(prUrl);
     if (!parsed)
@@ -238,7 +152,6 @@ async function fetchPrReviewComments(prUrl) {
         return [];
     }
 }
-/** Fetch the failing-run logs for a check via `gh run view --log-failed`. Best-effort, truncated. */
 async function fetchCiFailureLogs(check, maxChars = 8000) {
     const runId = check.link?.match(/\/runs\/(\d+)/)?.[1] ?? check.link?.match(/\/actions\/runs\/(\d+)/)?.[1];
     if (!runId)
@@ -247,14 +160,12 @@ async function fetchCiFailureLogs(check, maxChars = 8000) {
         const { stdout } = await execFileAsync('gh', ['run', 'view', runId, '--log-failed'], { maxBuffer: 32 * 1024 * 1024 });
         if (stdout.length <= maxChars)
             return stdout;
-        // Keep the tail — the actual error is almost always at the end of the log.
         return `... (truncated ${stdout.length - maxChars} chars) ...\n` + stdout.slice(-maxChars);
     }
     catch {
         return '';
     }
 }
-/** Collect a live PR snapshot from `gh`. The poll-mode seam for `runPrWatch`. */
 async function pollPrSnapshot(prUrl, sourceTeammate) {
     const [checks, comments] = await Promise.all([
         fetchPrChecks(prUrl),
@@ -262,15 +173,6 @@ async function pollPrSnapshot(prUrl, sourceTeammate) {
     ]);
     return { prUrl, sourceTeammate, checks, comments };
 }
-/**
- * Run the pr-watch poll loop. Each pass: retire the dedupe guards of any fixers
- * that have finished (so a still-red check can spawn its next wave), resolve watch
- * targets, snapshot each PR, decide actions against the running `handled` set and
- * per-PR `waves` budget, then react — spawning fresh fixers, or emitting a
- * one-shot `needs-human` event once a PR's wave budget is spent. Every acted-on
- * dedupe key is recorded so a failure/comment never spawns twice within a wave,
- * and `waves` hard-caps the total spawns per PR (issue #338).
- */
 export async function runPrWatch(deps, opts = {}) {
     const intervalMs = opts.intervalMs ?? 15000;
     const maxPolls = opts.maxPolls ?? 0;
@@ -280,8 +182,6 @@ export async function runPrWatch(deps, opts = {}) {
     const pollSnapshot = deps.pollSnapshot ?? pollPrSnapshot;
     const fetchLogs = deps.fetchLogs ?? fetchCiFailureLogs;
     const emit = deps.onEvent ?? (() => { });
-    // dedupeKey -> spawned teammate label, for the settle sweep. When a fixer
-    // finishes, its guard clears so the next wave (if still warranted) can fire.
     const inFlight = new Map();
     let polls = 0;
     let spawned = 0;
@@ -290,9 +190,6 @@ export async function runPrWatch(deps, opts = {}) {
         if (opts.shouldStop?.()) {
             return { polls, spawned, neededHuman, handled, waves, stoppedBy: 'signal' };
         }
-        // Retire guards for finished fixers so a check that's STILL red after a fix
-        // can spawn its next wave (bounded by `waves`). Skipped when no settle probe
-        // is wired — then a check gets one wave until pr-watch restarts.
         if (deps.reactionSettled && inFlight.size > 0) {
             for (const [key, label] of [...inFlight]) {
                 let done = false;
@@ -327,8 +224,6 @@ export async function runPrWatch(deps, opts = {}) {
             }
             const actions = decidePrActions(snap, handled, waves, maxWaves);
             for (const action of actions) {
-                // Record the key BEFORE reacting so a spawn failure can't loop-spam the
-                // same failure — a bad action is dropped, not retried forever.
                 handled.add(action.dedupeKey);
                 if (action.kind === 'needs-human') {
                     neededHuman++;
@@ -341,7 +236,6 @@ export async function runPrWatch(deps, opts = {}) {
                     });
                     continue;
                 }
-                // Spend a wave from this PR's budget for the spawn we're about to make.
                 waves.set(action.prUrl, (waves.get(action.prUrl) ?? 0) + 1);
                 const prompt = action.kind === 'ci-fix'
                     ? buildCiFixPrompt(action, await fetchLogs(action.check))

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

@@ -1,63 +1,27 @@
-/** Metadata for a registered team. */
 export interface TeamMeta {
     created_at: string;
     description?: string;
     enable_worktrees?: boolean;
-    /** Shared worktree path for all teammates (mutually exclusive with enable_worktrees). */
     use_worktree?: string;
-    /**
-     * Distributed teams: the pool of devices this team may auto-schedule teammates
-     * onto (from `agents devices`). One device → the whole team runs there; many →
-     * unpinned teammates are least-loaded-scheduled across them; empty/absent →
-     * every teammate runs locally (today's behavior).
-     */
     devices?: string[];
-    /**
-     * Distributed teams: how each device gets the code — a git URL to clone or a
-     * path that already exists on the host. Defaults to the local checkout's
-     * `origin` at create time. Used by `ensureRemoteRepo` to provision the repo.
-     */
     repo?: string;
-    /**
-     * The project (`agents projects`) this team works on. Its primary directory
-     * is a local teammate's base cwd when neither `--cwd` nor a worktree gives
-     * one, and its other bound directories become `--add-dir` grants.
-     */
     project?: string;
 }
-/** Map of team name to team metadata. */
 export type TeamRegistry = Record<string, TeamMeta>;
-/**
- * Load all teams from the registry file. Returns an empty object only when
- * the file does not exist. A malformed file is a hard error — silently
- * returning {} would let any caller wipe the user's registry on the next
- * write, which is exactly the data-loss path we are trying to close.
- */
 export declare function loadTeams(): Promise<TeamRegistry>;
 interface CreateTeamOptions {
     description?: string;
     enableWorktrees?: boolean;
-    /** Path to an existing worktree for all teammates to share. */
     useWorktree?: string;
-    /** Distributed pool of devices this team may auto-schedule teammates onto. */
     devices?: string[];
-    /** How each device gets the code (git URL to clone, or a path on the host). */
     repo?: string;
-    /** The `agents projects` project this team works on. */
     project?: string;
 }
-/** Create a new team. Throws if a team with the same name already exists. */
 export declare function createTeam(name: string, options?: CreateTeamOptions): Promise<TeamMeta>;
-/** Return existing team metadata or create a new team if it does not exist. */
 export declare function ensureTeam(name: string): Promise<TeamMeta>;
-/** Mark a team as disbanded so saveMeta will not resurrect its teammates. */
 export declare function markTeamDisbanded(name: string): Promise<void>;
-/** True when the team was disbanded and has not been re-created since. */
 export declare function isTeamDisbanded(name: string): Promise<boolean>;
-/** Remove a team from the registry. Returns false if the team did not exist. */
 export declare function removeTeam(name: string): Promise<boolean>;
-/** Check whether a team with the given name exists in the registry. */
 export declare function teamExists(name: string): Promise<boolean>;
-/** Get metadata for a specific team. Returns null if team does not exist. */
 export declare function getTeam(name: string): Promise<TeamMeta | null>;
 export {};

package/dist/lib/teams/registry.js

@@ -1,12 +1,3 @@
-/**
- * Team registry.
- *
- * Manages the persistent registry of named teams stored at
- * ~/.agents/.history/teams/registry.json. This is per-machine runtime
- * state (timestamps + worktree paths that include absolute filesystem
- * paths) and intentionally lives under .history/ so it's NOT pulled in
- * by `agents repo push`.
- */
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
@@ -18,16 +9,9 @@ import { logAndContinueOnLockCompromised } from '../lock-compromise.js';
 async function registryPath() {
     return getTeamsRegistryPath();
 }
-/**
- * Run `fn` while holding an exclusive cross-process lock on the registry
- * file. proper-lockfile requires the target to exist, so we touch it first.
- * Stale locks (from crashed callers) auto-expire after `stale` ms.
- */
 async function withRegistryLock(p, fn) {
     await fs.mkdir(path.dirname(p), { recursive: true });
     if (!fsSync.existsSync(p)) {
-        // Use 'wx' so a concurrent caller doesn't clobber data written between
-        // our existsSync check and writeFile.
         try {
             await fs.writeFile(p, '{}', { flag: 'wx' });
         }
@@ -48,12 +32,6 @@ async function withRegistryLock(p, fn) {
         await release();
     }
 }
-/**
- * Load all teams from the registry file. Returns an empty object only when
- * the file does not exist. A malformed file is a hard error — silently
- * returning {} would let any caller wipe the user's registry on the next
- * write, which is exactly the data-loss path we are trying to close.
- */
 export async function loadTeams() {
     const p = await registryPath();
     let raw;
@@ -76,7 +54,6 @@ async function saveTeams(reg) {
     const p = await registryPath();
     atomicWriteJsonSync(p, reg);
 }
-/** Create a new team. Throws if a team with the same name already exists. */
 export async function createTeam(name, options) {
     if (options?.enableWorktrees && options?.useWorktree) {
         throw new Error('Cannot use both --enable-worktrees and --use-worktree. Pick one.');
@@ -100,15 +77,10 @@ export async function createTeam(name, options) {
         await saveTeams(reg);
         return m;
     });
-    // A re-created name is a fresh team — drop any prior disband tombstone so
-    // saveMeta will persist new teammates again (RUSH-2450).
     await clearTeamDisbanded(name);
-    // Audit the lifecycle boundary, not the CLI shell — captures every creation
-    // path (create + ensure) with team metadata the generic command log lacks.
     emit('teams.create', { module: 'teams', team: name, worktrees: Boolean(options?.enableWorktrees || options?.useWorktree) });
     return meta;
 }
-/** Return existing team metadata or create a new team if it does not exist. */
 export async function ensureTeam(name) {
     const p = await registryPath();
     let created = false;
@@ -122,35 +94,24 @@ export async function ensureTeam(name) {
         created = true;
         return m;
     });
-    // `teams add` auto-creates the team on first teammate — audit that creation
-    // too, but only when it actually happened (not the get-existing path).
     if (created) {
         await clearTeamDisbanded(name);
         emit('teams.create', { module: 'teams', team: name, worktrees: false });
     }
     return meta;
 }
-/**
- * Tombstone dir for disbanded teams (RUSH-2450). Lives next to the registry so
- * a long-lived supervisor can see that a team was deliberately removed and
- * refuse to re-persist its in-memory AgentProcess objects via saveMeta.
- * Cleared on create/ensure so a re-used name is a fresh team.
- */
 function disbandedDir() {
     return path.join(path.dirname(getTeamsRegistryPath()), 'disbanded');
 }
 function disbandedPath(name) {
-    // Encode the name so a team called `../x` cannot escape the dir.
     const safe = Buffer.from(name, 'utf8').toString('base64url');
     return path.join(disbandedDir(), `${safe}.json`);
 }
-/** Mark a team as disbanded so saveMeta will not resurrect its teammates. */
 export async function markTeamDisbanded(name) {
     const dir = disbandedDir();
     await fs.mkdir(dir, { recursive: true });
     await fs.writeFile(disbandedPath(name), JSON.stringify({ team: name, disbanded_at: new Date().toISOString() }), 'utf-8');
 }
-/** Clear a disband tombstone — called when the name is re-created. */
 async function clearTeamDisbanded(name) {
     try {
         await fs.unlink(disbandedPath(name));
@@ -160,7 +121,6 @@ async function clearTeamDisbanded(name) {
             throw err;
     }
 }
-/** True when the team was disbanded and has not been re-created since. */
 export async function isTeamDisbanded(name) {
     try {
         await fs.access(disbandedPath(name));
@@ -170,7 +130,6 @@ export async function isTeamDisbanded(name) {
         return false;
     }
 }
-/** Remove a team from the registry. Returns false if the team did not exist. */
 export async function removeTeam(name) {
     const p = await registryPath();
     const existed = await withRegistryLock(p, async () => {
@@ -181,21 +140,15 @@ export async function removeTeam(name) {
         await saveTeams(reg);
         return true;
     });
-    // Always stamp the tombstone when removeTeam is invoked from disband — even
-    // if the registry entry was already gone, so a concurrent supervisor still
-    // sees the disband. Idempotent.
     await markTeamDisbanded(name);
-    // "Disband" — only fires when a real team was removed, not a no-op.
     if (existed)
         emit('teams.disband', { module: 'teams', team: name });
     return existed;
 }
-/** Check whether a team with the given name exists in the registry. */
 export async function teamExists(name) {
     const reg = await loadTeams();
     return Boolean(reg[name]);
 }
-/** Get metadata for a specific team. Returns null if team does not exist. */
 export async function getTeam(name) {
     const reg = await loadTeams();
     return reg[name] ?? null;