@edspencer/paddock 0.65.0 → 0.66.1

package/README.md

@@ -7,7 +7,7 @@ sessions organized by project, in a web UI.
 npx @edspencer/paddock
 ```
 
-Then open <http://127.0.0.1:4000>.
+Then open <http://127.0.0.1:7233>.
 
 Or point it at work you've already done — see [Open your own project](#open-your-own-project).
 
@@ -107,7 +107,7 @@ Without `--here`, Paddock never touches the directory you ran it from.
 ## Options
 
 ```
-  -p, --port <port>       HTTP/WS port (default 4000)
+  -p, --port <port>       HTTP/WS port (default 7233)
       --host <host>       Bind address (default 127.0.0.1)
   -d, --data-dir <path>   Projects + state (default ~/.paddock)
       --here              Open the CURRENT directory as the workspace
@@ -138,7 +138,7 @@ A multi-arch Docker image is published alongside this package, and is the better
 fit for a server deployment:
 
 ```sh
-docker run -d -p 127.0.0.1:4000:4000 -v /srv/paddock-data:/data \
+docker run -d -p 127.0.0.1:7233:7233 -v /srv/paddock-data:/data \
   -e CLAUDE_CODE_OAUTH_TOKEN=… \
   -e PADDOCK_DANGEROUSLY_ALLOW_OPEN=1 \
   ghcr.io/edspencer/paddock:latest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.65.0",
+  "version": "0.66.1",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

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

@@ -16,6 +16,7 @@ import { HerdctlService } from "./herdctl.js";
 import { GitService } from "./git.js";
 import { GithubAuth } from "./github-auth.js";
 import { type Transcriber } from "./transcribe.js";
+import type { SessionHub } from "./session-hub.js";
 import { SweepService } from "./sweep.js";
 import { ArchiveStore } from "./archive.js";
 import { StarStore } from "./star.js";
@@ -49,6 +50,13 @@ export interface BuiltApp {
     events: PaddockEventBus;
     /** Unified trigger registry (Epic T / T1) — the sole trigger CRUD surface. */
     triggers: TriggerService;
+    /**
+     * The WS layer's session hub — every in-flight turn, and the fan-out to the
+     * sockets watching it. Exposed for callers that need to observe or annotate a
+     * turn without holding a socket (the destructive-op interlock reaches it the
+     * same way, via the route context).
+     */
+    hub: SessionHub;
     /** Tear down the fleet + close the server (no process.exit, for tests). */
     close: () => Promise<void>;
 }

package/packages/server/dist/app.js

@@ -399,5 +399,8 @@ export async function buildApp(opts = {}) {
         await herdctl.stop().catch(() => undefined);
         await app.close().catch(() => undefined);
     };
-    return { app, cfg, projects, herdctl, git, githubAuth, sweep, archive, star, readState, unread, parentDetach, runProvenance, queuedMessage, transcriber, events, triggers, close };
+    // `hub` rides along like every other built piece: it is the WS layer's turn
+    // bookkeeping, and the only place a caller can observe or annotate a turn
+    // without a live socket (see SessionHub.noteCancel).
+    return { app, cfg, projects, herdctl, git, githubAuth, sweep, archive, star, readState, unread, parentDetach, runProvenance, queuedMessage, transcriber, events, triggers, hub: chatHandler.managementOpsContext.hub, close };
 }

package/packages/server/dist/cli/args.d.ts

@@ -48,9 +48,9 @@ export declare function nodeVersionProblem(nodeVersion: string): string | undefi
 /**
  * Translate a listen failure into something a human can act on.
  *
- * `EADDRINUSE` on 4000 is the likeliest first-run failure — a popular port and
- * Paddock's own default — and Node's raw error names neither the port nor the
- * flag that fixes it.
+ * `EADDRINUSE` is the likeliest first-run failure — usually a second Paddock, or
+ * a Temporal frontend, which defaults to the same 7233 — and Node's raw error
+ * names neither the port nor the flag that fixes it.
  */
 export declare function explainListenError(err: unknown, host: string, port: string): string;
-export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 4000, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n      --here              Open the CURRENT directory as the workspace (see below)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening a directory (--here)\n  Run `paddock --here` inside a project and Paddock opens THAT directory as its\n  workspace: Claude works in your files, and any Claude Code sessions you already\n  have for the directory are offered for import. It:\n\n    \u00B7 creates .paddock/ in the directory for this workspace's own state\n    \u00B7 creates .chats/ for transcripts, and adds both to .gitignore\n    \u00B7 offers your ~/.claude sessions for this directory for import \u2014 nothing\n      there is moved, copied or linked until you confirm\n\n  Once done, later runs in the same directory resume it \u2014 no flag needed.\n  Without --here, Paddock never touches the directory you ran it from.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml:\n\n    claude:\n      transcripts: host   # own | host, default own\n      credentials: host   # own | host, default host\n      instructions: host  # own | host, default own\n      hooks: host         # own | host, default own\n      mcpServers: host    # own | host, default own\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. Off by default, which is a change: your curated CLAUDE.md does not\n  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always\n  does.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\n  mcpServers: host attaches the MCP servers declared in your ~/.claude.json \u2014\n  the top-level ones, plus a project's own when its directory matches. To give\n  this instance a server your machine doesn't have, declare it instead in a\n  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a\n  string goes so tokens stay out of it. That keeps a token out of the file, not\n  out of `ps`: leave driveMode on its default (session) for a server holding\n  one, since batch passes the definition to claude as a command-line argument.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";
+export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 7233, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n      --here              Open the CURRENT directory as the workspace (see below)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening a directory (--here)\n  Run `paddock --here` inside a project and Paddock opens THAT directory as its\n  workspace: Claude works in your files, and any Claude Code sessions you already\n  have for the directory are offered for import. It:\n\n    \u00B7 creates .paddock/ in the directory for this workspace's own state\n    \u00B7 creates .chats/ for transcripts, and adds both to .gitignore\n    \u00B7 offers your ~/.claude sessions for this directory for import \u2014 nothing\n      there is moved, copied or linked until you confirm\n\n  Once done, later runs in the same directory resume it \u2014 no flag needed.\n  Without --here, Paddock never touches the directory you ran it from.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml:\n\n    claude:\n      transcripts: host   # own | host, default own\n      credentials: host   # own | host, default host\n      instructions: host  # own | host, default own\n      hooks: host         # own | host, default own\n      mcpServers: host    # own | host, default own\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. Off by default, which is a change: your curated CLAUDE.md does not\n  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always\n  does.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\n  mcpServers: host attaches the MCP servers declared in your ~/.claude.json \u2014\n  the top-level ones, plus a project's own when its directory matches. To give\n  this instance a server your machine doesn't have, declare it instead in a\n  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a\n  string goes so tokens stay out of it. That keeps a token out of the file, not\n  out of `ps`: leave driveMode on its default (session) for a server holding\n  one, since batch passes the definition to claude as a command-line argument.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";

package/packages/server/dist/cli/args.js

@@ -95,9 +95,9 @@ export function nodeVersionProblem(nodeVersion) {
 /**
  * Translate a listen failure into something a human can act on.
  *
- * `EADDRINUSE` on 4000 is the likeliest first-run failure — a popular port and
- * Paddock's own default — and Node's raw error names neither the port nor the
- * flag that fixes it.
+ * `EADDRINUSE` is the likeliest first-run failure — usually a second Paddock, or
+ * a Temporal frontend, which defaults to the same 7233 — and Node's raw error
+ * names neither the port nor the flag that fixes it.
  */
 export function explainListenError(err, host, port) {
     const code = err?.code;
@@ -108,7 +108,7 @@ export function explainListenError(err, host, port) {
     }
     if (code === "EACCES") {
         return (`not allowed to bind ${host}:${port}.\n` +
-            `Ports below 1024 need elevated privileges — use a higher one:  paddock --port 4000`);
+            `Ports below 1024 need elevated privileges — use a higher one:  paddock --port 7233`);
     }
     return String(err?.message ?? err);
 }
@@ -118,7 +118,7 @@ Usage
   npx @edspencer/paddock [options]
 
 Options
-  -p, --port <port>       HTTP/WS port (default 4000, or $PORT)
+  -p, --port <port>       HTTP/WS port (default 7233, or $PORT)
       --host <host>       Bind address (default 127.0.0.1)
   -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)
       --here              Open the CURRENT directory as the workspace (see below)

package/packages/server/dist/cli/paddock.js

@@ -276,7 +276,7 @@ async function main() {
     // the login `CLAUDE_CONFIG_DIR` scoping hides (#683). It logs at `warn`, which
     // survives the quiet default set just above. Continuity (chosen above) usually
     // means it has nothing to say, because there is nothing left to bridge.
-    const port = process.env.PORT ?? "4000";
+    const port = process.env.PORT ?? "7233";
     const host = process.env.HOST ?? "127.0.0.1";
     // Imported dynamically, AFTER the env above is set: a static import would
     // pull in app.ts -> config.ts and resolve config against the wrong data dir.

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

@@ -475,6 +475,13 @@ export interface PaddockConfig {
  * top-level record sections here.
  */
 export interface PaddockConfigFile {
+    /**
+     * Which version of THIS format the file is written in (#724). Absent reads as
+     * `1` — the shape every pre-adoption file already has — and a version newer
+     * than `CONFIG_SCHEMA_VERSION` refuses the boot rather than being
+     * lenient-parsed. See `schema-version.ts` for when to bump it.
+     */
+    schemaVersion?: number | string;
     port?: number | string;
     host?: string;
     dataDir?: string;

package/packages/server/dist/config.js

@@ -23,6 +23,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 import { DEFAULT_DRIVE_MODE, isKnownDriveMode, isKnownModel, } from "./models.js";
+import { SCHEMA_VERSION_KEY, configSchemaRefusal } from "./schema-version.js";
 import { DEFAULT_MAX_SPAWN_DEPTH, isValidMaxSpawnDepth } from "./spawn-capability.js";
 import { DEFAULT_TRANSCRIPTS_MODE, isKnownTranscriptsMode, } from "./transcripts.js";
 import { DEFAULT_CREDENTIALS_MODE, isKnownCredentialsMode, } from "./claude-credentials.js";
@@ -154,6 +155,13 @@ export function loadConfigFile(dataDir) {
     // an object (which would crash with an unclear TypeError). Deeper `null`s and
     // wrong-typed sections already degrade to defaults via fileOr/fileOpt.
     const obj = parsed;
+    // The downgrade guard (#724), BEFORE any lenient interpretation below. A file
+    // from the future must never be half-read: every unknown key here is dropped,
+    // and `writeInstanceConfig` would then persist the loss. Fail closed, exactly
+    // as `resolveClaudeHome` does.
+    const refusal = configSchemaRefusal(obj[SCHEMA_VERSION_KEY], configPath);
+    if (refusal !== undefined)
+        throw new Error(refusal);
     for (const key of Object.keys(obj)) {
         if (obj[key] === null)
             delete obj[key];
@@ -276,7 +284,7 @@ export function loadPaddockConfig() {
     const legacyClaudeHome = userClaudeHome();
     const defaultWebDist = resolveDefaultWebDist(import.meta.url);
     return Object.freeze({
-        port: Number(envOr("PORT", fileOr(file.port, "4000"))),
+        port: Number(envOr("PORT", fileOr(file.port, "7233"))),
         // Safe by default (#435): bind loopback unless explicitly told otherwise, so
         // a fresh source/tarball run is network-closed. Non-loopback + no auth is then
         // gated by the bind-safety guard (see bind-safety.ts). Existing deployments

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

@@ -119,6 +119,31 @@ export interface ChatTurnOptions {
  */
 export { keeperAgentName, keeperSlugFromAgent, SWEEPER_PREFIX, sweeperAgentName, HOOK_AGENT_PREFIX, hookAgentName, TRIGGER_AGENT_PREFIX, triggerAgentName, visibleProjectAgentNames, BROWSER_MCP_TOOL, DENIED_TOOLS, browserMcpServers, KEEPER_MAX_CONCURRENT, KEEPER_SESSION_TIMEOUT, } from "./herdctl-agent-names.js";
 export declare function sliceTranscriptAtUuid(raw: string, cutUuid: string, endOnCompletedAssistant?: boolean): string | null;
+/**
+ * Trim a transcript back to the last point at which every `tool_use` has its
+ * `tool_result` (issue #731).
+ *
+ * FORK is the caller. Unlike delete/promote/revert, forking mid-turn is not an
+ * accident to be interlocked away — it is a designed, load-bearing feature: the
+ * `fork_chat` fan-out (#214) is invoked BY a keeper from inside its own running
+ * turn, and `forkKickoffPrompt` even apologises to the child for the truncated
+ * final exchange. Refusing a fork while the source is running would break that
+ * contract outright.
+ *
+ * What we can fix is the artifact. A snapshot taken mid-tool-call ends on an
+ * assistant `tool_use` whose `tool_result` had not been written yet, and the
+ * real Anthropic Messages API REJECTS that shape on resume ("tool_use ids were
+ * found without tool_result blocks"), so the fork is born unresumable. Cutting
+ * the copy back to the last balanced boundary costs the child an exchange it was
+ * told to ignore anyway, and buys a transcript that loads.
+ *
+ * The source transcript is never touched — this only ever shapes the COPY.
+ *
+ * Returns `raw` byte-identical when nothing is unpaired (the overwhelmingly
+ * common idle-fork case), and also when trimming would leave nothing at all — an
+ * empty chat is a worse outcome than a suspect one.
+ */
+export declare function trimToPairedToolBoundary(raw: string): string;
 export declare class HerdctlService {
     private readonly cfg;
     private readonly mcpSources;
@@ -490,6 +515,58 @@ export declare class HerdctlService {
      * — so `retained` is how a caller tells "gone" from "no longer shown here".
      */
     deleteSession(agentName: string, sessionId: string): Promise<ChatDeletion>;
+    /**
+     * Drop the agent-level session pointer when it names a transcript we just
+     * removed. Issue #730 — silent data loss, and the fix is one `rm` of a file
+     * that is already dangling by the time we get here.
+     *
+     * herdctl keeps ONE "this agent's current session" pointer per agent at
+     * `<stateDir>/sessions/<agent>.json`, rewritten after every batch turn — so it
+     * always names whichever chat ran most recently. It exists for exactly one
+     * purpose: resume that session when a caller asks for a turn WITHOUT naming a
+     * session. Paddock's chat sends always name one, so we never read it.
+     *
+     * It still reaches us, via how the JobExecutor reacts to it going stale.
+     * Deleting the most-recently-active chat leaves the pointer naming a transcript
+     * that is no longer on disk. On the NEXT turn — any chat, `resume: A`
+     * explicitly — the executor's timeout-aware read of the pointer judges it
+     * `file_not_found`, clears it, and reports "no session". The branch that
+     * handles that case then refuses to honor the caller's `resume`, because a
+     * pointer HAD existed a moment ago and the executor reads that as "this agent's
+     * session just expired, so start fresh" (herdctl's `hadAgentSession` gate,
+     * job-executor.js). It is the wrong reading: the pointer named B, the caller
+     * asked for A, and A's transcript is right there. The turn starts a brand-new
+     * session, the UI keeps showing A, and the user's message lands somewhere they
+     * will only find by reloading.
+     *
+     * That misreading is an upstream bug and the real fix belongs there — the gate
+     * should compare the cleared pointer's id against the caller's `resume` rather
+     * than treating any prior pointer as disqualifying (filed as
+     * edspencer/herdctl#448).
+     * What we do here is narrower and true regardless: a pointer to a transcript
+     * Paddock has just deleted is dangling, and herdctl would clear it at the next
+     * turn anyway — we clear it now, at the moment we make it dangle, so the next
+     * turn sees a clean "this agent owns no session" and adopts the caller's
+     * explicit `resume` (which is the same path a process restart takes, and why
+     * this always "worked after a restart").
+     *
+     * Only clears a pointer that names THIS session: another chat's pointer is
+     * live state and none of our business. Best-effort throughout — failing to
+     * tidy state must never fail the delete the user asked for.
+     *
+     * Called from every place Paddock removes a transcript from an agent's working
+     * directory: the `own` delete path, {@link promoteSession} (which moves the
+     * file out from under the source keeper by the same call), and the two
+     * import-undo paths that delete a copy an import placed. `archive` leaves the
+     * file alone, so it never dangles the pointer — which matches the reproduction
+     * exactly: archive is fine, delete and promote are not. Under
+     * `claude.transcripts: host` nothing is removed, so there is nothing to drop.
+     *
+     * The SDK session path (`driveMode: session`, the default) never reads the
+     * pointer for an explicit resume, so it is structurally immune; this is a
+     * `driveMode: batch` fix.
+     */
+    private dropAgentSessionPointer;
     /**
      * Set (or clear) a chat's custom display name. Writes through the fleet's
      * shared SessionMetadataStore so a subsequent getAgentSessions reflects it
@@ -622,6 +699,18 @@ export declare class HerdctlService {
      * failure, so a broken Stop looked like a no-op).
      */
     cancel(jobId: string): Promise<boolean>;
+    /**
+     * End a managed chat SESSION outright, by session id (issue #731). Where
+     * {@link cancel} ends the model turn — and on the session runtime deliberately
+     * leaves the session (and its `claude` subprocess) open for the next message —
+     * this closes the session itself, so nothing is left holding the transcript
+     * path open ahead of a destructive operation.
+     *
+     * Best-effort and null-safe: `false` when there was no live managed session to
+     * reap (the batch runtime never has one), or when the fleet isn't up. Callers
+     * decide liveness from {@link isSdkSessionLive}, not from this return value.
+     */
+    reapSession(sessionId: string): boolean;
     /**
      * Run a project's sweeper (curator) agent with a fresh session and the given
      * prompt. Used OUT OF BAND by SweepService — never from the user-chat path —

package/packages/server/dist/herdctl.js

@@ -46,7 +46,7 @@
  * That last nuance is now closed too: core exposes `fleet.invalidateSessions(name)`
  * and paddock calls it after each turn (`ws-turn.ts`) and around fork/promote.
  */
-import { FleetManager, countPendingAsyncQueueEntries, getCliSessionFile, } from "@herdctl/core";
+import { FleetManager, clearSession, countPendingAsyncQueueEntries, getCliSessionFile, getSessionInfo, } from "@herdctl/core";
 import { consumeResumedTurn, consumeBackgroundTurns } from "./resume-drain.js";
 import { createSDKMessageHandler } from "@herdctl/chat";
 import { promises as fs } from "node:fs";
@@ -162,6 +162,71 @@ export function sliceTranscriptAtUuid(raw, cutUuid, endOnCompletedAssistant = fa
     }
     return lines.slice(0, end + 1).join("\n") + "\n";
 }
+/**
+ * Trim a transcript back to the last point at which every `tool_use` has its
+ * `tool_result` (issue #731).
+ *
+ * FORK is the caller. Unlike delete/promote/revert, forking mid-turn is not an
+ * accident to be interlocked away — it is a designed, load-bearing feature: the
+ * `fork_chat` fan-out (#214) is invoked BY a keeper from inside its own running
+ * turn, and `forkKickoffPrompt` even apologises to the child for the truncated
+ * final exchange. Refusing a fork while the source is running would break that
+ * contract outright.
+ *
+ * What we can fix is the artifact. A snapshot taken mid-tool-call ends on an
+ * assistant `tool_use` whose `tool_result` had not been written yet, and the
+ * real Anthropic Messages API REJECTS that shape on resume ("tool_use ids were
+ * found without tool_result blocks"), so the fork is born unresumable. Cutting
+ * the copy back to the last balanced boundary costs the child an exchange it was
+ * told to ignore anyway, and buys a transcript that loads.
+ *
+ * The source transcript is never touched — this only ever shapes the COPY.
+ *
+ * Returns `raw` byte-identical when nothing is unpaired (the overwhelmingly
+ * common idle-fork case), and also when trimming would leave nothing at all — an
+ * empty chat is a worse outcome than a suspect one.
+ */
+export function trimToPairedToolBoundary(raw) {
+    const lines = raw.split("\n");
+    const open = new Set();
+    /** Last index after which no tool_use is awaiting its result. */
+    let lastBalanced = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const t = lines[i].trim();
+        if (!t)
+            continue;
+        let o;
+        try {
+            o = JSON.parse(t);
+        }
+        catch {
+            // An unparseable line can't be reasoned about; treat it as opaque filler
+            // and let the surrounding balance decide.
+            if (open.size === 0)
+                lastBalanced = i;
+            continue;
+        }
+        const content = o.message?.content;
+        if (Array.isArray(content)) {
+            for (const block of content) {
+                const b = block;
+                if (b?.type === "tool_use" && typeof b.id === "string")
+                    open.add(b.id);
+                else if (b?.type === "tool_result" && typeof b.tool_use_id === "string") {
+                    open.delete(b.tool_use_id);
+                }
+            }
+        }
+        if (open.size === 0)
+            lastBalanced = i;
+    }
+    // Ends balanced (the idle-fork case) — hand back the exact bytes.
+    if (open.size === 0)
+        return raw;
+    if (lastBalanced < 0)
+        return raw;
+    return lines.slice(0, lastBalanced + 1).join("\n") + "\n";
+}
 export class HerdctlService {
     cfg;
     mcpSources;
@@ -736,6 +801,10 @@ export class HerdctlService {
             if (copies.has(sessionId)) {
                 const placed = getCliSessionFile(project.workingDir, sessionId, this.cfg.claudeHome);
                 await fs.rm(placed, { force: true }).catch(() => undefined);
+                // Same removal, same hazard as a chat delete: a pointer left naming a
+                // transcript we just removed breaks the NEXT resume of a DIFFERENT chat
+                // in this project. See dropAgentSessionPointer (#730).
+                await this.dropAgentSessionPointer(agent, sessionId);
             }
             released.push(sessionId);
         }
@@ -767,6 +836,7 @@ export class HerdctlService {
         if (path.resolve(placed) === path.resolve(origin))
             return;
         await fs.rm(placed, { force: true }).catch(() => undefined);
+        await this.dropAgentSessionPointer(agent, sessionId); // #730, as in undoImport
     }
     /**
      * Unregister a project's keeper + sweeper (+ any event-hook) agents at runtime.
@@ -825,12 +895,79 @@ export class HerdctlService {
      */
     async deleteSession(agentName, sessionId) {
         if (this.cfg.claude.transcripts === "own") {
-            return { removed: await this.manager.deleteSession(agentName, sessionId), retained: false };
+            const removed = await this.manager.deleteSession(agentName, sessionId);
+            await this.dropAgentSessionPointer(agentName, sessionId);
+            return { removed, retained: false };
         }
         await this.manager.unadoptSession(agentName, sessionId).catch(() => undefined);
         this.invalidateSessions(agentName);
         return { removed: false, retained: true };
     }
+    /**
+     * Drop the agent-level session pointer when it names a transcript we just
+     * removed. Issue #730 — silent data loss, and the fix is one `rm` of a file
+     * that is already dangling by the time we get here.
+     *
+     * herdctl keeps ONE "this agent's current session" pointer per agent at
+     * `<stateDir>/sessions/<agent>.json`, rewritten after every batch turn — so it
+     * always names whichever chat ran most recently. It exists for exactly one
+     * purpose: resume that session when a caller asks for a turn WITHOUT naming a
+     * session. Paddock's chat sends always name one, so we never read it.
+     *
+     * It still reaches us, via how the JobExecutor reacts to it going stale.
+     * Deleting the most-recently-active chat leaves the pointer naming a transcript
+     * that is no longer on disk. On the NEXT turn — any chat, `resume: A`
+     * explicitly — the executor's timeout-aware read of the pointer judges it
+     * `file_not_found`, clears it, and reports "no session". The branch that
+     * handles that case then refuses to honor the caller's `resume`, because a
+     * pointer HAD existed a moment ago and the executor reads that as "this agent's
+     * session just expired, so start fresh" (herdctl's `hadAgentSession` gate,
+     * job-executor.js). It is the wrong reading: the pointer named B, the caller
+     * asked for A, and A's transcript is right there. The turn starts a brand-new
+     * session, the UI keeps showing A, and the user's message lands somewhere they
+     * will only find by reloading.
+     *
+     * That misreading is an upstream bug and the real fix belongs there — the gate
+     * should compare the cleared pointer's id against the caller's `resume` rather
+     * than treating any prior pointer as disqualifying (filed as
+     * edspencer/herdctl#448).
+     * What we do here is narrower and true regardless: a pointer to a transcript
+     * Paddock has just deleted is dangling, and herdctl would clear it at the next
+     * turn anyway — we clear it now, at the moment we make it dangle, so the next
+     * turn sees a clean "this agent owns no session" and adopts the caller's
+     * explicit `resume` (which is the same path a process restart takes, and why
+     * this always "worked after a restart").
+     *
+     * Only clears a pointer that names THIS session: another chat's pointer is
+     * live state and none of our business. Best-effort throughout — failing to
+     * tidy state must never fail the delete the user asked for.
+     *
+     * Called from every place Paddock removes a transcript from an agent's working
+     * directory: the `own` delete path, {@link promoteSession} (which moves the
+     * file out from under the source keeper by the same call), and the two
+     * import-undo paths that delete a copy an import placed. `archive` leaves the
+     * file alone, so it never dangles the pointer — which matches the reproduction
+     * exactly: archive is fine, delete and promote are not. Under
+     * `claude.transcripts: host` nothing is removed, so there is nothing to drop.
+     *
+     * The SDK session path (`driveMode: session`, the default) never reads the
+     * pointer for an explicit resume, so it is structurally immune; this is a
+     * `driveMode: batch` fix.
+     */
+    async dropAgentSessionPointer(agentName, sessionId) {
+        try {
+            const sessionsDir = path.join(this.cfg.stateDir, "sessions");
+            // Read WITHOUT a timeout: the timeout-aware read is the one that clears,
+            // and we want to decide for ourselves, on the id alone.
+            const pointer = await getSessionInfo(sessionsDir, agentName);
+            if (pointer?.session_id !== sessionId)
+                return;
+            await clearSession(sessionsDir, agentName);
+        }
+        catch {
+            // Best-effort: the delete has already happened and stands.
+        }
+    }
     /**
      * Set (or clear) a chat's custom display name. Writes through the fleet's
      * shared SessionMetadataStore so a subsequent getAgentSessions reflects it
@@ -1173,6 +1310,25 @@ export class HerdctlService {
             return false;
         }
     }
+    /**
+     * End a managed chat SESSION outright, by session id (issue #731). Where
+     * {@link cancel} ends the model turn — and on the session runtime deliberately
+     * leaves the session (and its `claude` subprocess) open for the next message —
+     * this closes the session itself, so nothing is left holding the transcript
+     * path open ahead of a destructive operation.
+     *
+     * Best-effort and null-safe: `false` when there was no live managed session to
+     * reap (the batch runtime never has one), or when the fleet isn't up. Callers
+     * decide liveness from {@link isSdkSessionLive}, not from this return value.
+     */
+    reapSession(sessionId) {
+        try {
+            return this.fleet?.reapChatSession(sessionId) ?? false;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Run a project's sweeper (curator) agent with a fresh session and the given
      * prompt. Used OUT OF BAND by SweepService — never from the user-chat path —
@@ -1321,6 +1477,10 @@ export class HerdctlService {
         const fromAgent = keeperAgentName(from.slug);
         await this.manager.deleteSession(fromAgent, sessionId).catch(() => undefined);
         await fs.rm(fromFile, { force: true });
+        // The source keeper's agent-level session pointer may name the chat we just
+        // moved out from under it. Left dangling it breaks the NEXT resume of any
+        // OTHER chat in the source project — see dropAgentSessionPointer (#730).
+        await this.dropAgentSessionPointer(fromAgent, sessionId);
         // Re-attribute the session to the new keeper, then drop the discovery +
         // attribution caches so the move shows immediately.
         await jobs.reattributeSession(this.cfg.stateDir, sessionId, to, st ? st.mtime : new Date());
@@ -1378,6 +1538,13 @@ export class HerdctlService {
             }
             raw = sliced;
         }
+        // #731: the source may be MID-TURN — always is, for the agent-initiated
+        // `fork_chat` fan-out — so the snapshot can end on a `tool_use` whose
+        // `tool_result` hasn't been written yet. Copying that shape gives the child
+        // a transcript the Messages API rejects on resume, i.e. a fork that exists
+        // but cannot be talked to. Cut the COPY back to the last balanced boundary;
+        // the source is untouched either way.
+        raw = trimToPairedToolBoundary(raw);
         const newId = randomUUID();
         // Rewrite the embedded session id on every line. Same compact-JSON
         // assumption `promoteSession` makes for `cwd` (`"sessionId":"<id>"` /

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

@@ -36,6 +36,7 @@ import { DEFAULT_RECOVERY } from "./recovery-config.js";
 import { DEFAULT_ATTACHMENTS, sanitizeAllowedTypes } from "./attachments-config.js";
 import { DEFAULT_CURATION } from "./curation-config.js";
 import { DEFAULT_ENVIRONMENT_PROMPT } from "./environment-prompt.js";
+import { CONFIG_SCHEMA_VERSION, SCHEMA_VERSION_KEY } from "./schema-version.js";
 import { DEFAULT_TRANSCRIPTS_MODE } from "./transcripts.js";
 import { DEFAULT_CREDENTIALS_MODE } from "./claude-credentials.js";
 import { DEFAULT_INSTRUCTIONS_MODE } from "./claude-instructions.js";
@@ -217,7 +218,7 @@ export const FIELDS = [
     // Logging.
     { key: "logLevel", group: "logging", label: "Log level", type: "enum", enumValues: LOG_LEVELS, envVars: ["LOG_LEVEL"], default: "info", editable: true, coerce: oneOf(LOG_LEVELS) },
     // Advanced — read-only display (process / filesystem bindings).
-    { key: "port", group: "advanced", label: "Port", type: "number", envVars: ["PORT"], default: 4000, editable: false },
+    { key: "port", group: "advanced", label: "Port", type: "number", envVars: ["PORT"], default: 7233, editable: false },
     { key: "host", group: "advanced", label: "Host", type: "string", envVars: ["HOST", "PADDOCK_HOST"], default: "127.0.0.1", editable: false },
     { key: "dataDir", group: "advanced", label: "Data dir", type: "string", envVars: ["PADDOCK_DATA_DIR"], default: null, editable: false },
     { key: "projectsRoot", group: "advanced", label: "Projects root", type: "string", envVars: ["PADDOCK_PROJECTS_DIR"], default: null, editable: false },
@@ -411,6 +412,16 @@ export function writeInstanceConfig(configPath, pairs) {
         else
             doc.setIn(p, value);
     }
+    // Stamp the schema version on a file that does not declare one yet (#724) —
+    // which includes every file written before adoption and every fresh one this
+    // branch creates. Written only when ABSENT, unlike `project.yaml`: this is a
+    // partial patch over a document whose other keys are round-tripped untouched,
+    // so it is not in a position to assert what version the WHOLE file is. A file
+    // that already declares one has been through `loadConfigFile`'s guard, so it
+    // is at or below this build's version and re-stamping would say nothing new.
+    if (doc.getIn([SCHEMA_VERSION_KEY]) === undefined) {
+        doc.setIn([SCHEMA_VERSION_KEY], CONFIG_SCHEMA_VERSION);
+    }
     const serialized = doc.toString();
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     // Atomic write: same-dir temp file + rename, so a reader never sees a

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

@@ -23,6 +23,8 @@ export declare class ProjectStore {
     constructor(root: string, dataDir?: string | undefined, log?: {
         warn: (message: string) => void;
     });
+    /** `${file} ${declaredVersion}` pairs already warned about — see {@link warnOnceAboutSchema}. */
+    private readonly schemaWarned;
     /** Ensure the projects root exists. Call once at startup. */
     init(): Promise<void>;
     /**
@@ -355,6 +357,15 @@ export declare class ProjectStore {
      */
     private ensureSidecarGitignore;
     private writeYaml;
+    /**
+     * Say out loud that a project was skipped for being from the future (#724),
+     * once per (file, declared version).
+     *
+     * `list()` runs on every `GET /api/projects`, so an unconditional warn would
+     * bury the log. Keyed on the declared version as well as the path so a
+     * hand-edit — or the same instance being downgraded further — speaks up again.
+     */
+    private warnOnceAboutSchema;
     private toDto;
     /**
      * Drop the derived DTO-only fields, leaving the on-disk shape.