@edspencer/paddock 0.60.0 → 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

@@ -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/transcripts.d.ts

@@ -21,13 +21,32 @@ 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 the one destructive branch (#620): 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. 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)) {

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.
  */