@edspencer/paddock 0.59.1 → 0.61.0

package/packages/server/dist/herdctl-agent-config.js

@@ -141,15 +141,22 @@ export function sweeperWorkingDir(cfg, slug) {
     return path.join(cfg.dataDir, "sweepers", slug === "" ? "_root" : slug);
 }
 /**
- * A project's sweeper (curator) agent config. TOOL-LESS: the sweeper has NO
- * tools (`allowed_tools: []`) — it never reads or writes files. Instead it
- * RETURNS the curated content as plain assistant text in marked sections
- * (OVERVIEW / CHANGELOG / optional CLAUDE, issue #177); SweepService parses
- * that text and writes OVERVIEW.md / CHANGELOG.md / CLAUDE.md itself.
+ * A project's sweeper (curator) agent config. TOOL-LESS BY DESIGN: it declares
+ * `allowed_tools: []` and never reads or writes files. Instead it RETURNS the
+ * curated content as plain assistant text in marked sections (OVERVIEW /
+ * CHANGELOG / optional CLAUDE, issue #177); SweepService parses that text and
+ * writes OVERVIEW.md / CHANGELOG.md / CLAUDE.md itself.
  *
  * This is cheaper and far more predictable than letting a Haiku agent drive
  * file edits: no tool-loop turns, no partial writes, no permission_mode /
- * denied_tools to reason about (all irrelevant with zero tools).
+ * denied_tools to reason about.
+ *
+ * What makes it tool-less is NOT the empty `allowed_tools` — herdctl emits an
+ * allow-list only when it is non-empty, so `[]` restricts nothing (#647). The
+ * actual guarantees are: no injected MCP servers (the sweeper is the one turn
+ * path that does not even get `send_file`), `max_turns: 4`, a system prompt
+ * whose first line is "You DO NOT use any tools", and a non-interactive
+ * `claude -p` run that cannot answer a permission prompt.
  */
 export function buildSweeperConfig(cfg, project) {
     // T5: the sweeper IS the default `curate-overview` (event/afterTurn) trigger. When a
@@ -171,9 +178,13 @@ export function buildSweeperConfig(cfg, project) {
         // addAgent does deep-merge the loaded defaults, they just never carry it).
         runtime: "cli",
         model: curatorModel ?? SWEEPER_DEFAULT_MODEL,
-        // Tool-less: a handful of turns is plenty since there are no tool loops.
+        // A handful of turns is plenty since there are no tool loops — and this, not
+        // the empty allow-list below, is one of the things actually bounding the run.
         max_turns: 4,
-        // NO tools. The sweeper returns text only; SweepService does the writing.
+        // Declares NO tools: the sweeper returns text only; SweepService does the
+        // writing. Note herdctl does not emit an empty allow-list at all, so this
+        // restricts nothing on its own (#647) — see the doc comment above for the
+        // properties that do make the sweeper tool-less in practice.
         allowed_tools: [],
         system_prompt: "You are a concise project curator. You DO NOT use any tools — you only " +
             "return text. From the recent activity, the current OVERVIEW.md, the " +
@@ -226,7 +237,8 @@ export function buildSweeperConfig(cfg, project) {
  * (`allowed_tools`/`permission_mode`/`model`/`max_turns`, projected by
  * {@link triggerToAgentToolConfig} from the trigger's `run`) IS its capability set.
  * Runs in the project's WORKING dir (so a trigger's Bash/Write act on the same tree
- * the keeper does). A tool-less trigger gets `allowed_tools: []` and can only return text.
+ * the keeper does). A trigger that declares no tools gets `allowed_tools: []` — which
+ * herdctl does not enforce as a deny-all; see {@link triggerToAgentToolConfig} (#647).
  */
 export function buildTriggerConfig(cfg, project, triggerName, trigger) {
     const config = {

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

@@ -134,6 +134,24 @@ export declare class HerdctlService {
      * {@link cancel}). Entries are removed when the turn's stream ends.
      */
     private liveSessions;
+    /**
+     * Background-phase turns keyed by the synthetic job id the sink minted for
+     * them, valued by the chat session they belong to (paddock#528).
+     *
+     * After a turn's primary `result` lands, {@link chatSession} returns and drops
+     * its {@link liveSessions} entry — but the session itself may live on, held
+     * open by the reaper because the turn launched background work, streaming
+     * autonomous re-invocation turns. Those turns are real, running, and shown as
+     * such; until now they were also uncancellable, because nothing registered
+     * them anywhere Stop could reach.
+     *
+     * `interrupt()` would be the wrong tool even if it could: it targets an
+     * in-flight model turn, and the wedge case is a session sitting idle holding
+     * background work that will never finish. So these route to a force-reap
+     * instead — end the session, let the stream end, and let the ordinary unwind
+     * emit `chat:complete`. Entries are removed when the background stream ends.
+     */
+    private backgroundTurns;
     /**
      * Incremental index of `<stateDir>/jobs`, backing the unread-badge reads
      * (`lastTurnCompletedAt*`) — one per service, reused across requests so a warm
@@ -147,6 +165,14 @@ export declare class HerdctlService {
     private jobsIndexOrNull;
     private get jobsIndex();
     constructor(cfg: PaddockConfig);
+    /**
+     * The Claude home every transcript symlink is planted in, plus whether paddock
+     * owns it (#620). One accessor, so no call site can quietly take a default and
+     * land in a different home than the FleetManager was built with — the bug
+     * `ensureSweeperHome` had, which put the sweeper's symlink in `~/.claude` while
+     * every other agent's went to the configured home.
+     */
+    private get claudeHomeTarget();
     /**
      * The environment system prompt to append to a keeper turn (issue #635), or
      * `undefined` when the instance opted out (`environmentPrompt: ""`) — herdctl
@@ -325,12 +351,61 @@ export declare class HerdctlService {
      */
     adoptChats(project: Project, opts?: {
         sourceCwd?: string;
+        /**
+         * Import only these sessions (#660). Anything else the engine adopts along
+         * the way is released again, exactly as a noise-filtered session is — see
+         * the "honouring the noise filter" note above, which this reuses wholesale.
+         * Undefined means "everything on offer", which is what a confirmed
+         * select-all sends and what the CLI has always sent.
+         */
+        sessionIds?: string[];
         mode?: AdoptionPlacementMode;
         dryRun?: boolean;
     }): Promise<{
         adopted: string[];
         skipped: AdoptSkipped[];
     }>;
+    /**
+     * Did an import of `sessionId` from `fromWorkingDir` place a NEW file?
+     *
+     * The same test `releaseWithheld` makes before deleting anything: an in-place
+     * adoption resolves the destination and the origin to one path, so there is no
+     * copy and nothing that may be removed.
+     */
+    private placedACopy;
+    /**
+     * What the LAST import into each workspace did, so it can be undone (#660).
+     *
+     * Keyed by workspace key (which may be `""` — the root). Holds the sessions
+     * that import actually brought in, and of those, the ones where it PLACED a
+     * copy and may therefore delete one again.
+     *
+     * Server-side rather than a token the client hands back: undo deletes files, so
+     * the set of paths it may touch must come from what this process actually did,
+     * not from a request body. A restart forgets it, which is the right failure —
+     * the offer to undo is a transient toast, not a durable feature.
+     *
+     * Only the most recent import per workspace is kept. Undoing an import two
+     * imports ago is not offered and would be a lie to describe as "undo".
+     */
+    private readonly lastImport;
+    /**
+     * Undo the import this process most recently performed into `project` (#660).
+     *
+     * Releases each adoption and deletes the copies that import placed, leaving the
+     * user's own `~/.claude` history exactly as it was. Returns the sessions it
+     * released; an empty array means there was nothing to undo (nothing imported
+     * yet, already undone, or the server restarted since).
+     *
+     * `sessionIds` narrows it to part of that import — the rest stays. Ids that
+     * were not part of it are ignored rather than rejected: undo is a best-effort
+     * safety net, and the alternative is a 400 for a button the user pressed once.
+     */
+    unadoptChats(project: Project, opts?: {
+        sessionIds?: string[];
+    }): Promise<{
+        released: string[];
+    }>;
     /**
      * Undo the adoption of a session detection had withheld, restoring the state
      * that existed before this import. See {@link adoptChats} for why the file
@@ -444,19 +519,39 @@ export declare class HerdctlService {
      * 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.
+     *
+     * Like {@link chatSession}, the session is registered in {@link liveSessions}
+     * under a synthetic turn id handed back via `onJobCreated`, so Stop can
+     * interrupt a long-running command (#632). The session is still NOT managed by
+     * the reaper — teardown remains this method's own `finally`.
      */
     runCommand(agentName: string, opts: {
         command: string;
         resume?: string | null;
         onMessage?: (msg: SDKMessage) => void | Promise<void>;
+        /** Receives the synthetic turn id Stop cancels this command turn by (#632). */
+        onJobCreated?: (jobId: string) => void;
     }): Promise<{
         sessionId: string | null;
     }>;
+    /**
+     * Register a background-phase turn so Stop can reach it (paddock#528). Called
+     * by the background turn sink once it knows both the synthetic job id it
+     * published and the session that stream belongs to. Re-registering the same
+     * job id with a later session id is fine — the sink refreshes the mapping if
+     * the stream resolves a different session.
+     */
+    registerBackgroundTurn(jobId: string, sessionId: string): void;
+    /** Forget a background-phase turn once its stream has ended. */
+    unregisterBackgroundTurn(jobId: string): void;
     /**
      * 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).
+     *  - **background phase** — the id is a synthetic id in
+     *    {@link backgroundTurns}; there is no model turn to interrupt, so reap the
+     *    session (paddock#528).
      *  - **batch mode** — the id is a real herdctl job id; abort it via `cancelJob`
      *    (which kills the CLI subprocess / aborts the SDK query).
      *

package/packages/server/dist/herdctl.js

@@ -191,6 +191,24 @@ export class HerdctlService {
      * {@link cancel}). Entries are removed when the turn's stream ends.
      */
     liveSessions = new Map();
+    /**
+     * Background-phase turns keyed by the synthetic job id the sink minted for
+     * them, valued by the chat session they belong to (paddock#528).
+     *
+     * After a turn's primary `result` lands, {@link chatSession} returns and drops
+     * its {@link liveSessions} entry — but the session itself may live on, held
+     * open by the reaper because the turn launched background work, streaming
+     * autonomous re-invocation turns. Those turns are real, running, and shown as
+     * such; until now they were also uncancellable, because nothing registered
+     * them anywhere Stop could reach.
+     *
+     * `interrupt()` would be the wrong tool even if it could: it targets an
+     * in-flight model turn, and the wedge case is a session sitting idle holding
+     * background work that will never finish. So these route to a force-reap
+     * instead — end the session, let the stream end, and let the ordinary unwind
+     * emit `chat:complete`. Entries are removed when the background stream ends.
+     */
+    backgroundTurns = new Map();
     /**
      * Incremental index of `<stateDir>/jobs`, backing the unread-badge reads
      * (`lastTurnCompletedAt*`) — one per service, reused across requests so a warm
@@ -208,6 +226,16 @@ export class HerdctlService {
     constructor(cfg) {
         this.cfg = cfg;
     }
+    /**
+     * The Claude home every transcript symlink is planted in, plus whether paddock
+     * owns it (#620). One accessor, so no call site can quietly take a default and
+     * land in a different home than the FleetManager was built with — the bug
+     * `ensureSweeperHome` had, which put the sweeper's symlink in `~/.claude` while
+     * every other agent's went to the configured home.
+     */
+    get claudeHomeTarget() {
+        return { path: this.cfg.claudeHome, owned: this.cfg.ownsClaudeHome };
+    }
     /**
      * The environment system prompt to append to a keeper turn (issue #635), or
      * `undefined` when the instance opted out (`environmentPrompt: ""`) — herdctl
@@ -297,7 +325,7 @@ export class HerdctlService {
             // at the .chats store in the metadata dir — so repo-backed transcripts stay
             // out of the external checkout's working tree (issue #187). For a notebook
             // project workingDir === dir, so this is the classic behavior.
-            await ensureProjectChats(project.workingDir, project.dir, this.cfg.claudeHome);
+            await ensureProjectChats(project.workingDir, project.dir, this.claudeHomeTarget);
             await this.ensureSweeperHome(project);
             await this.fleet.addAgent(this.keeperAgentConfig(project), { replace: true });
             await this.fleet.addAgent(this.sweeperAgentConfig(project), { replace: true });
@@ -371,7 +399,7 @@ export class HerdctlService {
     async ensureProjectAgent(project) {
         if (!this.fleet)
             return;
-        await ensureProjectChats(project.workingDir, project.dir, this.cfg.claudeHome);
+        await ensureProjectChats(project.workingDir, project.dir, this.claudeHomeTarget);
         await this.ensureSweeperHome(project);
         await this.fleet.addAgent(this.keeperAgentConfig(project), { replace: true });
         await this.fleet.addAgent(this.sweeperAgentConfig(project), { replace: true });
@@ -472,7 +500,7 @@ export class HerdctlService {
      */
     adoptableIndexOrNull = null;
     get adoptableIndex() {
-        return (this.adoptableIndexOrNull ??= new AdoptableIndex(this.cfg.claudeHome, this.cfg.stateDir));
+        return (this.adoptableIndexOrNull ??= new AdoptableIndex(this.cfg.claudeHome, this.cfg.stateDir, this.cfg.legacyClaudeHome));
     }
     /** What `project` could import right now (see `./adoptable.ts`). */
     async listAdoptable(project) {
@@ -523,12 +551,51 @@ export class HerdctlService {
         const mode = opts.mode ?? "copy";
         const dryRun = opts.dryRun ?? false;
         const summary = await this.listAdoptable(project);
+        // Translate the DISPLAY path a caller sends back into the path the engine
+        // actually reads that source through (#620). They differ for the user's own
+        // `~/.claude` history, which is reached via a mirror named for a synthetic
+        // path — handing the engine the recorded cwd would send it to the project's
+        // OWN transcript folder and import nothing.
+        //
+        // Filter rather than find: post-#620 the user's `~/.claude` folder for a cwd
+        // and the project's own `.chats/` are two different directories that both
+        // display as that cwd, so one display path can legitimately name two sources.
+        const engineDirs = (displayCwd) => {
+            const matched = summary.sources
+                .filter((s) => s.sourceCwd === displayCwd)
+                .map((s) => s.importFrom ?? s.sourceCwd);
+            // An unmatched path is one the route already validated as the project's own
+            // working directory; pass it straight through, as before.
+            return matched.length > 0 ? matched : [displayCwd];
+        };
         const sources = opts.sourceCwd !== undefined
-            ? [opts.sourceCwd]
-            : summary.sources.map((s) => s.sourceCwd);
+            ? engineDirs(opts.sourceCwd)
+            : summary.sources.map((s) => s.importFrom ?? s.sourceCwd);
         // sessionId -> why detection withheld it.
         const withheld = new Map(summary.filtered.map((f) => [f.sessionId, f.reason]));
+        // A selection narrows the offer the same way the noise filter does, and for
+        // the same reason: the engine adopts a whole SOURCE, so anything the user did
+        // not tick has to be released again afterwards. Tracked separately from
+        // `withheld` because a session the user simply did not choose is not a
+        // "skip" worth reporting back — it was never part of this import, and listing
+        // 23 of them would read as an import that half failed.
+        const deselected = opts.sessionIds === undefined
+            ? null
+            : (() => {
+                const wanted = new Set(opts.sessionIds);
+                const out = new Set();
+                for (const source of summary.sources) {
+                    for (const id of source.sessionIds)
+                        if (!wanted.has(id))
+                            out.add(id);
+                }
+                return out;
+            })();
         const adopted = [];
+        // Of `adopted`, the ones where this call PLACED a file — the only ones undo
+        // may ever delete. Computed here, where `fromWorkingDir` is still known;
+        // afterwards nothing can tell a copy from an in-place adoption.
+        const copies = [];
         const skipped = [];
         for (const fromWorkingDir of sources) {
             // Sequential, not parallel: each source re-scans the adoption store, so a
@@ -542,8 +609,20 @@ export class HerdctlService {
             skipped.push(...result.skipped);
             for (const sessionId of result.adopted) {
                 const reason = withheld.get(sessionId);
+                // Not chosen: release it, and say nothing about it. Checked BEFORE the
+                // noise filter so a deselected session stays silent even if it would
+                // also have been withheld.
+                if (deselected?.has(sessionId) === true) {
+                    if (!dryRun) {
+                        await this.releaseWithheld(agent, project, fromWorkingDir, sessionId, mode);
+                    }
+                    continue;
+                }
                 if (reason === undefined) {
                     adopted.push(sessionId);
+                    if (mode === "copy" && !dryRun && this.placedACopy(project, fromWorkingDir, sessionId)) {
+                        copies.push(sessionId);
+                    }
                     continue;
                 }
                 skipped.push({ sessionId, reason });
@@ -558,6 +637,8 @@ export class HerdctlService {
             this.invalidateSessions(agent);
             this.jobsIndexOrNull?.invalidate();
             this.invalidateAdoptable(project.slug);
+            // Replaces any earlier import: only the most recent one is undoable.
+            this.lastImport.set(project.slug, { adopted: [...adopted], copies });
         }
         // A session adopted from one source and then met again in the NEXT source
         // (its fresh copy now sits in the project's own transcript folder) comes back
@@ -567,6 +648,81 @@ export class HerdctlService {
         const done = new Set(adopted);
         return { adopted, skipped: skipped.filter((s) => !done.has(s.sessionId)) };
     }
+    /**
+     * Did an import of `sessionId` from `fromWorkingDir` place a NEW file?
+     *
+     * The same test `releaseWithheld` makes before deleting anything: an in-place
+     * adoption resolves the destination and the origin to one path, so there is no
+     * copy and nothing that may be removed.
+     */
+    placedACopy(project, fromWorkingDir, sessionId) {
+        const home = this.cfg.claudeHome;
+        const placed = getCliSessionFile(project.workingDir, sessionId, home);
+        const origin = getCliSessionFile(fromWorkingDir, sessionId, home);
+        return path.resolve(placed) !== path.resolve(origin);
+    }
+    /**
+     * What the LAST import into each workspace did, so it can be undone (#660).
+     *
+     * Keyed by workspace key (which may be `""` — the root). Holds the sessions
+     * that import actually brought in, and of those, the ones where it PLACED a
+     * copy and may therefore delete one again.
+     *
+     * Server-side rather than a token the client hands back: undo deletes files, so
+     * the set of paths it may touch must come from what this process actually did,
+     * not from a request body. A restart forgets it, which is the right failure —
+     * the offer to undo is a transient toast, not a durable feature.
+     *
+     * Only the most recent import per workspace is kept. Undoing an import two
+     * imports ago is not offered and would be a lie to describe as "undo".
+     */
+    lastImport = new Map();
+    /**
+     * Undo the import this process most recently performed into `project` (#660).
+     *
+     * Releases each adoption and deletes the copies that import placed, leaving the
+     * user's own `~/.claude` history exactly as it was. Returns the sessions it
+     * released; an empty array means there was nothing to undo (nothing imported
+     * yet, already undone, or the server restarted since).
+     *
+     * `sessionIds` narrows it to part of that import — the rest stays. Ids that
+     * were not part of it are ignored rather than rejected: undo is a best-effort
+     * safety net, and the alternative is a 400 for a button the user pressed once.
+     */
+    async unadoptChats(project, opts = {}) {
+        const agent = keeperAgentName(project.slug);
+        const last = this.lastImport.get(project.slug);
+        if (last === undefined)
+            return { released: [] };
+        const wanted = opts.sessionIds === undefined ? null : new Set(opts.sessionIds);
+        const target = last.adopted.filter((id) => wanted === null || wanted.has(id));
+        if (target.length === 0)
+            return { released: [] };
+        const copies = new Set(last.copies);
+        const released = [];
+        for (const sessionId of target) {
+            await this.manager.unadoptSession(agent, sessionId).catch(() => undefined);
+            // Delete ONLY a file this import placed. A session adopted in place has no
+            // copy, and its transcript is the user's own — removing it would destroy
+            // history rather than restore it.
+            if (copies.has(sessionId)) {
+                const placed = getCliSessionFile(project.workingDir, sessionId, this.cfg.claudeHome);
+                await fs.rm(placed, { force: true }).catch(() => undefined);
+            }
+            released.push(sessionId);
+        }
+        // Consume what was undone, so a second undo is a no-op rather than a repeat
+        // attempt to delete files that are already gone.
+        const remaining = last.adopted.filter((id) => !released.includes(id));
+        if (remaining.length === 0)
+            this.lastImport.delete(project.slug);
+        else
+            this.lastImport.set(project.slug, { adopted: remaining, copies: last.copies });
+        this.invalidateSessions(agent);
+        this.jobsIndexOrNull?.invalidate();
+        this.invalidateAdoptable(project.slug);
+        return { released };
+    }
     /**
      * Undo the adoption of a session detection had withheld, restoring the state
      * that existed before this import. See {@link adoptChats} for why the file
@@ -832,9 +988,15 @@ export class HerdctlService {
      * 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.
+     *
+     * Like {@link chatSession}, the session is registered in {@link liveSessions}
+     * under a synthetic turn id handed back via `onJobCreated`, so Stop can
+     * interrupt a long-running command (#632). The session is still NOT managed by
+     * the reaper — teardown remains this method's own `finally`.
      */
     async runCommand(agentName, opts) {
         const isResume = typeof opts.resume === "string";
+        const turnId = randomUUID();
         const session = await this.manager.openChatSession(agentName, {
             resume: opts.resume,
             // Stream the command's assistant text token-by-token (paddock#315).
@@ -843,6 +1005,14 @@ export class HerdctlService {
             // turn, so it gets the same environment context (#635).
             systemPromptAppend: this.environmentPromptAppend,
         });
+        // Register the live session under the synthetic turn id exactly as
+        // {@link chatSession} does, so `chat:cancel` routes to `session.interrupt()`
+        // (#632) — without this there is nothing for {@link cancel} to resolve and
+        // Stop is a no-op for the whole command. Removed in the same `finally` that
+        // closes the session, so the entry never outlives the turn.
+        this.liveSessions.set(turnId, session);
+        // Surface the synthetic id as the turn's jobId so the client renders Stop.
+        opts.onJobCreated?.(turnId);
         let sessionId = isResume ? opts.resume : null;
         try {
             // Gap A parity: BOTH branches consume via the non-closing consumeResumedTurn
@@ -873,15 +1043,35 @@ export class HerdctlService {
             // Stream error — fall through and let the caller surface completion.
         }
         finally {
+            // Deregister BEFORE closing, so a Stop racing teardown can't reach a
+            // session that is already shutting down.
+            this.liveSessions.delete(turnId);
             await session.close();
         }
         return { sessionId };
     }
+    /**
+     * Register a background-phase turn so Stop can reach it (paddock#528). Called
+     * by the background turn sink once it knows both the synthetic job id it
+     * published and the session that stream belongs to. Re-registering the same
+     * job id with a later session id is fine — the sink refreshes the mapping if
+     * the stream resolves a different session.
+     */
+    registerBackgroundTurn(jobId, sessionId) {
+        this.backgroundTurns.set(jobId, sessionId);
+    }
+    /** Forget a background-phase turn once its stream has ended. */
+    unregisterBackgroundTurn(jobId) {
+        this.backgroundTurns.delete(jobId);
+    }
     /**
      * 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).
+     *  - **background phase** — the id is a synthetic id in
+     *    {@link backgroundTurns}; there is no model turn to interrupt, so reap the
+     *    session (paddock#528).
      *  - **batch mode** — the id is a real herdctl job id; abort it via `cancelJob`
      *    (which kills the CLI subprocess / aborts the SDK query).
      *
@@ -901,6 +1091,19 @@ export class HerdctlService {
                 return false;
             }
         }
+        // Background phase: the primary turn is over and its liveSessions entry is
+        // gone, but the session is still open streaming autonomous re-invocation
+        // turns. Stop here means "end this session" — reaping reaches even a session
+        // the reap policy would hold open forever, and ending the stream is what
+        // drives the sink's onDone → chat:complete → the UI unlocking.
+        const backgroundSession = this.backgroundTurns.get(jobId);
+        if (backgroundSession !== undefined) {
+            const reaped = this.manager.reapChatSession(backgroundSession);
+            if (!reaped) {
+                console.warn(`[herdctl] no live managed session ${backgroundSession} to reap for background turn ${jobId}`);
+            }
+            return reaped;
+        }
         try {
             await this.manager.cancelJob(jobId);
             return true;
@@ -1268,7 +1471,7 @@ export class HerdctlService {
      */
     async ensureSweeperHome(project) {
         const dir = sweeperWorkingDir(this.cfg, project.slug);
-        await ensureProjectChats(dir, dir);
+        await ensureProjectChats(dir, dir, this.claudeHomeTarget);
     }
     triggerAgentConfig(project, triggerName, trigger) {
         return buildTriggerConfig(this.cfg, project, triggerName, trigger);

package/packages/server/dist/hook-config.d.ts

@@ -37,17 +37,17 @@ export declare const HOOK_EVENTS: ReadonlySet<HookEvent>;
 export type HookPermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan";
 /**
  * A hook's capability set (GG-1) — projected verbatim onto the hook's OWN herdctl
- * agent's tool config, so the registered agent enforces exactly these tools. An
- * absent/empty {@link HookCapabilities.allowedTools} is a **tool-less** hook (it can
- * only think + return text); granting `Bash` lets it spin down servers / delete
- * clones itself. This is intentionally the whole capability model — there is no
- * higher-level profile.
+ * agent's tool config, so the registered agent carries exactly these tools. An
+ * absent/empty {@link HookCapabilities.allowedTools} DECLARES a **tool-less** hook;
+ * granting `Bash` lets it spin down servers / delete clones itself. This is
+ * intentionally the whole capability model — there is no higher-level profile.
  */
 export interface HookCapabilities {
     /**
-     * The tools the hook agent may use (herdctl `allowed_tools`). Omit or `[]` for a
-     * tool-less hook. The CLI runtime auto-denies any tool NOT on this list, so this
-     * is the effective grant.
+     * The tools the hook agent may use (herdctl `allowed_tools`). Omit or `[]` to
+     * declare a tool-less hook — but note herdctl emits the allow-list only when it
+     * is NON-empty, so `[]` is not enforced as a deny-all and the agent falls back to
+     * Claude Code's default tools (#647; enforcement itself is #319).
      */
     allowedTools?: string[];
     /** Tools explicitly denied even if otherwise allowed (herdctl `denied_tools`). */
@@ -120,7 +120,7 @@ export interface ChatHookInfo {
     agentName: string;
     /** Whether the hook is armed (a disabled hook's past chats are still shown). */
     enabled: boolean;
-    /** The exact tool grant (herdctl `allowed_tools`); `[]` = a tool-less hook. */
+    /** The declared tool grant (herdctl `allowed_tools`); `[]` = none, unenforced (#647). */
     allowedTools: string[];
     /** Tools explicitly denied even if otherwise allowed, when the hook sets any. */
     deniedTools?: string[];
@@ -207,11 +207,13 @@ export declare function sanitizeHook(raw: unknown): PaddockHook | null;
 export declare function sanitizeHooks(raw: unknown): Record<string, PaddockHook> | undefined;
 /**
  * Project a hook's {@link HookCapabilities} onto the exact herdctl agent tool-config
- * fields (snake_case), so the registered `hook-<slug>-<name>` agent enforces the
- * capability BY CONSTRUCTION. A tool-less hook yields `allowed_tools: []` (the CLI
- * runtime then denies every tool). Always sets `allowed_tools` + `max_turns` so a
- * hook agent never silently inherits the keeper's broad default toolset; the other
- * fields are set only when the capability specifies them (else the fleet defaults
- * apply). This is the ONE place capability→config translation lives.
+ * fields (snake_case), so the registered `hook-<slug>-<name>` agent carries the
+ * capability BY CONSTRUCTION. A hook that declares no tools yields
+ * `allowed_tools: []`, which herdctl does NOT enforce as a deny-all — the same
+ * caveat spelled out on `triggerToAgentToolConfig` in `trigger-config.ts` (#647).
+ * Always sets `allowed_tools` + `max_turns` so a hook agent never silently inherits
+ * the keeper's broad default toolset; the other fields are set only when the
+ * capability specifies them (else the fleet defaults apply). This is the ONE place
+ * capability→config translation lives.
  */
 export declare function hookToAgentToolConfig(caps: HookCapabilities | undefined): Record<string, unknown>;

package/packages/server/dist/hook-config.js

@@ -199,18 +199,20 @@ export function sanitizeHooks(raw) {
 }
 /**
  * Project a hook's {@link HookCapabilities} onto the exact herdctl agent tool-config
- * fields (snake_case), so the registered `hook-<slug>-<name>` agent enforces the
- * capability BY CONSTRUCTION. A tool-less hook yields `allowed_tools: []` (the CLI
- * runtime then denies every tool). Always sets `allowed_tools` + `max_turns` so a
- * hook agent never silently inherits the keeper's broad default toolset; the other
- * fields are set only when the capability specifies them (else the fleet defaults
- * apply). This is the ONE place capability→config translation lives.
+ * fields (snake_case), so the registered `hook-<slug>-<name>` agent carries the
+ * capability BY CONSTRUCTION. A hook that declares no tools yields
+ * `allowed_tools: []`, which herdctl does NOT enforce as a deny-all — the same
+ * caveat spelled out on `triggerToAgentToolConfig` in `trigger-config.ts` (#647).
+ * Always sets `allowed_tools` + `max_turns` so a hook agent never silently inherits
+ * the keeper's broad default toolset; the other fields are set only when the
+ * capability specifies them (else the fleet defaults apply). This is the ONE place
+ * capability→config translation lives.
  */
 export function hookToAgentToolConfig(caps) {
     const out = {
-        // A hook's grant is exactly its allowedTools — default to NONE (tool-less), never
-        // the keeper's broad inherited allowlist. An empty list = the CLI runtime denies
-        // all tools, which is the correct "no capability" semantics.
+        // A hook's grant is exactly its allowedTools — default to NONE, never the
+        // keeper's broad inherited allowlist. An empty list expresses "no capability",
+        // though herdctl never emits it, so it is not enforced as one (#647).
         allowed_tools: caps?.allowedTools ?? [],
         max_turns: caps?.maxTurns ?? HOOK_DEFAULT_MAX_TURNS,
     };