@edspencer/paddock 0.62.0 → 0.64.0

package/packages/server/dist/projects.js

@@ -35,8 +35,9 @@ import { sanitizeAttachmentsOverride } from "./attachments-config.js";
 // them at `./projects.js` — the same one-place-to-import discipline as before.
 import { IMAGE_MIME, VIDEO_MIME, DOCUMENT_MIME, fileKind, contentTypeFor, } from "./project-mime.js";
 export { IMAGE_MIME, VIDEO_MIME, DOCUMENT_MIME, fileKind, contentTypeFor };
-import { SLUG_RE, ROOT_KEY, isRootKey, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, today, claudeTemplate, ProjectError, } from "./project-paths.js";
-export { ROOT_KEY, isRootKey, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, ProjectError, };
+import { SLUG_RE, ROOT_KEY, isRootKey, isPathInside, isManaged, contentDirFor, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, today, claudeTemplate, ProjectError, } from "./project-paths.js";
+export { ROOT_KEY, isRootKey, isPathInside, isManaged, contentDirFor, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, ProjectError, };
+import { gitRemotes, normalizeRemote } from "./adoptable.js";
 import { normalizeLinks, } from "./project-types.js";
 import * as projectFiles from "./project-files.js";
 // Barrel: re-export all type declarations + normalizeLinks + the config-type
@@ -78,8 +79,24 @@ function sanitizeModelsOverride(raw) {
 }
 export class ProjectStore {
     root;
-    constructor(root) {
+    dataDir;
+    log;
+    /**
+     * @param root The projects root (`cfg.projectsRoot`) — every project's metadata dir.
+     * @param dataDir The instance data dir (`cfg.dataDir`), used ONLY to reject a
+     *   `path:` that points inside Paddock's own state (issue #206). Optional so the
+     *   many tests that construct a bare store keep compiling; when omitted, `root`
+     *   alone is the containment check (in the default layout `projectsRoot` is
+     *   `<dataDir>/projects`, so it is the tighter of the two anyway).
+     * @param log Where non-fatal advisories go — currently only the declared-repo /
+     *   actual-remote mismatch on an existing `path` (issue #206), which must be
+     *   said out loud rather than silently ignored (#659) but must not fail the
+     *   create. Defaults to a no-op so a bare `new ProjectStore(root)` is unchanged.
+     */
+    constructor(root, dataDir, log = { warn: () => { } }) {
         this.root = root;
+        this.dataDir = dataDir;
+        this.log = log;
     }
     /** Ensure the projects root exists. Call once at startup. */
     async init() {
@@ -174,6 +191,213 @@ export class ProjectStore {
             return false;
         }
     }
+    /**
+     * Recursively delete `target`, but ONLY if it is strictly inside `projectsRoot`.
+     *
+     * The single choke point for every recursive delete in this store. Before issue
+     * #206 the containment was implicit: everything a project owned — including a
+     * repo-backed project's checkout — was nested under `<projectsRoot>/<slug>/`, so
+     * `fs.rm(dir, {recursive: true})` could not reach anything that wasn't ours.
+     * A LINKED project's working directory is the user's real work repo, outside the
+     * root, and that implicit safety is gone.
+     *
+     * So the check is made explicit and centralised here rather than re-derived at
+     * each call site: an `fs.rm` that escapes throws instead of deleting. Both
+     * current callers already only pass in-root paths — this exists so that stays
+     * true when someone later adds a third one.
+     */
+    async rmInsideRoot(target) {
+        const resolved = path.resolve(target);
+        const root = path.resolve(this.root);
+        if (resolved === root || !isPathInside(resolved, root)) {
+            throw new ProjectError(`Refusing to delete outside the projects root: ${target}`, "invalid");
+        }
+        await fs.rm(resolved, { recursive: true, force: true });
+    }
+    /**
+     * Undo a failed {@link create} by removing the directories it created — and
+     * ONLY those.
+     *
+     * This is the non-negotiable half of the acquisition rules (issue #206). The
+     * previous rollback was an unconditional `fs.rm(dir, {recursive, force})` on the
+     * slug dir, safe only because everything a project owned was nested inside it.
+     * Once `path:` lets a user nominate a clone TARGET, an unconditional recursive
+     * delete is a footgun aimed at whatever they typed — a home directory, say. So
+     * the caller records what it brought into being and this removes exactly that
+     * list; a pre-existing directory is never in it and therefore can never be
+     * deleted, no matter how the create failed.
+     *
+     * Removed deepest-first so a nested pair (slug dir + its checkout) unwinds
+     * cleanly. Failures are swallowed: the original error is the one worth
+     * reporting, and a rollback that can't finish must not mask it.
+     */
+    async rollback(created) {
+        for (const target of [...created].reverse()) {
+            await fs.rm(target, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+    /**
+     * Validate a `path:` (issue #206) and return it canonicalised, along with
+     * whether it already exists.
+     *
+     * This is the ONLY gate between a user-supplied string and a directory Paddock
+     * will hand an agent as its cwd (and may `git clone` into), so it is
+     * deliberately strict and ordered cheapest-first. It rejects:
+     *
+     *  - a relative path (a cwd must be unambiguous — it is baked into every
+     *    transcript path, and resolving it against the server's cwd is a footgun);
+     *  - a path that exists but isn't a directory;
+     *  - a path inside `projectsRoot` or the data dir — that is Paddock's own
+     *    state, and pointing at it re-creates the nesting this feature exists to
+     *    avoid (plus `remove()` would then really delete it);
+     *  - a path that is, contains, or sits inside another project's working
+     *    directory — two keepers sharing one cwd collide on transcripts (they are
+     *    keyed by cwd) and on the working tree itself.
+     *
+     * It deliberately does NOT reject a directory for not being a git repository.
+     * That would be the only mandatory git check in the codebase: everywhere else
+     * paddock PROBES and degrades (`GitService.isRepo()` → false, the Changes tab
+     * removes itself, commit/push return `{error: "not a repo"}`), and the default
+     * E2E server runs on a non-git directory on purpose.
+     *
+     * A MISSING path is not an error here — it is an acquisition instruction, which
+     * {@link acquirePath} resolves. Only the existing-path branch can be
+     * canonicalised by `realpath`, so for a missing one the containment checks run
+     * against the resolved-but-not-real path plus its nearest existing ancestor —
+     * otherwise `/tmp/link -> <projectsRoot>` with a missing leaf would slip past.
+     */
+    async validatePath(raw) {
+        const input = raw.trim();
+        if (!path.isAbsolute(input)) {
+            throw new ProjectError(`Project path must be absolute: ${input}`, "invalid");
+        }
+        // Resolve symlinks before ANY containment check — otherwise
+        // `/tmp/innocent -> <projectsRoot>/victim` would sail through them all. A
+        // path that doesn't exist yet can't be realpath'd, so fall back to resolving
+        // its nearest existing ancestor and re-appending the missing tail; that keeps
+        // a symlinked PARENT from smuggling the target back inside our own state.
+        const direct = await fs.realpath(input).catch(() => null);
+        const exists = direct !== null;
+        const resolved = direct ?? (await this.resolveViaExistingAncestor(input));
+        if (exists) {
+            const st = await fs.stat(resolved).catch(() => null);
+            if (!st?.isDirectory()) {
+                throw new ProjectError(`Project path is not a directory: ${input}`, "not_directory");
+            }
+        }
+        if (isPathInside(resolved, this.root)) {
+            throw new ProjectError(`Project path must be outside the projects root (${this.root}): ${input}`, "invalid");
+        }
+        if (this.dataDir && isPathInside(resolved, this.dataDir)) {
+            throw new ProjectError(`Project path must be outside the Paddock data dir (${this.dataDir}): ${input}`, "invalid");
+        }
+        // Reject overlap with an existing project's cwd in EITHER direction: pointing
+        // at a parent of another project's working dir is just as broken as pointing
+        // at a child of one.
+        for (const other of await this.list()) {
+            const cwd = other.workingDir;
+            if (isPathInside(resolved, cwd) || isPathInside(cwd, resolved)) {
+                throw new ProjectError(`Project path overlaps the working directory of project "${other.slug}" (${cwd}): ${input}`, "invalid");
+            }
+        }
+        return { resolved, exists };
+    }
+    /**
+     * Canonicalise a path that does not exist yet, by realpath-ing the deepest
+     * ancestor that DOES exist and re-appending the missing segments. Used only by
+     * {@link validatePath}, so a clone target under a symlinked parent still gets
+     * containment-checked against its real location.
+     */
+    async resolveViaExistingAncestor(input) {
+        let head = path.resolve(input);
+        const tail = [];
+        for (;;) {
+            const real = await fs.realpath(head).catch(() => null);
+            if (real)
+                return path.join(real, ...tail.reverse());
+            const parent = path.dirname(head);
+            // Hit the filesystem root without finding anything real: nothing left to
+            // resolve against, so the already-normalised path is the best answer.
+            if (parent === head)
+                return path.resolve(input);
+            tail.push(path.basename(head));
+            head = parent;
+        }
+    }
+    /**
+     * Bring a project's `path` into existence, returning the directories THIS call
+     * created so a failure can roll back exactly those and nothing else.
+     *
+     * The acquisition rules (issue #206):
+     *
+     *  - path exists ⇒ use it. With `repo` also set, verify the remote matches and
+     *    WARN on a mismatch rather than silently ignoring `repo` — that is the #659
+     *    bug class (a directory that is a clone of a *different* repo).
+     *  - path missing + `repo` ⇒ clone the repo to that path.
+     *  - path missing, managed ⇒ create the directory; the user is nominating where
+     *    their notes should live, and an empty dir is a valid notebook.
+     *  - path missing, unmanaged, no `repo` ⇒ error. There is nothing to acquire
+     *    from and an empty directory is not a codebase.
+     *
+     * **Cleanup rule:** `created` only ever gains directories this call brought into
+     * being. A pre-existing directory is never appended, so no rollback can delete
+     * one — the target is user-nominated and may be a home directory.
+     *
+     * `created` is an OUT-parameter rather than a return value on purpose. Returning
+     * the list would mean the caller only learns what to clean up on the success
+     * path: an `acquirePath` that threw would never hand back the directory it had
+     * already made, so a clone that died partway through would orphan it. Recording
+     * before the risky step is what makes the rollback complete.
+     */
+    async acquirePath(args) {
+        const { resolved, exists, repo, managed, warn, created } = args;
+        if (exists) {
+            // Used as-is. Nothing is appended to `created` — this directory is the
+            // user's, and it must survive any failure that follows.
+            if (repo)
+                await this.warnOnRemoteMismatch(resolved, repo, warn);
+            return;
+        }
+        if (!repo && !managed) {
+            throw new ProjectError(`Project path does not exist and there is no repo to clone from: ${resolved}`, "invalid");
+        }
+        // From here the directory is ours: record it BEFORE creating it, so a failure
+        // midway (a clone that dies after writing some objects) still rolls back.
+        created.push(resolved);
+        if (repo) {
+            try {
+                await cloneRepo(repo, resolved);
+            }
+            catch (err) {
+                throw new ProjectError(err instanceof Error ? err.message : `Failed to clone ${repo} to ${resolved}`, "invalid");
+            }
+            return;
+        }
+        await fs.mkdir(resolved, { recursive: true });
+    }
+    /**
+     * Warn when a directory's git remotes don't include `repo`.
+     *
+     * Deliberately a warning, not a rejection: the directory the user named is the
+     * one they meant, and plenty of legitimate setups (a fork, a mirror, an
+     * ssh-vs-https spelling) won't match exactly. But silently ignoring `repo` is
+     * how #659 happened, so the mismatch has to be said out loud. A directory with
+     * no git at all is not a mismatch — it is just not a repo, which is allowed.
+     *
+     * Reuses `adoptable.ts`'s reader, which parses `.git/config` directly (no
+     * subprocess) and already follows a linked worktree's `gitdir:`/`commondir`
+     * pointers, and returns URLs already through {@link normalizeRemote}.
+     */
+    async warnOnRemoteMismatch(dir, repo, warn) {
+        const remotes = await gitRemotes(dir);
+        if (remotes.length === 0)
+            return;
+        if (remotes.includes(normalizeRemote(repo)))
+            return;
+        warn(`Project path ${dir} is a git repo whose remotes (${remotes.join(", ")}) ` +
+            `do not include the declared repo ${repo}. Using the directory as given; ` +
+            `the repo URL is recorded as a hint only.`);
+    }
     /**
      * Create a project: mkdir + write project.yaml (from template) + seed
      * CHANGELOG.md. Idempotency: throws ProjectError("exists") if the slug
@@ -190,12 +414,32 @@ export class ProjectStore {
         if (await this.exists(slug)) {
             throw new ProjectError(`Project already exists: ${slug}`, "exists");
         }
-        // Repo-backed project (issue #187): validate the URL up front so a bad value
-        // never reaches `git clone` and the project isn't half-created.
+        // Validate the repo URL up front so a bad value never reaches `git clone`
+        // and the project isn't half-created (issue #187).
         const repo = input.repo?.trim() || undefined;
         if (repo && !isValidRepoUrl(repo)) {
             throw new ProjectError(`Invalid repo URL: ${repo}`, "invalid");
         }
+        const rawPath = input.path?.trim() || undefined;
+        // The managed axis (issue #206). Absent input derives the same way a legacy
+        // file does, so "what you get by default" is one rule everywhere.
+        const managed = isManaged({ managed: input.managed, repo, path: rawPath });
+        // Paddock curating its own files INTO a repo it also clones has no sensible
+        // meaning, so refuse rather than silently dropping one half. Refusing is the
+        // reversible choice: accepting it now and changing what it means later would
+        // be a migration.
+        if (managed && repo) {
+            throw new ProjectError("A managed project cannot have a repo — Paddock would be curating files " +
+                "into a checkout it clones. Use managed: false to work in the repo, or " +
+                "drop `repo` for a notebook.", "invalid");
+        }
+        if (!managed && !repo && !rawPath) {
+            throw new ProjectError("An unmanaged project needs a `path` (a directory to work in) or a `repo` " +
+                "(one to clone), or both.", "invalid");
+        }
+        // Validate BEFORE anything is created, so a bad path leaves nothing behind.
+        const checked = rawPath ? await this.validatePath(rawPath) : undefined;
+        const linkedPath = checked?.resolved;
         const now = today();
         const yaml = {
             name,
@@ -211,51 +455,121 @@ export class ProjectStore {
             summary: input.summary ?? "",
             links: input.links ?? [],
             pinned: [],
-            // Carry `repo` only when repo-backed (same round-trip discipline as model).
+            // ALWAYS written explicitly, even though it is optional on disk: the
+            // derived default exists to give LEGACY files their old meaning, not to be
+            // relied on by files we write ourselves.
+            managed,
+            // Carry `repo` only when set (same round-trip discipline as model).
             ...(repo ? { repo } : {}),
+            // Carry the canonicalised path only when set (issue #206).
+            ...(linkedPath ? { path: linkedPath } : {}),
         };
+        // Everything this call brings into being, newest last — the ONLY things a
+        // failure below is allowed to remove. A pre-existing directory is never in
+        // here, which is what stops a rollback deleting a user-nominated target that
+        // might be their home directory.
+        const created = [];
         const dir = this.dirFor(slug);
+        if (!(await fs.stat(dir).then(() => true).catch(() => false)))
+            created.push(dir);
         await fs.mkdir(dir, { recursive: true });
-        // For a repo-backed project, clone the external repo into the nested checkout
-        // BEFORE writing any metadata, so a clone failure rolls the whole thing back
-        // (rm the freshly-made dir) rather than leaving a broken project.yaml behind.
-        if (repo) {
-            const checkoutName = repoCheckoutName(repo);
-            const checkoutDir = path.join(dir, checkoutName);
-            try {
-                await cloneRepo(repo, checkoutDir);
+        try {
+            if (linkedPath && checked) {
+                // Acquire the nominated path: use it, clone into it, or create it.
+                // `created` is threaded in so a mid-acquisition failure still rolls back
+                // what was made — see acquirePath.
+                await this.acquirePath({
+                    resolved: linkedPath,
+                    exists: checked.exists,
+                    repo,
+                    managed,
+                    warn: (message) => this.log.warn(message),
+                    created,
+                });
             }
-            catch (err) {
-                await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
-                throw new ProjectError(err instanceof Error ? err.message : `Failed to clone ${repo}`, "invalid");
+            else if (repo) {
+                // No path nominated: clone into the nested checkout, as before (#187).
+                const checkoutName = repoCheckoutName(repo);
+                const checkoutDir = path.join(dir, checkoutName);
+                created.push(checkoutDir);
+                try {
+                    await cloneRepo(repo, checkoutDir);
+                }
+                catch (err) {
+                    throw new ProjectError(err instanceof Error ? err.message : `Failed to clone ${repo}`, "invalid");
+                }
+                // Keep the nested checkout (a full git repo) OUT of the instance data
+                // repo: a sidecar `.gitignore` ignores the checkout dir (git-in-git per
+                // #187's option A). `.chats/` is likewise data-repo noise.
+                await this.ensureSidecarGitignore(dir, checkoutName);
             }
-            // Keep the nested checkout (a full git repo) OUT of the instance data repo:
-            // a sidecar `.gitignore` ignores the checkout dir (git-in-git per #187's
-            // option A). `.chats/` (our transcript store) is likewise data-repo noise.
-            await this.ensureSidecarGitignore(dir, checkoutName);
+            await this.finishCreate({ slug, yaml, dir, name, now, managed });
         }
-        await this.writeYaml(slug, yaml);
-        await fs.writeFile(path.join(dir, CHANGELOG_FILE), [
-            `# Changelog — ${name}`,
-            "",
-            "<!--",
-            "Reverse-chronological. Newest entry on top, under a `## YYYY-MM-DD` heading.",
-            "-->",
-            "",
-            `## ${now}`,
-            "- Project opened.",
-            "",
-        ].join("\n"), "utf8");
-        // Seed a minimal per-project CLAUDE.md (issue #177) — but ONLY for a NOTEBOOK
-        // project. A repo-backed project defers to the repo's OWN CLAUDE.md (loaded
-        // natively via the cwd walk-up from the checkout); the sweeper must never
-        // touch that upstream-owned file, so we don't seed a competing one (#187).
-        if (!repo) {
-            await fs.writeFile(path.join(dir, CLAUDE_FILE), claudeTemplate(name, yaml.summary), "utf8");
+        catch (err) {
+            // ONE rollback covering everything after the slug dir, not just the
+            // acquisition: a `writeYaml` or seed-file failure used to leave the
+            // directories we had just made (a clone target, a created notes dir) behind
+            // with no project to own them.
+            await this.rollback(created);
+            throw err;
         }
         // No OVERVIEW.md at creation — the first sweep writes it.
         return this.toDto(dir, yaml, false);
     }
+    /**
+     * Write a new project's `project.yaml` and seed its content files. Split out of
+     * {@link create} so the whole sequence sits inside that method's single
+     * try/rollback rather than trailing off the end of it.
+     */
+    async finishCreate(args) {
+        const { slug, yaml, dir, name, now, managed } = args;
+        await this.writeYaml(slug, yaml);
+        const contentDir = contentDirFor(dir, yaml);
+        // The curated trio follows the content (issue #206): for a managed project
+        // with an external `path` these land out there rather than in the data dir.
+        // `dir` is already made; `contentDir` may be the same directory or the
+        // freshly-acquired path, both of which exist by now.
+        //
+        // Never clobber: a managed `path` may point at a folder of notes that already
+        // has a CHANGELOG.md, and seeding "Project opened." over the user's history
+        // would be the worst kind of data loss — silent and plausible. For a fresh
+        // project dir the file is always absent, so this only bites in the new case.
+        const changelogFile = path.join(contentDir, CHANGELOG_FILE);
+        const changelogExists = await fs
+            .access(changelogFile)
+            .then(() => true)
+            .catch(() => false);
+        if (!changelogExists) {
+            await fs.writeFile(changelogFile, [
+                `# Changelog — ${name}`,
+                "",
+                "<!--",
+                "Reverse-chronological. Newest entry on top, under a `## YYYY-MM-DD` heading.",
+                "-->",
+                "",
+                `## ${now}`,
+                "- Project opened.",
+                "",
+            ].join("\n"), "utf8");
+        }
+        // Seed a minimal per-project CLAUDE.md (issue #177) — but ONLY for a MANAGED
+        // project, and never over an existing one. An UNMANAGED project's working
+        // directory owns its own `CLAUDE.md` (upstream's, in a checkout the user
+        // source-controls); the sweeper must never write that file, so we don't seed a
+        // competing one. A managed project with an external `path` DOES get one, out
+        // there with the rest of its content — but if that directory already has a
+        // `CLAUDE.md` (a pre-existing notes folder), it is the user's and stays.
+        if (managed) {
+            const claudeFile = path.join(contentDir, CLAUDE_FILE);
+            const claudeExists = await fs
+                .access(claudeFile)
+                .then(() => true)
+                .catch(() => false);
+            if (!claudeExists) {
+                await fs.writeFile(claudeFile, claudeTemplate(name, yaml.summary), "utf8");
+            }
+        }
+    }
     /**
      * Promote an existing NOTEBOOK project into a REPO-BACKED one IN PLACE (issue
      * #213), preserving its chats + sidecar metadata. This relaxes #187's create-time
@@ -293,8 +607,18 @@ export class ProjectStore {
             throw new ProjectError("The root workspace cannot be repo-backed", "invalid");
         }
         const current = await this.get(slug); // throws not_found
-        if (current.repoBacked) {
-            throw new ProjectError(`Project is already repo-backed: ${slug}`, "invalid");
+        // Promotion means "start working in a clone of this repo", so it only makes
+        // sense for a project Paddock currently manages. An UNMANAGED project already
+        // works in code somebody source-controls (issue #206).
+        if (!current.managed) {
+            throw new ProjectError(`Project is already backed by a repo or directory: ${slug}`, "invalid");
+        }
+        // A managed project with its own `path` is a notes folder the user nominated;
+        // promoting it would clone into that directory. Say so specifically — the
+        // generic message above would be misleading.
+        if (current.path) {
+            throw new ProjectError(`Project "${slug}" keeps its content in ${current.path} and cannot be promoted; ` +
+                `create an unmanaged project pointing at the repo instead`, "invalid");
         }
         const repo = repoUrl?.trim();
         if (!repo || !isValidRepoUrl(repo)) {
@@ -330,6 +654,12 @@ export class ProjectStore {
         const next = {
             ...this.stripDto(current),
             repo,
+            // Promotion crosses the managed axis (issue #206): the keeper's cwd becomes
+            // a checkout that owns its own CLAUDE.md, which is exactly what unmanaged
+            // means. Set explicitly — `stripDto` carries the notebook's concrete
+            // `managed: true` forward, and leaving it would persist the one combination
+            // `create()` rejects (managed + repo).
+            managed: false,
             updated: today(),
         };
         try {
@@ -364,6 +694,24 @@ export class ProjectStore {
             started: current.started, // immutable
             updated: today(),
         };
+        // `path` and `managed` are immutable (issue #206), enforced here rather than
+        // by their absence from UpdateProjectInput — that type is a compile-time shape
+        // while `rest` is spread from a request body.
+        //
+        // For `path` both directions matter: a project must not be RE-POINTED (its cwd
+        // is baked into every transcript path, so moving it strands the history), and
+        // one must not be given a path by a stray key, which would silently hand its
+        // keeper a cwd somewhere else on the box that never went through
+        // `validatePath`. `managed` is re-asserted from `current` for the same reason
+        // — flipping it would move where the curated trio lives and either start the
+        // sweeper writing into a checkout or orphan the existing notes. (Changing it
+        // deliberately is a migration, not a PATCH; see #708 for what a silent
+        // location flip does to history.)
+        if (current.path)
+            next.path = current.path;
+        else
+            delete next.path;
+        next.managed = current.managed;
         if (driveModePatch === null) {
             // Clear the per-project override -> inherit the global default (issue #122).
             delete next.driveMode;
@@ -440,7 +788,7 @@ export class ProjectStore {
     /** Read OVERVIEW.md, or "" if it doesn't exist yet. */
     async readOverview(slug) {
         try {
-            return await fs.readFile(path.join(this.dirFor(slug), OVERVIEW_FILE), "utf8");
+            return await fs.readFile(path.join(await this.contentDirOf(slug), OVERVIEW_FILE), "utf8");
         }
         catch (err) {
             if (err.code === "ENOENT")
@@ -450,12 +798,12 @@ export class ProjectStore {
     }
     /** Replace OVERVIEW.md wholesale (the sweep regenerates it each time). */
     async writeOverview(slug, content) {
-        await fs.writeFile(path.join(this.dirFor(slug), OVERVIEW_FILE), content, "utf8");
+        await fs.writeFile(path.join(await this.contentDirOf(slug), OVERVIEW_FILE), content, "utf8");
     }
     /** Read CHANGELOG.md, or "" if it doesn't exist yet (issue #188). */
     async readChangelog(slug) {
         try {
-            return await fs.readFile(path.join(this.dirFor(slug), CHANGELOG_FILE), "utf8");
+            return await fs.readFile(path.join(await this.contentDirOf(slug), CHANGELOG_FILE), "utf8");
         }
         catch (err) {
             if (err.code === "ENOENT")
@@ -465,19 +813,39 @@ export class ProjectStore {
     }
     /** Whether OVERVIEW.md exists for this project. */
     async overviewExists(slug) {
+        return this.overviewExistsIn(await this.contentDirOf(slug));
+    }
+    /**
+     * {@link overviewExists} for a content dir already in hand.
+     *
+     * `readSafe` needs this: it has just parsed the yaml, so it can derive the
+     * content dir for free, whereas going through the slug would re-read
+     * `project.yaml` on every project of every `list()`.
+     */
+    async overviewExistsIn(contentDir) {
         try {
-            await fs.access(path.join(this.dirFor(slug), OVERVIEW_FILE));
+            await fs.access(path.join(contentDir, OVERVIEW_FILE));
             return true;
         }
         catch {
             return false;
         }
     }
+    /**
+     * Where this project's curated trio lives (issue #206) — see
+     * {@link contentDirFor}. Falls back to the metadata dir for a slug that names
+     * no project, so a caller reading a missing project still gets "" rather than
+     * throwing.
+     */
+    async contentDirOf(slug) {
+        const project = await this.readSafe(slug);
+        return project?.contentDir ?? this.dirFor(slug);
+    }
     // --- CLAUDE.md (durable identity & conventions, sweep-amended) ----------
     /** Read CLAUDE.md, or "" if it doesn't exist yet (issue #177). */
     async readClaudeMd(slug) {
         try {
-            return await fs.readFile(path.join(this.dirFor(slug), CLAUDE_FILE), "utf8");
+            return await fs.readFile(path.join(await this.contentDirOf(slug), CLAUDE_FILE), "utf8");
         }
         catch (err) {
             if (err.code === "ENOENT")
@@ -502,8 +870,7 @@ export class ProjectStore {
         const trimmed = curatedBody.trim();
         if (!trimmed)
             return;
-        const dir = this.dirFor(slug);
-        const file = path.join(dir, CLAUDE_FILE);
+        const file = path.join(await this.contentDirOf(slug), CLAUDE_FILE);
         let body;
         try {
             body = await fs.readFile(file, "utf8");
@@ -602,13 +969,12 @@ export class ProjectStore {
             throw new ProjectError("Refusing to delete the root workspace", "invalid");
         }
         const project = await this.get(slug); // throws not_found
-        const dir = this.dirFor(slug);
-        // Guard against deleting the projects root itself if a bad slug slipped in.
-        const resolved = path.resolve(dir);
-        if (resolved === path.resolve(this.root) || !resolved.startsWith(path.resolve(this.root) + path.sep)) {
-            throw new ProjectError("Refusing to delete outside the projects root", "invalid");
-        }
-        await fs.rm(dir, { recursive: true, force: true });
+        // Only ever the METADATA dir — never `project.workingDir`. For a LINKED
+        // project (issue #206) those differ and the working dir is the user's real
+        // clone: deleting the project unlinks it, it does not delete their work.
+        // `rmInsideRoot` enforces that structurally (a linked path is outside the
+        // root by validation, so it cannot be reached from here at all).
+        await this.rmInsideRoot(this.dirFor(slug));
         return project;
     }
     /**
@@ -626,7 +992,7 @@ export class ProjectStore {
         const trimmed = body.trim();
         if (!trimmed)
             return;
-        const file = path.join(this.dirFor(slug), CHANGELOG_FILE);
+        const file = path.join(await this.contentDirOf(slug), CHANGELOG_FILE);
         const title = `# Changelog — ${slug}`;
         // Drop a leading top-level heading the model may have emitted, so the
         // Paddock-owned title isn't duplicated.
@@ -695,8 +1061,11 @@ export class ProjectStore {
                 return null;
             yaml = this.normalize({}, key);
         }
-        // overviewExists is a cheap fs.access; do it after the yaml parse succeeds.
-        const hasOverview = await this.overviewExists(key);
+        // A cheap fs.access, done after the yaml parse succeeds. Deliberately the
+        // content-dir-in-hand variant: the slug-taking `overviewExists` would re-read
+        // this very `project.yaml` to find the content dir, once per project of every
+        // `list()`.
+        const hasOverview = await this.overviewExistsIn(contentDirFor(dir, yaml));
         return this.toDto(dir, yaml, hasOverview);
     }
     /** Fill defaults / coerce a parsed project.yaml into a complete ProjectYaml. */
@@ -776,6 +1145,25 @@ export class ProjectStore {
             // repo (issue #187): carried only when present — its presence is what marks
             // the project repo-backed and drives the workingDir resolution in toDto.
             ...(typeof p.repo === "string" && p.repo.trim() ? { repo: p.repo.trim() } : {}),
+            // path (issue #206): carried only when present AND absolute — its presence
+            // is what makes workingDirFor return the cwd verbatim. The absolute check is
+            // a read-boundary backstop against a hand-edited relative value, which would
+            // otherwise resolve against the server's cwd; dropping it degrades the
+            // project to an unbacked one rather than pointing an agent somewhere
+            // arbitrary. Existence/containment were checked at create time and are NOT
+            // re-checked here — `normalize` runs on every list() and must stay pure +
+            // cheap, and a path that has since gone away should surface as a broken cwd,
+            // not silently mutate into a different kind of project.
+            ...(typeof p.path === "string" && path.isAbsolute(p.path.trim())
+                ? { path: p.path.trim() }
+                : {}),
+            // managed (issue #206): carried ONLY when explicitly set on disk. An absent
+            // value must stay absent so it keeps deriving from the backing
+            // (`!(repo || path)`) — baking a concrete `true` in here would flip every
+            // legacy repo-backed project to managed the first time its yaml was
+            // re-written, and the sweeper would start writing CLAUDE.md into a checkout.
+            // Same round-trip discipline as `driveMode`, and for a much sharper reason.
+            ...(typeof p.managed === "boolean" ? { managed: p.managed } : {}),
             // schedules (issue #265): carried only when at least one well-formed entry
             // survives sanitization — an absent/empty map stays absent on disk, so files
             // without schedules round-trip unchanged. A malformed entry is dropped (not
@@ -875,18 +1263,32 @@ export class ProjectStore {
             // sanitised so a corrupt hand-edit never reaches the web. Absent ⇒ omitted (#384).
             curation: sanitizeCurationOverride(yaml.curation),
             dir,
-            // Repo-backed (#187): the keeper's cwd is the nested checkout; a notebook's
-            // cwd is the metadata dir itself. `repoBacked` is the presence of `repo`.
-            workingDir: workingDirFor(dir, yaml.repo),
-            repoBacked: Boolean(yaml.repo),
+            // The keeper's cwd: `path` verbatim (#206), else the nested checkout for a
+            // repo-backed project (#187), else the metadata dir.
+            workingDir: workingDirFor(dir, yaml.repo, yaml.path),
+            // Where the curated trio lives, and whether Paddock curates at all — the
+            // two facts that replaced `repoBacked` (#206). Both ALWAYS concrete here,
+            // with `managed` resolved through the derived default so a legacy file
+            // without the key keeps the meaning it has always had.
+            contentDir: contentDirFor(dir, yaml),
+            managed: isManaged(yaml),
             hasOverview,
         };
     }
+    /**
+     * Drop the derived DTO-only fields, leaving the on-disk shape.
+     *
+     * `managed` deliberately SURVIVES: it is a real `project.yaml` key, and because
+     * the DTO's value is always concrete, the first `update()` of a legacy project
+     * pins its derived value explicitly on disk. That is the desired direction —
+     * the file stops depending on a default — and it is safe precisely because the
+     * value written is the one the derivation already produced.
+     */
     stripDto(p) {
-        const { dir: _dir, workingDir: _workingDir, repoBacked: _repoBacked, hasOverview: _hasOverview, group, ...rest } = p;
+        const { dir: _dir, workingDir: _workingDir, contentDir: _contentDir, hasOverview: _hasOverview, group, ...rest } = p;
         void _dir;
         void _workingDir;
-        void _repoBacked;
+        void _contentDir;
         void _hasOverview;
         // Keep an empty area off the yaml so it isn't persisted as `group: ""`.
         return group?.trim() ? { ...rest, group } : rest;