@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/herdctl.d.ts

@@ -0,0 +1,572 @@
+/**
+ * HerdctlService — REAL wrapper around @herdctl/core's FleetManager.
+ *
+ * This module is NOT a stub: it imports and constructs the public
+ * @herdctl/core API (paddock depends on ^5.27.0). It is the single seam between
+ * paddock and herdctl, so that any remaining gaps in the public API are isolated
+ * here. See docs/INTEGRATION.md for the verified call-by-call contract.
+ *
+ * As of @herdctl/core 5.11.0 the four prior app-layer workarounds are GONE —
+ * paddock now uses the first-class APIs:
+ *
+ *  - **Runtime agents:** `fleet.addAgent({...})` / `fleet.removeAgent(name)`
+ *    register/unregister a project's keeper + sweeper agents in memory. No more
+ *    generate-per-agent-yaml + regenerate-herdctl.yaml + `reload()` dance. The
+ *    FleetManager boots from a minimal zero-agent config (fleet + defaults only)
+ *    and every agent is added programmatically. `addAgent` validates the config,
+ *    deep-merges fleet `defaults`, resolves the working_directory to an absolute
+ *    path, and wires it into the scheduler so it is immediately triggerable and
+ *    shows up in `getFleetStatus()` / `getAgentInfo()`.
+ *
+ *  - **Sessions:** `fleet.getAgentSessions(name, {limit})` and
+ *    `fleet.getAgentSessionMessages(name, sessionId)` derive the agent's
+ *    working_directory + Docker mode from the loaded config — no hand-rolled
+ *    SessionDiscoveryService keyed on working dirs.
+ *
+ *  - **Streaming:** `trigger(agent, schedule?, { onMessage, prompt, resume })`.
+ *    `onMessage(msg: SDKMessage)` fires per SDK message; the returned
+ *    TriggerResult carries the final `sessionId`. New chat = `resume: null`;
+ *    resume = `resume: <sessionId>`. This is the `batch` drive-mode path; the
+ *    default `session` mode instead drives `openChatSession`, which ALWAYS runs
+ *    the SDK runtime regardless of the agent's `runtime` field (see #585).
+ *
+ *  - **Delete / rename a chat:** `fleet.deleteSession(name, sessionId)` removes
+ *    the transcript (and invalidates the discovery cache), and
+ *    `fleet.setSessionName(name, sessionId, customName)` sets a custom name —
+ *    both keyed by agent name, no deep imports.
+ *
+ * Freshness note: `fleet.getAgentSessions` uses the FleetManager's internal
+ * SessionDiscoveryService, which has a 30s directory cache. A brand-new
+ * project's transcript dir does not exist until its first turn, and the
+ * discovery service does NOT cache a missing directory — so the first session
+ * of a project surfaces immediately. `deleteSession`/`setSessionName` invalidate
+ * the cache internally. The one nuance vs. the prior code: a *second* new chat
+ * created in an already-listed project within 30s may take up to the cache TTL
+ * to appear (the prior code invalidated a private cache we can no longer reach).
+ * That last nuance is now closed too: core exposes `fleet.invalidateSessions(name)`
+ * and paddock calls it after each turn (`ws-turn.ts`) and around fork/promote.
+ */
+import { FleetManager, type DiscoveredSession, type ChatMessage, type SDKMessage, type TriggerResult, type AgentInfo, type FleetStatus, type SlashCommand, type InjectedMcpServerDef, type SessionWakeHandler, type ResolveInjectedMcpServers, type ScheduleTriggerHandler, type ScheduleInfo, type JobMetadata, type AdoptionPlacementMode, type AdoptSkippedSession } from "@herdctl/core";
+import type { PaddockConfig } from "./config.js";
+import type { Project } from "./projects.js";
+import { type PaddockTrigger } from "./trigger-config.js";
+import { type AdoptableSummary, type FilterReason } from "./adoptable.js";
+/**
+ * One session an import did NOT bring in, with a reason a UI can show verbatim.
+ *
+ * A superset of the engine's own `AdoptSkippedSession`: paddock's noise filter
+ * (`./adoptable.ts`) contributes its own reasons on top of the engine's, and a
+ * caller renders the string either way rather than switching on it.
+ */
+export type AdoptSkipped = AdoptSkippedSession | {
+    sessionId: string;
+    reason: FilterReason;
+    detail?: string;
+};
+/** Options passed through to a streamed trigger. */
+export interface ChatTurnOptions {
+    prompt: string;
+    /** Session to resume; `null` forces a fresh session; omit for agent fallback. */
+    resume?: string | null;
+    onMessage?: (msg: SDKMessage) => void | Promise<void>;
+    onJobCreated?: (jobId: string) => void;
+    triggerType?: string;
+    /**
+     * In-process MCP servers to inject for this turn (issue #112). herdctl's CLI
+     * runtime stands up a localhost HTTP bridge per server and auto-allowlists its
+     * `mcp__<key>__*` tools, so no change to the static `allowed_tools` is needed.
+     */
+    injectedMcpServers?: Record<string, InjectedMcpServerDef>;
+    /**
+     * Gap B (session mode only): a sink for messages that arrive on the session's
+     * stream AFTER the primary turn's terminal `result` — i.e. autonomous
+     * background-completion re-invocation turns the reaper holds the session open
+     * for. When provided, {@link chatSession} keeps consuming the same stream and
+     * forwards each subsequent message here so the caller can render it live (see
+     * `consumeBackgroundTurns` in ./resume-drain.ts). Omit for no live delivery of
+     * background turns (they still persist to the transcript regardless).
+     */
+    onBackgroundMessage?: (msg: SDKMessage) => void | Promise<void>;
+    /**
+     * Gap B (session mode only): called once the background stream ENDS (the reaper
+     * reaped the session). Lets the caller finalize the single hub turn it rendered
+     * background re-invocations onto (emit chat:complete + end the turn) so the
+     * streaming indicator clears. Paired with {@link onBackgroundMessage}.
+     */
+    onBackgroundDone?: () => void | Promise<void>;
+}
+/**
+ * The name/visibility helpers + tool/model constants are pure (they only read
+ * their arguments, no fleet/cfg/session state), so they live in a sibling module
+ * for readability + isolated unit-testing (issue #403). Re-exported here so every
+ * external importer keeps resolving them via `./herdctl.js` unchanged.
+ */
+export { keeperAgentName, keeperSlugFromAgent, SWEEPER_PREFIX, sweeperAgentName, HOOK_AGENT_PREFIX, hookAgentName, TRIGGER_AGENT_PREFIX, triggerAgentName, visibleProjectAgentNames, BROWSER_MCP_TOOL, DENIED_TOOLS, browserMcpServers, KEEPER_MAX_CONCURRENT, KEEPER_SESSION_TIMEOUT, } from "./herdctl-agent-names.js";
+export declare function sliceTranscriptAtUuid(raw: string, cutUuid: string, endOnCompletedAssistant?: boolean): string | null;
+export declare class HerdctlService {
+    private readonly cfg;
+    private fleet;
+    private started;
+    /**
+     * The model currently registered for each agent (keyed by agent name). Lets
+     * `ensureAgentModel` skips a re-registration when the
+     * requested model already matches the live agent config.
+     *
+     * SINGLE-USER CAVEAT: the keeper is one shared agent per project, so the
+     * model is last-write-wins across concurrent chats of the same project — if
+     * two chats of the same project pick different models, whichever triggered
+     * last wins for both. Acceptable for paddock's single-user POC; a clean
+     * per-trigger model override is a herdctl follow-up.
+     */
+    private agentModels;
+    /**
+     * Each agent's working directory (the keeper's cwd), recorded at
+     * registration. Used to resolve the `claude` CLI transcript for a resume so we
+     * can measure its pending async-input-queue depth (the resume self-interrupt
+     * fix's residue gate — see {@link residueDepthFor} + `./resume-drain.ts`).
+     */
+    private agentWorkingDirs;
+    /**
+     * Live session-mode turns keyed by the synthetic turn id we hand back as the
+     * `jobId` (Paddock#111). `openChatSession` creates no herdctl job record, so
+     * there's no core `jobId` to cancel via `cancelJob`; instead we register the
+     * live {@link RuntimeSession} here and Stop → `session.interrupt()` (see
+     * {@link cancel}). Entries are removed when the turn's stream ends.
+     */
+    private liveSessions;
+    /**
+     * Incremental index of `<stateDir>/jobs`, backing the unread-badge reads
+     * (`lastTurnCompletedAt*`) — one per service, reused across requests so a warm
+     * scan only parses records it has never seen (#529). See
+     * `./herdctl-jobs-index.ts` for the invariant it rests on and its invalidation.
+     *
+     * Built lazily on first read, like the job-record helpers it replaced: unit
+     * tests construct this service against a partial config with no `stateDir`,
+     * and must keep being able to.
+     */
+    private jobsIndexOrNull;
+    private get jobsIndex();
+    constructor(cfg: PaddockConfig);
+    /**
+     * Construct + initialize the FleetManager against a minimal zero-agent
+     * config (fleet + defaults only). Agents are then registered programmatically
+     * via `fleet.addAgent(...)` — a keeper + sweeper for each workspace, the root
+     * included. No per-agent yaml files; no `reload()`.
+     */
+    init(projects: Project[]): Promise<void>;
+    /** Start the scheduler (keeper agents currently have no schedules, but this
+     * keeps the fleet "running" for status + future cron curators). */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Expose the raw FleetManager (events, advanced ops) to callers that need it. */
+    get manager(): FleetManager;
+    /**
+     * Is a `claude` SUBPROCESS still alive on this session at the SDK/reaper layer
+     * (issue #397)? Consults herdctl's `SessionReaper` via the fleet's session
+     * lifecycle manager: `true` while the reaper is keeping a session open for a
+     * killed background task (keepAlive) or holding it through its re-invocation
+     * grace. Paddock's recovery engine treats this as a busy signal so it never
+     * fires a COMPETING resume into a session a prior subprocess still holds live
+     * (which the SDK resolves by interrupting the in-flight turn). Null-safe: with
+     * no fleet, no session-lifecycle manager (batch mode / reaper disabled), or any
+     * error, returns `false` — the pre-#397 behaviour.
+     */
+    isSdkSessionLive(sessionId: string): boolean;
+    fleetStatus(): Promise<FleetStatus>;
+    agents(): Promise<AgentInfo[]>;
+    /**
+     * Register (or replace) a project's keeper + sweeper agents at runtime. Uses
+     * `fleet.addAgent` (replace: true), so a re-create or rename of the same slug
+     * is idempotent. The new agents are immediately triggerable and visible in
+     * fleet status — no yaml + reload round-trip.
+     */
+    ensureProjectAgent(project: Project): Promise<void>;
+    /**
+     * Register (or replace) every trigger a project declares that runs on its OWN scoped
+     * agent `trigger-<slug>-<name>` (Epic T). Idempotent (`addAgent` replace:true). Which triggers
+     * get a scoped agent is decided by {@link triggerRunsOnOwnAgent}: EVENT triggers
+     * always; SCHEDULE triggers only when they declare a non-empty `run.tools` allow-list
+     * (T2 — an unscoped schedule still rides the keeper's forwarded `schedules` block and
+     * runs as the keeper); webhook triggers are reserved (no ingress). A scoped schedule
+     * ALSO keeps its keeper `schedules` entry — that is only the cron TIMING; the fired
+     * turn executes on this scoped agent. A trigger-less project is a no-op. Called at
+     * boot ({@link init}) and on every {@link ensureProjectAgent}.
+     */
+    registerTriggerAgents(project: Project): Promise<void>;
+    /**
+     * Register (or replace) ONE trigger's scoped agent at runtime (Epic T) — the herdctl
+     * half of a trigger mutation (the Paddock half persists it via
+     * `ProjectStore.setTrigger`). Idempotent; immediately fireable. Consumed by
+     * {@link import("./triggers.js").TriggerService}. A no-op for a trigger that does NOT
+     * run on its own agent ({@link triggerRunsOnOwnAgent}) — an unscoped schedule arms via
+     * the keeper re-register; a webhook is reserved.
+     */
+    ensureTriggerAgent(project: Project, name: string, trigger: PaddockTrigger): Promise<void>;
+    /**
+     * Unregister one event trigger's agent at runtime (Epic T / T1) — the inverse of
+     * {@link ensureTriggerAgent}. Never throws if the agent is already gone.
+     */
+    removeTriggerAgent(slug: string, name: string): Promise<void>;
+    /**
+     * Ensure a project's keeper agent is registered at `model`, re-registering it
+     * (addAgent replace:true) only when the model actually changed. Used by the
+     * WS chat path to honor a per-chat model override before triggering.
+     *
+     * No herdctl per-trigger model API exists yet, so a model override is applied
+     * by re-registering the (single, shared) keeper agent. See the `agentModels`
+     * single-user caveat: this is last-write-wins across concurrent chats of the
+     * same project.
+     */
+    ensureAgentModel(project: Project, model: string): Promise<void>;
+    /**
+     * Force the FleetManager's session-discovery cache to drop its cached listing
+     * for an agent, so a brand-new chat surfaces immediately (rather than waiting
+     * out the 30s directory cache). New public API in @herdctl/core 5.12.0. No-op
+     * and never throws if the fleet isn't ready.
+     */
+    invalidateSessions(agentName: string): void;
+    /**
+     * Detector for a project's importable native Claude Code chats, with its own
+     * mtime-keyed cache. Lazy for the same reason {@link jobsIndex} is: unit tests
+     * construct this service against a partial config.
+     */
+    private adoptableIndexOrNull;
+    private get adoptableIndex();
+    /** What `project` could import right now (see `./adoptable.ts`). */
+    listAdoptable(project: Project): Promise<AdoptableSummary>;
+    /**
+     * Drop the cached adoptable summary for a workspace (or all of them).
+     *
+     * The workspace key may be `""` (the root), so this forwards the argument
+     * as-is — `if (!slug)` here would silently clear the WRONG thing.
+     */
+    invalidateAdoptable(projectKey?: string): void;
+    /**
+     * Import a project's native Claude Code chats.
+     *
+     * With `sourceCwd`, imports that one source; without, every source detection
+     * currently offers. `mode` defaults to `copy`, which never mutates the user's
+     * original `~/.claude` transcripts and preserves their mtimes; `move` and
+     * `link` exist for the CLI and nothing in the web UI should reach them.
+     *
+     * ## Honouring the noise filter
+     *
+     * Detection withholds empty and slash-command-only transcripts, but the engine
+     * adopts a whole SOURCE — it has no "adopt these ids" call. Left alone, that
+     * means the header offers 2 chats and the import brings in 4, including a
+     * zero-byte stub. So anything the engine adopted that detection had withheld is
+     * released again ({@link FleetManager.unadoptSession}) and reported in
+     * `skipped` under the filter's own reason, and — in `copy` mode only — the copy
+     * this call just placed is removed.
+     *
+     * That deletion is deliberately narrow. It happens only when all of: the mode
+     * is `copy` (in `move` the original is GONE, so the copy is the user's only
+     * remaining copy and must never be touched); the engine reported the id as
+     * newly `adopted` in THIS call, so it placed the file here and did not find one
+     * (`destination-exists` is a skip, not an adopt); and the destination path
+     * differs from the source, so an in-place adoption can never delete an
+     * original. The result is that a withheld session is left exactly as it was
+     * before the import.
+     *
+     * Afterwards the herdctl session cache, the jobs index and the adoptable cache
+     * are all dropped, so the imported chats list on the very next request — the
+     * same trio {@link promoteSession} invalidates for the same reason.
+     */
+    adoptChats(project: Project, opts?: {
+        sourceCwd?: string;
+        mode?: AdoptionPlacementMode;
+        dryRun?: boolean;
+    }): Promise<{
+        adopted: string[];
+        skipped: AdoptSkipped[];
+    }>;
+    /**
+     * Undo the adoption of a session detection had withheld, restoring the state
+     * that existed before this import. See {@link adoptChats} for why the file
+     * removal is safe and why it is limited to `copy` mode.
+     */
+    private releaseWithheld;
+    /**
+     * Unregister a project's keeper + sweeper (+ any event-hook) agents at runtime.
+     * Uses `fleet.removeAgent`, the inverse of ensureProjectAgent. Running jobs are
+     * unaffected; the scheduler stops triggering the removed agents. `hookNames` are
+     * the project's declared hook names (from its DTO) so their `hook-<slug>-<name>`
+     * agents are torn down too — caller passes `Object.keys(project.hooks ?? {})`.
+     */
+    removeProjectAgent(slug: string, hookNames?: string[], triggerNames?: string[]): Promise<void>;
+    /**
+     * Delete a single chat (session) by agent name + session id. The FleetManager
+     * resolves the agent's working directory, removes the transcript JSONL, and
+     * invalidates the discovery cache so the list reflects it immediately.
+     * Validates the sessionId (rejects path traversal). Returns true if a
+     * transcript file was removed, false if none existed.
+     */
+    deleteSession(agentName: string, sessionId: string): Promise<boolean>;
+    /**
+     * Set (or clear) a chat's custom display name. Writes through the fleet's
+     * shared SessionMetadataStore so a subsequent getAgentSessions reflects it
+     * immediately. Pass null/empty to clear.
+     */
+    renameSession(agentName: string, sessionId: string, name: string | null): Promise<void>;
+    /**
+     * Trigger an agent with a prompt and stream output via onMessage.
+     * Returns the TriggerResult (carries the final sessionId).
+     */
+    chat(agentName: string, opts: ChatTurnOptions): Promise<TriggerResult>;
+    /**
+     * Pending async-input-queue depth of a resumed session's `claude` transcript —
+     * the residue gate for the resume self-interrupt drain (see `./resume-drain.ts`
+     * and {@link drainBacklogThenConsume}). Resolves the agent's CLI transcript from
+     * its recorded working directory. Returns 0 (→ no drain, original fast path) for
+     * an unknown agent or any read error, so a detection failure never changes turn
+     * behavior. Public so the ws.ts wake consumer can gate on it too.
+     */
+    residueDepthFor(agentName: string, sessionId: string): Promise<number>;
+    /**
+     * Session-mode counterpart to {@link chat} (Paddock#111). Drives the turn
+     * through a persistent, herdctl-managed `openChatSession` (`manageLifecycle:
+     * true`) instead of a one-shot `trigger()`, so a `ScheduleWakeup` / `/loop` the
+     * turn leaves behind is captured by the reaper (herdctl#307) and re-fired
+     * through the scheduler — i.e. cross-turn autonomy actually works. The turn
+     * itself streams identically (same `onMessage` shape), so callers are unchanged.
+     *
+     * Contract differences from {@link chat}:
+     *  - No herdctl job record exists, so the returned `jobId` is a synthetic turn
+     *    id we register in {@link liveSessions}; Stop maps to `session.interrupt()`
+     *    via {@link cancel}.
+     *  - We do NOT `close()` the session: it's managed, so the reaper tears it down
+     *    when idle (and captures its wakeups on the Stop hook). Per the core
+     *    contract, the message stream ending IS the reap.
+     */
+    chatSession(agentName: string, opts: ChatTurnOptions): Promise<TriggerResult>;
+    /**
+     * Register the consumer that drives scheduler-fired session wakes (Paddock#111
+     * gap 3). herdctl resumes the woken session (`manageLifecycle: true`) and hands
+     * it here; the handler must consume the stream onto the hub/transcript so the
+     * autonomous turn is visible even though no client is watching. A no-op if the
+     * fleet has no lifecycle manager. Safe to call before/after {@link init}.
+     */
+    onSessionWake(handler: SessionWakeHandler | undefined): void;
+    /**
+     * Register the resolver herdctl calls to RE-ESTABLISH this session's in-process
+     * injected MCP servers when a scheduler-fired wake resumes an idle/reaped session
+     * (edspencer/herdctl#390, wired in @herdctl/core 5.22.1). The wake path drives the
+     * turn inside herdctl (a `ScheduleWakeup` / `/loop` / `CronCreate` re-fire), so it
+     * bypasses Paddock's per-turn injection — without this the resumed `claude`
+     * subprocess re-spawns with the `mcp__paddock*__*` tools "allowed" but UNBACKED,
+     * so they vanish from the catalog for the whole autonomous stretch (the "MCP flap").
+     * The resolver is SYNCHRONOUS (herdctl threads its result into `openChatSession`
+     * before the subprocess spawns) and MUST NOT throw — herdctl catches + logs a throw
+     * and degrades to no-injection, but we return `undefined` (safe no-injection default)
+     * rather than rely on that. A no-op if the fleet has no lifecycle manager; safe to
+     * call before/after {@link init}. Thin passthrough, mirroring {@link onSessionWake}.
+     */
+    setResolveInjectedMcpServers(resolve: ResolveInjectedMcpServers | undefined): void;
+    /**
+     * Register the consumer that OWNS execution of a fired schedule (issue #265 /
+     * DD-1, herdctl#375). When set, herdctl routes every scheduler-fired trigger
+     * (interval / cron / forced "trigger now") here instead of running it headless
+     * via its built-in ScheduleExecutor — so Paddock runs the turn on its OWN hub /
+     * resume path (`startAgentTurn`), keeping the scheduled chat visible + re-attachable
+     * (and never `isSidechain`-hidden). A no-op fallback to headless applies if no
+     * handler is registered. Thin passthrough, mirroring {@link onSessionWake}.
+     */
+    onScheduleTrigger(handler: ScheduleTriggerHandler | undefined): void;
+    /**
+     * The runtime state of a project keeper's schedules (issue #266 / D4) — the
+     * live `ScheduleInfo` herdctl tracks (status, `lastRunAt`/`nextRunAt`,
+     * `lastError`) for the schedules Paddock forwarded into the keeper agent. The
+     * D4 UI merges this with the project.yaml declaration (which carries the
+     * Paddock-only `prompt`/`promptFile`/`resume_session`) for the list view. A
+     * schedule-less keeper (or one herdctl hasn't finished arming) yields `[]`;
+     * errors are swallowed to `[]` so the settings pane degrades to the declared
+     * definitions rather than failing to render.
+     */
+    listAgentSchedules(project: Project): Promise<ScheduleInfo[]>;
+    /**
+     * Run a slash command (e.g. `/compact`) against an agent's chat session.
+     *
+     * Unlike {@link chat}, which sends the text as a one-shot prompt via
+     * `trigger()`, this drives herdctl's streaming session (`openChatSession`) —
+     * the only mode in which the SDK dispatches slash commands and exposes control
+     * requests. The command runs against the resumed `sessionId`, so `/compact`
+     * compacts the real chat history. SDK messages stream via `onMessage` (same
+     * shape as {@link chat}); resolves when the turn completes, then closes the
+     * session. Returns the resolved session id.
+     */
+    runCommand(agentName: string, opts: {
+        command: string;
+        resume?: string | null;
+        onMessage?: (msg: SDKMessage) => void | Promise<void>;
+    }): Promise<{
+        sessionId: string | null;
+    }>;
+    /**
+     * Cancel a running turn (Stop button → WS chat:cancel). Handles BOTH drive
+     * modes off the single id the client holds as `jobId`:
+     *  - **session mode** — the id is a synthetic turn id in {@link liveSessions};
+     *    interrupt the live `RuntimeSession` (there is no herdctl job to cancel).
+     *  - **batch mode** — the id is a real herdctl job id; abort it via `cancelJob`
+     *    (which kills the CLI subprocess / aborts the SDK query).
+     *
+     * Returns `true` if something was actually cancelled. Errors are logged rather
+     * than silently swallowed (the previous `.catch(() => undefined)` hid every
+     * failure, so a broken Stop looked like a no-op).
+     */
+    cancel(jobId: string): Promise<boolean>;
+    /**
+     * Run a project's sweeper (curator) agent with a fresh session and the given
+     * prompt. Used OUT OF BAND by SweepService — never from the user-chat path —
+     * so a sweep can never enqueue another sweep. resume:null forces a clean
+     * session each time (the sweep is stateless).
+     *
+     * The sweeper is tool-less and returns its result as plain assistant text
+     * (the two marked sections SweepService parses), so we accumulate the
+     * assistant text deltas via @herdctl/chat's shared translator (same pattern
+     * as ws.ts) and return them alongside the TriggerResult.
+     */
+    runSweeper(slug: string, prompt: string): Promise<{
+        result: TriggerResult;
+        text: string;
+    }>;
+    /** Recent sessions for a project's keeper agent, used to build the sweep digest. */
+    recentSessions(project: Project, limit?: number): Promise<DiscoveredSession[]>;
+    /**
+     * List a project's chats across ALL of its VISIBLE agents (Epic G / G3, GG-5):
+     * the keeper PLUS every declared event-hook agent (`hook-<slug>-<name>`), so a
+     * hook's chats show up in the sidebar alongside the keeper's. The sweeper is
+     * deliberately excluded — it's the `hideChats` case (its curation chats stay
+     * hidden, unchanged). See
+     * {@link visibleProjectAgentNames}.
+     *
+     * Sessions are keyed by working directory in core's discovery, and every one of
+     * a project's agents shares the project cwd, so `getAgentSessions` attributes each
+     * session to the specific agent that owns it (keeper vs. a hook). We query each
+     * visible agent and merge — deduping by session id defensively (attribution is
+     * per-agent, so overlap shouldn't happen) — then re-sort mtime-descending to
+     * restore the interleaved recency order a single listing would have had. Each
+     * per-agent query is fault-isolated: a hook whose agent failed to register (or was
+     * just removed) yields `[]` instead of failing the whole list.
+     *
+     * A **hook-less project** (the overwhelmingly common case) has exactly one visible
+     * agent — its keeper — so we short-circuit to the single un-merged listing: same
+     * one directory scan (and no dedup/sort work) the pre-G3 keeper-only path did, i.e.
+     * zero added cost unless the project actually declares hooks. The extra per-hook
+     * scans only kick in for a project that has hook chats to show.
+     */
+    listSessions(project: Project): Promise<DiscoveredSession[]>;
+    /**
+     * The on-disk job-record reads (run history + the unread badge) live in
+     * `./herdctl-jobs.js` as pure functions over `<stateDir>/jobs` (issue #403);
+     * these thin wrappers thread `this.cfg.stateDir` (or, for the two unread-badge
+     * reads, this service's {@link jobsIndex}). See there for the full semantics of
+     * each (unread signal, per-project grouping, run history).
+     */
+    lastTurnCompletedAt(): Promise<Map<string, string>>;
+    lastTurnCompletedAtByProject(): Promise<Map<string, Map<string, string>>>;
+    listProjectRuns(project: Project, limit?: number): Promise<JobMetadata[]>;
+    listRunsForAgents(agents: string[], limit?: number): Promise<JobMetadata[]>;
+    /**
+     * Promote a chat into a NEW project: re-home its transcript into that
+     * project's `.chats/` (rewriting the embedded `cwd` so the transcript reports
+     * the new project dir) and re-point the session's herdctl job records at the
+     * new keeper. After this + the cache invalidations below the chat lists and
+     * resumes under the new project with NO restart — doing the same writes from
+     * outside the process would need one, to drop the attribution-index cache.
+     *
+     * Moves one chat from one keeper's store to another's. The root is a workspace
+     * like any other, so root chats carry the promote action too.
+     *
+     * The caller MUST have already created `to` and registered its keeper
+     * (ensureProjectAgent), so its `.chats/` + transcript symlink exist. Throws if
+     * the source transcript can't be read (e.g. unknown session id).
+     */
+    promoteSession(sessionId: string, from: Project, to: Project): Promise<void>;
+    /**
+     * Fork a project chat: eagerly duplicate `sourceSessionId`'s transcript into a
+     * brand-new session in the SAME project, so the fork exists immediately — a
+     * real, resumable chat with the full parent history visible — rather than being
+     * materialized only when the user sends a first message. The source is left
+     * untouched (this is a copy, not a move).
+     *
+     * Same mechanics as {@link promoteSession} (copy the JSONL, keep it
+     * discoverable + attributed), with two differences: a NEW session id is minted
+     * and rewritten onto every transcript line (so the copy is internally
+     * consistent with its new filename — Claude Code stamps appended lines with the
+     * file's id, and a mismatch is version-fragile), and the source file is kept.
+     * `cwd` is unchanged (the fork stays in the same project). Returns the new id.
+     */
+    /**
+     * Whether a chat transcript exists for `sessionId` in `project`. Used by the
+     * self-management MCP write tools (#214) to validate a caller-supplied target
+     * before forking / messaging it, so a bad id yields a clean "not found" instead
+     * of a raw ENOENT (fork) or a false-positive success (send_message). Rejects a
+     * malformed id (path-traversal guard) as non-existent.
+     */
+    sessionExists(project: Project, sessionId: string): Promise<boolean>;
+    forkSession(project: Project, sourceSessionId: string, name?: string, fromUuid?: string): Promise<string>;
+    /**
+     * Revert a chat back to an earlier message (issue #451): truncate the session's
+     * transcript at `toUuid`, in place, keeping the SAME session id — so the chat's
+     * identity/URL is preserved and the next turn continues as if the later
+     * messages never happened. The dropped tail is backed up (recoverable) to a
+     * `.reverts/` sidecar that is deliberately kept out of the discoverable
+     * `<id>.jsonl` namespace so it never lists as a chat.
+     *
+     * NOTE: this rolls back the CONVERSATION only — real-world side-effects of the
+     * reverted turns (files written, PRs opened, messages sent) are NOT undone. The
+     * caller's UI is responsible for warning about that. Returns the number of
+     * transcript records dropped.
+     */
+    revertSession(project: Project, sessionId: string, toUuid: string): Promise<{
+        removed: number;
+    }>;
+    /**
+     * Attribute an *in-flight* session to its agent the moment its id is known —
+     * mid first turn — so a brand-new chat lists in the sidebar immediately
+     * instead of only after the first turn finishes (issue #100).
+     *
+     * The core attribution index is built from herdctl job records, and herdctl
+     * writes the resolved `session_id` into a run's own job record only on
+     * completion. While the first turn runs, that record has `session_id: null`,
+     * so the session is unattributed and {@link SessionDiscoveryService.getAgentSessions}
+     * filters it out. We close that window with the SAME synthetic-job-record
+     * trick used for fork/promote: write an adoption record keyed to the session
+     * id, then drop the discovery + attribution caches so the next list call
+     * surfaces it. Idempotent — a stable per-session job id means a repeat call
+     * just overwrites the same file, and when the real run later finalizes its own
+     * record (same session id, same agent) the attribution is unchanged.
+     *
+     * @param sessionId - The freshly-resolved session id of the running turn
+     * @param agentName - The qualified agent the session belongs to
+     */
+    attributeRunningSession(sessionId: string, agentName: string): Promise<void>;
+    /** Read the parsed messages of a session, by agent name. */
+    sessionMessages(agentName: string, sessionId: string): Promise<ChatMessage[]>;
+    /**
+     * Slash commands available to an agent, memoized per agent name. The set is
+     * stable per project (built-ins + the project's `.claude/commands` + any
+     * MCP-provided commands) and each underlying `listAgentCommands` call spawns a
+     * short-lived `claude` streaming subprocess (open → query → close), so we
+     * cache aggressively. The cache is process-lifetime: it fills on first use and
+     * only clears on server restart — the same boot-only invalidation the fleet's
+     * agent registration already relies on. A concurrent first call is
+     * deduplicated by caching the in-flight promise, so a burst of composer fetches
+     * spawns exactly one subprocess.
+     */
+    private commandsCache;
+    listCommands(agentName: string): Promise<SlashCommand[]>;
+    private keeperAgentConfig;
+    private sweeperAgentConfig;
+    /**
+     * Create the sweeper's own working directory (+ symlink its encoded transcript
+     * path at a `.chats/` inside it), so the tool-less curator never shares a CLI
+     * session directory with the project's keeper (issue #548). Reuses
+     * `ensureProjectChats` with the sweeper dir as both cwd and chats host, which
+     * also mkdir's the dir itself. Never throws — the helper swallows its own
+     * errors, and a missing symlink only means Claude keeps its default location.
+     */
+    private ensureSweeperHome;
+    private triggerAgentConfig;
+    private ensureConfigFile;
+}