@edspencer/paddock 0.59.1 → 0.61.0

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);
@@ -1311,7 +1329,7 @@ export function registerChatWorkspaceRoutes(app, ctx) {
         schema: {
             tags: ["Chats"],
             summary: "Count the native Claude Code chats this project could import",
-            description: "Returns the terminal `claude` sessions that could be imported into this project but are not yet visible in it: the project's own working directory, plus any Claude transcript folder whose recorded working directory matches the project (by checkout name for a repo-backed project, by exact path for a notebook project). Sidechains, already-imported sessions and sessions belonging to a real Paddock run are excluded by the engine; empty and slash-command-only transcripts are additionally withheld as noise and reported under `filtered`, so a count lower than the raw total always has an explanation. Response: `{ count, sources: [{ sourceCwd, sessionIds }], filtered: [{ sessionId, sourceCwd, reason }] }`. The count is LIVE — re-read it after an import rather than remembering a dismissal.",
+            description: "Returns the terminal `claude` sessions that could be imported into this project but are not yet visible in it: the project's own working directory, plus any Claude transcript folder whose recorded working directory matches the project (by checkout name for a repo-backed project, by exact path for a notebook project). Sidechains, already-imported sessions and sessions belonging to a real Paddock run are excluded by the engine; empty transcripts, slash-command-only transcripts and Paddock's own sweeper curation runs (`too-small` / `slash-command-only` / `sweeper-run`) are additionally withheld as noise and reported under `filtered`, so a count lower than the raw total always has an explanation. Response: `{ count, sources: [{ sourceCwd, sessionIds }], filtered: [{ sessionId, sourceCwd, reason }] }`. The count is LIVE — re-read it after an import rather than remembering a dismissal.",
             params: {
                 type: "object",
                 properties: {
@@ -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);
@@ -1340,7 +1367,7 @@ export function registerChatWorkspaceRoutes(app, ctx) {
         schema: {
             tags: ["Chats"],
             summary: "Import native Claude Code chats into this project",
-            description: "Imports the terminal `claude` sessions reported by GET …/adoptable-chats. With no body (or no `sourceCwd`) every detected source is imported; with `sourceCwd` only that source is, and it must be one this project actually offers — an unrecognised path is a 400 rather than an invitation to scan arbitrary directories. Transcripts are COPIED, never moved: the user's own `~/.claude` history is left intact and the copies keep their original mtimes, so imported chats sort by when they really happened. Afterwards the session, run-record and detection caches are dropped, so the chats appear on the very next list request with no restart. Response: `{ adopted, skipped }` — `skipped` carries the engine's reason per session (`sidechain`, `already-adopted`, `destination-exists`, `attributed-to-run`, `unreadable`, `placement-failed`, `record-failed`).",
+            description: "Imports the terminal `claude` sessions reported by GET …/adoptable-chats. With no body (or no `sourceCwd`) every detected source is imported; with `sourceCwd` only that source is, and it must be one this project actually offers — an unrecognised path is a 400 rather than an invitation to scan arbitrary directories. `sessionIds` narrows the import to a chosen SUBSET of what is on offer (what the confirmation dialog sends); ids that are not on offer are simply not imported, and anything the engine adopts as a side effect of taking a whole source is released again. Transcripts are COPIED, never moved: the user's own `~/.claude` history is left intact and the copies keep their original mtimes, so imported chats sort by when they really happened. Afterwards the session, run-record and detection caches are dropped, so the chats appear on the very next list request with no restart. Response: `{ adopted, skipped }` — `skipped` carries the engine's reason per session (`sidechain`, `already-adopted`, `destination-exists`, `attributed-to-run`, `unreadable`, `placement-failed`, `record-failed`).",
             params: {
                 type: "object",
                 properties: {
@@ -1355,6 +1382,11 @@ export function registerChatWorkspaceRoutes(app, ctx) {
                     sourceCwd: {
                         description: "Optional single source working directory to import from. Must be one of the `sourceCwd` values reported by GET …/adoptable-chats (or the project's own working directory); anything else is rejected with 400.",
                     },
+                    sessionIds: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional subset of the offered session ids to import. Omit to import everything on offer.",
+                    },
                 },
                 required: [],
             },
@@ -1382,7 +1414,10 @@ export function registerChatWorkspaceRoutes(app, ctx) {
                         .send({ error: `Not an importable source: ${sourceCwd}`, code: "invalid" });
                 }
             }
-            const result = await herdctl.adoptChats(project, { sourceCwd });
+            const result = await herdctl.adoptChats(project, {
+                sourceCwd,
+                sessionIds: req.body?.sessionIds,
+            });
             // Stamp each imported chat's provenance so the list can badge it as
             // imported rather than as an ordinary human chat. `stampIfAbsent`, not
             // `stamp`: provenance describes how a chat came to exist and is never
@@ -1403,4 +1438,52 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             return sendProjectError(reply, err);
         }
     });
+    app.post("/unadopt-chats", {
+        schema: {
+            tags: ["Chats"],
+            summary: "Undo the most recent native-chat import into this project",
+            description: "Reverses the import this server most recently performed into the workspace: each adoption is released and the copies that import placed are deleted, leaving the user's own `~/.claude` history untouched. `sessionIds` undoes part of that import; omit it to undo all of it. Deliberately scoped to the LAST import and remembered in memory — undo may delete files, so the paths it can touch come from what this process actually did rather than from the request body, and a restart forgets the offer rather than acting on a stale one. Response: `{ released }`, the session ids actually released; an empty array means there was nothing to undo (nothing imported, already undone, or the server restarted since).",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "Project slug." },
+                },
+                required: ["slug"],
+            },
+            body: {
+                type: ["object", "null"],
+                additionalProperties: true,
+                properties: {
+                    sessionIds: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional subset of the last import's session ids to release. Omit to undo the whole import. Ids outside that import are ignored.",
+                    },
+                },
+                required: [],
+            },
+            response: {
+                200: {
+                    description: "Object `{ released }` listing the session ids released.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        try {
+            const project = await projects.get(req.params.slug);
+            const result = await herdctl.unadoptChats(project, {
+                sessionIds: req.body?.sessionIds,
+            });
+            // Drop the provenance marker the import stamped, so a session that is
+            // later re-imported is badged by that import rather than carrying a
+            // marker from one that has been undone.
+            await Promise.all(result.released.map((sessionId) => runProvenance.clear(sessionId).catch(() => undefined)));
+            return result;
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
 }

package/packages/server/dist/run-provenance.d.ts

@@ -104,6 +104,17 @@ export declare class RunProvenanceStore {
      * survives.
      */
     stampIfAbsent(sessionId: string, provenance: RunProvenance): Promise<void>;
+    /**
+     * Forget a chat's provenance (#660).
+     *
+     * The inverse of {@link stamp}, for the one case where a chat's creation is
+     * itself undone: undoing a native-chat import releases the adoption and deletes
+     * the copy, and a marker left behind would badge a LATER import of the same
+     * session as belonging to the one that was undone. Returns silently when there
+     * was nothing recorded, so an undo of a partially-stamped import is not an
+     * error.
+     */
+    clear(sessionId: string): Promise<void>;
     /** Write-through, serialised so overlapping stamps can't corrupt the file. */
     private persist;
 }

package/packages/server/dist/run-provenance.js

@@ -192,6 +192,24 @@ export class RunProvenanceStore {
             return;
         await this.stamp(sessionId, provenance);
     }
+    /**
+     * Forget a chat's provenance (#660).
+     *
+     * The inverse of {@link stamp}, for the one case where a chat's creation is
+     * itself undone: undoing a native-chat import releases the adoption and deletes
+     * the copy, and a marker left behind would badge a LATER import of the same
+     * session as belonging to the one that was undone. Returns silently when there
+     * was nothing recorded, so an undo of a partially-stamped import is not an
+     * error.
+     */
+    async clear(sessionId) {
+        if (!isSafeId(sessionId))
+            return;
+        const map = await this.ensureLoaded();
+        if (!map.delete(sessionId))
+            return;
+        await this.persist(map);
+    }
     /** Write-through, serialised so overlapping stamps can't corrupt the file. */
     persist(map) {
         this.writing = this.writing.then(async () => {

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

package/packages/server/dist/ws-turn.d.ts

@@ -1,16 +1,3 @@
-/**
- * The turn-execution engine, extracted from ws.ts (#403).
- *
- * `makeTurnEngine({ deps, hub })` relocates — intact — the mutually-recursive core
- * that ws.ts's makeChatHandler used to hold in one closure: the trigger cluster,
- * the self-MCP injection context, the per-turn injected-MCP builders + wake cache,
- * the shared `startAgentTurn` execution engine, and the Layer-2/3 recovery
- * (`injectRecoveryNudge` + `RecoveryEngine`). These pieces cross-reference each
- * other (startAgentTurn ↔ recoveryEngine.armWatch, triggers ↔ startAgentTurn,
- * selfMcp injection ↔ startAgentTurn), so they must share ONE scope — moving them
- * as a group keeps that intact with no late-binding. ws.ts's socket layer consumes
- * the returned surface.
- */
 import type { SDKMessage, InjectedMcpServerDef } from "@herdctl/core";
 import type { Project } from "./projects.js";
 import { SessionHub } from "./session-hub.js";

package/packages/server/dist/ws-turn.js

@@ -1,3 +1,17 @@
+/**
+ * The turn-execution engine, extracted from ws.ts (#403).
+ *
+ * `makeTurnEngine({ deps, hub })` relocates — intact — the mutually-recursive core
+ * that ws.ts's makeChatHandler used to hold in one closure: the trigger cluster,
+ * the self-MCP injection context, the per-turn injected-MCP builders + wake cache,
+ * the shared `startAgentTurn` execution engine, and the Layer-2/3 recovery
+ * (`injectRecoveryNudge` + `RecoveryEngine`). These pieces cross-reference each
+ * other (startAgentTurn ↔ recoveryEngine.armWatch, triggers ↔ startAgentTurn,
+ * selfMcp injection ↔ startAgentTurn), so they must share ONE scope — moving them
+ * as a group keeps that intact with no late-binding. ws.ts's socket layer consumes
+ * the returned surface.
+ */
+import { randomUUID } from "node:crypto";
 import { createSDKMessageHandler } from "@herdctl/chat";
 import { keeperAgentName, keeperSlugFromAgent } from "./herdctl.js";
 import { isKnownDriveMode, getContextLimit } from "./models.js";
@@ -172,6 +186,13 @@ export function makeTurnEngine(engine) {
         let producedReply = false;
         let noticeEmitted = false;
         let sawError = false;
+        // #528: the synthetic job id published for this background stretch, and the
+        // session id currently registered against it. The stretch is a real running
+        // turn as far as the UI is concerned, so it needs a cancellable identity —
+        // without one `chat:active` carries `jobId: null`, the client's deferred
+        // cancel never fires, and Stop puts nothing on the wire at all.
+        let bgJobId = null;
+        let registeredSession = null;
         // #429: sub-agent launches recovered live from the tool_use input, keyed by
         // toolUseId, so the enriched card renders without a refresh (see subagentLaunchFields).
         const launches = new Map();
@@ -180,6 +201,19 @@ export function makeTurnEngine(engine) {
             sessionId: resolvedSession,
             jobId: turn?.jobId ?? null,
         });
+        /**
+         * Point the published job id at whatever session this stream has resolved.
+         * Deferred rather than done once at mint time because the id is published when
+         * the turn opens, which can precede the first message that names a session;
+         * re-run on every message so a stream that resolves (or moves to) a different
+         * session stays cancellable.
+         */
+        const syncBackgroundRegistration = () => {
+            if (!bgJobId || !resolvedSession || registeredSession === resolvedSession)
+                return;
+            deps.herdctl.registerBackgroundTurn(bgJobId, resolvedSession);
+            registeredSession = resolvedSession;
+        };
         const emitNotice = (notice) => {
             if (!turn || noticeEmitted)
                 return;
@@ -196,6 +230,13 @@ export function makeTurnEngine(engine) {
                 return;
             resolvedSession = sid;
             turn = hub.startTurn(projectSlug, null, sid);
+            // #528: give the stretch a cancellable identity the moment it opens, exactly
+            // as the foreground path does via onJobCreated. Stop then routes to a
+            // force-reap of this session rather than an interrupt — there is no model
+            // turn in flight here to interrupt.
+            bgJobId = randomUUID();
+            turn.setJobId(bgJobId);
+            syncBackgroundRegistration();
             const t = turn;
             translate = createSDKMessageHandler({
                 onText: (chunk) => {
@@ -252,6 +293,7 @@ export function makeTurnEngine(engine) {
             ensureTurn(m.session_id ?? resolvedSession);
             if (m.session_id)
                 turn.setSession(m.session_id);
+            syncBackgroundRegistration();
             if (messageProducedReply(m))
                 producedReply = true;
             const notice = noticeFromMessage(m);
@@ -266,6 +308,14 @@ export function makeTurnEngine(engine) {
         // Finalize the single turn once the background stream ends (reaper reap). No-op
         // if nothing was ever rendered (a sidechain-only stretch opened no turn).
         const onDone = () => {
+            // Drop the cancellable identity first, and unconditionally: the stream is
+            // over, so a later Stop must fall through to the "already finished" path
+            // rather than reaping whatever session has since taken this id. Runs even
+            // for a sidechain-only stretch that opened no turn, and on a second call.
+            if (bgJobId)
+                deps.herdctl.unregisterBackgroundTurn(bgJobId);
+            bgJobId = null;
+            registeredSession = null;
             if (!turn)
                 return;
             turn.emit({

package/packages/server/dist/ws.js

@@ -46,13 +46,21 @@ export function makeChatHandler(deps) {
     // currently attached, so a turn survives the death of the socket that started
     // it (issue #54). See session-hub.ts.
     const hub = new SessionHub();
-    // Per-session marker of the last queued message the server has already drained
-    // (#245), keyed `agent \0 sessionId` and stamped with that message's client
-    // timestamp. Lets an idle-drain skip a message it already sent — e.g. a stale
-    // localStorage copy a reloaded client re-asserts — instead of double-sending.
-    // In-memory (shared across this handler's sockets); a rare double-send only
-    // survives a server restart, when the persisted store is already empty anyway.
-    const lastFlushedTs = new Map();
+    // Per-session marker of the queued messages the server has already drained
+    // (#245), keyed `agent \0 sessionId`. Lets a drain skip a message it already
+    // sent — e.g. a stale localStorage copy a reloaded client re-asserts — instead
+    // of double-sending. In-memory (shared across this handler's sockets); a rare
+    // double-send only survives a server restart, when the persisted store is
+    // already empty anyway.
+    //
+    // A message's identity is the (ts, text) TUPLE, not the timestamp alone (#628).
+    // The client deliberately KEEPS one enqueue ts when APPENDING to an existing
+    // queue (#245 stable identity), so "same ts, different text" is a genuinely new
+    // message — deduping on the ts alone silently destroyed the appended text.
+    // Timestamps are monotonic per session (a fresh queue stamps `Date.now()`), so
+    // anything strictly OLDER than `ts` is stale by construction and only the texts
+    // flushed AT `ts` need remembering — one bounded set per session.
+    const lastFlushed = new Map();
     // Every currently-connected socket, so a turn's start/stop transition can be
     // broadcast to all clients — powering the per-chat sidebar streaming dots that
     // must update even for chats whose pane isn't mounted (issue #53).
@@ -385,7 +393,7 @@ export function makeChatHandler(deps) {
         // successfully and (b) when a queue is set while the session is idle — a queue
         // that arrived (e.g. via the reconnect outbox) after the turn it was meant to
         // follow already ended. `take` makes the read+clear atomic so the two callers
-        // can never both send it; the `lastFlushedTs` marker skips a message already
+        // can never both send it; the `lastFlushed` marker skips a message already
         // drained (a stale client re-assert on reload) so it isn't sent twice.
         const drainQueue = async (slug, sessionId) => {
             if (!deps.queuedMessage)
@@ -395,7 +403,14 @@ export function makeChatHandler(deps) {
             if (!queued?.text)
                 return;
             const markerKey = `${agent}${KEY_SEP}${sessionId}`;
-            const already = (lastFlushedTs.get(markerKey) ?? 0) >= queued.createdAtMs;
+            const marker = lastFlushed.get(markerKey);
+            // Already drained, on the (ts, text) tuple (#628): either this exact text
+            // went out at this exact ts, or the whole message predates the last one we
+            // flushed — which, timestamps being monotonic, can only be a stale re-assert.
+            // An APPEND reuses the ts with longer text, so it is NOT a duplicate.
+            const already = marker !== undefined &&
+                (queued.createdAtMs < marker.ts ||
+                    (queued.createdAtMs === marker.ts && marker.texts.has(queued.text)));
             // Tell every attached client (origin + reconnected sockets) to clear its copy
             // of this message. When we're really sending it, carry the text so the client
             // renders the sent bubble in-transcript; on a stale re-assert we only clear.
@@ -409,7 +424,12 @@ export function makeChatHandler(deps) {
             });
             if (already)
                 return;
-            lastFlushedTs.set(markerKey, queued.createdAtMs);
+            // Record the tuple. A newer ts supersedes the marker outright (everything at
+            // the old ts is now stale); the same ts adds one more flushed text.
+            if (marker !== undefined && marker.ts === queued.createdAtMs)
+                marker.texts.add(queued.text);
+            else
+                lastFlushed.set(markerKey, { ts: queued.createdAtMs, texts: new Set([queued.text]) });
             // Broadcast the flush frame BEFORE kicking the turn so the user bubble renders
             // above the reply. Run it detached, like a human send. A leading-slash queued
             // message is a slash command (e.g. "/compact"): route it through the command
@@ -865,6 +885,11 @@ export function makeChatHandler(deps) {
             const slug = msg.payload.projectSlug;
             const { command, sessionId } = msg.payload;
             let resolvedSession = sessionId ?? null;
+            // The turn id Stop cancels this command by (#632). Hardcoded `null` until
+            // now, so a `/compact` was permanently un-stoppable: the client's cancel is
+            // guarded by `if (meta.jobId)`, and even the deferred pre-arm cancel (#196)
+            // waited forever for an id that never arrived.
+            let jobId = null;
             const seen = initTurnUsage();
             // Same hub-tracked turn as onChatSend so a slash-command turn also survives
             // a mid-turn socket drop (issue #54). A command always targets an existing
@@ -873,7 +898,7 @@ export function makeChatHandler(deps) {
             const routing = () => ({
                 projectSlug: slug,
                 sessionId: resolvedSession,
-                jobId: null,
+                jobId,
             });
             // #429: sub-agent launches recovered live from the tool_use input (a command
             // like a custom slash-command can still spawn a Task/Agent), keyed by toolUseId.
@@ -923,6 +948,13 @@ export function makeChatHandler(deps) {
                 const { sessionId: finalSession } = await deps.herdctl.runCommand(agentName, {
                     command,
                     resume: resolvedSession,
+                    // Arm Stop the moment the session exists (#632) — the same contract
+                    // onChatSend uses, so the client renders and can fire Stop while the
+                    // command is still working.
+                    onJobCreated: (id) => {
+                        jobId = id;
+                        turn.setJobId(id);
+                    },
                     onMessage: async (m) => {
                         // A slash-command turn can spawn a Task too; its nested steps never
                         // render top-level ({@link isSidechainMessage}).

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paddock/server",
-  "version": "0.59.1",
+  "version": "0.61.0",
   "private": true,
   "type": "module"
 }