@edspencer/paddock 0.60.0 → 0.61.1

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

@@ -165,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
@@ -511,11 +519,18 @@ 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;
     }>;

package/packages/server/dist/herdctl.js

@@ -226,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
@@ -315,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 });
@@ -389,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 });
@@ -490,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) {
@@ -541,9 +551,26 @@ 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
@@ -961,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).
@@ -972,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
@@ -1002,6 +1043,9 @@ 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 };
@@ -1427,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,
     };

package/packages/server/dist/routes/chats.js

@@ -868,11 +868,18 @@ export function registerChatWorkspaceRoutes(app, ctx) {
     // optional `when` (epoch-ms) lets the client pass its own timestamp; defaults
     // to now. Mirrors the archive toggle's shape/validation. Monotonic in the
     // store (an older `when` is a no-op), so it never resurrects a stale unread.
+    //
+    // `keepUnread: true` marks the seen as INFERRED rather than intentional (#608):
+    // the watermark still advances, but an explicit "mark unread" override is left
+    // alone. The web client uses it when a turn happens to land while the chat is
+    // focused — "you were watching" must not silently spend a flag the user (or an
+    // API caller) set seconds earlier. The response reports the resulting flag so a
+    // caller can see what its request did.
     app.post("/chats/:sessionId/seen", {
         schema: {
             tags: ["Chats"],
             summary: "Mark a project chat as seen",
-            description: "Persists the user's last-viewed moment for a project chat server-side, driving the cross-device unread affordance. Optional body `{ when }` (epoch-ms) defaults to now; monotonic in the store (an older `when` is a no-op). Responds 200 with `{ ok, lastSeen }`.",
+            description: "Persists the user's last-viewed moment for a project chat server-side, driving the cross-device unread affordance. Optional body `{ when }` (epoch-ms) defaults to now; monotonic in the store (an older `when` is a no-op). Clears the chat's MANUAL unread override (see the `/unread` route) unless `keepUnread` is true, which marks the request as an INFERRED seen and leaves an explicit flag intact. Responds 200 with `{ ok, lastSeen, unread }`, `unread` being the override's state afterwards.",
             params: {
                 type: "object",
                 properties: {
@@ -886,12 +893,15 @@ export function registerChatWorkspaceRoutes(app, ctx) {
                 additionalProperties: true,
                 properties: {
                     when: { description: "Epoch-ms timestamp to record as last seen; defaults to now." },
+                    keepUnread: {
+                        description: "When true, advance the watermark WITHOUT clearing the manual unread override — for a seen that was inferred rather than intended. Defaults to false.",
+                    },
                 },
                 required: [],
             },
             response: {
                 200: {
-                    description: "Object `{ ok, lastSeen }` with the recorded watermark.",
+                    description: "Object `{ ok, lastSeen, unread }` with the recorded watermark and the manual unread override's state afterwards.",
                     type: "object",
                     additionalProperties: true,
                 },
@@ -906,9 +916,17 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             const user = readStateUser(req);
             await readState.setLastSeen(user, agent, req.params.sessionId, when);
             // Marking a chat seen also clears any MANUAL unread override (#458): once
-            // the user has viewed it, the "look at it again later" flag is spent.
-            await unread.setUnread(user, agent, req.params.sessionId, false).catch(() => undefined);
-            return reply.code(200).send({ ok: true, lastSeen: when });
+            // the user has viewed it, the "look at it again later" flag is spent —
+            // UNLESS the caller flagged this as an inferred seen (#608), in which case
+            // the explicit intent outranks it and the flag stands.
+            let stillUnread = false;
+            if (req.body?.keepUnread === true) {
+                stillUnread = await unread.isUnread(user, agent, req.params.sessionId);
+            }
+            else {
+                await unread.setUnread(user, agent, req.params.sessionId, false).catch(() => undefined);
+            }
+            return reply.code(200).send({ ok: true, lastSeen: when, unread: stillUnread });
         }
         catch (err) {
             return sendProjectError(reply, err);
@@ -1330,7 +1348,16 @@ export function registerChatWorkspaceRoutes(app, ctx) {
     }, async (req, reply) => {
         try {
             const project = await projects.get(req.params.slug);
-            return await herdctl.listAdoptable(project);
+            const summary = await herdctl.listAdoptable(project);
+            // `importFrom` is a server-internal detail — the synthetic path a legacy
+            // source is reached through (#620). Clients round-trip `sourceCwd`, so
+            // strip it rather than publishing a `~/.claude` path in the DTO; the
+            // response schema is `additionalProperties: true`, so it would otherwise
+            // serialize.
+            return {
+                ...summary,
+                sources: summary.sources.map(({ importFrom: _importFrom, ...rest }) => rest),
+            };
         }
         catch (err) {
             return sendProjectError(reply, err);

package/packages/server/dist/sweep.js

@@ -38,6 +38,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { keeperAgentName } from "./herdctl.js";
+import { classifyAgentError } from "./agent-errors.js";
 import { DEFAULT_CURATION, resolveCurationConfig, } from "./curation-config.js";
 import { curatorTriggerOf, triggerPromptFileAbsPath, } from "./trigger-config.js";
 const STATE_FILE = "sweep-state.json";
@@ -204,7 +205,18 @@ export class SweepService {
                 lastSweptSessionMtime: wm.lastSweptSessionMtime,
                 lastSweptAt: Date.now(),
             });
-            this.log.error({ err, slug }, "sweep: sweeper run errored (non-fatal)");
+            // #684: this is a best-effort background task whose failure is already
+            // labelled non-fatal, so a recognised cause gets ONE line at warn — no
+            // `err`, because pino serialising it is what put four copies of the
+            // curator system prompt on a first-time user's terminal. An unrecognised
+            // failure keeps the full object: that is the case somebody needs it.
+            const cause = classifyAgentError(err);
+            if (cause === undefined) {
+                this.log.error({ err, slug }, "sweep: sweeper run errored (non-fatal)");
+            }
+            else {
+                this.log.warn({ slug }, `sweep: skipped, ${cause} (non-fatal — chat is unaffected)`);
+            }
         }
         finally {
             this.running.delete(slug);

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

@@ -21,13 +21,39 @@ export declare function projectChatsDir(projectDir: string): string;
  * store stays in the project's metadata dir (the data repo) — so transcripts
  * never pollute the external repo's working tree — hence the two are split.
  *
- * `claudeHomePath` is the Claude home to plant the symlink in. Callers holding a
- * config MUST pass `cfg.claudeHome` (#588): the engine is constructed with that
- * same resolved value, and a symlink planted in a different home than the one
- * the engine reads is exactly the "chats list but open empty" failure. The
- * env-derived default is kept only for callers with no config (unit tests).
+ * `home.path` is the Claude home to plant the symlink in, and it is REQUIRED —
+ * no default (#620). Callers must pass `cfg.claudeHome`: the engine is
+ * constructed with that same resolved value, and a symlink planted in a
+ * different home than the one the engine reads is exactly the "chats list but
+ * open empty" failure (#588). It used to default to the env-derived home for
+ * callers with no config, and `ensureSweeperHome` silently took that default —
+ * so the sweeper's symlink landed in a different home than every other agent's.
+ * Making the parameter required is what stops that class of bug at the type
+ * level.
+ *
+ * `home.owned` gates EVERY write into the home (#620, #682). Two of them:
+ *
+ *  - Migrating an existing real transcript directory into `.chats/` copies the
+ *    files and then REMOVES the originals. That is correct self-healing inside a
+ *    home paddock owns, where such a directory can only be paddock's own doing.
+ *    Inside the user's `~/.claude` it is somebody else's data — a `claude` CLI
+ *    session run in a directory paddock happens to also manage — so we leave it
+ *    strictly alone and let the SDK keep writing there.
+ *  - Planting the redirect symlink at a path that does not exist yet. Not
+ *    destructive on the day it happens, which is why it was missed, but it
+ *    silently claims where the user's FUTURE sessions for that directory get
+ *    written (#682). See the branch itself for the full argument.
+ *
+ * Either way those transcripts stay importable through adoption (#588), which is
+ * the deliberate, user-driven version of the same move.
  */
-export declare function ensureProjectChats(workingDir: string, chatsHostDir?: string, claudeHomePath?: string): Promise<void>;
+export interface ClaudeHomeTarget {
+    /** Absolute path to the Claude home to plant the redirect symlink in. */
+    path: string;
+    /** Whether paddock owns this home — see `PaddockConfig.ownsClaudeHome`. */
+    owned: boolean;
+}
+export declare function ensureProjectChats(workingDir: string, chatsHostDir: string, home: ClaudeHomeTarget): Promise<void>;
 /**
  * Read a session's FIRST user message text, untruncated, straight from its
  * transcript JSONL (issue #62). Claude Code's own `preview` is capped at 100

package/packages/server/dist/transcripts.js

@@ -1,8 +1,9 @@
 /**
  * Transcript relocation (backing-store Phase 3).
  *
- * Claude Code writes a session transcript to `~/.claude/projects/<encoded-cwd>/`,
- * where `<encoded-cwd>` is the agent's absolute working directory with every
+ * Claude Code writes a session transcript to `<claudeHome>/projects/<encoded-cwd>/`,
+ * where `<claudeHome>` is `CLAUDE_CONFIG_DIR` (paddock's own `<dataDir>/claude-home`
+ * since #620) and `<encoded-cwd>` is the agent's absolute working directory with every
  * non-[A-Za-z0-9] char replaced by '-'. That makes transcripts path-coupled and
  * not portable. We relocate them INTO the project by making the encoded path a
  * **symlink to `<projectDir>/.chats/`** — Claude then writes through the symlink
@@ -17,7 +18,6 @@
 import { promises as fs, createReadStream } from "node:fs";
 import { createInterface } from "node:readline";
 import path from "node:path";
-import { claudeHome } from "./config.js";
 /**
  * Encode a working directory the way Claude Code names its transcript dir.
  * For paths under 200 chars this is just the non-alphanumeric→'-' replacement
@@ -31,27 +31,8 @@ export function encodeProjectDir(dir) {
 export function projectChatsDir(projectDir) {
     return path.join(projectDir, ".chats");
 }
-/**
- * Ensure `<chatsHostDir>/.chats/` exists and that Claude Code's encoded
- * transcript path for `workingDir` is a symlink pointing at it (migrating an
- * existing real transcript dir in the process). Safe to call on every agent
- * registration. Never throws — a failure here must not block agent registration
- * or chat.
- *
- * `workingDir` is the agent's cwd (which Claude encodes into the transcript dir
- * name); `chatsHostDir` is where the `.chats/` store actually lives. For a
- * notebook project these are the same dir (the default). For a REPO-BACKED
- * project (issue #187) the keeper's cwd is the nested checkout but the `.chats/`
- * store stays in the project's metadata dir (the data repo) — so transcripts
- * never pollute the external repo's working tree — hence the two are split.
- *
- * `claudeHomePath` is the Claude home to plant the symlink in. Callers holding a
- * config MUST pass `cfg.claudeHome` (#588): the engine is constructed with that
- * same resolved value, and a symlink planted in a different home than the one
- * the engine reads is exactly the "chats list but open empty" failure. The
- * env-derived default is kept only for callers with no config (unit tests).
- */
-export async function ensureProjectChats(workingDir, chatsHostDir = workingDir, claudeHomePath = claudeHome()) {
+export async function ensureProjectChats(workingDir, chatsHostDir, home) {
+    const claudeHomePath = home.path;
     try {
         const chatsDir = projectChatsDir(chatsHostDir);
         await fs.mkdir(chatsDir, { recursive: true });
@@ -68,6 +49,13 @@ export async function ensureProjectChats(workingDir, chatsHostDir = workingDir,
             }
             return;
         }
+        // A real directory of existing transcripts. In a home paddock does NOT own
+        // these are the user's own CLI transcripts (#620) — leave them exactly where
+        // they are. The SDK keeps reading and appending to them, and adoption is how
+        // the user pulls them into the project if they want to. Bailing here also
+        // means we never plant a symlink over them.
+        if (st?.isDirectory() && !home.owned)
+            return;
         // A real directory of existing transcripts — migrate into .chats, then link.
         if (st?.isDirectory()) {
             for (const entry of await fs.readdir(encoded)) {
@@ -88,6 +76,24 @@ export async function ensureProjectChats(workingDir, chatsHostDir = workingDir,
             await fs.symlink(chatsDir, encoded);
             return;
         }
+        // Nothing there yet. In a home paddock does NOT own, planting here is the
+        // data-loss branch (#682): the encoded path is where the USER's future
+        // `claude` sessions for this directory land, so a link redirects every one of
+        // them into paddock's `.chats/` — from that moment "their history" and "our
+        // store" are the same files, and an ordinary `rm -rf .chats` destroys
+        // transcripts paddock never owned. It also breaks unrelated tooling that
+        // expects `~/.claude/projects/<enc>` to be a directory. Creating a name the
+        // user has not used yet is not "overwriting", so it slipped past the letter
+        // of claude-home.ts's invariant while breaking its intent.
+        //
+        // The cost of bailing is that transcripts stay in the user's home instead of
+        // being self-contained in `.chats/`, which is exactly the pre-#620 trade for
+        // the `CLAUDE_HOME=~/.claude` escape hatch. Chat still works end to end:
+        // paddock and the engine both resolve THIS home, so discovery, resume and
+        // rename all read the real directory. Adoption (#588) remains the deliberate,
+        // user-driven way to pull those transcripts into a project.
+        if (!home.owned)
+            return;
         // Nothing there yet — just create the symlink so future turns land in .chats.
         await fs.symlink(chatsDir, encoded);
     }

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

@@ -197,11 +197,21 @@ export declare function curatorTriggerOf(triggers: Record<string, PaddockTrigger
 /**
  * Project a trigger's {@link TriggerRun} onto the exact herdctl agent tool-config
  * fields (snake_case), so an event/webhook trigger's OWN `trigger-<slug>-<name>`
- * agent enforces the capability BY CONSTRUCTION. Always sets `allowed_tools` +
+ * agent carries the capability BY CONSTRUCTION. Always sets `allowed_tools` +
  * `max_turns` so a trigger agent never silently inherits the keeper's broad default
- * toolset; a tool-less trigger yields `allowed_tools: []` (the CLI runtime then
- * denies every tool). The ONE place run→agent-config translation lives. (The exact
- * analogue of `hookToAgentToolConfig`.)
+ * toolset.
+ *
+ * CAVEAT on the EMPTY case (#647): a trigger that declares no tools yields
+ * `allowed_tools: []`, and BOTH herdctl runtimes emit the allow-list only when it is
+ * non-empty (`if (allowed_tools?.length)`, in `cli-runtime` and `sdk-adapter` alike).
+ * So an empty list is indistinguishable from an unset one — no `--allowedTools` flag,
+ * no `allowedTools` option — and the agent runs with Claude Code's DEFAULT tools.
+ * `[]` is a declaration of intent, NOT an enforced deny-all: `max_turns`, the prompt
+ * and `permission_mode` are the real bounds. Making a grant enforceable at all is
+ * #319. Pinned by `test/unit/empty-allowed-tools-runtime.test.ts`.
+ *
+ * The ONE place run→agent-config translation lives. (The exact analogue of
+ * `hookToAgentToolConfig`.)
  */
 export declare function triggerToAgentToolConfig(run: TriggerRun): Record<string, unknown>;
 /**
@@ -250,7 +260,7 @@ export interface ChatTriggerInfo {
     agentName: string;
     /** Whether the trigger is armed (a disabled trigger's past chats are still shown). */
     enabled: boolean;
-    /** The exact tool grant (herdctl `allowed_tools`); `[]` = a tool-less trigger. */
+    /** The declared tool grant (herdctl `allowed_tools`); `[]` = none, unenforced (#647). */
     allowedTools: string[];
     /** The permission mode the trigger's turns run under, when it sets one. */
     permissionMode?: TriggerPermissionMode;
@@ -262,9 +272,9 @@ export interface ChatTriggerInfo {
 /**
  * Project a persisted trigger ({@link TriggerDto} fields) onto the web-facing
  * {@link ChatTriggerInfo}, resolving the SAME capability defaults
- * {@link triggerToAgentToolConfig} uses so the banner mirrors the enforced grant
- * exactly: an absent/empty allow-list surfaces as a tool-less `[]`, and an unset
- * `maxTurns` surfaces the {@link TRIGGER_DEFAULT_MAX_TURNS} bound herdctl applies.
+ * {@link triggerToAgentToolConfig} uses so the banner mirrors the registered grant
+ * exactly: an absent/empty allow-list surfaces as `[]`, and an unset `maxTurns`
+ * surfaces the {@link TRIGGER_DEFAULT_MAX_TURNS} bound herdctl applies.
  * The WHEN fields are read off the discriminated `trigger` so the banner can state
  * the trigger type and the exact firing condition.
  */

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

@@ -107,7 +107,7 @@ const runSchema = z.object({
     session: z.enum(["new", "resume"]).default("new"),
     /** Optional per-trigger model override (else the keeper default applies). */
     model: z.string().trim().min(1).optional(),
-    /** Deny-by-default allow-list = the trigger's capability. `[]` = tool-less. */
+    /** The trigger's declared capability. `[]` = no tools declared (see #647: unenforced). */
     tools: z.array(z.string().trim().min(1)).default([]),
     /** Recursion bound for internal spawning (reuses B1); 0 = may not spawn. */
     maxSpawnDepth: z.number().int().nonnegative().optional(),
@@ -298,11 +298,21 @@ export function curatorTriggerOf(triggers) {
 /**
  * Project a trigger's {@link TriggerRun} onto the exact herdctl agent tool-config
  * fields (snake_case), so an event/webhook trigger's OWN `trigger-<slug>-<name>`
- * agent enforces the capability BY CONSTRUCTION. Always sets `allowed_tools` +
+ * agent carries the capability BY CONSTRUCTION. Always sets `allowed_tools` +
  * `max_turns` so a trigger agent never silently inherits the keeper's broad default
- * toolset; a tool-less trigger yields `allowed_tools: []` (the CLI runtime then
- * denies every tool). The ONE place run→agent-config translation lives. (The exact
- * analogue of `hookToAgentToolConfig`.)
+ * toolset.
+ *
+ * CAVEAT on the EMPTY case (#647): a trigger that declares no tools yields
+ * `allowed_tools: []`, and BOTH herdctl runtimes emit the allow-list only when it is
+ * non-empty (`if (allowed_tools?.length)`, in `cli-runtime` and `sdk-adapter` alike).
+ * So an empty list is indistinguishable from an unset one — no `--allowedTools` flag,
+ * no `allowedTools` option — and the agent runs with Claude Code's DEFAULT tools.
+ * `[]` is a declaration of intent, NOT an enforced deny-all: `max_turns`, the prompt
+ * and `permission_mode` are the real bounds. Making a grant enforceable at all is
+ * #319. Pinned by `test/unit/empty-allowed-tools-runtime.test.ts`.
+ *
+ * The ONE place run→agent-config translation lives. (The exact analogue of
+ * `hookToAgentToolConfig`.)
  */
 export function triggerToAgentToolConfig(run) {
     const out = {
@@ -361,9 +371,9 @@ export function triggersToHerdctlSchedules(map) {
 /**
  * Project a persisted trigger ({@link TriggerDto} fields) onto the web-facing
  * {@link ChatTriggerInfo}, resolving the SAME capability defaults
- * {@link triggerToAgentToolConfig} uses so the banner mirrors the enforced grant
- * exactly: an absent/empty allow-list surfaces as a tool-less `[]`, and an unset
- * `maxTurns` surfaces the {@link TRIGGER_DEFAULT_MAX_TURNS} bound herdctl applies.
+ * {@link triggerToAgentToolConfig} uses so the banner mirrors the registered grant
+ * exactly: an absent/empty allow-list surfaces as `[]`, and an unset `maxTurns`
+ * surfaces the {@link TRIGGER_DEFAULT_MAX_TURNS} bound herdctl applies.
  * The WHEN fields are read off the discriminated `trigger` so the banner can state
  * the trigger type and the exact firing condition.
  */