@edspencer/paddock 0.66.0 → 0.66.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.66.0",
+  "version": "0.66.2",
   "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/herdctl-jobs.d.ts

@@ -72,6 +72,26 @@ export declare function listProjectRuns(stateDir: string, project: Project, limi
  * view degrades to config-only rather than failing to render.
  */
 export declare function listRunsForAgents(stateDir: string, agents: string[], limit?: number): Promise<JobMetadata[]>;
+/**
+ * Drop the job records of one or more CHATS (#732) — called when Paddock removes
+ * a chat from a project, so the record cannot outlive the transcript and keep
+ * the sidebar badge counting a chat that is no longer there to open.
+ */
+export declare function purgeSessionJobs(stateDir: string, sessionIds: string[]): Promise<number>;
+/**
+ * Drop the job records of one or more AGENTS (#734) — called when a project is
+ * deleted, for every agent name that project owned (keeper, sweeper, hooks,
+ * triggers). Agent-keyed rather than project-keyed because the agent name is
+ * what the record actually carries.
+ *
+ * This is the containment half of the fix rather than the structural one: the
+ * durable answer to "a re-created project inherits the old one's records" is to
+ * key them by a stable project id instead of the user-controlled, reusable slug.
+ * That is a herdctl-side identity change (records are herdctl's format, written
+ * by its runtimes); purging on delete makes the leak impossible NOW without
+ * waiting for it, and stays correct afterwards.
+ */
+export declare function purgeAgentJobs(stateDir: string, agents: string[]): Promise<number>;
 /**
  * Point every herdctl job record for `sessionId` at the project's keeper so
  * the core attribution index (last-write-wins per session) lists the session

package/packages/server/dist/herdctl-jobs.js

@@ -138,6 +138,100 @@ export async function listRunsForAgents(stateDir, agents, limit = 200) {
     const filtered = jobs.filter((j) => wanted.has(j.agent));
     return limit > 0 ? filtered.slice(0, limit) : filtered;
 }
+/**
+ * Delete every job record matching `match`, plus each one's sibling `.jsonl`
+ * output file. Returns how many records were removed.
+ *
+ * The shared inverse of the writes above (#732 / #734). The jobs directory is
+ * append-only and fleet-wide, and until now NOTHING ever removed a record — so a
+ * record outlived whatever it described. Two user-visible consequences, one
+ * mechanism:
+ *
+ *  - A deleted CHAT kept feeding {@link lastTurnCompletedAtByProject}, i.e. the
+ *    sidebar unread badge, with no chat left to open to clear it (#732).
+ *  - A deleted PROJECT left its keeper's whole history behind, keyed by the
+ *    agent name — which is derived from the slug, which is derived from the
+ *    NAME. Re-creating a project called the same thing therefore inherited the
+ *    previous incarnation's `/runs`, prompt text and reply summaries included
+ *    (#734).
+ *
+ * Records are matched by reading them, not by parsing filenames: a job id
+ * encodes only a date and six characters of the session id, which is neither an
+ * agent nor a reliable session key.
+ *
+ * Best-effort per file, deliberately: a record we cannot read is a record we
+ * cannot prove is ours, so it is left alone rather than removed on a guess, and
+ * an unlink failure never fails the delete the user actually asked for. The
+ * caller invalidates {@link JobsDirIndex} afterwards — the index also drops
+ * vanished files on its own next scan, so this is belt-and-braces.
+ */
+async function purgeJobs(stateDir, match) {
+    const jobsDir = jobsDirOf(stateDir);
+    let entries = [];
+    try {
+        entries = await fs.readdir(jobsDir);
+    }
+    catch {
+        return 0; // no jobs dir yet — nothing to purge
+    }
+    let removed = 0;
+    for (const name of entries) {
+        if (!name.endsWith(".yaml"))
+            continue;
+        const file = path.join(jobsDir, name);
+        let parsed = null;
+        try {
+            parsed = YAML.parse(await fs.readFile(file, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || !match(parsed))
+            continue;
+        await fs.rm(file, { force: true }).catch(() => undefined);
+        // The record names its own output file; fall back to the `<id>.jsonl`
+        // convention {@link writeAgentAdoptionJob} writes when it does not.
+        const output = typeof parsed.output_file === "string" && parsed.output_file.length > 0
+            ? parsed.output_file
+            : path.join(jobsDir, `${name.slice(0, -".yaml".length)}.jsonl`);
+        // Only ever unlink an output file that lives in the jobs dir we just read.
+        if (path.dirname(path.resolve(output)) === path.resolve(jobsDir)) {
+            await fs.rm(output, { force: true }).catch(() => undefined);
+        }
+        removed++;
+    }
+    return removed;
+}
+/**
+ * Drop the job records of one or more CHATS (#732) — called when Paddock removes
+ * a chat from a project, so the record cannot outlive the transcript and keep
+ * the sidebar badge counting a chat that is no longer there to open.
+ */
+export async function purgeSessionJobs(stateDir, sessionIds) {
+    if (sessionIds.length === 0)
+        return 0;
+    const wanted = new Set(sessionIds);
+    return purgeJobs(stateDir, (r) => typeof r.session_id === "string" && wanted.has(r.session_id));
+}
+/**
+ * Drop the job records of one or more AGENTS (#734) — called when a project is
+ * deleted, for every agent name that project owned (keeper, sweeper, hooks,
+ * triggers). Agent-keyed rather than project-keyed because the agent name is
+ * what the record actually carries.
+ *
+ * This is the containment half of the fix rather than the structural one: the
+ * durable answer to "a re-created project inherits the old one's records" is to
+ * key them by a stable project id instead of the user-controlled, reusable slug.
+ * That is a herdctl-side identity change (records are herdctl's format, written
+ * by its runtimes); purging on delete makes the leak impossible NOW without
+ * waiting for it, and stays correct afterwards.
+ */
+export async function purgeAgentJobs(stateDir, agents) {
+    if (agents.length === 0)
+        return 0;
+    const wanted = new Set(agents);
+    return purgeJobs(stateDir, (r) => typeof r.agent === "string" && wanted.has(r.agent));
+}
 /**
  * Point every herdctl job record for `sessionId` at the project's keeper so
  * the core attribution index (last-write-wins per session) lists the session

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

@@ -515,6 +515,52 @@ 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 herdctl job records for chats that have left this instance (#732),
+     * so a record cannot outlive its transcript and keep the sidebar unread badge
+     * counting a chat there is no longer anything to open.
+     *
+     * Takes a LIST rather than one id, and is called by the delete routes rather
+     * than from inside {@link deleteSession}, for one reason: purging is a scan of
+     * the whole shared jobs directory, and the batch route deletes up to 500 chats
+     * in a loop. Per-chat purging would re-scan a 2,000-record directory 500 times
+     * (see `herdctl-jobs-index.ts` for what that costs). One pass, all ids.
+     *
+     * Callers pass only the chats whose transcript was actually REMOVED. Under
+     * `claude.transcripts: host` a delete RELEASES instead — the chat is still
+     * listed there, a known deferred gap (#693, asserted by
+     * `delete-chat-host-transcripts.test.ts`), and purging would close it as a
+     * side effect, because the job record is part of what re-attributes a
+     * structurally-discovered session to the keeper. Resolving somebody else's
+     * deferred decision by accident is not this change's business, and keeping the
+     * record for a chat that is still in the list is coherent anyway:
+     * `buildChatTurns` prunes against the live chat list, so the badge follows the
+     * list either way — and will stop counting the chat the moment #693 makes it
+     * leave.
+     *
+     * Best-effort: tidying state must never fail the delete the user asked for.
+     */
+    purgeSessionJobs(sessionIds: string[]): Promise<void>;
+    /**
+     * Drop the herdctl job records of every agent a project owned (#734) — the
+     * records half of a project delete.
+     *
+     * Job records are keyed by AGENT NAME, and an agent name is derived from the
+     * slug, which is derived from the project NAME. So without this, deleting
+     * "Foo" and creating a new "Foo" hands the new project the old one's run
+     * history: prompts, reply summaries, and a phantom `chatTurns` entry that
+     * shows an unread badge on a project with zero chats. Files, `.chats/` and
+     * `read-state.json` were already cleaned; these were the one thing left.
+     *
+     * Takes the same hook/trigger name lists {@link removeProjectAgent} does, so
+     * the two together are the full inverse of the create flow — and so they stay
+     * in step: if a delete ever has to sweep DESCENDANT workspaces (nesting), both
+     * need the same widening, not just one. Matching is on the exact agent name,
+     * so deleting `foo` cannot touch a sibling `foo-bar`.
+     *
+     * Best-effort — the project directory is already gone by the time we get here.
+     */
+    purgeProjectJobs(slug: string, hookNames?: string[], triggerNames?: string[]): Promise<void>;
     /**
      * 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

package/packages/server/dist/herdctl.js

@@ -903,6 +903,64 @@ export class HerdctlService {
         this.invalidateSessions(agentName);
         return { removed: false, retained: true };
     }
+    /**
+     * Drop the herdctl job records for chats that have left this instance (#732),
+     * so a record cannot outlive its transcript and keep the sidebar unread badge
+     * counting a chat there is no longer anything to open.
+     *
+     * Takes a LIST rather than one id, and is called by the delete routes rather
+     * than from inside {@link deleteSession}, for one reason: purging is a scan of
+     * the whole shared jobs directory, and the batch route deletes up to 500 chats
+     * in a loop. Per-chat purging would re-scan a 2,000-record directory 500 times
+     * (see `herdctl-jobs-index.ts` for what that costs). One pass, all ids.
+     *
+     * Callers pass only the chats whose transcript was actually REMOVED. Under
+     * `claude.transcripts: host` a delete RELEASES instead — the chat is still
+     * listed there, a known deferred gap (#693, asserted by
+     * `delete-chat-host-transcripts.test.ts`), and purging would close it as a
+     * side effect, because the job record is part of what re-attributes a
+     * structurally-discovered session to the keeper. Resolving somebody else's
+     * deferred decision by accident is not this change's business, and keeping the
+     * record for a chat that is still in the list is coherent anyway:
+     * `buildChatTurns` prunes against the live chat list, so the badge follows the
+     * list either way — and will stop counting the chat the moment #693 makes it
+     * leave.
+     *
+     * Best-effort: tidying state must never fail the delete the user asked for.
+     */
+    async purgeSessionJobs(sessionIds) {
+        await jobs.purgeSessionJobs(this.cfg.stateDir, sessionIds).catch(() => 0);
+        this.jobsIndexOrNull?.invalidate();
+    }
+    /**
+     * Drop the herdctl job records of every agent a project owned (#734) — the
+     * records half of a project delete.
+     *
+     * Job records are keyed by AGENT NAME, and an agent name is derived from the
+     * slug, which is derived from the project NAME. So without this, deleting
+     * "Foo" and creating a new "Foo" hands the new project the old one's run
+     * history: prompts, reply summaries, and a phantom `chatTurns` entry that
+     * shows an unread badge on a project with zero chats. Files, `.chats/` and
+     * `read-state.json` were already cleaned; these were the one thing left.
+     *
+     * Takes the same hook/trigger name lists {@link removeProjectAgent} does, so
+     * the two together are the full inverse of the create flow — and so they stay
+     * in step: if a delete ever has to sweep DESCENDANT workspaces (nesting), both
+     * need the same widening, not just one. Matching is on the exact agent name,
+     * so deleting `foo` cannot touch a sibling `foo-bar`.
+     *
+     * Best-effort — the project directory is already gone by the time we get here.
+     */
+    async purgeProjectJobs(slug, hookNames = [], triggerNames = []) {
+        const agents = [
+            keeperAgentName(slug),
+            sweeperAgentName(slug),
+            ...hookNames.map((name) => hookAgentName(slug, name)),
+            ...triggerNames.map((name) => triggerAgentName(slug, name)),
+        ];
+        await jobs.purgeAgentJobs(this.cfg.stateDir, agents).catch(() => 0);
+        this.jobsIndexOrNull?.invalidate();
+    }
     /**
      * 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

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

@@ -74,7 +74,17 @@ export interface InstanceConfigFieldDto {
     help?: string;
     type: FieldType;
     enumValues?: readonly string[];
+    /** EFFECTIVE now: the value the running (frozen) process resolved at boot. */
     value: unknown;
+    /**
+     * PENDING: what this field would resolve to if the process restarted right
+     * now — i.e. what is in `paddock.config.yaml` this instant (or the built-in
+     * default where the file says nothing, or `value` where an env var wins). This
+     * is what the editor renders and what a save round-trips through (#722).
+     */
+    pendingValue: unknown;
+    /** `pendingValue` differs from `value` — the file has diverged from the process. */
+    pendingRestart: boolean;
     default: unknown;
     editable: boolean;
     sensitive: boolean;
@@ -92,9 +102,33 @@ export interface InstanceConfigDto {
     groups: InstanceConfigGroupDto[];
     /** Absolute path of the file a PUT writes to (informational). */
     configPath: string;
-    /** Always false — instance config is frozen at boot; edits need a restart. */
-    restartRequired: false;
+    /**
+     * At least one editable field's `pendingValue` differs from its `value`: the
+     * file on disk no longer describes the running process, and a restart would
+     * change behaviour. Was hardcoded `false` before #722 — which meant nothing
+     * ever told an operator their own save was unapplied.
+     */
+    restartRequired: boolean;
+    /**
+     * Fingerprint of the config file as read for THIS response (`null` when the
+     * file does not exist yet). A client echoes it back as `expectedVersion` on
+     * the PUT; the server refuses the write if the file changed meanwhile, so two
+     * tabs conflict loudly instead of silently last-writer-winning (#722).
+     */
+    configVersion: string | null;
+    /**
+     * Set when the file exists but could not be read or parsed. Pending values are
+     * unknowable in that state, so they fall back to the effective ones — better
+     * to say why than to silently report "nothing pending".
+     */
+    configFileError?: string;
 }
+/**
+ * The current fingerprint of the config file (`null` when absent) — the PUT
+ * path's half of the optimistic-concurrency check. Deliberately re-reads rather
+ * than trusting a cached value: the point is to notice a write we did not make.
+ */
+export declare function instanceConfigVersion(configPath: string): string | null;
 /**
  * Resolve the path a PUT writes to: an explicit `PADDOCK_CONFIG` env var wins
  * (the same rule {@link import("./config.js").loadConfigFile} reads it back
@@ -102,9 +136,25 @@ export interface InstanceConfigDto {
  */
 export declare function instanceConfigPath(cfg: PaddockConfig): string;
 /**
- * Build the grouped GET DTO from the resolved (frozen) config + live env. Each
- * field reports its current `value`, built-in `default`, and whether an env var
- * currently shadows it (so the UI renders env-shadowed fields read-only).
+ * Build the grouped GET DTO from the resolved (frozen) config, the live env AND
+ * the config file on disk. Each field reports:
+ *
+ *  - `value` — EFFECTIVE now, out of the frozen boot config;
+ *  - `pendingValue` — what a restart would resolve, out of the file this instant;
+ *  - `pendingRestart` — those two differ.
+ *
+ * Reading the file is the load-bearing part (#722). While this built the DTO
+ * from the frozen config alone, `GET` could not observe ANY write — including
+ * the one the caller had just made — so a successful save appeared to revert,
+ * two tabs clobbered each other with nothing able to notice, and
+ * `restartRequired` had no choice but to be a hardcoded `false`.
+ *
+ * Pending values are computed for EDITABLE, non-env-shadowed fields only:
+ *  - an env-shadowed field resolves to the same env value after a restart, so
+ *    the file cannot make it diverge;
+ *  - the read-only `advanced` bindings are normalised at boot (`dataDir` and
+ *    friends are canonicalised, `port` is `Number()`-ed), so comparing them
+ *    against raw file text would manufacture divergence that isn't there.
  */
 export declare function buildInstanceConfig(cfg: PaddockConfig): InstanceConfigDto;
 /** A rejected PUT: which field failed and why (surfaced as a 400). */
@@ -117,6 +167,7 @@ export declare class InstanceConfigError extends Error {
  * {@link InstanceConfigError} on the first offending field:
  *  - an unknown key,
  *  - a read-only / non-editable key,
+ *  - a key an env var currently shadows,
  *  - a value the field's `coerce` rejects.
  * Returns the coerced `{ key, value }` pairs ready to write. A field whose value
  * is `null` (an editable optional being cleared) is returned with `value: null`