@edspencer/paddock 0.58.0 → 0.59.1

package/package.json

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

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

@@ -0,0 +1,56 @@
+/**
+ * Pure argument parsing and message formatting for the `paddock` CLI.
+ *
+ * ## Why this is its own module
+ *
+ * These functions want unit tests, and the entrypoint they used to live in
+ * cannot be imported without running. The first attempt kept them in
+ * `paddock.ts` behind a run-directly guard:
+ *
+ * ```ts
+ * if (pathToFileURL(process.argv[1]).href === import.meta.url) main();
+ * ```
+ *
+ * **That guard shipped a silent no-op to npm.** npm installs a `bin` as a
+ * SYMLINK at `node_modules/.bin/paddock`, so `process.argv[1]` is the symlink
+ * path while `import.meta.url` is the module's realpath. They never match, the
+ * condition is always false, and `npx @edspencer/paddock` printed nothing and
+ * exited 0 — in 0.57.0, 0.58.0 and 0.59.0. It went unnoticed because the manual
+ * checks invoked `node <file>` directly, which is the one path where the guard
+ * does hold.
+ *
+ * `realpathSync(argv[1])` would fix that instance. Splitting the module removes
+ * the need for the guard entirely, so there is no condition left to get wrong on
+ * the next shim, platform or package manager. `paddock.ts` now always runs.
+ */
+export interface CliOptions {
+    port?: string;
+    host?: string;
+    dataDir?: string;
+    here: boolean;
+    open: boolean;
+    verbose: boolean;
+    help: boolean;
+    version: boolean;
+}
+/** A usage error. Thrown rather than exiting, so parsing stays testable. */
+export declare class CliError extends Error {
+}
+export declare const MIN_NODE_MAJOR = 22;
+export declare function parseArgs(argv: string[]): CliOptions;
+/**
+ * Why this Node is unusable, or `undefined` if it is fine.
+ *
+ * `engines` only warns by default, and the failure it eventually produces is an
+ * unexplained syntax error deep inside a dependency.
+ */
+export declare function nodeVersionProblem(nodeVersion: string): string | undefined;
+/**
+ * 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.
+ */
+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 links ~/.claude/projects/<encoded-dir> at this workspace\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 in the\n  environment: CLAUDE_CODE_OAUTH_TOKEN (Max/Pro) or ANTHROPIC_API_KEY (API\n  billing). If you already use Claude Code on this machine, an existing login\n  under ~/.claude is picked up automatically. Otherwise run `claude setup-token`.\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

@@ -0,0 +1,159 @@
+/**
+ * Pure argument parsing and message formatting for the `paddock` CLI.
+ *
+ * ## Why this is its own module
+ *
+ * These functions want unit tests, and the entrypoint they used to live in
+ * cannot be imported without running. The first attempt kept them in
+ * `paddock.ts` behind a run-directly guard:
+ *
+ * ```ts
+ * if (pathToFileURL(process.argv[1]).href === import.meta.url) main();
+ * ```
+ *
+ * **That guard shipped a silent no-op to npm.** npm installs a `bin` as a
+ * SYMLINK at `node_modules/.bin/paddock`, so `process.argv[1]` is the symlink
+ * path while `import.meta.url` is the module's realpath. They never match, the
+ * condition is always false, and `npx @edspencer/paddock` printed nothing and
+ * exited 0 — in 0.57.0, 0.58.0 and 0.59.0. It went unnoticed because the manual
+ * checks invoked `node <file>` directly, which is the one path where the guard
+ * does hold.
+ *
+ * `realpathSync(argv[1])` would fix that instance. Splitting the module removes
+ * the need for the guard entirely, so there is no condition left to get wrong on
+ * the next shim, platform or package manager. `paddock.ts` now always runs.
+ */
+/** A usage error. Thrown rather than exiting, so parsing stays testable. */
+export class CliError extends Error {
+}
+export const MIN_NODE_MAJOR = 22;
+export function parseArgs(argv) {
+    const opts = {
+        here: false,
+        open: false,
+        verbose: false,
+        help: false,
+        version: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const next = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new CliError(`${arg} needs a value`);
+            return v;
+        };
+        switch (arg) {
+            case "-p":
+            case "--port":
+                opts.port = next();
+                break;
+            case "--host":
+                opts.host = next();
+                break;
+            case "-d":
+            case "--data-dir":
+                opts.dataDir = next();
+                break;
+            case "--here":
+                opts.here = true;
+                break;
+            case "-o":
+            case "--open":
+                opts.open = true;
+                break;
+            case "--verbose":
+                opts.verbose = true;
+                break;
+            case "-h":
+            case "--help":
+                opts.help = true;
+                break;
+            case "-v":
+            case "--version":
+                opts.version = true;
+                break;
+            default:
+                throw new CliError(`unknown option: ${arg}\nRun \`paddock --help\` for usage.`);
+        }
+    }
+    return opts;
+}
+/**
+ * Why this Node is unusable, or `undefined` if it is fine.
+ *
+ * `engines` only warns by default, and the failure it eventually produces is an
+ * unexplained syntax error deep inside a dependency.
+ */
+export function nodeVersionProblem(nodeVersion) {
+    const major = Number(nodeVersion.split(".")[0]);
+    if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR)
+        return undefined;
+    return (`Node ${nodeVersion} is too old — Paddock needs Node ${MIN_NODE_MAJOR}+.\n` +
+        `Upgrade Node, then re-run. (nodejs.org, or \`nvm install ${MIN_NODE_MAJOR}\`)`);
+}
+/**
+ * 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.
+ */
+export function explainListenError(err, host, port) {
+    const code = err?.code;
+    if (code === "EADDRINUSE") {
+        return (`port ${port} is already in use.\n` +
+            `Something else is listening on ${host}:${port} — possibly another Paddock.\n` +
+            `Pick a different port:  paddock --port ${Number(port) + 1}`);
+    }
+    if (code === "EACCES") {
+        return (`not allowed to bind ${host}:${port}.\n` +
+            `Ports below 1024 need elevated privileges — use a higher one:  paddock --port 4000`);
+    }
+    return String(err?.message ?? err);
+}
+export const USAGE = `paddock — run a Paddock instance locally
+
+Usage
+  npx @edspencer/paddock [options]
+
+Options
+  -p, --port <port>       HTTP/WS port (default 4000, 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)
+  -o, --open              Open the app in your browser once it is listening
+      --verbose           Show the server's own logs (quiet by default)
+  -v, --version           Print the Paddock version and exit
+  -h, --help              Show this help
+
+Opening a directory (--here)
+  Run \`paddock --here\` inside a project and Paddock opens THAT directory as its
+  workspace: Claude works in your files, and any Claude Code sessions you already
+  have for the directory are offered for import. It:
+
+    · creates .paddock/ in the directory for this workspace's own state
+    · creates .chats/ for transcripts, and adds both to .gitignore
+    · links ~/.claude/projects/<encoded-dir> at this workspace
+
+  Once done, later runs in the same directory resume it — no flag needed.
+  Without --here, Paddock never touches the directory you ran it from.
+
+Credentials
+  Paddock drives Claude Code, so it needs Claude credentials in the
+  environment: CLAUDE_CODE_OAUTH_TOKEN (Max/Pro) or ANTHROPIC_API_KEY (API
+  billing). If you already use Claude Code on this machine, an existing login
+  under ~/.claude is picked up automatically. Otherwise run \`claude setup-token\`.
+
+Your data
+  Everything lives in one directory — ~/.paddock unless you pass --data-dir.
+  Projects, chat transcripts and settings all persist there between runs. Move
+  that directory to move your instance; delete it to start over. Nothing is
+  stored anywhere else.
+
+Notes
+  Binds loopback with authentication disabled, which is safe for a laptop. To
+  expose it on a network, set PADDOCK_AUTH_MODE first — Paddock refuses to bind
+  a routable interface wide open. See AUTH.md.
+
+Docs: https://github.com/edspencer/paddock`;

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

@@ -0,0 +1,25 @@
+/** Directory name that both stores `--here` state and marks the workspace. */
+export declare const HERE_MARKER = ".paddock";
+/** Has this directory been opened with `--here` before? */
+export declare function isHereWorkspace(dir: string): boolean;
+/**
+ * How many of `dir`'s existing Claude Code sessions are worth offering.
+ *
+ * **`encodePathForCli`, not `transcripts.ts`'s `encodeProjectDir`.** The latter
+ * omits Claude Code's truncate-and-hash branch for paths over 200 characters,
+ * on the explicit assumption that "paddock's project dirs are always short".
+ * An arbitrary user directory is exactly where that assumption fails.
+ *
+ * `MIN_TRANSCRIPT_BYTES` is shared with `AdoptableIndex` so the number quoted
+ * here matches what the UI will actually offer to import — a count that
+ * disagreed with the import screen would be worse than no count.
+ */
+export declare function countClaudeSessions(claudeHome: string, dir: string): number;
+/**
+ * Add `entry` to `dir`'s `.gitignore` if no equivalent line is already there.
+ *
+ * Mirrors `ProjectStore.ensureRootGitignore`: read, tolerate the equivalent
+ * forms, append rather than overwrite. `--here` runs inside somebody's real
+ * repository, so clobbering their `.gitignore` is not an option.
+ */
+export declare function ensureGitignored(dir: string, entry: string): void;

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

@@ -0,0 +1,104 @@
+/**
+ * `--here` support: opening the user's own directory as a Paddock workspace (#640).
+ *
+ * ## Why this needs no new concept
+ *
+ * A *project* cannot live outside `projectsRoot` — `dirFor` joins the key onto
+ * the root with no branch, deliberately. But the **root workspace** is a
+ * different thing: its key is `""`, so `dirFor("")` resolves to `projectsRoot`
+ * itself, and `projectsRoot` is user-configurable. Pointing
+ * `PADDOCK_PROJECTS_DIR` at a directory therefore makes that directory the root
+ * workspace, named after its own basename, with no schema change anywhere.
+ *
+ * Session adoption then works by construction: `AdoptableIndex`'s notebook
+ * branch matches on exact `cwd === project.workingDir` equality, and in this
+ * mode the workspace's working directory IS the user's cwd.
+ *
+ * ## Why the data dir goes inside the directory
+ *
+ * `--here` puts state in `<dir>/.paddock` rather than the shared `~/.paddock`.
+ * Two reasons, and the second is the important one:
+ *
+ *  1. **Self-containment.** Opening directory A and later directory B must not
+ *     have them share one job store, herdctl config and sidecar set — that is
+ *     how A's run history leaks into B's UI.
+ *  2. **It gives us an unambiguous marker.** A second, flagless run in the same
+ *     directory should resume it (the `git` model: `--here` is `git init`,
+ *     `.paddock/` is `.git`). Keying that off `project.yaml` would be ambiguous
+ *     — that filename already exists in the wild, including in every project
+ *     directory of the `edspencer/projects` notes repo — whereas `.paddock/` is
+ *     ours and its presence means exactly one thing.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { encodePathForCli } from "@herdctl/core";
+import { MIN_TRANSCRIPT_BYTES } from "../adoptable.js";
+/** Directory name that both stores `--here` state and marks the workspace. */
+export const HERE_MARKER = ".paddock";
+/** Has this directory been opened with `--here` before? */
+export function isHereWorkspace(dir) {
+    try {
+        return fs.statSync(path.join(dir, HERE_MARKER)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * How many of `dir`'s existing Claude Code sessions are worth offering.
+ *
+ * **`encodePathForCli`, not `transcripts.ts`'s `encodeProjectDir`.** The latter
+ * omits Claude Code's truncate-and-hash branch for paths over 200 characters,
+ * on the explicit assumption that "paddock's project dirs are always short".
+ * An arbitrary user directory is exactly where that assumption fails.
+ *
+ * `MIN_TRANSCRIPT_BYTES` is shared with `AdoptableIndex` so the number quoted
+ * here matches what the UI will actually offer to import — a count that
+ * disagreed with the import screen would be worse than no count.
+ */
+export function countClaudeSessions(claudeHome, dir) {
+    const folder = path.join(claudeHome, "projects", encodePathForCli(dir));
+    let entries;
+    try {
+        entries = fs.readdirSync(folder);
+    }
+    catch {
+        return 0;
+    }
+    let n = 0;
+    for (const entry of entries) {
+        if (!entry.endsWith(".jsonl"))
+            continue;
+        try {
+            if (fs.statSync(path.join(folder, entry)).size >= MIN_TRANSCRIPT_BYTES)
+                n++;
+        }
+        catch {
+            /* raced or unreadable — not offerable either way */
+        }
+    }
+    return n;
+}
+/**
+ * Add `entry` to `dir`'s `.gitignore` if no equivalent line is already there.
+ *
+ * Mirrors `ProjectStore.ensureRootGitignore`: read, tolerate the equivalent
+ * forms, append rather than overwrite. `--here` runs inside somebody's real
+ * repository, so clobbering their `.gitignore` is not an option.
+ */
+export function ensureGitignored(dir, entry) {
+    const file = path.join(dir, ".gitignore");
+    let existing = "";
+    try {
+        existing = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        /* no .gitignore yet */
+    }
+    const bare = entry.replace(/^\/|\/$/g, "");
+    const have = new Set(existing.split("\n").map((l) => l.trim()));
+    if (have.has(`/${bare}/`) || have.has(`${bare}/`) || have.has(bare))
+        return;
+    const body = existing && !existing.endsWith("\n") ? `${existing}\n` : existing;
+    fs.writeFileSync(file, `${body}${entry}\n`, "utf8");
+}

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

@@ -1,30 +1,2 @@
 #!/usr/bin/env node
-export interface CliOptions {
-    port?: string;
-    host?: string;
-    dataDir?: string;
-    open: boolean;
-    verbose: boolean;
-    help: boolean;
-    version: boolean;
-}
-/** A usage error. Thrown rather than exiting, so `parseArgs` stays testable. */
-export declare class CliError extends Error {
-}
-export declare function parseArgs(argv: string[]): CliOptions;
-/**
- * Why this Node is unusable, or `undefined` if it is fine.
- *
- * Split from the exit so it can be tested. `engines` only warns by default, and
- * the failure it eventually produces is an unexplained syntax error deep inside
- * a dependency — which is nobody's idea of a first-run experience.
- */
-export declare function nodeVersionProblem(nodeVersion: string): string | undefined;
-/**
- * Translate a listen failure into something a human can act on.
- *
- * `EADDRINUSE` on 4000 is the single most likely first-run failure — it is a
- * popular port and Paddock's own default — 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 {};

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

@@ -22,8 +22,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
-import { fileURLToPath, pathToFileURL } from "node:url";
-const MIN_NODE_MAJOR = 22;
+import { fileURLToPath } from "node:url";
+import { HERE_MARKER, isHereWorkspace, countClaudeSessions, ensureGitignored } from "./here.js";
+import { CliError, USAGE, parseArgs, nodeVersionProblem, explainListenError, } from "./args.js";
 /** This module's own directory: `<…>/packages/server/dist/cli`. */
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 /**
@@ -52,52 +53,6 @@ function findUp(rel) {
 }
 /** Nearest ancestor holding a `package.json` — `packages/server` in both layouts. */
 const packageRoot = findUp("package.json") ?? path.resolve(moduleDir, "../..");
-/** A usage error. Thrown rather than exiting, so `parseArgs` stays testable. */
-export class CliError extends Error {
-}
-export function parseArgs(argv) {
-    const opts = { open: false, verbose: false, help: false, version: false };
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        const next = () => {
-            const v = argv[++i];
-            if (v === undefined)
-                throw new CliError(`${arg} needs a value`);
-            return v;
-        };
-        switch (arg) {
-            case "-p":
-            case "--port":
-                opts.port = next();
-                break;
-            case "--host":
-                opts.host = next();
-                break;
-            case "-d":
-            case "--data-dir":
-                opts.dataDir = next();
-                break;
-            case "-o":
-            case "--open":
-                opts.open = true;
-                break;
-            case "--verbose":
-                opts.verbose = true;
-                break;
-            case "-h":
-            case "--help":
-                opts.help = true;
-                break;
-            case "-v":
-            case "--version":
-                opts.version = true;
-                break;
-            default:
-                throw new CliError(`unknown option: ${arg}\nRun \`paddock --help\` for usage.`);
-        }
-    }
-    return opts;
-}
 function fail(message) {
     console.error(`paddock: ${message}`);
     process.exit(1);
@@ -111,52 +66,6 @@ function readVersion() {
         return "unknown";
     }
 }
-const USAGE = `paddock — run a Paddock instance locally
-
-Usage
-  npx @edspencer/paddock [options]
-
-Options
-  -p, --port <port>       HTTP/WS port (default 4000, or $PORT)
-      --host <host>       Bind address (default 127.0.0.1)
-  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)
-  -o, --open              Open the app in your browser once it is listening
-      --verbose           Show the server's own logs (quiet by default)
-  -v, --version           Print the Paddock version and exit
-  -h, --help              Show this help
-
-Credentials
-  Paddock drives Claude Code, so it needs Claude credentials in the
-  environment: CLAUDE_CODE_OAUTH_TOKEN (Max/Pro) or ANTHROPIC_API_KEY (API
-  billing). If you already use Claude Code on this machine, an existing login
-  under ~/.claude is picked up automatically. Otherwise run \`claude setup-token\`.
-
-Your data
-  Everything lives in one directory — ~/.paddock unless you pass --data-dir.
-  Projects, chat transcripts and settings all persist there between runs. Move
-  that directory to move your instance; delete it to start over. Nothing is
-  stored anywhere else.
-
-Notes
-  Binds loopback with authentication disabled, which is safe for a laptop. To
-  expose it on a network, set PADDOCK_AUTH_MODE first — Paddock refuses to bind
-  a routable interface wide open. See AUTH.md.
-
-Docs: https://github.com/edspencer/paddock`;
-/**
- * Why this Node is unusable, or `undefined` if it is fine.
- *
- * Split from the exit so it can be tested. `engines` only warns by default, and
- * the failure it eventually produces is an unexplained syntax error deep inside
- * a dependency — which is nobody's idea of a first-run experience.
- */
-export function nodeVersionProblem(nodeVersion) {
-    const major = Number(nodeVersion.split(".")[0]);
-    if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR)
-        return undefined;
-    return (`Node ${nodeVersion} is too old — Paddock needs Node ${MIN_NODE_MAJOR}+.\n` +
-        `Upgrade Node, then re-run. (nodejs.org, or \`nvm install ${MIN_NODE_MAJOR}\`)`);
-}
 /**
  * Put our bundled `claude` on PATH for child processes.
  *
@@ -225,6 +134,48 @@ function noteFirstRun(dataDir) {
         "",
     ].join("\n"));
 }
+/**
+ * Say what `--here` is about to do to this directory, on the run that does it.
+ *
+ * The flag IS the consent — there is no prompt, and no `--yes` to remember.
+ * But consent only means something if you can know what you agreed to, so the
+ * effects are announced rather than asked about. Printed only on the first
+ * `--here` in a directory; resuming an already-opened one says nothing.
+ */
+function announceHereConsent(dir, dataDir) {
+    console.log([
+        "",
+        `  Opening ${dir} as a Paddock workspace.`,
+        `    · ${path.relative(dir, dataDir) || HERE_MARKER}/ and .chats/ created here, and added to .gitignore`,
+        "    · ~/.claude sessions for this directory are linked at the workspace",
+        "  Later runs here resume it — no flag needed.",
+        "",
+    ].join("\n"));
+}
+/**
+ * Tell the user their existing Claude history could be opened here.
+ *
+ * The only way anyone discovers `--here` exists. Read-only: a bare run counts
+ * transcripts and prints, and changes nothing on disk.
+ */
+function offerHereIfSessionsExist(dir) {
+    const claudeHome = process.env.CLAUDE_HOME ?? path.join(os.homedir(), ".claude");
+    let sessions = 0;
+    try {
+        sessions = countClaudeSessions(claudeHome, dir);
+    }
+    catch {
+        return; // detection is a courtesy; never let it break a boot
+    }
+    if (sessions === 0)
+        return;
+    console.log([
+        "",
+        `  This directory has ${sessions} Claude Code session${sessions === 1 ? "" : "s"}.`,
+        "  Run `paddock --here` to open it as a workspace and import them.",
+        "",
+    ].join("\n"));
+}
 /** Open `url` in the default browser. Best-effort: failing is never fatal. */
 function openBrowser(url) {
     const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
@@ -243,26 +194,6 @@ function openBrowser(url) {
         /* as above */
     }
 }
-/**
- * Translate a listen failure into something a human can act on.
- *
- * `EADDRINUSE` on 4000 is the single most likely first-run failure — it is a
- * popular port and Paddock's own default — 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;
-    if (code === "EADDRINUSE") {
-        return (`port ${port} is already in use.\n` +
-            `Something else is listening on ${host}:${port} — possibly another Paddock.\n` +
-            `Pick a different port:  paddock --port ${Number(port) + 1}`);
-    }
-    if (code === "EACCES") {
-        return (`not allowed to bind ${host}:${port}.\n` +
-            `Ports below 1024 need elevated privileges — use a higher one:  paddock --port 4000`);
-    }
-    return String(err?.message ?? err);
-}
 async function main() {
     let opts;
     try {
@@ -285,12 +216,44 @@ async function main() {
     if (problem !== undefined)
         fail(problem);
     addBundledBinsToPath();
+    // Canonical, because working directories "MUST be canonical so session
+    // discovery (which encodes the real path) can find Claude transcripts"
+    // (config.ts). On macOS a /tmp vs /private/tmp divergence would silently
+    // break adoption — and macOS is most laptops.
+    let cwd = process.cwd();
+    try {
+        cwd = fs.realpathSync(cwd);
+    }
+    catch {
+        /* keep the literal path; the server will surface any real problem */
+    }
+    // `--here` is the consent. A flagless run in a directory ALREADY opened this
+    // way resumes it — the git model, where `--here` is `git init` and `.paddock/`
+    // is `.git`. A flagless run anywhere else touches nothing.
+    const resuming = !opts.here && isHereWorkspace(cwd);
+    const hereMode = opts.here || resuming;
     // Apply CLI defaults as env vars. This is the whole integration surface: the
     // server resolves config inside `buildApp()`, so anything set before the
     // dynamic import below is picked up with no special-casing in config.ts.
     // Precedence is explicit flag > existing env > our default.
-    const dataDir = path.resolve(opts.dataDir ?? process.env.PADDOCK_DATA_DIR ?? path.join(os.homedir(), ".paddock"));
-    noteFirstRun(dataDir);
+    const dataDir = path.resolve(opts.dataDir ??
+        process.env.PADDOCK_DATA_DIR ??
+        (hereMode ? path.join(cwd, HERE_MARKER) : path.join(os.homedir(), ".paddock")));
+    if (hereMode) {
+        if (!resuming)
+            announceHereConsent(cwd, dataDir);
+        // The root workspace IS `projectsRoot` (its key is ""), so pointing this at
+        // the user's directory makes that directory the workspace. No schema change,
+        // no new project type — see cli/here.ts.
+        process.env.PADDOCK_PROJECTS_DIR = cwd;
+        fs.mkdirSync(dataDir, { recursive: true });
+        ensureGitignored(cwd, `/${HERE_MARKER}/`);
+        ensureGitignored(cwd, "/.chats/");
+    }
+    else {
+        noteFirstRun(dataDir);
+        offerHereIfSessionsExist(cwd);
+    }
     process.env.PADDOCK_DATA_DIR = dataDir;
     if (opts.port)
         process.env.PORT = opts.port;
@@ -323,17 +286,20 @@ async function main() {
         fail(explainListenError(err, host, port));
     }
     const url = `http://${host}:${port}`;
-    console.log(`\n  Paddock is running at ${url}\n  Data: ${dataDir}\n  Press Ctrl-C to stop.\n`);
+    // ALWAYS name the workspace, not just in --here mode. Behaviour that varies
+    // with cwd is only safe if it is observable: "why is this instance different
+    // today" should be answerable by reading the two lines the tool just printed.
+    console.log([
+        "",
+        `  Paddock is running at ${url}`,
+        `  Workspace: ${hereMode ? cwd : dataDir}${resuming ? "  (resumed)" : ""}`,
+        "  Press Ctrl-C to stop.",
+        "",
+    ].join("\n"));
     if (opts.open)
         openBrowser(url);
 }
-// Run only when executed directly, so the unit tests can import the pure parts.
-// `pathToFileURL`, not `"file://" + argv[1]`: the naive concatenation breaks on
-// any path containing a space or non-ASCII character — the same percent-encoding
-// trap as #636.
-if (process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url) {
-    main().catch((err) => {
-        console.error("fatal:", err);
-        process.exit(1);
-    });
-}
+main().catch((err) => {
+    console.error("fatal:", err);
+    process.exit(1);
+});

package/packages/server/package.json

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