@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/workflows.js

@@ -1,10 +1,3 @@
-/**
- * Workflow management library.
- *
- * Workflows are directory bundles with a WORKFLOW.md containing YAML frontmatter.
- * They optionally contain subagents/, skills/, and plugins/ subdirectories that
- * are composed at runtime by `agents run <workflow>`.
- */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -12,14 +5,7 @@ import * as yaml from 'yaml';
 import { capableAgents, supports } from './capabilities.js';
 import { getProjectAgentsDir, getSystemWorkflowsDir, getUserWorkflowsDir, getTrashWorkflowsDir, getEnabledExtraRepos, getPluginsDir, getSystemPluginsDir, getProjectPluginsDir, } from './state.js';
 import { listInstalledVersions } from './installations/versions.js';
-/**
- * Hard upper bound on items a single `for_each` expands, absent an explicit
- * `max_items`. A guard against a runaway producer spawning unbounded teammates
- * (acceptance criterion in issue #343). Anthropic's Dynamic Workflows cap at
- * 1000; we default lower and let authors raise it deliberately.
- */
 export const DEFAULT_FOR_EACH_CAP = 256;
-/** Parse WORKFLOW.md frontmatter from a workflow directory. Returns null if invalid. */
 export function parseWorkflowFrontmatter(workflowDir) {
     const workflowMdPath = path.join(workflowDir, 'WORKFLOW.md');
     if (!fs.existsSync(workflowMdPath))
@@ -36,9 +22,6 @@ export function parseWorkflowFrontmatter(workflowDir) {
         const parsed = yaml.parse(frontmatter);
         if (!parsed || typeof parsed !== 'object')
             return null;
-        // Capability-scoping fields are wired into the run (see src/commands/exec.ts);
-        // coerce to string arrays defensively so a malformed `tools: foo` (scalar) or
-        // `tools: [Read, 3]` (mixed) never reaches buildExecCommand as a bad shape.
         const asStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string') ? v : undefined;
         return {
             name: parsed.name || '',
@@ -70,21 +53,6 @@ function readWorkflowBody(workflowDir) {
         return content.trim();
     return lines.slice(endIndex + 2).join('\n').trim();
 }
-/**
- * Defensively coerce a frontmatter `loop:` value into a LoopConfigRaw.
- *
- * Mirrors the asStringArray discipline above: a malformed field is dropped to
- * undefined rather than passed through, so the loop driver never sees a bad
- * shape. Returns undefined when `loop:` is absent or not an object, or when no
- * recognized field survives coercion (an all-garbage block is treated as
- * "no loop", not "empty loop").
- *
- * Field rules:
- *   - until:          only the literal `signal` is accepted; anything else dropped.
- *   - max_iterations: a finite positive integer; non-numbers/<=0 dropped.
- *   - budget:         a finite positive number (tokens); non-numbers/<=0 dropped.
- *   - interval:       a string (e.g. "0", "30m"); non-strings dropped.
- */
 export function parseLoopBlock(v) {
     if (!v || typeof v !== 'object' || Array.isArray(v))
         return undefined;
@@ -105,23 +73,14 @@ export function parseLoopBlock(v) {
         out.interval = raw.interval;
     return Object.keys(out).length > 0 ? out : undefined;
 }
-/** A finite positive integer, or undefined. Shared guard for count-like fields. */
 function asPosInt(v) {
     return typeof v === 'number' && Number.isFinite(v) && Number.isInteger(v) && v > 0
         ? v
         : undefined;
 }
-/** A non-empty trimmed string, or undefined. */
 function asNonEmptyString(v) {
     return typeof v === 'string' && v.trim().length > 0 ? v : undefined;
 }
-/**
- * Defensively coerce a frontmatter `verify:` sub-block into a ForEachVerifySpec.
- *
- * Requires an `agent`; drops the whole block otherwise (a verify panel with no
- * skeptic is meaningless). `votes` defaults to 1 (a single confirmation) and
- * `keep_if` to `majority`; both are validated against their allowed shapes.
- */
 export function parseVerifyBlock(v) {
     if (!v || typeof v !== 'object' || Array.isArray(v))
         return undefined;
@@ -142,13 +101,6 @@ export function parseVerifyBlock(v) {
         out.prompt = prompt;
     return out;
 }
-/**
- * Defensively coerce a frontmatter `for_each:` block into a ForEachSpec (issue
- * #343). Mirrors `parseLoopBlock`'s discipline: a block missing the two
- * load-bearing fields (`agent` + `prompt`) drops to undefined rather than
- * passing a half-formed spec to the expander. Optional numeric/verify fields
- * are individually validated and dropped when malformed.
- */
 export function parseForEachBlock(v) {
     if (!v || typeof v !== 'object' || Array.isArray(v))
         return undefined;
@@ -161,8 +113,6 @@ export function parseForEachBlock(v) {
     const produce = asNonEmptyString(raw.produce);
     if (produce)
         out.produce = produce;
-    // `for_each: ${step}` references a prior step's list. Accept either the
-    // snake-case `for_each` key or an explicit `items_ref`.
     const itemsRef = asNonEmptyString(raw.for_each) ?? asNonEmptyString(raw.items_ref);
     if (itemsRef)
         out.itemsRef = itemsRef;
@@ -180,34 +130,12 @@ export function parseForEachBlock(v) {
         out.verify = verify;
     return out;
 }
-/**
- * Substitute `{{item}}` / `{{index}}` (and 1-based `{{n}}`) in a prompt
- * template. Unknown `{{...}}` tokens are left intact so a template can carry
- * placeholders the caller resolves elsewhere.
- */
 export function renderForEachTemplate(template, item, index) {
     return template
         .replace(/\{\{\s*item\s*\}\}/g, item)
         .replace(/\{\{\s*index\s*\}\}/g, String(index))
         .replace(/\{\{\s*n\s*\}\}/g, String(index + 1));
 }
-/**
- * Expand a `for_each` spec against a producer's output into concrete teammate
- * descriptors (issue #343) — the heart of the declarative fan-out.
- *
- * Pure and deterministic: no I/O, no spawning. `src/lib/teams/forEach.ts`
- * feeds the result to `AgentManager.spawn`, staging each descriptor into the
- * supervisor's existing mid-flight-add path — so this reuses the dynamic-DAG
- * substrate rather than introducing a new engine.
- *
- * For N produced items (capped at `spec.max_items` / `DEFAULT_FOR_EACH_CAP`):
- *   - one `stage` teammate per item, depending on `producerName` if given;
- *   - when `verify` is set, `votes` `verify` teammates per item, each
- *     depending on that item's stage teammate.
- *
- * Names are unique (`<base>-<n>` and `<base>-<n>-verify-<v>`) so `--after`
- * linkage and the teams cycle check carry over unchanged.
- */
 export function expandForEach(spec, items, opts = {}) {
     const cap = spec.max_items ?? DEFAULT_FOR_EACH_CAP;
     const producedCount = items.length;
@@ -251,21 +179,6 @@ export function expandForEach(spec, items, opts = {}) {
         cap,
     };
 }
-/**
- * Decide which subagent .md stems a workflow may use, given the discovered
- * subagent files and the parsed `allowedAgents` frontmatter. This is the
- * fail-closed security boundary for issue #324:
- *
- *   - `allowedAgents === undefined` (field absent)  -> NO restriction; allow all.
- *   - `allowedAgents === []`        (present, empty) -> allow ZERO; copy none.
- *   - `allowedAgents = [a, b]`                       -> allow only those stems.
- *
- * An explicit empty array must NEVER widen to "allow all" — that would copy
- * every subagent definition into the run, granting MORE access than declared.
- *
- * `available` are the .md filenames found in subagents/ (e.g. `security.md`).
- * Returns the stems to copy and any allowedAgents entries with no matching file.
- */
 export function resolveAllowedSubagents(available, allowedAgents) {
     const stems = available.filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, ''));
     if (allowedAgents === undefined) {
@@ -278,50 +191,12 @@ export function resolveAllowedSubagents(available, allowedAgents) {
         missing: allowedAgents.filter(a => !present.has(a)),
     };
 }
-/** The Claude tool an orchestrator uses to dispatch subagents. Must stay in a
- *  workflow's `--tools` allowlist whenever the workflow ships dispatchable
- *  subagents, or the orchestrator has no way to reach them. */
 const SUBAGENT_DISPATCH_TOOL = 'Task';
-/**
- * Keep the subagent-dispatch tool (`Task`) in a `tools:`-restricted workflow's
- * allowlist when the workflow actually ships subagents to dispatch.
- *
- * A WORKFLOW.md `tools:` list becomes Claude's `--tools` set, which *restricts*
- * the available built-ins. An orchestrator whose `subagents/` files were just
- * copied into the shared agents dir but whose `tools:` omits `Task` cannot
- * reach any of them — it silently no-ops (observed: the run emits only "I'll
- * wait for the completion notification" and exits). Omitting `Task` while
- * shipping a `subagents/` dir is always an authoring miss, so we re-add it at
- * the source rather than relying on every workflow author to remember.
- *
- * Returns `tools` unchanged when the workflow has no subagents or already lists
- * `Task`; otherwise appends `Task`.
- */
 export function ensureSubagentDispatchTool(tools, hasSubagents) {
     if (!hasSubagents || tools.includes(SUBAGENT_DISPATCH_TOOL))
         return tools;
     return [...tools, SUBAGENT_DISPATCH_TOOL];
 }
-/**
- * Prune stale workflow-managed subagent files from the shared per-agent agents
- * dir before a scoped run writes the permitted set (issue #401, follow-up to
- * #324). A prior *unrestricted* run of a workflow copies every subagent
- * definition into the shared `~/.claude/agents/` dir; a later run that declares
- * `allowedAgents:` copies only the permitted ones but never removes the
- * leftovers — so an unlisted subagent stays on disk and remains dispatchable,
- * silently defeating the fail-closed scope.
- *
- * Fail-closed fix (mirrors how `cleanupWorkflowMcpConfig` only tears down what
- * the workflow itself created): remove any file that (a) belongs to THIS
- * workflow's subagents/ — matched by filename, i.e. the workflow-managed
- * universe — and (b) is NOT in the permitted set. A user's own hand-placed
- * subagent shares no name with a workflow subagent file, so it is never
- * touched. Permitted files are left in place; the caller (re)copies them.
- *
- * `workflowSubagentFiles` are the .md filenames in the workflow's subagents/
- * dir (e.g. `security.md`); `allowedStems` are the permitted stems from
- * `resolveAllowedSubagents`. Returns the filenames actually removed.
- */
 export function pruneStaleWorkflowSubagents(sharedAgentsDir, workflowSubagentFiles, allowedStems) {
     if (!fs.existsSync(sharedAgentsDir))
         return [];
@@ -332,7 +207,7 @@ export function pruneStaleWorkflowSubagents(sharedAgentsDir, workflowSubagentFil
             continue;
         const stem = file.replace(/\.md$/, '');
         if (allow.has(stem))
-            continue; // permitted → the copy step will (re)write it
+            continue;
         const target = path.join(sharedAgentsDir, file);
         if (fs.existsSync(target)) {
             fs.rmSync(target, { force: true });
@@ -341,7 +216,6 @@ export function pruneStaleWorkflowSubagents(sharedAgentsDir, workflowSubagentFil
     }
     return pruned;
 }
-/** Count subagent .md files in a workflow's subagents/ directory. */
 export function countWorkflowSubagents(workflowDir) {
     const subagentsDir = path.join(workflowDir, 'subagents');
     if (!fs.existsSync(subagentsDir))
@@ -377,7 +251,6 @@ function containsFlowDiagram(content) {
 }
 const KIMI_WORKFLOW_MARKER = 'agents_workflow';
 const OPENCLAW_WORKFLOW_MARKER_ENV = 'AGENTS_CLI_WORKFLOW';
-/** Convert a canonical agents-cli workflow bundle into a Kimi flow skill. */
 export function transformWorkflowForKimi(workflowPath, name) {
     const fm = parseWorkflowFrontmatter(workflowPath);
     if (!fm)
@@ -395,14 +268,6 @@ export function transformWorkflowForKimi(workflowPath, name) {
     const instructions = (body || fm.description).trim();
     return `---\n${frontmatter}\n---\n\n\`\`\`d2\nBEGIN -> step -> END\nstep: |md\n${indentD2BlockString(instructions)}\n|\n\`\`\`\n`;
 }
-/**
- * Convert a canonical agents-cli workflow bundle into an Antigravity workflow
- * markdown file. Antigravity discovers workflows as flat `<name>.md` files under
- * `~/.gemini/config/global_workflows/` (scanned by `agy` at startup) and exposes
- * each as a `/<name>` slash command. Frontmatter carries the required `description`
- * plus the shared `agents_workflow` ownership marker so agents-cli never clobbers a
- * user-authored workflow of the same name.
- */
 export function transformWorkflowForAntigravity(workflowPath, name) {
     const fm = parseWorkflowFrontmatter(workflowPath);
     if (!fm)
@@ -415,7 +280,6 @@ export function transformWorkflowForAntigravity(workflowPath, name) {
     }).trim();
     return `---\n${frontmatter}\n---\n\n${body.trim()}\n`;
 }
-/** Convert a canonical agents-cli workflow bundle into an OpenClaw Lobster file. */
 export function transformWorkflowForOpenClaw(workflowPath, name) {
     const fm = parseWorkflowFrontmatter(workflowPath);
     if (!fm)
@@ -444,9 +308,7 @@ export function transformWorkflowForOpenClaw(workflowPath, name) {
         ],
     });
 }
-/** Marker comment prefix written into agents-cli-managed Grok `.rhai` files. */
 export const GROK_WORKFLOW_MARKER = 'agents_workflow';
-/** Escape a string for embedding inside a Rhai double-quoted literal. */
 function escapeRhaiString(s) {
     return s
         .replace(/\\/g, '\\\\')
@@ -455,17 +317,6 @@ function escapeRhaiString(s) {
         .replace(/\n/g, '\\n')
         .replace(/\r/g, '\\n');
 }
-/**
- * Convert a canonical agents-cli workflow bundle into a Grok native Rhai
- * workflow script. Grok discovers saved workflows as
- * `~/.grok/workflows/<name>.rhai` (and project `.grok/workflows/`) and exposes
- * each as a `/<name>` slash command (enabled by default since v0.2.111).
- *
- * The projection is a single-agent orchestrator that feeds the WORKFLOW.md
- * body as the agent prompt plus the caller's `args.prompt` (or string args).
- * Multi-phase fan-out is left to hand-authored Rhai — agents-cli's job is to
- * land the orchestrator instructions in the native path.
- */
 export function transformWorkflowForGrok(workflowPath, name) {
     const fm = parseWorkflowFrontmatter(workflowPath);
     if (!fm)
@@ -494,7 +345,6 @@ export function transformWorkflowForGrok(workflowPath, name) {
         ``,
     ].join('\n');
 }
-/** Read the agents_workflow marker from a Grok `.rhai` file, if present. */
 export function grokWorkflowMarker(filePath) {
     try {
         const content = fs.readFileSync(filePath, 'utf-8');
@@ -522,7 +372,6 @@ function resolveWorkflowPath(ref, cwd) {
     const candidate = path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
     return isWorkflowDir(candidate) ? candidate : null;
 }
-/** Plugin-root marketplace dirs in project → user → system → extra order. */
 function pluginMarketplaceDirs(cwd) {
     const pluginsDirs = [];
     const projectPlugins = getProjectPluginsDir(cwd);
@@ -548,15 +397,6 @@ function isPluginDirectory(pluginRoot, entry) {
     }
     return isDir;
 }
-/**
- * Plugin `workflows/` directories in discovery order (project → user → system →
- * extra). Used by name resolution and listing so a plugin-packaged workflow is
- * runnable via `agents run <name>` without a separate install into
- * ~/.agents/workflows/ (Phase 5 packaging). Within the plugin band, project
- * plugins beat user/system plugins (same first-hit-wins as other layers).
- *
- * Pass `pluginName` to restrict to one plugin (for `name@plugin` resolution).
- */
 export function listPluginWorkflowDirs(cwd = process.cwd(), pluginName) {
     const pluginRoots = [];
     for (const pluginsDir of pluginMarketplaceDirs(cwd)) {
@@ -582,11 +422,6 @@ export function listPluginWorkflowDirs(cwd = process.cwd(), pluginName) {
     }
     return pluginRoots;
 }
-/**
- * True when `ref` is a single bare workflow / source identifier (no path
- * separators, no `..`, no `@`). Name lookup must not path-join multi-segment
- * or traversal refs into search roots. `name@source` is parsed separately.
- */
 export function isBareWorkflowName(ref) {
     if (!ref || ref === '.' || ref === '..')
         return false;
@@ -596,15 +431,10 @@ export function isBareWorkflowName(ref) {
         return false;
     if (ref.includes('@'))
         return false;
-    // Reject absolute paths (posix or Windows).
     if (path.isAbsolute(ref))
         return false;
     return path.basename(ref) === ref;
 }
-/**
- * Parse a workflow run target: optional `workflow:` type prefix and optional
- * `@source` pin. Returns null when the form is not a valid name lookup.
- */
 export function parseWorkflowRef(ref) {
     let r = ref.trim();
     if (r.startsWith('workflow:'))
@@ -623,13 +453,6 @@ export function parseWorkflowRef(ref) {
         return null;
     return { name: r };
 }
-/**
- * Resolve an `agents run <workflow>` reference.
- *
- * Directories are accepted anywhere on disk when they contain WORKFLOW.md.
- * Name lookup precedence (docs/07-entrypoints): project > user > plugin > extra > system.
- * Pin a source with `name@plugin` or `name@extra-alias` (optional `workflow:` prefix).
- */
 export function resolveWorkflowRef(ref, cwd = process.cwd()) {
     const direct = resolveWorkflowPath(ref, cwd);
     if (direct)
@@ -637,7 +460,6 @@ export function resolveWorkflowRef(ref, cwd = process.cwd()) {
     const parsed = parseWorkflowRef(ref);
     if (!parsed)
         return null;
-    // Source-qualified: only that plugin or extra-repo workflows/ (no layered fallback).
     if (parsed.source) {
         for (const dir of listPluginWorkflowDirs(cwd, parsed.source)) {
             const workflowPath = path.join(dir, parsed.name);
@@ -668,14 +490,8 @@ export function resolveWorkflowRef(ref, cwd = process.cwd()) {
     }
     return null;
 }
-/**
- * Discover all workflow directories (those containing WORKFLOW.md) in a local path.
- * Checks if the path itself is a workflow, then scans a top-level workflows/ subdirectory,
- * then falls back to scanning all immediate subdirectories.
- */
 export function discoverWorkflowsFromRepo(repoPath) {
     const results = [];
-    // The path itself may be a single workflow directory.
     if (fs.existsSync(path.join(repoPath, 'WORKFLOW.md'))) {
         const frontmatter = parseWorkflowFrontmatter(repoPath);
         if (frontmatter) {
@@ -687,7 +503,6 @@ export function discoverWorkflowsFromRepo(repoPath) {
                 }];
         }
     }
-    // Try a workflows/ subdirectory first, then fall back to scanning root subdirectories.
     const workflowsSubdir = path.join(repoPath, 'workflows');
     const scanDir = fs.existsSync(workflowsSubdir) ? workflowsSubdir : repoPath;
     let entries;
@@ -713,11 +528,6 @@ export function discoverWorkflowsFromRepo(repoPath) {
     }
     return results;
 }
-/**
- * List all workflows in central storage + plugin packages.
- * Precedence: user > plugin > extra > system (first writer wins; project is
- * cwd-scoped and handled by resolveWorkflowRef / the resource handler).
- */
 export function listInstalledWorkflows(cwd = process.cwd()) {
     const result = new Map();
     const extraRepos = getEnabledExtraRepos();
@@ -741,7 +551,7 @@ export function listInstalledWorkflows(cwd = process.cwd()) {
             if (!entry.isDirectory() || entry.name.startsWith('.'))
                 continue;
             if (result.has(entry.name))
-                continue; // Higher-priority layer already present
+                continue;
             const workflowPath = path.join(dir, entry.name);
             const frontmatter = parseWorkflowFrontmatter(workflowPath);
             if (!frontmatter)
@@ -756,7 +566,6 @@ export function listInstalledWorkflows(cwd = process.cwd()) {
     }
     return result;
 }
-/** Copy a workflow directory into user central storage (~/.agents/workflows/<name>/). */
 export function installWorkflowCentrally(sourcePath, name) {
     const targetPath = path.join(getUserWorkflowsDir(), name);
     try {
@@ -771,7 +580,6 @@ export function installWorkflowCentrally(sourcePath, name) {
         return { success: false, error: err.message };
     }
 }
-/** Move a workflow from user central storage to trash. */
 export function removeWorkflow(name) {
     const sourcePath = path.join(getUserWorkflowsDir(), name);
     if (!fs.existsSync(sourcePath)) {
@@ -787,16 +595,6 @@ export function removeWorkflow(name) {
         return { success: false, error: err.message };
     }
 }
-/**
- * Antigravity user workflows are NOT version-isolated. `agy` scans a single,
- * shared, HOME-global directory at startup — `~/.gemini/config/global_workflows/`
- * — and that dir is a real directory in the user's home, never symlinked into a
- * per-version home (only `~/.gemini/antigravity-cli` is version-scoped). Writing
- * into a version home therefore lands somewhere agy never reads. So every
- * antigravity version resolves to the same real shared dir; `versionHome` is
- * intentionally ignored. (Verified via strace of `agy`: it opens
- * `$HOME/.gemini/config/global_workflows/<name>.md` and never the version home.)
- */
 export function antigravityWorkflowsDir() {
     return path.join(process.env.HOME ?? os.homedir(), '.gemini', 'config', 'global_workflows');
 }
@@ -816,7 +614,7 @@ function parseSubrecipeFrontmatter(filePath) {
             parsed = value;
         }
     }
-    catch { /* ignore malformed subagent frontmatter */ }
+    catch { }
     return {
         name: typeof parsed.name === 'string' ? parsed.name : undefined,
         description: typeof parsed.description === 'string' ? parsed.description : undefined,
@@ -848,12 +646,6 @@ export function writeGooseSubrecipe(workflowPath, subrecipeName, destDir) {
     fs.mkdirSync(destDir, { recursive: true });
     fs.writeFileSync(path.join(destDir, `${subrecipeName}.yaml`), yaml.stringify(recipe), 'utf-8');
 }
-/**
- * Render the main Goose recipe YAML for a workflow — the exact bytes the Goose
- * `WORKFLOW_TARGETS` entry writes to `<name>.yaml`. Extracted so the writer and
- * the doctor content-drift check (`matches`) render from ONE source and can
- * never disagree. Returns null on invalid frontmatter.
- */
 export function renderGooseRecipeYaml(workflowPath, name) {
     const frontmatter = parseWorkflowFrontmatter(workflowPath);
     if (!frontmatter)
@@ -922,7 +714,6 @@ export function openclawWorkflowMarker(filePath) {
         return null;
     }
 }
-/** Iterate all installed (agent, version) pairs that support workflows. */
 export function iterWorkflowsCapableVersions(filter) {
     const result = [];
     for (const agentId of capableAgents('workflows')) {
@@ -932,7 +723,6 @@ export function iterWorkflowsCapableVersions(filter) {
         for (const version of versions) {
             if (filter?.version && filter.version !== version)
                 continue;
-            // Honour version floors (e.g. grok workflows since 0.2.111).
             if (!supports(agentId, 'workflows', version).ok)
                 continue;
             result.push({ agent: agentId, version });

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

@@ -1,142 +1,53 @@
-/**
- * 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>;
-/**
- * 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. */
 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 + 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. */
 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. */
 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. */
 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 {};