@agentproto/worktree 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,24 +1,228 @@
-export { cleanupWorktreeTool, provisionWorktreeTool, runGateTool } from './tools/index.js';
+export { ServiceStatusOutput, cleanupWorktreeTool, listServicesTool, provisionWorktreeTool, runGateTool, runScriptTool, serviceStatusSchema, startServiceTool, stopServiceTool } from './tools/index.js';
 export { worktreeProvider } from './provider/index.js';
 import { z } from 'zod';
+import http from 'node:http';
 import { RuntimeWorkflow, AgentSessionHost } from '@agentproto/workflow-runtime';
 import { StartAgentArgs, SessionDescriptor, TurnEvent, TurnResult, HarnessClient, ConnectHarnessOptions } from '@agentproto/harness';
 import '@agentproto/tool';
 import '@agentproto/driver';
 
+/**
+ * Raised when `worktree.cleanup` can't remove the worktree: either we
+ * categorized the tree ourselves and found a dirty class the caller didn't
+ * authorize (`blocked` names it), or — the no-flags default path — git's own
+ * `worktree remove` refused and we never asked why (`blocked` is empty,
+ * `message` carries git's stderr verbatim).
+ */
+declare class WorktreeNotRemovableError extends Error {
+    readonly cwd: string;
+    readonly blocked: readonly ("untracked" | "modified")[];
+    /**
+     * `blocked` is empty when git itself refused without us categorizing the
+     * tree first (the no-flags default path, PLAN.md §5.2 layer 3) — `detail`
+     * then carries git's own stderr instead of a named class.
+     */
+    constructor(cwd: string, blocked: readonly ("untracked" | "modified")[], detail?: string);
+}
+
+/**
+ * Provenance — which session(s) worked in this worktree, historically,
+ * including dead ones (PLAN.md §1.5). Not a fourth status axis: it never
+ * changes `class`, only triage ("what was the session doing when it
+ * stranded these files?").
+ *
+ * The join is over the EXISTING sessions registry
+ * (`packages/runtime/src/sessions.ts`) — upholding the no-registry
+ * principle (PLAN.md §1.4): nothing new is mirrored, this only reads
+ * files another package already owns and persists. Read directly off disk
+ * (not via a running daemon) so `worktree ls --status` works with no
+ * daemon required, matching `worktree check`'s posture (PLAN.md §3.3).
+ *
+ * ## Where the registry lives (AIP-46 §State partitioning)
+ *
+ * It is no longer one file. The runtime partitions per workspace —
+ * `~/.agentproto/workspaces/<slug>/sessions.json` — and leaves the old
+ * global `~/.agentproto/sessions.json` in place, frozen, as the
+ * pre-partition history. So the default read is the UNION of every bucket
+ * plus that legacy artifact.
+ *
+ * Reading only the legacy file would be quietly destructive here rather
+ * than merely stale: this feeds `computeWorktreeStatus` → the GC plan →
+ * `applyGc`, which REMOVES worktrees. A worktree whose sessions all live
+ * in a bucket would present as never-touched and become eligible for
+ * removal. Under-reporting provenance deletes work; over-reporting only
+ * keeps a worktree around. The union is the safe direction, and the
+ * legacy file stays in the union precisely because provenance's job is
+ * history.
+ *
+ * The bucket layout is duplicated here rather than imported, matching
+ * what this file already did with the sessions path: `@agentproto/worktree`
+ * does not depend on `@agentproto/runtime` and this join is not worth
+ * inverting that.
+ *
+ * Two known limits, both designed in rather than hidden (PLAN.md §1.5):
+ *   - each snapshot is a recency window (`HISTORY_CAP = 200` per bucket,
+ *     `packages/runtime/src/sessions.ts`), not an archive — an old
+ *     worktree's sessions may already be evicted.
+ *   - Without a per-worktree creation marker, the join can span
+ *     generations (a worktree removed and recreated at the same path
+ *     inherits the old generation's sessions). PR-B writes that marker
+ *     (`agentproto-worktree.json` in the worktree's private gitdir); this PR
+ *     only reads it if present and is honest — `confidence: "best-effort"`
+ *     — when it's absent, which is every worktree today.
+ */
+
+/** The pre-partition global snapshot. Still read — it holds every session
+ *  from before the split and the runtime leaves it intact — but no longer
+ *  written. See this file's header. */
+declare const SESSIONS_FILE_PATH: () => string;
+/** Root of the runtime's per-workspace state buckets (AIP-46 §Layout):
+ *  `<root>/<slug>/sessions.json`. */
+declare const SESSIONS_BUCKETS_ROOT: () => string;
+/** The subset of `SessionDescriptor` (`packages/runtime/src/sessions.ts`) provenance needs. */
+declare const sessionRefSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    startedAt: z.ZodString;
+    endedAt: z.ZodOptional<z.ZodString>;
+    status: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SessionRef = z.infer<typeof sessionRefSchema>;
+type ProvenanceConfidence = "exact" | "best-effort";
+interface ProvenanceInfo {
+    confidence: ProvenanceConfidence;
+    sessions: SessionRef[];
+}
+/**
+ * Read the persisted sessions registry.
+ *
+ * With `path`: that exact file, nothing else — what callers pinning a
+ * fixture want.
+ *
+ * Without: the union of every per-workspace bucket plus the legacy global
+ * snapshot (see this file's header for why the union, and why
+ * under-reporting here is dangerous rather than merely lossy). Deduped by
+ * session id, buckets winning over the frozen legacy copy of the same row.
+ *
+ * Missing file (no daemon has ever run) is a legitimate empty registry,
+ * not an error — mirrors `loadHistorySnapshot`'s own ENOENT handling in
+ * `sessions.ts`. A malformed file (present but unparseable) is surfaced by
+ * returning `null` so callers can distinguish "no history" from "history
+ * is unreadable"; in the union that means null only when every source that
+ * exists is unreadable, since one corrupt bucket shouldn't blind the join
+ * to the rest.
+ */
+declare function readSessionsRegistry(path?: string): Promise<SessionRef[] | null>;
+/** `session.cwd == wtPath || session.cwd.startsWith(wtPath + sep)` (PLAN.md §1.5 — containment, not equality). */
+declare function sessionInWorktree(session: SessionRef, worktreePath: string): boolean;
+/** The creation marker PR-B writes into `$(git rev-parse --git-dir)/agentproto-worktree.json`. */
+declare const worktreeMarkerSchema: z.ZodObject<{
+    worktreeId: z.ZodString;
+    createdAt: z.ZodString;
+    createdBySessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type WorktreeMarker = z.infer<typeof worktreeMarkerSchema>;
+/**
+ * Read the per-worktree creation marker, if PR-B has written one. This PR
+ * never writes it — only reads, so a worktree created before PR-B shipped
+ * (all of them, today) honestly reports `confidence: "best-effort"`.
+ */
+declare function readWorktreeMarker(worktreePath: string): Promise<WorktreeMarker | null>;
+/**
+ * Write the creation marker into `$(git rev-parse --git-dir)/agentproto-
+ * worktree.json` — the worktree's own private gitdir, not the shared
+ * `.git/config` (PLAN.md §1.5 rejected `git config --local` for exactly
+ * this reason: in a linked worktree it reads/writes the main repo's shared
+ * config, so it wouldn't die with the worktree and would collide across
+ * worktrees). Called once, by `worktree.provision`, right after the
+ * worktree is created; nothing else ever rewrites it.
+ */
+declare function writeWorktreeMarker(worktreePath: string, marker: WorktreeMarker): Promise<void>;
+interface ComputeProvenanceOptions {
+    sessionsPath?: string;
+}
+/**
+ * The §1.5 join: sessions whose `cwd` is contained in `worktreePath`,
+ * bounded by the marker's `createdAt` when present (filters out sessions
+ * from a prior generation at the same path). `confidence` is `"exact"` only
+ * when that marker exists; otherwise `"best-effort"` — the join may span
+ * generations and is bounded by `HISTORY_CAP`'s recency window.
+ */
+declare function computeProvenance(worktreePath: string, options?: ComputeProvenanceOptions): Promise<ProvenanceInfo>;
+
+/**
+ * Salvage-before-discard (PLAN.md §5.2 layer 4). `worktree archive` re-earns
+ * its name by snapshotting a worktree's uncommitted state before it removes
+ * anything: `git diff HEAD` → `changes.patch`, plus a byte-copy of every
+ * unignored untracked file, into
+ * `~/.agentproto/worktree-salvage/<repoName>/<slug>-<tipSha7>-<date>/` with a
+ * `MANIFEST.json`. Every file is fsynced before this returns — only once the
+ * snapshot is durable does the caller proceed to force-remove.
+ *
+ * Deliberately forge-independent: no PR lookup here. This writer's only job
+ * is "don't lose bytes before deletion," not classification — `ls --status`
+ * (status.ts) already owns the forge-derived `integration` axis, and gc
+ * (PR-D) is where a salvage manifest and a status entry would be cross-
+ * referenced, not here.
+ */
+
+declare const SALVAGE_ROOT: () => string;
+interface SalvageManifest {
+    repo: string;
+    /** `null` for a detached HEAD. */
+    branch: string | null;
+    tipSha: string;
+    createdAt: string;
+    /** Relative paths of every unignored untracked file that was copied in. */
+    untrackedFiles: string[];
+    /** Whether `changes.patch` has any content (tracked-file changes existed). */
+    hasPatch: boolean;
+    provenance: ProvenanceInfo;
+}
+interface SalvageWorktreeInput {
+    repoName: string;
+    worktreePath: string;
+    branch: string | null;
+    tipSha: string;
+    /** Identifies this worktree in the salvage directory name, e.g. its slug or branch. */
+    slug: string;
+    sessionsPath?: string;
+    /** Injectable clock so tests can freeze `createdAt` / the directory name. */
+    now?: () => string;
+    /** Override for `~/.agentproto/worktree-salvage` — tests use a temp dir. */
+    salvageRoot?: string;
+}
+interface SalvageResult {
+    dir: string;
+    manifest: SalvageManifest;
+}
+/**
+ * Snapshot `worktreePath`'s uncommitted state into a fresh salvage
+ * directory. Safe to call on a clean tree (writes an empty patch, no
+ * untracked files, still a manifest) — every path this function returns is
+ * fsynced before it resolves.
+ */
+declare function salvageWorktree(input: SalvageWorktreeInput): Promise<SalvageResult>;
+
 interface ExecResult {
     exitCode: number;
     stdout: string;
     stderr: string;
 }
+/** Extra `AGENTPROTO_*` (or any) vars, merged onto `process.env` for the child. */
+interface ExecOptions {
+    env?: Record<string, string>;
+}
 /** Run an argv (no shell — args pass through verbatim, no injection risk). */
-declare function execArgv(command: string, args: readonly string[], cwd: string): Promise<ExecResult>;
+declare function execArgv(command: string, args: readonly string[], cwd: string, opts?: ExecOptions): Promise<ExecResult>;
 /**
  * Run a single command string through a shell. Callers pass `depsCmd` /
- * `gateCmd` as a trusted, developer-authored config value (the same trust
- * model as a CI job's `script:` line) — not untrusted end-user input.
+ * `gateCmd` / a config `setup` line as a trusted, developer-authored value
+ * (the same trust model as a CI job's `script:` line) — not untrusted
+ * end-user input. `opts.env` layers `AGENTPROTO_*` vars onto the child.
  */
-declare function execShell(cmd: string, cwd: string): Promise<ExecResult>;
+declare function execShell(cmd: string, cwd: string, opts?: ExecOptions): Promise<ExecResult>;
 declare function execGit(repoRoot: string, args: readonly string[]): Promise<ExecResult>;
 
 /** Compile a `/`-separated glob (supporting `*`, `?`, `**`) into an anchored regex. */
@@ -26,6 +230,359 @@ declare function globToRegExp(pattern: string): RegExp;
 /** Expand a glob against `root`, returning root-relative posix paths of matching files. */
 declare function expandGlob(root: string, pattern: string): Promise<string[]>;
 
+/**
+ * `agentproto.json` — the declarative per-repo worktree lifecycle.
+ *
+ * SECURITY: this file is always read from the **committed tree of the base
+ * ref** (`git show <base>:agentproto.json`), never from a worktree's working
+ * tree. A branch (or an agent editing files inside a worktree) therefore
+ * cannot inject setup/teardown hooks or service commands that run on the host
+ * — only what a reviewer merged into the base branch executes.
+ */
+declare const CONFIG_FILENAME = "agentproto.json";
+/** `scripts.<name>` — a command, optionally a long-running service with a port. */
+declare const scriptSchema: z.ZodObject<{
+    command: z.ZodString;
+    type: z.ZodOptional<z.ZodLiteral<"service">>;
+    port: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const configSchema: z.ZodObject<{
+    worktree: z.ZodOptional<z.ZodObject<{
+        setup: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        teardown: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    }, z.core.$strip>>;
+    scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        command: z.ZodString;
+        type: z.ZodOptional<z.ZodLiteral<"service">>;
+        port: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type ScriptConfig = z.infer<typeof scriptSchema>;
+type AgentprotoConfig = z.infer<typeof configSchema>;
+/** A validation failure with the offending file surfaced for error messages. */
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse + validate raw `agentproto.json` text. Throws {@link ConfigError} on
+ * malformed JSON or a schema violation.
+ */
+declare function parseConfig(raw: string): AgentprotoConfig;
+/** Normalise a hook (string | string[] | undefined) into an ordered command list. */
+declare function normalizeHook(hook: string | readonly string[] | undefined): string[];
+/** A named script, with its config attached — the shape supervisor/tools consume. */
+interface NamedScript extends ScriptConfig {
+    name: string;
+}
+/** All declared scripts as a list. */
+declare function listScripts(config: AgentprotoConfig): NamedScript[];
+/** Only the `type: "service"` scripts. */
+declare function listServices(config: AgentprotoConfig): NamedScript[];
+/** Look up a single named script, or `undefined` if it isn't declared. */
+declare function getScript(config: AgentprotoConfig, name: string): NamedScript | undefined;
+/**
+ * Load `agentproto.json` from the **committed tree** of `base` (default
+ * `origin/main`) via `git show <base>:agentproto.json`. Returns `null` when
+ * the base tree has no such file (the common "repo hasn't opted in" case).
+ * Throws {@link ConfigError} on a present-but-invalid file.
+ */
+declare function loadConfigFromBase(repoRoot: string, base?: string): Promise<AgentprotoConfig | null>;
+
+/**
+ * Typed env surface for worktree lifecycle hooks, scripts, and services.
+ *
+ * Every `AGENTPROTO_*` variable the lifecycle feature injects is named here
+ * once — bodies compose env via {@link hookEnv} / {@link serviceEnv} rather
+ * than reading `process.env` (or writing literal `"AGENTPROTO_..."` keys)
+ * ad hoc. Keeps the contract in one place and the derivations testable.
+ */
+/** The `AGENTPROTO_*` variables injected into every hook / script / service. */
+declare const ENV_VARS: {
+    /** Absolute path to the original repo checkout the worktree was cut from. */
+    readonly sourceCheckoutPath: "AGENTPROTO_SOURCE_CHECKOUT_PATH";
+    /** Absolute path to the worktree directory. */
+    readonly worktreePath: "AGENTPROTO_WORKTREE_PATH";
+    /** The worktree's branch name. */
+    readonly branchName: "AGENTPROTO_BRANCH_NAME";
+    /** A service's own allocated port. */
+    readonly port: "AGENTPROTO_PORT";
+    /** A service's own reverse-proxy URL. */
+    readonly url: "AGENTPROTO_URL";
+};
+/** The shared context every worktree lifecycle command runs against. */
+interface WorktreeEnvContext {
+    /** Absolute path to the original repo checkout. */
+    sourceCheckoutPath: string;
+    /** Absolute path to the worktree directory. */
+    worktreePath: string;
+    /** The worktree's branch name. */
+    branchName: string;
+}
+/**
+ * Base env shared by hooks, scripts, and services — the worktree location and
+ * the branch/checkout it derives from. Values are strings only (never
+ * `undefined`), so the result merges cleanly onto `process.env`.
+ */
+declare function hookEnv(ctx: WorktreeEnvContext): Record<string, string>;
+/** A sibling service, as seen by a peer's env. */
+interface PeerService {
+    /** The declared script name (e.g. `"web"`). */
+    name: string;
+    /** The port the service listens on. */
+    port: number;
+    /** The service's reverse-proxy URL. */
+    url: string;
+}
+/**
+ * Upper-case a service name and replace every non-alphanumeric run with a
+ * single `_`, for use inside an env var key (`web-api` → `WEB_API`).
+ */
+declare function serviceEnvToken(name: string): string;
+/** `AGENTPROTO_SERVICE_<TOKEN>_PORT` / `..._URL` for a named peer. */
+declare function peerEnvKey(name: string, suffix: "PORT" | "URL"): string;
+/**
+ * Peer-discovery env for a set of sibling services: each contributes
+ * `AGENTPROTO_SERVICE_<NAME>_PORT` and `AGENTPROTO_SERVICE_<NAME>_URL`.
+ */
+declare function peerEnv(peers: readonly PeerService[]): Record<string, string>;
+/**
+ * Full env for a running service: the shared {@link hookEnv}, the service's
+ * own `AGENTPROTO_PORT` / `AGENTPROTO_URL`, and {@link peerEnv} for every
+ * sibling.
+ */
+declare function serviceEnv(args: {
+    ctx: WorktreeEnvContext;
+    self: PeerService;
+    peers: readonly PeerService[];
+}): Record<string, string>;
+
+/** One hook command's result, kept for error reporting / logging. */
+interface HookRun {
+    command: string;
+    result: ExecResult;
+}
+/** Raised when a `setup` hook exits non-zero — carries the captured output. */
+declare class HookError extends Error {
+    readonly command: string;
+    readonly result: ExecResult;
+    constructor(phase: "setup" | "teardown", run: HookRun);
+}
+/**
+ * Run the `worktree.setup` hooks sequentially in the worktree, with the
+ * `AGENTPROTO_*` context env injected. The first non-zero exit throws
+ * {@link HookError} (setup failure must fail provisioning). No-op when the
+ * repo declares no setup.
+ */
+declare function runSetup(config: AgentprotoConfig, ctx: WorktreeEnvContext): Promise<HookRun[]>;
+/**
+ * Run the `worktree.teardown` hooks sequentially. Unlike setup, a failing
+ * teardown hook does NOT throw — cleanup must proceed — so failures are
+ * returned for the caller to log. No-op when no teardown is declared.
+ */
+declare function runTeardown(config: AgentprotoConfig, ctx: WorktreeEnvContext): Promise<HookRun[]>;
+
+/**
+ * The proxy routing table: `<hostname>` → local service port.
+ *
+ * Kept separate from the HTTP server (see `proxy-server.ts`) so the supervisor
+ * can register/unregister routes without owning a live socket, and so routing
+ * can be unit-tested without binding a port.
+ */
+declare class ProxyTable {
+    private readonly routes;
+    /** Register (or replace) the target port for a hostname. */
+    set(hostname: string, port: number): void;
+    /** Remove a hostname's route. Returns whether it was present. */
+    delete(hostname: string): boolean;
+    /** The target port registered for an exact hostname, if any. */
+    get(hostname: string): number | undefined;
+    /**
+     * Resolve a raw `Host` header (which may carry a `:port` suffix, and for
+     * IPv6 a bracketed host) to a target port.
+     */
+    lookup(hostHeader: string | undefined): number | undefined;
+    /** All `[hostname, port]` routes currently registered. */
+    entries(): Array<[string, number]>;
+    /** Number of registered routes. */
+    get size(): number;
+}
+/** Strip a trailing `:port` from a Host header, honouring `[ipv6]:port`. */
+declare function stripPort(hostHeader: string): string;
+
+/** A declared service with its resolved port / hostname / proxy URL. */
+interface ServiceRuntime {
+    name: string;
+    command: string;
+    hostname: string;
+    port: number;
+    url: string;
+}
+/** The observable state of a service (v1: no restart — just track the exit). */
+interface ServiceStatus {
+    name: string;
+    hostname: string;
+    port: number;
+    url: string;
+    pid: number | null;
+    status: "running" | "exited";
+    exitCode: number | null;
+    startedAt: string | null;
+}
+interface SupervisorOptions {
+    ctx: WorktreeEnvContext;
+    /** The `type: "service"` scripts from the repo's `agentproto.json`. */
+    services: readonly NamedScript[];
+    /** Repo label for the hostname (typically the repo dir basename). */
+    repo: string;
+    /** Whether the worktree's branch is the repo default (drops the branch label). */
+    isDefaultBranch: boolean;
+    /** Port the reverse proxy listens on — used to build each service's URL. */
+    proxyPort: number;
+    /** When given, service hostnames are (de)registered here as they start/stop. */
+    proxyTable?: ProxyTable;
+}
+/**
+ * Supervises the long-running services declared for one worktree. Ports are
+ * allocated up front for every declared service so peer discovery is complete
+ * (a service started later is visible to one started earlier only if its port
+ * was reserved — which it is), and hostnames register with the proxy table as
+ * services come up.
+ *
+ * v1 scope: no crash-restart loop. A service that exits is marked `exited`
+ * with its code; callers decide what to do.
+ */
+declare class ServiceSupervisor {
+    private readonly opts;
+    private readonly tracked;
+    private constructor();
+    /**
+     * Build a supervisor, allocating a port for every declared service (declared
+     * port if free, else ephemeral) and resolving each one's hostname + URL.
+     * Nothing is spawned yet.
+     */
+    static create(opts: SupervisorOptions): Promise<ServiceSupervisor>;
+    /** Every declared service's resolved runtime (ports/urls), regardless of state. */
+    runtimes(): ServiceRuntime[];
+    /** Peers of `name` — every other declared service, as `PeerService` records. */
+    private peersOf;
+    private toStatus;
+    /**
+     * Start a declared service. Idempotent: returns the current status if it's
+     * already running. Injects `AGENTPROTO_PORT` / `AGENTPROTO_URL` for itself
+     * plus `AGENTPROTO_SERVICE_<PEER>_PORT|URL` for every sibling.
+     */
+    start(name: string): ServiceStatus;
+    /** Stop a running service (SIGTERM). Returns whether one was running. */
+    stop(name: string): Promise<boolean>;
+    /** Stop every running service. */
+    stopAll(): Promise<void>;
+    /** Current status of a single service, or `undefined` if not declared. */
+    get(name: string): ServiceStatus | undefined;
+    /** Current status of every declared service. */
+    list(): ServiceStatus[];
+}
+
+/** Build (but don't start) the proxy HTTP server backed by `table`. */
+declare function createProxyServer(table: ProxyTable): http.Server;
+interface RunningProxy {
+    /** The port the proxy is listening on. */
+    port: number;
+    /** The underlying server. */
+    server: http.Server;
+    /** Stop the proxy. */
+    close(): Promise<void>;
+}
+/** Start the proxy server on `port` (0 → OS-assigned). Resolves once listening. */
+declare function startProxy(table: ProxyTable, port?: number): Promise<RunningProxy>;
+
+/**
+ * Hostname derivation for the `*.localhost` reverse proxy.
+ *
+ * A service is reachable at:
+ *   http://<script>--<branch-slug>--<repo-slug>.localhost:<proxy-port>
+ * except on the repo's default branch, where the branch label is dropped:
+ *   http://<script>--<repo-slug>.localhost:<proxy-port>
+ *
+ * `*.localhost` resolves to 127.0.0.1 on modern systems, so no DNS work is
+ * needed — the proxy just matches on the Host header.
+ */
+/** Lowercase, non-alphanumerics → `-`, collapse repeats, trim leading/trailing `-`. */
+declare function slugify(input: string): string;
+interface HostnameParts {
+    /** The script/service name (e.g. `"web"`). */
+    script: string;
+    /** The worktree's branch (e.g. `"wt/fix-flaky"`). */
+    branch: string;
+    /** The repo identifier (e.g. its directory basename). */
+    repo: string;
+    /** True when `branch` is the repo's default branch — drops the branch label. */
+    isDefaultBranch: boolean;
+}
+/** The bare hostname (no scheme, no port) a service is proxied under. */
+declare function serviceHostname(parts: HostnameParts): string;
+/** The full proxy URL (`http://<hostname>:<proxy-port>`) for a service. */
+declare function serviceUrl(parts: HostnameParts, proxyPort: number): string;
+
+/**
+ * Port allocation for supervised services.
+ *
+ * A service declares a preferred `port`; we use it if free, otherwise we fall
+ * back to an OS-assigned ephemeral port. Allocation binds a probe socket on
+ * 127.0.0.1 to decide — there's an inherent TOCTOU window between the probe
+ * closing and the service binding, but for local dev supervision that's the
+ * same race every "is this port free" check has, and the service will simply
+ * fail to bind if something grabbed it in between.
+ */
+/** Resolve to `true` if a TCP listen on `127.0.0.1:<port>` succeeds. */
+declare function isPortFree(port: number): Promise<boolean>;
+/** Ask the OS for a free ephemeral port (bind to 0, read the assigned port). */
+declare function ephemeralPort(): Promise<number>;
+/**
+ * Allocate a port for a service: the declared `preferred` if it's free,
+ * otherwise an OS-assigned ephemeral port. Ports in `reserved` (already handed
+ * out to sibling services this session) are treated as taken.
+ */
+declare function allocatePort(preferred: number | undefined, reserved?: ReadonlySet<number>): Promise<number>;
+
+/**
+ * Derive the hostname-facing repo label from a repo root path — its directory
+ * basename (the proxy slugs it further).
+ */
+declare function repoLabel(repoRoot: string): string;
+/**
+ * Best-effort detection of a repo's default branch, for deciding whether the
+ * branch label is dropped from a service hostname. Prefers the symbolic
+ * `origin/HEAD` ref, falls back to `main` / `master` presence, then `main`.
+ */
+declare function detectDefaultBranch(repoRoot: string): Promise<string>;
+
+/** The shared reverse-proxy routing table (hostname → service port). */
+declare const sharedProxyTable: ProxyTable;
+/** Default reverse-proxy port when a caller doesn't pin one. */
+declare const DEFAULT_PROXY_PORT = 18780;
+interface ResolveSupervisorInput {
+    repoRoot: string;
+    worktreePath: string;
+    branch: string;
+    base?: string;
+    proxyPort?: number;
+}
+/** The context the service tools resolve before touching the supervisor. */
+interface ResolvedWorktreeRuntime {
+    supervisor: ServiceSupervisor;
+    config: AgentprotoConfig;
+}
+/**
+ * Resolve (creating on first use) the supervisor for a worktree: read the
+ * committed `agentproto.json` from `base`, build service runtimes with
+ * allocated ports, and cache it keyed by worktree path.
+ */
+declare function resolveSupervisor(input: ResolveSupervisorInput): Promise<ResolvedWorktreeRuntime>;
+/** The cached supervisor for a worktree, if one has been resolved. */
+declare function getSupervisor(worktreePath: string): ServiceSupervisor | undefined;
+/** Stop all services for a worktree and drop its supervisor (used by cleanup). */
+declare function disposeSupervisor(worktreePath: string): Promise<void>;
+
 /**
  * Input to the worktree-agent workflow: launch a coding agent inside a
  * fresh git worktree, gate its work, and — on approval — clean up.
@@ -50,6 +607,410 @@ type WorktreeAgentInput = z.infer<typeof worktreeAgentInputSchema>;
  */
 declare const worktreeAgentWorkflow: RuntimeWorkflow;
 
+/**
+ * `ForgeClient` — the only network-facing surface the reconciliation rule
+ * (`status.ts`) depends on. Kept as an interface (not a concrete `gh` call)
+ * so:
+ *   1. `status.ts` stays testable with a fake — the fixture-repo tests never
+ *      shell out to a real forge or touch the network.
+ *   2. The shape is forge-portable by construction (PLAN.md §7.1): GitLab has
+ *      the same two facts — "PRs/MRs whose head is this branch" and "PRs/MRs
+ *      that contain this commit" — under different verbs
+ *      (`refs/merge-requests/<n>/head`, `GET /merge_requests?…`). Only
+ *      GitHub ships today; a `GitlabForgeClient` is a second implementation
+ *      of this same interface, not a redesign.
+ *
+ * Two implementations ship: `GhCliForgeClient` (shells out to the `gh` CLI,
+ * inheriting the caller's own `gh auth` session — zero config) and
+ * `RestForgeClient` (plain `fetch` against the GitHub REST API using
+ * `GITHUB_TOKEN` — no new npm dependency). `createForgeClient` picks
+ * whichever is usable; when neither is, callers get a client that always
+ * reports itself unreachable, which the reconciliation rule already knows
+ * how to fall back from (PLAN.md §1.3 step 5: memo, else `unknown(offline)`,
+ * never a guess).
+ */
+/** A pull/merge request as the reconciliation rule needs to see it. */
+interface ForgePullRequestRef {
+    number: number;
+    state: "open" | "closed";
+    merged: boolean;
+    mergedAt: string | null;
+    headRefName: string;
+    headRefOid: string;
+}
+/**
+ * Thrown by a `ForgeClient` method when the forge could not be reached or
+ * queried at all (network failure, missing/unauthenticated CLI, non-2xx HTTP
+ * response). Never thrown for a legitimate empty result (a branch/commit
+ * with no PRs is a valid, resolvable answer — `[]`, not an error). Callers
+ * treat this as PLAN.md §1.3 step 5: "never guess."
+ */
+declare class ForgeUnavailableError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+interface ForgeClient {
+    /** PRs/MRs (any state) whose head branch is exactly `branch`. */
+    pullRequestsForBranch(branch: string): Promise<ForgePullRequestRef[]>;
+    /**
+     * PRs/MRs associated with a specific commit SHA — the rename/retarget-proof
+     * signal (PLAN.md §1.3 step 2b): finds the PR even if the branch was
+     * renamed or deleted before merge.
+     */
+    pullRequestsForCommit(sha: string): Promise<ForgePullRequestRef[]>;
+    /**
+     * Ensure `oid` (a PR's `headRefOid`) is present in the local object
+     * database, fetching `refs/pull/<number>/head` if it isn't. Always
+     * fetchable even after the head branch was deleted on the remote
+     * (PLAN.md §1.3 step 2, verified for #273/#312/#325/#271).
+     */
+    ensurePullHeadFetched(prNumber: number, oid: string): Promise<void>;
+}
+/** A client that always reports itself unreachable — the "no gh, no token" case. */
+declare class UnreachableForgeClient implements ForgeClient {
+    private readonly reason;
+    constructor(reason: string);
+    pullRequestsForBranch(): Promise<ForgePullRequestRef[]>;
+    pullRequestsForCommit(): Promise<ForgePullRequestRef[]>;
+    ensurePullHeadFetched(): Promise<void>;
+}
+/** Runs `gh` in `repoRoot` so it auto-detects owner/repo from the `origin` remote there. */
+declare class GhCliForgeClient implements ForgeClient {
+    private readonly repoRoot;
+    constructor(repoRoot: string);
+    private runRaw;
+    private run;
+    private parseOutput;
+    pullRequestsForBranch(branch: string): Promise<ForgePullRequestRef[]>;
+    pullRequestsForCommit(sha: string): Promise<ForgePullRequestRef[]>;
+    ensurePullHeadFetched(prNumber: number, oid: string): Promise<void>;
+}
+/** Parse `owner/repo` out of a `git remote get-url origin` value (ssh or https form). */
+declare function parseGithubOwnerRepo(remoteUrl: string): {
+    owner: string;
+    repo: string;
+} | null;
+declare class RestForgeClient implements ForgeClient {
+    private readonly owner;
+    private readonly repo;
+    private readonly repoRoot;
+    private readonly token;
+    private readonly fetchFn;
+    constructor(owner: string, repo: string, repoRoot: string, token: string, fetchFn?: typeof fetch);
+    private headers;
+    private get;
+    private pullRequestList;
+    pullRequestsForBranch(branch: string): Promise<ForgePullRequestRef[]>;
+    pullRequestsForCommit(sha: string): Promise<ForgePullRequestRef[]>;
+    ensurePullHeadFetched(prNumber: number, oid: string): Promise<void>;
+}
+/**
+ * Pick the best available `ForgeClient` for `repoRoot`: `gh` CLI first (zero
+ * config, inherits the caller's own auth), else `GITHUB_TOKEN` REST, else a
+ * client that always reports unreachable — the reconciliation rule already
+ * knows how to fall back from that (memo, else `unknown(offline)`).
+ */
+declare function createForgeClient(repoRoot: string): Promise<ForgeClient>;
+
+/**
+ * The status engine (PLAN.md §1–§1.5): a worktree's status is derived at
+ * read time from three orthogonal axes — `tree`, `integration`, `liveness`
+ * — plus a `provenance` field that never affects classification. Nothing
+ * here is a registry: every value is recomputed from git, the forge, and
+ * the sessions snapshot on every call (PLAN.md §1.4's no-registry
+ * principle). The one piece of durable state, the verdict memo
+ * (`~/.agentproto/worktree-verdicts.json`), is a memo of *immutable* facts
+ * only (a merged PR stays merged) — deleting it changes nothing but speed
+ * and offline honesty, the acid test a real registry fails.
+ *
+ * The reconciliation rule (`reconcileIntegration`, PLAN.md §1.3) is the
+ * heart of this module: it is why ad-hoc shell answers to "how many
+ * worktrees are stale?" went 5 → 22 → 21+8 in one session, and why this is
+ * code with tests instead. Every step is a pure function of `(T,
+ * origin/main, the forge's merged-PR records)` — content-addressed inputs,
+ * so two runs at the same repo state produce byte-identical answers.
+ */
+
+type TreeState = {
+    state: "clean";
+} | {
+    state: "dirty";
+    modified: number;
+    staged: number;
+    untracked: number;
+    /**
+     * Newest mtime (epoch ms) among the worktree's own dirty paths
+     * (unstaged, staged, and untracked), or `null` if it couldn't be
+     * determined. Feeds `classify`'s `RECENT_WRITE_HOLD_WINDOW_MS` guard —
+     * a liveness-independent "someone touched this a moment ago" signal.
+     */
+    newestMtimeMs: number | null;
+};
+/**
+ * `git status --porcelain=v2` in the worktree itself (not `repoRoot` — tree
+ * state is per-worktree). Gitignored files never appear here (no
+ * `--ignored` flag passed), matching git's own non-`--force` `worktree
+ * remove` tolerance for them (PLAN.md §0.5) — the two notions of "clean"
+ * agree by construction.
+ */
+declare function computeTreeState(worktreePath: string): Promise<TreeState>;
+declare const integrationStateSchema: z.ZodUnion<readonly [z.ZodObject<{
+    state: z.ZodLiteral<"fresh">;
+    checkedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"merged">;
+    via: z.ZodLiteral<"squash">;
+    pr: z.ZodNumber;
+    offline: z.ZodBoolean;
+    checkedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"partial">;
+    pr: z.ZodNumber;
+    aheadBy: z.ZodNumber;
+    offline: z.ZodBoolean;
+    checkedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"open">;
+    pr: z.ZodNumber;
+    offline: z.ZodBoolean;
+    checkedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"pushed-no-pr">;
+    checkedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"unpushed">;
+    aheadBy: z.ZodNumber;
+    checkedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"local-only">;
+    checkedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"gone-unexplained">;
+    checkedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"diverged">;
+    offline: z.ZodBoolean;
+    checkedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"detached">;
+    checkedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"unknown">;
+    reason: z.ZodLiteral<"offline">;
+    checkedAt: z.ZodString;
+}, z.core.$strip>]>;
+/** PLAN.md §1.2's `integration` axis, in full — every state the rule can produce. */
+type IntegrationState = z.infer<typeof integrationStateSchema>;
+declare const verdictMemoRecordSchema: z.ZodObject<{
+    repo: z.ZodString;
+    branch: z.ZodString;
+    tipSha: z.ZodString;
+    verdict: z.ZodUnion<readonly [z.ZodObject<{
+        state: z.ZodLiteral<"fresh">;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"merged">;
+        via: z.ZodLiteral<"squash">;
+        pr: z.ZodNumber;
+        offline: z.ZodBoolean;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"partial">;
+        pr: z.ZodNumber;
+        aheadBy: z.ZodNumber;
+        offline: z.ZodBoolean;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"open">;
+        pr: z.ZodNumber;
+        offline: z.ZodBoolean;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"pushed-no-pr">;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"unpushed">;
+        aheadBy: z.ZodNumber;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"local-only">;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"gone-unexplained">;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"diverged">;
+        offline: z.ZodBoolean;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"detached">;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+        reason: z.ZodLiteral<"offline">;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>]>;
+    checkedAt: z.ZodString;
+}, z.core.$strip>;
+type VerdictMemoRecord = z.infer<typeof verdictMemoRecordSchema>;
+declare const VERDICT_MEMO_PATH: () => string;
+/** Only forge-derived verdicts are ever memoised (PLAN.md §1.4/§2) — local-only classifications need no cache. */
+interface VerdictMemoStore {
+    get(repo: string, branch: string, tipSha: string): Promise<VerdictMemoRecord | null>;
+    set(record: VerdictMemoRecord): Promise<void>;
+}
+/**
+ * `~/.agentproto/worktree-verdicts.json` — entries keyed by `(repo, branch,
+ * tipSha)`. This is NOT a third status authority (PLAN.md §1.4): every
+ * entry memoises an immutable fact (a containment check between two fixed
+ * SHAs has one eternal answer; a merged PR stays merged). Deleting the file
+ * changes nothing but speed and offline honesty.
+ */
+declare class FileVerdictMemoStore implements VerdictMemoStore {
+    private readonly path;
+    private cache;
+    constructor(path?: string);
+    private load;
+    get(repo: string, branch: string, tipSha: string): Promise<VerdictMemoRecord | null>;
+    set(record: VerdictMemoRecord): Promise<void>;
+}
+/** In-memory-only store — for tests, or callers that don't want a durable memo. */
+declare class InMemoryVerdictMemoStore implements VerdictMemoStore {
+    private readonly map;
+    get(repo: string, branch: string, tipSha: string): Promise<VerdictMemoRecord | null>;
+    set(record: VerdictMemoRecord): Promise<void>;
+}
+interface GitWorktreeRef {
+    path: string;
+    /** `null` for a detached HEAD. */
+    branch: string | null;
+    head: string;
+}
+/** Parses `git worktree list --porcelain` — every linked worktree of `repoRoot`, wherever it lives. */
+declare function listGitWorktrees(repoRoot: string): Promise<GitWorktreeRef[]>;
+interface ReconcileIntegrationInput {
+    repoRoot: string;
+    repoName: string;
+    /** `null` for a detached HEAD — short-circuits to `{ state: "detached" }` (step 0). */
+    branch: string | null;
+    tipSha: string;
+    forge: ForgeClient;
+    memo: VerdictMemoStore;
+    /** Default `"origin/main"` — matches `loadConfigFromBase`'s own default. */
+    defaultBranchRef?: string;
+    /** Injectable clock so callers (the determinism test) can freeze `checkedAt`. */
+    now?: () => string;
+}
+/**
+ * PLAN.md §1.3 — the heart of the design. Implements the six-step rule
+ * exactly: local ancestry first (cheap, no forge), then the forge's
+ * merged-PR containment check (the squash-proof signal), then open PRs,
+ * then local upstream tracking, with the verdict memo as the only fallback
+ * when the forge is unreachable. Never guesses (step 5): a memo miss while
+ * offline is `unknown(offline)`, full stop.
+ */
+declare function reconcileIntegration(input: ReconcileIntegrationInput): Promise<IntegrationState>;
+/** `services` is always empty in PR-A — service liveness needs the daemon's in-process `ServiceSupervisor` (out of scope, see below). */
+type LivenessState = {
+    state: "idle";
+    sessions: ProvenanceInfo["sessions"];
+    services: string[];
+} | {
+    state: "sessions";
+    sessions: ProvenanceInfo["sessions"];
+    services: string[];
+} | {
+    state: "daemon-unreachable";
+    sessions: ProvenanceInfo["sessions"];
+    services: string[];
+};
+/**
+ * Live sessions whose `cwd` is contained in this worktree, read off the
+ * same persisted sessions snapshot as provenance (PLAN.md §1.5) — no
+ * running daemon required, matching `worktree check`'s no-daemon posture
+ * (PLAN.md §3.3). Service liveness needs the daemon's in-process
+ * `ServiceSupervisor` and is out of scope here (`services` is always `[]`);
+ * `daemon-unreachable` fires only when the sessions snapshot itself is
+ * present but unreadable (corrupt/permission-denied), not merely absent —
+ * "no daemon has ever run" is a legitimate empty registry, not an error.
+ */
+declare function computeLiveness(worktreePath: string, options?: ComputeProvenanceOptions): Promise<LivenessState>;
+type GateState = {
+    state: "none";
+};
+type WorktreeClass = "reclaim" | "salvage" | "hold";
+interface Classification {
+    reclaimable: boolean;
+    class: WorktreeClass;
+}
+/**
+ * `reclaimable ⇔ tree=clean ∧ integration ∈ {merged, fresh} ∧ liveness ∈
+ * {idle, daemon-unreachable}` (PLAN.md §1.2). `daemon-unreachable` is
+ * allowed because the hard guarantee against losing work is git's own
+ * non-`--force` removal refusal, not the liveness probe. `fresh` reclaims
+ * when clean for the same reason: a clean tree has nothing uncommitted to
+ * lose, so it doesn't matter that `fresh` can't distinguish "never had
+ * commits" from "real commits, fast-forwarded into main" (see
+ * `reconcileIntegration` step 1) — either way there's nothing at risk.
+ *
+ * Salvage is narrower than reclaim on purpose: only `merged` (always
+ * forge-confirmed — see `reconcileIntegration`) ever licenses destroying
+ * dirty, uncommitted work — `fresh` never does, clean or not, because the
+ * ambiguity in what `fresh` can prove is exactly what destroyed a live
+ * worktree via `gc --apply --salvage-dirty` on 2026-07-15: a branch with
+ * zero commits of its own read as "merged" and its uncommitted work was
+ * salvaged-then-removed out from under a running agent. A `merged ∧ dirty`
+ * worktree written to inside `RECENT_WRITE_HOLD_WINDOW_MS` also holds
+ * instead of salvaging — see that constant's doc. Everything else is
+ * `hold`.
+ */
+declare function classify(tree: TreeState, integration: IntegrationState, liveness: LivenessState, nowMs?: number): Classification;
+interface WorktreeStatusEntry {
+    path: string;
+    branch: string | null;
+    head: string;
+    tree: TreeState;
+    integration: IntegrationState;
+    liveness: LivenessState;
+    provenance: ProvenanceInfo;
+    gate: GateState;
+    reclaimable: boolean;
+    class: WorktreeClass;
+}
+interface ComputeWorktreeStatusInput {
+    repoRoot: string;
+    repoName: string;
+    worktree: GitWorktreeRef;
+    forge: ForgeClient;
+    memo: VerdictMemoStore;
+    defaultBranchRef?: string;
+    sessionsPath?: string;
+    now?: () => string;
+    /**
+     * Clock for `classify`'s `RECENT_WRITE_HOLD_WINDOW_MS` guard — deliberately
+     * separate from `now`. `now` freezes `checkedAt` stamps for deterministic
+     * tests and is often a fixed past instant; file mtimes are always real
+     * wall-clock, so comparing them against a frozen-past `now` would make
+     * every dirty fixture look like it was written in the future (a negative,
+     * and therefore always-"recent", delta). Defaults to `Date.now()`.
+     */
+    nowMs?: number;
+}
+/** Computes all three axes + provenance + classification for one worktree. */
+declare function computeWorktreeStatus(input: ComputeWorktreeStatusInput): Promise<WorktreeStatusEntry>;
+interface ListWorktreeStatusesInput {
+    repoRoot: string;
+    repoName: string;
+    forge: ForgeClient;
+    memo: VerdictMemoStore;
+    defaultBranchRef?: string;
+    sessionsPath?: string;
+    now?: () => string;
+}
+/** Enumerates every linked worktree of `repoRoot` (`git worktree list`) and computes its status. */
+declare function listWorktreeStatuses(input: ListWorktreeStatusesInput): Promise<WorktreeStatusEntry[]>;
+
 /** The subset of `HarnessClient` the host drives — narrowed for fake-client tests. */
 type DaemonClient = Pick<HarnessClient, "start" | "prompt" | "output" | "kill" | "waitForAny" | "close">;
 interface DaemonAgentSessionHost extends AgentSessionHost {
@@ -88,4 +1049,152 @@ declare function connectDaemonAgentSessionHost(opts?: ConnectHarnessOptions): Pr
 /** Build the host over an already-connected client (exported for tests with a fake client). */
 declare function makeDaemonAgentSessionHost(client: DaemonClient): DaemonAgentSessionHost;
 
-export { type DaemonAgentSessionHost, type DaemonClient, type ExecResult, type WorktreeAgentInput, connectDaemonAgentSessionHost, execArgv, execGit, execShell, expandGlob, globToRegExp, makeDaemonAgentSessionHost, worktreeAgentInputSchema, worktreeAgentWorkflow };
+/**
+ * `gc` (PLAN.md §5, PR-D): plan → apply → salvage over the status engine's
+ * classification (`status.ts`, PR-A). This module owns no new git knowledge
+ * — it reuses `listGitWorktrees` / `computeWorktreeStatus` / `classify` for
+ * every fact and `salvageWorktree` / `worktree.cleanup` (PR-C) for every
+ * mutation. Its only original logic is sequencing the four safety layers
+ * (PLAN.md §5.2):
+ *
+ *   1. `planGc` is pure read: it classifies every worktree and returns a
+ *      plan. Nothing is mutated by calling it — the CLI's dry-run default
+ *      *is* just "call planGc, print it, stop."
+ *   2. `applyGc` re-derives each worktree's class from scratch immediately
+ *      before touching it (a fresh `listGitWorktrees` + `computeWorktreeStatus`,
+ *      not a reuse of the plan's stale snapshot) and refuses to act if the
+ *      class changed since the plan was made.
+ *   3. The actual removal is `worktree.cleanup` with NO discard flags for a
+ *      reclaim-class entry — git's own non-`--force` refusal is the backstop
+ *      this module leans on, never a force flag "just in case."
+ *   4. A salvage-class entry is only ever touched via `salvageWorktree`
+ *      followed by `worktree.cleanup` with both discard flags — snapshot
+ *      first, removal only after the snapshot is durable (mirrors `worktree
+ *      archive`'s CLI verb, PR-C).
+ *
+ * The main worktree (`repoRoot` itself) is never part of the plan: `git
+ * worktree list`'s first entry is always the main checkout, and a repo
+ * sitting on an up-to-date default branch is trivially `fresh ∧ clean` —
+ * exactly what `reclaim` looks for. Git itself refuses to remove
+ * the main working tree ("is a main working tree", verified empirically),
+ * but this module doesn't lean on that as the only guard: the main worktree
+ * is filtered out before classification even runs, so it can never appear
+ * in a plan, let alone be attempted.
+ */
+
+type GcClass = "reclaim" | "salvage" | "hold";
+interface ClassifyForGcOptions {
+    /**
+     * A clean, idle/daemon-unreachable DETACHED worktree moves from `hold` to
+     * `reclaim` (PLAN.md §5.1). This is the only reclassification power any
+     * flag has: every other hold reason — partial, open, unknown(offline),
+     * gone-unexplained, diverged — is untouched by any flag, ever. Default
+     * false.
+     */
+    includeDetached?: boolean;
+    /** Threaded straight through to `classify`'s `RECENT_WRITE_HOLD_WINDOW_MS` guard. Defaults to `Date.now()`. */
+    nowMs?: number;
+}
+/**
+ * gc's own classifier, layered on top of `classify` (status.ts) rather than
+ * reimplementing it — reuse first (AGENTS.md, PLAN.md §0.6). The one thing
+ * `classify` cannot know is `--include-detached`, a gc-specific flag; that
+ * override lives here, not in the read-only status engine `ls --status`
+ * also depends on.
+ */
+declare function classifyForGc(tree: TreeState, integration: IntegrationState, liveness: LivenessState, options?: ClassifyForGcOptions): GcClass;
+interface GcPlanEntry {
+    path: string;
+    branch: string | null;
+    head: string;
+    tree: TreeState;
+    integration: IntegrationState;
+    liveness: LivenessState;
+    /** Classification per PLAN.md §5.1, after `--include-detached` (if set). */
+    class: GcClass;
+}
+interface PlanGcInput {
+    repoRoot: string;
+    repoName: string;
+    forge: ForgeClient;
+    memo: VerdictMemoStore;
+    defaultBranchRef?: string;
+    sessionsPath?: string;
+    includeDetached?: boolean;
+    now?: () => string;
+    /** See `ComputeWorktreeStatusInput.nowMs` (status.ts) — kept separate from `now`. Defaults to `Date.now()`. */
+    nowMs?: number;
+}
+/**
+ * The dry-run plan (PLAN.md §5.2 layer 1): classify every linked worktree,
+ * mutate nothing. This is the human's decision surface — `gc` with no flags
+ * is exactly "call this, print it, stop."
+ */
+declare function planGc(input: PlanGcInput): Promise<GcPlanEntry[]>;
+interface ApplyGcOptions {
+    repoRoot: string;
+    repoName: string;
+    forge: ForgeClient;
+    memo: VerdictMemoStore;
+    defaultBranchRef?: string;
+    sessionsPath?: string;
+    includeDetached?: boolean;
+    /** Archive (salvage-then-remove) every salvage-class entry. Default false — salvage entries are left untouched. */
+    salvageDirty?: boolean;
+    now?: () => string;
+    /** See `ComputeWorktreeStatusInput.nowMs` (status.ts) — kept separate from `now`. Defaults to `Date.now()`. */
+    nowMs?: number;
+    /** Override for `~/.agentproto/worktree-salvage` — tests use a temp dir. */
+    salvageRoot?: string;
+}
+type GcApplyOutcome = {
+    path: string;
+    branch: string | null;
+    result: "reclaimed";
+} | {
+    path: string;
+    branch: string | null;
+    result: "salvaged";
+    salvageDir: string;
+} | {
+    path: string;
+    branch: string | null;
+    result: "held";
+}
+/** Salvage-class, but `--salvage-dirty` was not passed: left untouched by design. */
+ | {
+    path: string;
+    branch: string | null;
+    result: "skipped-dirty";
+}
+/** Layer 2: re-classified at apply time to something other than the plan said — refuses rather than acting on a stale plan. */
+ | {
+    path: string;
+    branch: string | null;
+    result: "aborted-reclassified";
+    from: GcClass;
+    to: GcClass;
+}
+/** The worktree named in the plan no longer exists (already removed by something else since the plan was made). */
+ | {
+    path: string;
+    branch: string | null;
+    result: "aborted-vanished";
+}
+/** git itself (or the salvage snapshot) refused — the TOCTOU backstop actually firing, or a real I/O failure. */
+ | {
+    path: string;
+    branch: string | null;
+    result: "failed";
+    message: string;
+};
+/**
+ * Execute a plan (PLAN.md §5.2 layers 2–4). Every entry is re-classified
+ * from scratch immediately before it's touched; a `hold` entry is never
+ * touched, a `salvage` entry is only touched when `salvageDirty` is true,
+ * and every removal goes through `worktree.cleanup` — never a hand-rolled
+ * `git worktree remove`.
+ */
+declare function applyGc(plan: readonly GcPlanEntry[], options: ApplyGcOptions): Promise<GcApplyOutcome[]>;
+
+export { type AgentprotoConfig, type ApplyGcOptions, CONFIG_FILENAME, type Classification, type ClassifyForGcOptions, type ComputeProvenanceOptions, type ComputeWorktreeStatusInput, ConfigError, DEFAULT_PROXY_PORT, type DaemonAgentSessionHost, type DaemonClient, ENV_VARS, type ExecOptions, type ExecResult, FileVerdictMemoStore, type ForgeClient, type ForgePullRequestRef, ForgeUnavailableError, type GateState, type GcApplyOutcome, type GcClass, type GcPlanEntry, GhCliForgeClient, type GitWorktreeRef, HookError, type HookRun, type HostnameParts, InMemoryVerdictMemoStore, type IntegrationState, type ListWorktreeStatusesInput, type LivenessState, type NamedScript, type PeerService, type PlanGcInput, type ProvenanceConfidence, type ProvenanceInfo, ProxyTable, type ReconcileIntegrationInput, type ResolveSupervisorInput, type ResolvedWorktreeRuntime, RestForgeClient, type RunningProxy, SALVAGE_ROOT, SESSIONS_BUCKETS_ROOT, SESSIONS_FILE_PATH, type SalvageManifest, type SalvageResult, type SalvageWorktreeInput, type ScriptConfig, type ServiceRuntime, type ServiceStatus, ServiceSupervisor, type SessionRef, type SupervisorOptions, type TreeState, UnreachableForgeClient, VERDICT_MEMO_PATH, type VerdictMemoRecord, type VerdictMemoStore, type WorktreeAgentInput, type WorktreeClass, type WorktreeEnvContext, type WorktreeMarker, WorktreeNotRemovableError, type WorktreeStatusEntry, allocatePort, applyGc, classify, classifyForGc, computeLiveness, computeProvenance, computeTreeState, computeWorktreeStatus, connectDaemonAgentSessionHost, createForgeClient, createProxyServer, detectDefaultBranch, disposeSupervisor, ephemeralPort, execArgv, execGit, execShell, expandGlob, getScript, getSupervisor, globToRegExp, hookEnv, isPortFree, listGitWorktrees, listScripts, listServices, listWorktreeStatuses, loadConfigFromBase, makeDaemonAgentSessionHost, normalizeHook, parseConfig, parseGithubOwnerRepo, peerEnv, peerEnvKey, planGc, readSessionsRegistry, readWorktreeMarker, reconcileIntegration, repoLabel, resolveSupervisor, runSetup, runTeardown, salvageWorktree, serviceEnv, serviceEnvToken, serviceHostname, serviceUrl, sessionInWorktree, sharedProxyTable, slugify, startProxy, stripPort, worktreeAgentInputSchema, worktreeAgentWorkflow, writeWorktreeMarker };