@phnx-labs/agents-cli 1.22.68 → 1.22.69

package/dist/lib/smart-launch.js

@@ -90,15 +90,29 @@ export function formatEmptyAutoPoolError() {
         'mark one with `agents devices role <name> worker`, or widen the pool with `agents config set auto.pool all`.');
 }
 export function formatNoHealthyDeviceError(pool, signals, agent) {
+    let timedOutCount = 0;
     const excluded = pool.map((key) => {
         const signal = signals.get(key);
-        const reason = signal?.reachable !== true
-            ? 'unreachable'
-            : signal.headroom === 'loaded'
+        let reason;
+        if (signal?.reachable === true) {
+            reason = signal.headroom === 'loaded'
                 ? 'overloaded'
                 : signal.installed !== true || signal.signedIn !== true
                     ? 'no ready harness account'
                     : 'ineligible';
+        }
+        else if (signal?.timedOut) {
+            // A slow link is not an offline box. Saying "unreachable" here sent
+            // operators hunting a fleet outage that did not exist (PHNX-3682).
+            timedOutCount++;
+            reason = 'probe timed out';
+        }
+        else if (signal === undefined) {
+            reason = 'no probe signal';
+        }
+        else {
+            reason = 'unreachable';
+        }
         return `${key} (${reason})`;
     }).join(', ');
     const target = agent ? `can run ${agent}` : "for 'run auto'";
@@ -108,7 +122,16 @@ export function formatNoHealthyDeviceError(pool, signals, agent) {
     // in this error's own candidate set, not just the ones with a doc.
     const marked = describeAutoPool({ roster: pool });
     const poolNote = marked ? ` [pool: ${marked}]` : '';
-    return `agents: no healthy device ${target}${poolNote} — excluded: ${excluded}; earliest window resets unknown`;
+    // Only talk about usage windows when a device was actually turned away for
+    // one. A pool that timed out needs a link/latency hint, not a reset time.
+    const scope = timedOutCount === pool.length
+        ? `every probe (${pool.length}) exceeded`
+        : `${timedOutCount} of ${pool.length} probes exceeded`;
+    const hint = timedOutCount > 0
+        ? `; ${scope} the probe budget — those devices are likely up but slow to answer`
+            + ' (relayed Tailscale paths). Retry, or check `tailscale status` for a direct path.'
+        : '; earliest window resets unknown';
+    return `agents: no healthy device ${target}${poolNote} — excluded: ${excluded}${hint}`;
 }
 /**
  * Pick the least-loaded healthy device that can run `agent` when the harness is

package/dist/lib/storage/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `lib/storage` — the surface-agnostic core the managed-storage surfaces share:
+ *
+ *   - {@link selection}  the ONE managed-vs-BYO selection policy.
+ *   - {@link visibility} the ONE visibility model + product default (`me`).
+ *
+ * Consume the SELECTION + VISIBILITY POLICY from here; keep each surface's typed,
+ * `kind`-tagged backend adapter (endpoint, namespace, covers) in that surface's
+ * own module. `agents artifacts share` (`lib/share/`) and `agents traces`
+ * (`lib/traces/`) are the two current adapters; the `sessions` sync adapter is
+ * the next consumer.
+ */
+export { type StorageBackendKind, type StorageSelectionOpts, selectStorageBackendKind, isManagedSelection, } from './selection.js';
+export { type ShareVisibility, type VisibilityFlags, PUBLISH_VISIBILITY_LEVELS, EDITABLE_VISIBILITY_LEVELS, MANAGED_DEFAULT_VISIBILITY, BYO_DEFAULT_VISIBILITY, defaultVisibilityForBackend, explicitVisibility, resolveVisibility, publishVisibility, } from './visibility.js';

package/dist/lib/storage/index.js

@@ -0,0 +1,14 @@
+/**
+ * `lib/storage` — the surface-agnostic core the managed-storage surfaces share:
+ *
+ *   - {@link selection}  the ONE managed-vs-BYO selection policy.
+ *   - {@link visibility} the ONE visibility model + product default (`me`).
+ *
+ * Consume the SELECTION + VISIBILITY POLICY from here; keep each surface's typed,
+ * `kind`-tagged backend adapter (endpoint, namespace, covers) in that surface's
+ * own module. `agents artifacts share` (`lib/share/`) and `agents traces`
+ * (`lib/traces/`) are the two current adapters; the `sessions` sync adapter is
+ * the next consumer.
+ */
+export { selectStorageBackendKind, isManagedSelection, } from './selection.js';
+export { PUBLISH_VISIBILITY_LEVELS, EDITABLE_VISIBILITY_LEVELS, MANAGED_DEFAULT_VISIBILITY, BYO_DEFAULT_VISIBILITY, defaultVisibilityForBackend, explicitVisibility, resolveVisibility, publishVisibility, } from './visibility.js';

package/dist/lib/storage/selection.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The ONE managed-vs-BYO storage-backend selection policy.
+ *
+ * Every surface that persists to Phoenix-managed storage (`agents artifacts
+ * share` today, `agents sessions` sync next) makes the SAME choice: run on OUR
+ * managed infrastructure when the caller is signed in to Phoenix, and only fall
+ * back to a bring-your-own bucket when the caller explicitly asked for it. This
+ * module owns that decision so it is not re-derived — and re-drifted — per
+ * surface.
+ *
+ * What lives here is ONLY the identity + selection policy. It deliberately does
+ * NOT know a surface's endpoint, namespace shape, public-read semantics, or OG
+ * covers — those differ (share uses an email-handle namespace with public reads
+ * and covers; a traces/sessions adapter uses the userId and differs again). Each
+ * surface keeps its own DISCRIMINATED, typed adapter that reads this decision and
+ * returns its own `kind`-tagged backend. See `lib/share/backend.ts` and
+ * `lib/traces/backend.ts` for the two adapters.
+ */
+import { type PhoenixSession } from '../identity/client.js';
+/** The two legitimate principals any managed-capable surface can resolve to. */
+export type StorageBackendKind = 'managed' | 'byo';
+export interface StorageSelectionOpts {
+    /**
+     * True when the SURFACE detected an explicit bring-your-own override — a
+     * `--byo` flag, a caller-supplied static write token, a `…_BACKEND=byo` env,
+     * or a full BYO endpoint config. Detecting WHICH signals count is the
+     * surface's job (they differ per surface); this policy only honors the boolean.
+     */
+    byoOverride?: boolean;
+    /**
+     * DI seam for the Phoenix session. `undefined` reads the real persisted
+     * session (`readSession()`); `null` means "explicitly signed out".
+     */
+    session?: PhoenixSession | null;
+}
+/**
+ * Pick the storage principal. Managed when signed in (`readSession() != null`)
+ * AND the surface reported no explicit BYO override; otherwise BYO.
+ *
+ * This is not a fallback chain — it is a single decision. A surface that cannot
+ * authenticate EITHER principal (signed out AND no BYO config) still reads `byo`
+ * here and fails loud in its own adapter, where the actionable "run auth login
+ * or set up your bucket" message belongs.
+ */
+export declare function selectStorageBackendKind(opts?: StorageSelectionOpts): StorageBackendKind;
+/** True when the shared policy resolves to the managed principal. Thin sugar
+ * over {@link selectStorageBackendKind} for the common boolean check. */
+export declare function isManagedSelection(opts?: StorageSelectionOpts): boolean;

package/dist/lib/storage/selection.js

@@ -0,0 +1,39 @@
+/**
+ * The ONE managed-vs-BYO storage-backend selection policy.
+ *
+ * Every surface that persists to Phoenix-managed storage (`agents artifacts
+ * share` today, `agents sessions` sync next) makes the SAME choice: run on OUR
+ * managed infrastructure when the caller is signed in to Phoenix, and only fall
+ * back to a bring-your-own bucket when the caller explicitly asked for it. This
+ * module owns that decision so it is not re-derived — and re-drifted — per
+ * surface.
+ *
+ * What lives here is ONLY the identity + selection policy. It deliberately does
+ * NOT know a surface's endpoint, namespace shape, public-read semantics, or OG
+ * covers — those differ (share uses an email-handle namespace with public reads
+ * and covers; a traces/sessions adapter uses the userId and differs again). Each
+ * surface keeps its own DISCRIMINATED, typed adapter that reads this decision and
+ * returns its own `kind`-tagged backend. See `lib/share/backend.ts` and
+ * `lib/traces/backend.ts` for the two adapters.
+ */
+import { readSession } from '../identity/client.js';
+/**
+ * Pick the storage principal. Managed when signed in (`readSession() != null`)
+ * AND the surface reported no explicit BYO override; otherwise BYO.
+ *
+ * This is not a fallback chain — it is a single decision. A surface that cannot
+ * authenticate EITHER principal (signed out AND no BYO config) still reads `byo`
+ * here and fails loud in its own adapter, where the actionable "run auth login
+ * or set up your bucket" message belongs.
+ */
+export function selectStorageBackendKind(opts = {}) {
+    if (opts.byoOverride === true)
+        return 'byo';
+    const session = opts.session === undefined ? readSession() : opts.session;
+    return session != null ? 'managed' : 'byo';
+}
+/** True when the shared policy resolves to the managed principal. Thin sugar
+ * over {@link selectStorageBackendKind} for the common boolean check. */
+export function isManagedSelection(opts = {}) {
+    return selectStorageBackendKind(opts) === 'managed';
+}

package/dist/lib/storage/visibility.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The ONE visibility model, identical on every surface that publishes to managed
+ * storage. Three levels the operator ever chooses between:
+ *
+ *   - PRIVATE  = `me`      — owner-only, Phoenix-gated. THE DEFAULT for a new
+ *                            managed share (see {@link MANAGED_DEFAULT_VISIBILITY}).
+ *   - TEAM     = `org`     — everyone at the sharer's signed-in email DOMAIN,
+ *                            Phoenix-gated. Automatic from the domain — there is
+ *                            no organization to create and no member to add.
+ *   - PUBLIC   = `public`  — explicit opt-in; listed in the gallery, gets an OG
+ *                            card.
+ *
+ * Two capability-URL levels remain for the power path (unguessable link, not a
+ * login gate): `unlisted` (obscurity — noindex, gallery-hidden, still
+ * world-readable) and `private`-token-gated (`--protected`: a `?k=` key the
+ * Worker checks, 404 without it). `me`/`org` require a Phoenix session; the
+ * Worker refuses them for a bare WRITE_TOKEN (BYO) publish, which is why the BYO
+ * default stays `public`.
+ *
+ * The names match the Worker's own metadata vocabulary (`lib/share/worker-template.ts`),
+ * so this module is the single client-side source of truth for the level set and
+ * the DEFAULT, reusable by any surface.
+ */
+/** Every visibility level the Worker understands. `me`/`org` are the
+ * Phoenix-gated (login-required) levels; `public`/`unlisted`/`private` are the
+ * link-reachable levels. */
+export type ShareVisibility = 'public' | 'unlisted' | 'private' | 'me' | 'org';
+/** The levels a publish (`share <file> --visibility`) may select. */
+export declare const PUBLISH_VISIBILITY_LEVELS: readonly ShareVisibility[];
+/** The levels an ALREADY-published page may be re-scoped to in place
+ * (`share visibility <target> <level>`). Excludes `private`: re-scoping to
+ * token-gated needs a fresh viewer token, which only the publish path mints. */
+export declare const EDITABLE_VISIBILITY_LEVELS: readonly ShareVisibility[];
+/**
+ * The product default for a MANAGED (signed-in) share: PRIVATE = owner-only,
+ * Phoenix-gated. A publish with no visibility flag lands here.
+ */
+export declare const MANAGED_DEFAULT_VISIBILITY: ShareVisibility;
+/**
+ * The default for a BYO (bring-your-own bucket) publish. `me`/`org` are refused
+ * server-side for a WRITE_TOKEN publish — there is no Phoenix owner to gate on —
+ * so a BYO share with no flag stays `public`, matching the pre-managed behavior.
+ */
+export declare const BYO_DEFAULT_VISIBILITY: ShareVisibility;
+import type { StorageBackendKind } from './selection.js';
+/** The no-flags default for a given storage backend: `me` on managed,
+ * `public` on BYO. */
+export declare function defaultVisibilityForBackend(kind: StorageBackendKind): ShareVisibility;
+export interface VisibilityFlags {
+    /** An explicit `--visibility <level>`. */
+    visibility?: ShareVisibility;
+    /** `--unlisted` / `--private` (obscurity, not read-auth). */
+    unlisted?: boolean;
+    /** `--protected` — token-gated read auth (maps to `private`). */
+    protected?: boolean;
+}
+/**
+ * The visibility the caller EXPLICITLY asked for, or `undefined` when they
+ * passed no visibility signal at all. `--protected` wins over `--unlisted`
+ * (stronger control), which wins over an explicit `--visibility`.
+ *
+ * The distinction between "explicit" and "no preference" is what lets a caller
+ * apply the product default only when nothing was asked — a caller that passes
+ * `--visibility public` gets `public`, never the `me` default.
+ */
+export declare function explicitVisibility(opts?: VisibilityFlags): ShareVisibility | undefined;
+/**
+ * Resolve visibility from the caller's flags, falling back to `fallback` when no
+ * explicit signal was given. The library fallback stays `public` so a caller
+ * that hasn't opted into the managed private default (e.g. an existing lib
+ * consumer) is never silently flipped; the surface applies the product default
+ * itself via {@link defaultVisibilityForBackend}.
+ */
+export declare function resolveVisibility(opts?: VisibilityFlags, fallback?: ShareVisibility): ShareVisibility;
+/**
+ * The visibility a PUBLISH should stamp: the caller's explicit flag if any, else
+ * the product default for the resolved backend (`me` on managed, `public` on
+ * BYO). This is the one call a publishing surface makes — `agents artifacts
+ * share` today, `agents sessions` sync next — so "private by default when signed
+ * in" is decided in exactly one place.
+ */
+export declare function publishVisibility(opts: VisibilityFlags, kind: StorageBackendKind): ShareVisibility;

package/dist/lib/storage/visibility.js

@@ -0,0 +1,99 @@
+/**
+ * The ONE visibility model, identical on every surface that publishes to managed
+ * storage. Three levels the operator ever chooses between:
+ *
+ *   - PRIVATE  = `me`      — owner-only, Phoenix-gated. THE DEFAULT for a new
+ *                            managed share (see {@link MANAGED_DEFAULT_VISIBILITY}).
+ *   - TEAM     = `org`     — everyone at the sharer's signed-in email DOMAIN,
+ *                            Phoenix-gated. Automatic from the domain — there is
+ *                            no organization to create and no member to add.
+ *   - PUBLIC   = `public`  — explicit opt-in; listed in the gallery, gets an OG
+ *                            card.
+ *
+ * Two capability-URL levels remain for the power path (unguessable link, not a
+ * login gate): `unlisted` (obscurity — noindex, gallery-hidden, still
+ * world-readable) and `private`-token-gated (`--protected`: a `?k=` key the
+ * Worker checks, 404 without it). `me`/`org` require a Phoenix session; the
+ * Worker refuses them for a bare WRITE_TOKEN (BYO) publish, which is why the BYO
+ * default stays `public`.
+ *
+ * The names match the Worker's own metadata vocabulary (`lib/share/worker-template.ts`),
+ * so this module is the single client-side source of truth for the level set and
+ * the DEFAULT, reusable by any surface.
+ */
+/** The levels a publish (`share <file> --visibility`) may select. */
+export const PUBLISH_VISIBILITY_LEVELS = [
+    'public',
+    'unlisted',
+    'private',
+    'me',
+    'org',
+];
+/** The levels an ALREADY-published page may be re-scoped to in place
+ * (`share visibility <target> <level>`). Excludes `private`: re-scoping to
+ * token-gated needs a fresh viewer token, which only the publish path mints. */
+export const EDITABLE_VISIBILITY_LEVELS = [
+    'public',
+    'unlisted',
+    'me',
+    'org',
+];
+/**
+ * The product default for a MANAGED (signed-in) share: PRIVATE = owner-only,
+ * Phoenix-gated. A publish with no visibility flag lands here.
+ */
+export const MANAGED_DEFAULT_VISIBILITY = 'me';
+/**
+ * The default for a BYO (bring-your-own bucket) publish. `me`/`org` are refused
+ * server-side for a WRITE_TOKEN publish — there is no Phoenix owner to gate on —
+ * so a BYO share with no flag stays `public`, matching the pre-managed behavior.
+ */
+export const BYO_DEFAULT_VISIBILITY = 'public';
+/** The no-flags default for a given storage backend: `me` on managed,
+ * `public` on BYO. */
+export function defaultVisibilityForBackend(kind) {
+    return kind === 'managed' ? MANAGED_DEFAULT_VISIBILITY : BYO_DEFAULT_VISIBILITY;
+}
+/**
+ * The visibility the caller EXPLICITLY asked for, or `undefined` when they
+ * passed no visibility signal at all. `--protected` wins over `--unlisted`
+ * (stronger control), which wins over an explicit `--visibility`.
+ *
+ * The distinction between "explicit" and "no preference" is what lets a caller
+ * apply the product default only when nothing was asked — a caller that passes
+ * `--visibility public` gets `public`, never the `me` default.
+ */
+export function explicitVisibility(opts = {}) {
+    if (opts.protected === true)
+        return 'private';
+    if (opts.unlisted === true)
+        return 'unlisted';
+    if (opts.visibility === 'public' ||
+        opts.visibility === 'unlisted' ||
+        opts.visibility === 'private' ||
+        opts.visibility === 'me' ||
+        opts.visibility === 'org') {
+        return opts.visibility;
+    }
+    return undefined;
+}
+/**
+ * Resolve visibility from the caller's flags, falling back to `fallback` when no
+ * explicit signal was given. The library fallback stays `public` so a caller
+ * that hasn't opted into the managed private default (e.g. an existing lib
+ * consumer) is never silently flipped; the surface applies the product default
+ * itself via {@link defaultVisibilityForBackend}.
+ */
+export function resolveVisibility(opts = {}, fallback = 'public') {
+    return explicitVisibility(opts) ?? fallback;
+}
+/**
+ * The visibility a PUBLISH should stamp: the caller's explicit flag if any, else
+ * the product default for the resolved backend (`me` on managed, `public` on
+ * BYO). This is the one call a publishing surface makes — `agents artifacts
+ * share` today, `agents sessions` sync next — so "private by default when signed
+ * in" is decided in exactly one place.
+ */
+export function publishVisibility(opts, kind) {
+    return explicitVisibility(opts) ?? defaultVisibilityForBackend(kind);
+}

package/dist/lib/teams/agents.js

@@ -2361,7 +2361,9 @@ export class AgentManager {
                     ? `at its agents.max-concurrent cap (${e.detail} running)`
                     : e.reason === 'not-installed'
                         ? `does not have ${this.placementAgentLabel(agent)} installed`
-                        : e.reason;
+                        : e.reason === 'probe-timed-out'
+                            ? 'did not answer the probe in time (likely up but on a slow/relayed link)'
+                            : e.reason;
                 console.error(chalk.dim(`[placement] '${e.device}' excluded from auto-pick — ${why}`));
             }
         }

package/dist/lib/teams/placement-probe.js

@@ -137,6 +137,7 @@ export async function probePoolSignals(pool, agent, opts = {}) {
             continue; // fully unknown device — leave it out of the map
         signals.set(name, {
             reachable: s?.reachable,
+            timedOut: s?.timedOut,
             headroom: s ? headroom(s) : undefined,
             loadPercent: s?.loadPercent,
             memPercent: s?.memPercent,

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

@@ -10,6 +10,13 @@ import type { Headroom } from '../devices/health.js';
 export interface DevicePlacementSignal {
     /** SSH probe answered. `false` → excluded (unreachable). undefined → unknown. */
     reachable?: boolean;
+    /**
+     * The probe was killed for exceeding its budget rather than failing to
+     * connect. Ranking treats it exactly like `reachable:false` — an
+     * unresponsive box is still not placeable — but the operator-facing
+     * exclusion reason says "probe timed out", not "unreachable" (PHNX-3682).
+     */
+    timedOut?: boolean;
     /** Headroom bucket from load+memory. `'loaded'` → excluded (overloaded). */
     headroom?: Headroom;
     /** Normalized CPU load percent (finer rank tiebreak within a headroom tier). */
@@ -60,7 +67,7 @@ export interface PlacementOptions {
     preferred?: ReadonlySet<string>;
 }
 /** Why a device was excluded from the viable set, for the fail-loud message. */
-export type ExclusionReason = 'unreachable' | 'overloaded' | 'capped' | 'not-installed';
+export type ExclusionReason = 'unreachable' | 'probe-timed-out' | 'overloaded' | 'capped' | 'not-installed';
 /** A pool device dropped from the auto-pick, with the reason + live detail. */
 export interface ExcludedDevice {
     device: string;

package/dist/lib/teams/scheduler.js

@@ -199,7 +199,10 @@ export function classifyExclusions(devices, roster, opts) {
     for (const d of devices) {
         const s = signals?.get(d);
         if (s?.reachable === false) {
-            excluded.push({ device: d, reason: 'unreachable' });
+            // A probe killed for exceeding its budget is a slow link, not a box that
+            // is down. Same exclusion either way — an unresponsive device is still not
+            // placeable — but the operator sees which one it was (PHNX-3682).
+            excluded.push({ device: d, reason: s.timedOut ? 'probe-timed-out' : 'unreachable' });
             continue;
         }
         if (s?.installed === false) {

package/dist/lib/traces/backend.js

@@ -10,6 +10,7 @@
  * `agents artifacts setup`.
  */
 import { readSession } from '../identity/client.js';
+import { selectStorageBackendKind } from '../storage/selection.js';
 export const DEFAULT_TRACES_DOMAIN = 'traces.agents-cli.sh';
 /**
  * Resolve the backend for the current machine. Throws when not signed in.
@@ -21,11 +22,21 @@ export const DEFAULT_TRACES_DOMAIN = 'traces.agents-cli.sh';
 export function resolveTracesBackend() {
     const envBase = (process.env['AGENTS_TRACES_BASE_URL'] ?? '').replace(/\/+$/, '').trim();
     const envToken = (process.env['AGENTS_TRACES_WRITE_TOKEN'] ?? '').trim();
-    if (envBase && envToken) {
-        return { baseUrl: envBase, token: envToken, userId: 'byo' };
+    // The traces surface's only BYO signal is the full BASE_URL + WRITE_TOKEN env
+    // pair; the managed-vs-BYO decision itself is the shared selection policy.
+    const byoOverride = Boolean(envBase && envToken);
+    if (selectStorageBackendKind({ byoOverride }) === 'byo') {
+        if (byoOverride) {
+            return { baseUrl: envBase, token: envToken, userId: 'byo' };
+        }
+        // Not signed in and no BYO env pair — the managed principal is the only one
+        // this surface exposes, so fail loud with the login hint.
+        throw new Error("Not signed in. Run 'agents auth login' to sync traces to your Phoenix account.");
     }
     const session = readSession();
     if (!session) {
+        // selectStorageBackendKind read the same session and returned 'managed', so a
+        // null here means it was cleared between the two reads — treat as signed out.
         throw new Error("Not signed in. Run 'agents auth login' to sync traces to your Phoenix account.");
     }
     if (!session.access_token) {

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

@@ -0,0 +1,166 @@
+/**
+ * The coarse bucket a held worktree falls into. These are the three the ticket
+ * names, and they demand very different follow-ups:
+ *
+ * - `unmerged-commits` — the one that matters. The branch carries commits with
+ *   no patch-equivalent upstream: real work visible to nobody. Candidate for
+ *   "push the branch or open a PR", never deletion.
+ * - `uncommitted-changes` — a dirty tree. Could be live work, could be build
+ *   output nobody will miss. Needs a human eye, not an automatic action.
+ * - `undeterminable` — a broken or locked checkout whose merge state or status
+ *   could not be read. Fails closed by design; must be re-examined, never swept.
+ */
+export type HeldBucket = 'unmerged-commits' | 'uncommitted-changes' | 'undeterminable';
+/**
+ * The specific reason inside a bucket. `undeterminable` splits into the two the
+ * sweep distinguishes so an operator can tell a locked index (`status-unreadable`)
+ * from a repo with no resolvable default ref (`merge-state-unknown`).
+ */
+export type HeldReason = 'unmerged-commits' | 'uncommitted-changes' | 'status-unreadable' | 'merge-state-unknown';
+/** One classified held worktree — the structured record the sweep threw away. */
+export interface HeldWorktree {
+    /** Repo root that owns this worktree (the dir holding `.agents/worktrees`). */
+    repo: string;
+    /** basename(repo), for compact tables. */
+    repoName: string;
+    /** Worktree slug (the dir under `.agents/worktrees`). */
+    name: string;
+    /** Absolute path to the worktree. */
+    path: string;
+    /** Checked-out branch, or null for a detached HEAD. */
+    branch: string | null;
+    bucket: HeldBucket;
+    reason: HeldReason;
+    /**
+     * Commits on this worktree with no patch-equivalent upstream (`git cherry`).
+     * -1 means the answer could not be established.
+     */
+    unmergedCommits: number;
+    /** `git status --porcelain` line count; -1 means it could not be read. */
+    dirtyFiles: number;
+    /** True when `<branch>` already exists on `origin` (so the work is visible). */
+    hasRemoteBranch: boolean;
+    /** Whole days since the worktree dir was last modified. */
+    ageDays: number;
+    /** Disk footprint of the worktree dir in bytes, or -1 if it could not be read. */
+    sizeBytes: number;
+}
+/**
+ * Resolve the default branch ref to compare against: `origin/HEAD` when set,
+ * else whichever of `origin/main` / `origin/master` exists. Returns null when
+ * none resolve, which makes every worktree `merge-state-unknown` rather than
+ * silently comparing against nothing.
+ */
+export declare function resolveDefaultRef(repoRoot: string): Promise<string | null>;
+/**
+ * Count commits with no patch-equivalent upstream. Returns -1 when the answer
+ * cannot be established, which the classifier treats as `merge-state-unknown`.
+ *
+ * Patch-id (`git cherry`), NOT ancestry, is load-bearing: this fleet
+ * rebase-merges, so a landed branch's SHAs are rewritten and
+ * `merge-base --is-ancestor` reports *not merged* for work that fully landed.
+ * It also subsumes the unpushed check — an unpushed commit has no upstream
+ * equivalent, so it surfaces as unmerged rather than needing a separate probe.
+ */
+export declare function countUnmergedCommits(worktreePath: string, defaultRef: string | null): Promise<number>;
+/** One `git worktree list --porcelain` record. */
+interface PorcelainEntry {
+    path: string;
+    branch: string | null;
+    detached: boolean;
+}
+export declare function parseWorktreePorcelain(out: string): PorcelainEntry[];
+/**
+ * True when `child` is `parent` or sits beneath it, compared on path
+ * boundaries. A raw `startsWith` makes `.../fix-1103` look like it is inside
+ * `.../fix-110`, so the primary checkout would be mistaken for a neighbour.
+ */
+export declare function isInside(child: string, parent: string): boolean;
+/** Everything the bucket decision depends on, gathered once. */
+export interface HeldFacts {
+    /** null for detached HEAD. */
+    branch: string | null;
+    /** `git status --porcelain` line count; -1 = could not read. */
+    dirtyFiles: number;
+    /** `git cherry` count; -1 = could not determine. */
+    unmergedCommits: number;
+}
+/**
+ * Decide which bucket a worktree falls into, or null when it is neither stranded
+ * nor dirty nor broken (clean and fully upstream — nothing to surface). Pure.
+ *
+ * Precedence is chosen for SURFACING, not for the sweep's deletion decision:
+ * the work-loss signal wins. A determinable `unmerged-commits` is reported as
+ * exactly that even when the tree is also dirty, because the recoverable work
+ * is the priority — an operator seeing `uncommitted-changes` would push nothing.
+ * Only when the merge state itself is unreadable do we fall to `undeterminable`,
+ * because then we genuinely cannot tell whether work is stranded.
+ */
+export declare function classifyHeld(facts: HeldFacts): {
+    bucket: HeldBucket;
+    reason: HeldReason;
+} | null;
+/**
+ * Classify every worktree registered under one repo and return only the held
+ * ones. Read-only — no `git worktree remove`, no `branch -d`, no push. The
+ * primary checkout (the first porcelain record, always the repo root) is never
+ * a `.agents/worktrees` slug, so it is skipped implicitly.
+ */
+export declare function collectHeldWorktrees(repoRoot: string): Promise<HeldWorktree[]>;
+/**
+ * Discover repo roots that own a `.agents/worktrees` container beneath
+ * `searchHome`. Mirrors the sweep's discovery: match directory SHAPE, prune the
+ * heavy dirs so a large home stays fast. Read-only.
+ */
+export declare function discoverWorktreeRepos(searchHome: string, maxDepth?: number): Promise<string[]>;
+/** Discover + classify every held worktree beneath `searchHome`. Read-only. */
+export declare function collectHeldWorktreesUnder(searchHome: string): Promise<HeldWorktree[]>;
+/** A held set grouped by bucket, with the itemised entries kept. */
+export interface HeldSummary {
+    total: number;
+    buckets: Record<HeldBucket, HeldWorktree[]>;
+}
+/** Group a flat held list into its three buckets. Pure. */
+export declare function summarizeHeld(held: HeldWorktree[]): HeldSummary;
+/** One device's contribution to a fleet-wide roll-up. */
+export interface DeviceHeld {
+    device: string;
+    held: HeldWorktree[];
+}
+/** A fleet-wide roll-up: every device's held worktrees, still bucketed. Pure. */
+export interface FleetHeldSummary extends HeldSummary {
+    devices: {
+        device: string;
+        total: number;
+    }[];
+}
+/**
+ * Merge several devices' held sets into one fleet roll-up, stamping each entry
+ * with its source device so the `unmerged-commits` bucket names where the
+ * stranded work lives. Pure — the SSH fan-out that produces the input lives in
+ * the command layer.
+ */
+export declare function aggregateHeld(perDevice: DeviceHeld[]): FleetHeldSummary;
+/** Outcome of the safe recovery action on one stranded worktree. */
+export interface PushResult {
+    name: string;
+    branch: string | null;
+    pushed: boolean;
+    reason: string;
+}
+/**
+ * The safe automatic action for the `unmerged-commits` bucket (ticket step 3):
+ * PUBLISH the branch so the work becomes visible, never remove anything.
+ *
+ * Gated hard, fails closed:
+ *  - only a worktree whose live classification is still `unmerged-commits`;
+ *  - only when the branch does NOT already exist on `origin` — a branch that is
+ *    already pushed (including one behind an open PR) needs nothing, and this
+ *    also means we never force-update a remote ref;
+ *  - a slug-shaped worktree name only, never shelled otherwise.
+ *
+ * `git push` sets no `--force`: it fast-forwards a new ref or fails loud. A
+ * failure is returned, never swallowed.
+ */
+export declare function pushStrandedBranch(repoRoot: string, wt: HeldWorktree): Promise<PushResult>;
+export {};