moflo 4.12.12 → 4.13.0

package/.claude/guidance/shipped/moflo-cli-reference.md

@@ -4,7 +4,7 @@
 
 ---
 
-## CLI Commands (26 Commands, 140+ Subcommands)
+## CLI Commands (27 Commands, 140+ Subcommands)
 
 ### Core Commands
 
@@ -40,6 +40,7 @@
 | `epic`        | 3           | Epic orchestrator — run/status/reset with single-branch or auto-merge strategy |
 | `doctor`      | 1           | System diagnostics with health checks                                         |
 | `completions` | 4           | Shell completions (bash, zsh, fish, powershell)                               |
+| `worktree`    | 3           | Provisioned git worktrees (add, list, remove) — alias `wt`                     |
 
 ### Quick Examples (MCP Preferred)
 
@@ -59,6 +60,49 @@ npx flo daemon start
 
 ---
 
+## Provisioned Worktrees (`flo worktree`)
+
+A bare `git worktree add` produces a valid checkout and an unrunnable workspace — no
+`node_modules`, none of the gitignored `.env` files, and dev servers that collide with the
+primary checkout on fixed ports. `flo worktree add` creates the worktree **and** provisions it.
+
+```bash
+flo worktree add feature/123-thing        # create + provision (this is what /flo -wt runs)
+flo worktree add feature/123 --json       # {"path":…,"branch":…,"index":0,"provisioned":true}
+flo worktree list                         # every worktree + its provisioning state
+flo worktree remove feature/123-thing     # refuses a dirty tree unless --force
+```
+
+Provisioning is driven by an optional `worktree:` block in `moflo.yaml`. **With no block, `add`
+creates the worktree and provisions nothing** — identical to a plain `git worktree add`.
+
+```yaml
+worktree:
+  dir: ../myrepo-worktrees   # default: <repo-parent>/<repo>-worktrees
+  copy: [".env", ".env.*"]   # gitignored files copied from the primary checkout
+  link: ["node_modules"]     # symlinked (junctioned on Windows) from the primary checkout
+  setup: "npm ci"            # run in the new worktree, with MOFLO_WORKTREE_INDEX in its env
+```
+
+| Key | Use it when | Watch out for |
+|-----|-------------|---------------|
+| `copy` | A fresh checkout is missing gitignored config a build needs | It relocates **secrets** outside the repo and outside its `.gitignore`. Sources must live inside the primary checkout; `../secrets` is rejected. |
+| `link` | `node_modules` is large and the project does not use npm workspaces | A symlinked root `node_modules` is fragile under npm/yarn workspaces — prefer `setup: npm ci` there. An existing destination is never clobbered. |
+| `setup` | Install/build steps must run per workspace | A non-zero exit marks the provision failed but leaves the worktree in place. |
+
+**Port collisions.** moflo cannot rewrite a project's hardcoded ports. It gives each worktree a
+small stable integer — unique among live worktrees, reused when one is removed — as
+`MOFLO_WORKTREE_INDEX` in the `setup` command's environment. Offset your own ports from it:
+
+```yaml
+worktree:
+  setup: "npm ci && node -e \"require('fs').writeFileSync('.env.local','PORT='+(3500+Number(process.env.MOFLO_WORKTREE_INDEX)*20))\""
+```
+
+Memory needs no setup: durable learnings already converge across a repo's worktrees
+automatically. See `moflo-cross-install-memory-sharing.md` for the snapshot recipe that also
+skips the structural cold-start.
+
 ## Available Agents
 
 The shipped agent roster — each is invoked via the `Agent` tool with `subagent_type: <name>`. The canonical handle is the `name:` frontmatter inside `.claude/agents/**/*.md` (filename may differ from agent name). Aspirational agents that never shipped were retired — `retired-files.json` enforces auto-prune on consumer upgrade.

package/.claude/guidance/shipped/moflo-cross-install-memory-sharing.md

@@ -138,3 +138,4 @@ A foreign-writer warning from the Writers Audit check (`flo doctor -c writers`)
 - `.claude/guidance/moflo-memory-strategy.md` — Namespaces, RAG indexing, and the durable-vs-derived split this doc builds on
 - `.claude/guidance/moflo-memory-protocol.md` — Search-and-traverse protocol for the shared `learnings` once it is populated
 - `.claude/guidance/moflo-core-guidance.md` — CLI, daemon, and `moflo.yaml` reference (the `memory` config block)
+- `.claude/guidance/moflo-cli-reference.md` — `flo worktree`, which provisions a new worktree's gitignored files, `node_modules`, and per-workspace port index (memory sharing needs no setup; the rest of the workspace does)

package/.claude/skills/fl/phases.md

@@ -106,30 +106,64 @@ implementation, tests, simplify, commit, and PR from inside it. The current chec
 untouched. Durable learnings still converge automatically — a worktree shares the repo's
 `<git-common-dir>/moflo/durable.db` (see `/memory-worktree`).
 
-Compute paths with Node, never string-concatenate — the branch name contains `/`, and the
-worktree dir must sit **outside** the checkout on every OS (Rule #1: no hardcoded separators,
-no `/tmp`, no `mkdir -p`):
+Use `flo worktree add`. It computes the path, creates the branch off the repo's default
+branch, and **provisions** the tree per the optional `worktree:` block in `moflo.yaml` — copying
+gitignored `.env` material, linking `node_modules`, running a `setup` command. A fresh worktree is
+otherwise a valid checkout and an unrunnable workspace. Do not hand-roll the path or shell
+`git worktree add` directly: the path computation and the copy/link/setup steps are
+platform-sensitive (Rule #1) and live in tested code.
 
 ```bash
-# 1. Fresh base — update main in the current checkout first (worktrees share objects).
-git fetch origin main
+cd "<repo-root>" && flo worktree add "<type>/<issue-number>-<short-desc>" --json
+```
+
+Bind the repo root to the call. `flo worktree` resolves the repo from its working directory, and in
+Claude Code that resets between calls — run it from the wrong place and it silently targets a
+different repository (`Not a registered worktree of this repo` on the good day, the wrong repo's
+worktree on the bad one).
 
-# 2. Resolve a sibling worktree path: <repo-parent>/<repo>-worktrees/<slugged-branch>
-#    Slug the branch's "/" to "-" so the dir is flat and valid on Windows/macOS/Linux.
-node -e "const p=require('path'),cp=require('child_process');const root=cp.execSync('git rev-parse --show-toplevel').toString().trim();const branch=process.argv[1];const slug=branch.replace(/[\\\\/]/g,'-');const dir=p.join(p.dirname(root),p.basename(root)+'-worktrees',slug);console.log(dir)" "<type>/<issue-number>-<short-desc>"
+It prints one JSON object — read `path` from it:
 
-# 3. Create the worktree + branch off origin/main in one step (the printed path from step 2).
-git worktree add -b <type>/<issue-number>-<short-desc> "<computed-path>" origin/main
+```json
+{"path":"/abs/path/to/repo-worktrees/type-123-slug","branch":"type/123-slug","index":0,"provisioned":true}
 ```
 
-Then `cd "<computed-path>"` and run **every** remaining phase (implement → tests → simplify →
-commit → PR) from there. Report the worktree path to the user. Leave the worktree in place
-after the PR — the user may want to inspect it; note that `git worktree remove "<path>"` cleans
-it up when done.
+Then run **every** remaining phase (implement → tests → simplify → commit → PR) against that
+`path`, and report it to the user.
+
+**A bare `cd` does not stick.** In Claude Code the Bash working directory resets to the project root
+after each call, so `cd <path>` in one call and `npm test` in the next runs the test in the WRONG
+tree — the primary checkout — and everything looks fine until the PR contains no changes. Bind the
+directory to each command instead:
+
+- shell commands — put the `cd` in the *same* call: `cd "<path>" && npm test`
+- git — prefer `git -C "<path>" status` over cd'ing at all
+- file edits — use the absolute path under `<path>`; never a repo-relative one
+
+**Fallback — `flo worktree` not available.** The command ships in the same package as this skill,
+so normally they move together. They can still drift apart: a `flo` binary on PATH older than the
+synced `.claude/skills/`, or a moflo source checkout whose change has not been published and
+reinstalled yet. If the command errors with `Unknown command: worktree`, do NOT stop — create the
+worktree the plain way and continue the run, noting to the user that provisioning was skipped:
+
+```bash
+git fetch origin
+node -e "const p=require('path'),cp=require('child_process');const root=cp.execSync('git rev-parse --show-toplevel').toString().trim();const branch=process.argv[1];const dir=p.join(p.dirname(root),p.basename(root)+'-worktrees',branch.replace(/[\\/]/g,'-'));console.log(dir)" "<type>/<issue-number>-<short-desc>"
+git worktree add -b "<type>/<issue-number>-<short-desc>" "<computed-path>" origin/main
+```
 
-If `git worktree add` fails because the path already exists (a prior run), reuse it:
-`cd "<computed-path>" && git status` and continue, or pick a `-2` suffix — do not delete a dir
-you did not just create.
+The tree is then a valid checkout with no `node_modules` and no gitignored `.env` files — fine for a
+typecheck-only ticket, and not for one that runs the app.
+
+Notes:
+- `--from <ref>` overrides the base ref (default: the repo's default branch via `origin/HEAD`).
+- `provisioned: false` means a copy/link/setup step failed — the worktree is still a usable
+  checkout. Surface the failing step to the user rather than silently continuing to run tests that
+  will fail for want of a dependency.
+- If the branch's worktree already exists (a prior run), `add` reuses it rather than deleting it.
+- Leave the worktree in place after the PR — the user may want to inspect it. Clean up with
+  `flo worktree remove "<branch>"` (it refuses a tree with uncommitted changes unless `--force`).
+  `flo worktree list` shows every worktree and its provisioning state.
 
 ### 3.3 Implement
 Follow the plan from the ticket.

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/eric-cielo/moflo/main/docs/Moflo_md.png?v=6" alt="MoFlo" />
+  <img src="https://raw.githubusercontent.com/eric-cielo/moflo/main/docs/Moflo_wide.png?v=7" alt="MoFlo" />
 </p>
 
 # MoFlo
@@ -349,6 +349,89 @@ Inside Claude Code, the `/flo` (or `/fl`) slash command drives GitHub issue exec
 
 Flags compose: e.g. `/flo -sd -m <issue>` runs the SDD cycle and auto-merges. Each modifier has a `--no-*` form (`--no-sdd`, `--no-verify`, `--no-merge`) to override a `moflo.yaml` default for a single run — including `--no-verify`, since verify-before-done is on by default. For full options and details, type `/flo` with no arguments — Claude Code will display the complete skill documentation. Also available as `/fl`.
 
+### Provisioned worktrees (`-w` / `flo worktree`)
+
+Running two tickets at once means two worktrees, and a bare `git worktree add` gives you a valid
+checkout that you cannot actually run: no `node_modules`, none of your gitignored `.env` files, and
+dev servers that fight the primary checkout over the same ports. `/flo -w` drives `flo worktree add`,
+which creates the worktree **and** provisions it.
+
+Provisioning is opt-in per project. **With no `worktree:` block in `moflo.yaml`, `flo worktree add`
+creates the worktree and provisions nothing** — exactly what a plain `git worktree add` would do.
+
+```yaml
+worktree:
+  dir: ../myrepo-worktrees   # default: <repo-parent>/<repo>-worktrees
+  copy: [".env", ".env.*"]   # gitignored files copied from the primary checkout
+  link: ["node_modules"]     # symlinked (junctioned on Windows) from the primary checkout
+  setup: "npm ci"            # run inside the new worktree after copy/link
+```
+
+| Key | Reach for it when | Watch out for |
+|-----|-------------------|---------------|
+| `copy` | A fresh checkout is missing gitignored config your build needs | It relocates **secrets** outside the repo, and outside its `.gitignore`. Sources must live inside the primary checkout — `../secrets` is refused. |
+| `link` | `node_modules` is large and you are not using npm workspaces | A symlinked root `node_modules` is fragile under npm/yarn workspaces — prefer `setup: npm ci` there. An existing path is never clobbered. |
+| `setup` | Install or build steps must run per workspace | A non-zero exit marks the provision failed but leaves the worktree in place. |
+
+**Ports.** MoFlo cannot rewrite your hardcoded ports — it has no way to know which files hold them.
+Instead each worktree gets a small integer, unique among live worktrees and reused when one is
+removed, exported to the `setup` command as `MOFLO_WORKTREE_INDEX`. Offset your own ports from it:
+
+```yaml
+worktree:
+  setup: "npm ci && node -e \"require('fs').writeFileSync('.env.local','PORT='+(3000+Number(process.env.MOFLO_WORKTREE_INDEX)*20))\""
+```
+
+`flo worktree remove` refuses a tree with uncommitted changes unless you pass `--force`, and names
+any gitignored files it discarded that provisioning did not create. MoFlo's own
+`.moflo/worktree.json` never counts as "uncommitted work" — otherwise every worktree it created
+would demand `--force` — but un-pushed specs under `.moflo/specs/` do.
+
+Memory needs no setup at all: durable learnings already converge across a repo's worktrees
+automatically — see [Sharing learnings across installations](#sharing-learnings-across-installations).
+
+#### Running it inside a Claude session
+
+`flo worktree` is a plain CLI command with no MCP wrapper, so it works the same whether you type it
+in a terminal or Claude runs it through Bash. `/flo -w` takes the second path — that is all the flag
+does.
+
+One thing to know if you drive it yourself from a session, and the reason `/flo -w` handles it for
+you: **Claude Code resets the Bash working directory to the project root after every call.** Two
+consequences, both silent when you get them wrong:
+
+```bash
+# ✗ the cd is gone by the next call — this resolves the WRONG repo
+cd path/to/repo
+flo worktree add feature/42-thing --json
+
+# ✓ bind the directory to the call
+cd path/to/repo && flo worktree add feature/42-thing --json
+```
+
+```bash
+# ✗ runs the tests in the PRIMARY checkout; the run goes green and the PR is empty
+cd "$WORKTREE"
+npm test
+
+# ✓ bind it, or skip cd entirely where the tool supports it
+cd "$WORKTREE" && npm test
+git -C "$WORKTREE" status
+```
+
+`flo worktree` resolves the repository from its working directory, so a call made from the wrong
+place targets a different repository — usually reported as `Not a registered worktree of this repo`,
+occasionally as work landing somewhere you did not intend. When editing files in the worktree, use
+absolute paths under the path `add` printed rather than repo-relative ones.
+
+Read the worktree location from `--json` rather than reconstructing it; the sibling-directory
+convention lives in one tested function, and a second copy of that rule will drift from it.
+
+If you are on a `flo` older than the skills synced into `.claude/` — which happens in a MoFlo source
+checkout before a change is published, or when a global `flo` lags the project's devDependency —
+the command reports `Unknown command: worktree`. `/flo -w` falls back to a plain `git worktree add`
+and tells you provisioning was skipped, rather than failing the run.
+
 ### Spec-Driven Development (SDD)
 
 `/flo` can run the full **spec → plan → (review) → implement → verify** cycle — the 2026 agentic-coding pattern — with two independent modifiers. Turning SDD on is opt-in, but once a run is armed for it (via `-sd` or `sdd.default`) **both halves are enforced**: the front half by an implement gate, the back half by verify-before-done.
@@ -637,6 +720,17 @@ flo gate prompt-reminder         # Context bracket tracking
 flo gate session-reset           # Reset gate state
 ```
 
+### Worktrees
+
+```bash
+flo worktree add feature/123-thing   # Create a worktree and provision it (alias: flo wt)
+flo worktree add feature/123 --json  # {"path":…,"branch":…,"index":0,"provisioned":true}
+flo worktree add feature/123 --from v2.1.0    # Branch off a specific ref
+flo worktree add feature/123 --no-provision   # Create it, skip copy/link/setup
+flo worktree list                    # Every worktree and its provisioning state
+flo worktree remove feature/123-thing         # Refuses a dirty tree unless --force
+```
+
 ### Diagnostics
 
 ```bash

package/dist/src/cli/commands/index.js

@@ -68,6 +68,11 @@ const commandLoaders = {
     epic: () => import('./epic.js'),
     // Spec-Driven Development artifacts (Epic #1269)
     sdd: () => import('./sdd.js'),
+    worktree: () => import('./worktree.js'),
+    // Alias key, not just `aliases: ['wt']` on the command: lazy commands resolve
+    // through `commandLoaders` by name, and an alias declared only on the command
+    // object is unreachable until something has already loaded it.
+    wt: () => import('./worktree.js'),
     // GitHub Repository Setup
     github: () => import('./github.js'),
     // /flo run ledger + per-run token rollup (#1333).

package/dist/src/cli/commands/worktree.js

@@ -0,0 +1,408 @@
+/**
+ * MoFlo Worktree Command — #1481.
+ *
+ * Lifecycle + provisioning for git worktrees, so `/flo -wt` produces a RUNNABLE
+ * workspace instead of a bare checkout. This file owns git invocation and output
+ * formatting only; every platform-sensitive filesystem decision lives in
+ * `../services/worktree-provision.ts` where a unit test can reach it (Rule #1).
+ *
+ * Usage:
+ *   flo worktree add <branch> [--from <ref>] [--no-provision] [--json]
+ *   flo worktree list [--json]
+ *   flo worktree remove <branch|path> [--force] [--json]
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { findProjectRoot } from '../services/project-root.js';
+import { loadMofloConfig } from '../config/moflo-config.js';
+import { WORKTREE_STATE_FILE_POSIX, allocateIndex, computeWorktreePath, isProvisionedPath, resolveForCompare, provisionWorktree, readWorktreeState, writeWorktreeState, } from '../services/worktree-provision.js';
+/**
+ * Run a git command. Never `shell: true` — args are passed as an array so a
+ * branch name containing shell metacharacters cannot be reinterpreted, and so
+ * the same call works identically on all three platforms.
+ */
+function git(args, cwd) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+    return {
+        ok: !result.error && result.status === 0,
+        stdout: (result.stdout ?? '').trim(),
+        stderr: (result.stderr ?? result.error?.message ?? '').trim(),
+    };
+}
+/**
+ * Parse `git worktree list --porcelain`. The first record is always the primary
+ * working tree; linked worktrees follow. Records are blank-line separated, and
+ * `branch` is a full ref (`refs/heads/x`) or absent when detached.
+ */
+function listWorktrees(repoRoot) {
+    const result = git(['worktree', 'list', '--porcelain'], repoRoot);
+    if (!result.ok)
+        return [];
+    const entries = [];
+    let current = {};
+    const flush = () => {
+        if (!current.path)
+            return;
+        entries.push({
+            path: current.path,
+            branch: current.branch ? current.branch.replace(/^refs\/heads\//, '') : null,
+            state: readWorktreeState(current.path),
+            primary: entries.length === 0,
+        });
+        current = {};
+    };
+    for (const line of result.stdout.split(/\r?\n/)) {
+        if (line.startsWith('worktree ')) {
+            flush();
+            current.path = line.slice('worktree '.length).trim();
+        }
+        else if (line.startsWith('branch ')) {
+            current.branch = line.slice('branch '.length).trim();
+        }
+    }
+    flush();
+    return entries;
+}
+/**
+ * The ref a new worktree branches from when `--from` is not given.
+ *
+ * `origin/HEAD` is the authoritative answer but is not always configured in a
+ * fresh clone, so fall back to `gh` (which the rest of this repo's tooling
+ * already assumes) and finally to whichever of `origin/main`/`origin/master`
+ * exists. Returns null when none resolve — better a clear error than silently
+ * branching off the wrong ref.
+ *
+ * Deliberately NOT shared with `getDefaultBranch` in `commands/github.ts`: that
+ * one returns a bare branch name and falls back to the literal `'main'`, which
+ * is right for generating a CI workflow and wrong here — silently branching a
+ * user's work off a guessed ref is the failure this returns null to avoid. It
+ * also tries `gh` first, where this prefers git (faster, and works offline).
+ */
+function resolveDefaultBase(repoRoot) {
+    const head = git(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'], repoRoot);
+    if (head.ok && head.stdout)
+        return head.stdout.replace(/^refs\/remotes\//, '');
+    const gh = spawnSync('gh', ['repo', 'view', '--json', 'defaultBranchRef', '--jq', '.defaultBranchRef.name'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+    });
+    if (!gh.error && gh.status === 0) {
+        const name = (gh.stdout ?? '').trim();
+        if (name)
+            return `origin/${name}`;
+    }
+    for (const candidate of ['origin/main', 'origin/master']) {
+        if (git(['rev-parse', '--verify', '--quiet', candidate], repoRoot).ok)
+            return candidate;
+    }
+    return null;
+}
+function renderSteps(steps) {
+    return steps
+        .map(step => {
+        const mark = step.status === 'done' ? '✓' : step.status === 'skipped' ? '·' : '✗';
+        const detail = step.detail ? ` (${step.detail})` : '';
+        return `  ${mark} ${step.kind} ${step.target}${detail}`;
+    })
+        .join('\n');
+}
+// =============================================================================
+// add
+// =============================================================================
+async function cmdAdd(ctx) {
+    const branch = ctx.args?.[1];
+    const json = ctx.flags.json === true;
+    if (!branch) {
+        return { success: false, message: 'Usage: flo worktree add <branch> [--from <ref>]', exitCode: 1 };
+    }
+    const repoRoot = findProjectRoot({ cwd: ctx.cwd });
+    const config = loadMofloConfig(repoRoot);
+    const worktreeConfig = config.worktree;
+    const target = computeWorktreePath(repoRoot, branch, worktreeConfig?.dir);
+    const existing = listWorktrees(repoRoot);
+    // Resolve the needle once, then compare resolved strings — realpathing both
+    // sides inside the scan costs 4 walks per worktree for the same answer.
+    const resolvedTarget = resolveForCompare(target);
+    const alreadyRegistered = existing.find(entry => resolveForCompare(entry.path) === resolvedTarget);
+    // Reuse rather than recreate: a prior run may have left work in this tree, and
+    // deleting a directory we did not just create is never this command's call.
+    if (!alreadyRegistered) {
+        if (existsSync(target)) {
+            return {
+                success: false,
+                message: `Path already exists but is not a registered worktree: ${target}\nRemove it by hand, or pass a different branch name.`,
+                exitCode: 1,
+            };
+        }
+        const explicitFrom = typeof ctx.flags.from === 'string';
+        const base = explicitFrom ? ctx.flags.from : resolveDefaultBase(repoRoot);
+        if (!base) {
+            return {
+                success: false,
+                message: 'Could not resolve a default base ref (no origin/HEAD, no gh, no origin/main or origin/master). Pass --from <ref>.',
+                exitCode: 1,
+            };
+        }
+        // Fetch so the DEFAULT base is current — branching a ticket off a stale
+        // origin/main is the failure this guards. An explicit `--from` that already
+        // resolves locally (a tag, another branch) is the user naming a specific
+        // commit, so skip the network round trip there. A fetch failure is never
+        // fatal: an offline machine should still get its worktree.
+        const baseIsLocal = git(['rev-parse', '--verify', '--quiet', base], repoRoot).ok;
+        if (!(explicitFrom && baseIsLocal))
+            git(['fetch', 'origin'], repoRoot);
+        const created = git(['worktree', 'add', '-b', branch, target, base], repoRoot);
+        if (!created.ok) {
+            return { success: false, message: `git worktree add failed: ${created.stderr}`, exitCode: 1 };
+        }
+    }
+    // Re-adding an existing worktree MUST keep its index. `existing` includes that
+    // worktree, so allocating afresh would hand it a new number and rewrite
+    // worktree.json — silently shifting every port a consumer derived from
+    // MOFLO_WORKTREE_INDEX in a tree they are already working in.
+    const index = alreadyRegistered?.state?.index ??
+        allocateIndex(existing.map(entry => entry.state?.index).filter((n) => typeof n === 'number'));
+    let provisioned = true;
+    // Distinct from `!provisioned`: skipping provisioning by request is not a
+    // failure, so it must not colour the exit code.
+    let provisionFailed = false;
+    let steps = [];
+    // Positive name, negative read (#1474): the parser turns `--no-provision`
+    // into `flags.provision = false`; an option DECLARED `no-provision` would be
+    // an unreachable no-op.
+    if (ctx.flags.provision === false) {
+        // Still record state so `list` reports the tree as moflo-created and the
+        // index stays allocated against it.
+        writeWorktreeState(target, { branch, index, primaryRoot: repoRoot, provisioned: false });
+        provisioned = false;
+    }
+    else {
+        const result = provisionWorktree({
+            primaryRoot: repoRoot,
+            worktreePath: target,
+            branch,
+            index,
+            config: worktreeConfig,
+            jsonMode: json,
+        });
+        provisioned = result.provisioned;
+        provisionFailed = !result.provisioned;
+        steps = result.steps;
+    }
+    if (json) {
+        console.log(JSON.stringify({ path: target, branch, index, provisioned, steps }));
+        return { success: !provisionFailed, exitCode: provisionFailed ? 1 : 0 };
+    }
+    const lines = [`Worktree: ${target}`, `Branch:   ${branch}`, `Index:    ${index}`];
+    if (steps.length > 0)
+        lines.push('Provisioning:', renderSteps(steps));
+    else if (ctx.flags.provision === false)
+        lines.push('Provisioning: skipped (--no-provision)');
+    else if (!worktreeConfig) {
+        lines.push('Provisioning: none configured (add a `worktree:` block to moflo.yaml)');
+    }
+    lines.push(`Remove with: flo worktree remove ${branch}`);
+    console.log(lines.join('\n'));
+    return { success: !provisionFailed, exitCode: provisionFailed ? 1 : 0 };
+}
+// =============================================================================
+// list
+// =============================================================================
+async function cmdList(ctx) {
+    const repoRoot = findProjectRoot({ cwd: ctx.cwd });
+    const entries = listWorktrees(repoRoot);
+    if (ctx.flags.json === true) {
+        console.log(JSON.stringify(entries.map(entry => ({
+            path: entry.path,
+            branch: entry.branch,
+            primary: entry.primary,
+            provisioned: entry.state?.provisioned ?? false,
+            managed: entry.state !== null,
+            index: entry.state?.index ?? null,
+        }))));
+        return { success: true, exitCode: 0 };
+    }
+    if (entries.length === 0) {
+        console.log('No worktrees.');
+        return { success: true, exitCode: 0 };
+    }
+    const lines = entries.map(entry => {
+        const tag = entry.primary
+            ? 'primary'
+            : entry.state === null
+                ? 'unmanaged'
+                : entry.state.provisioned
+                    ? `provisioned #${entry.state.index}`
+                    : `unprovisioned #${entry.state.index}`;
+        return `  ${entry.branch ?? '(detached)'}  [${tag}]\n    ${entry.path}`;
+    });
+    console.log(lines.join('\n'));
+    return { success: true, exitCode: 0 };
+}
+// =============================================================================
+// remove
+// =============================================================================
+/**
+ * Porcelain status lines that represent the USER's work.
+ *
+ * `flo worktree add` writes `.moflo/worktree.json` into the tree it creates, and
+ * `.moflo/` is not gitignored in every project — so a freshly created, untouched
+ * worktree reports as dirty. Counting moflo's own bookkeeping as user work would
+ * make `remove` demand `--force` on every worktree this command produced, which
+ * trains the user to always pass it and defeats the guard entirely.
+ *
+ * Only that ONE file is excused, never the whole `.moflo/` directory: a worktree
+ * may also hold un-pushed SDD specs and plans under `.moflo/specs/`, and those
+ * are user-authored work that must still block removal. Reaching that precision
+ * requires `-uall` at the call site — porcelain otherwise collapses an untracked
+ * directory to a single `?? .moflo/` line, which cannot be told apart from spec
+ * work living inside it.
+ *
+ * Each line is `XY <path>`; a rename is `XY <old> -> <new>`, and a path with
+ * unusual characters is quoted with C-style escapes. Only the leading two
+ * status columns are fixed width, so the path starts at index 3. A filename
+ * containing a literal ` -> ` inside quotes would mis-split — harmless, because
+ * the mis-split value simply fails to equal the state file and the line counts
+ * as user work, which is the safe direction (refuse removal, never delete).
+ */
+function userChanges(porcelain) {
+    const stateFile = WORKTREE_STATE_FILE_POSIX;
+    return porcelain
+        .split(/\r?\n/)
+        .filter(line => line.trim().length > 0)
+        .filter(line => {
+        const entry = line.slice(3).trim();
+        const target = (entry.includes(' -> ') ? entry.split(' -> ')[1] : entry).replace(/^"|"$/g, '');
+        return target !== stateFile;
+    });
+}
+/**
+ * Gitignored paths in the worktree that `remove` is about to destroy and that
+ * provisioning did not put there.
+ *
+ * `git status --porcelain` never lists ignored files, so the dirty gate above
+ * cannot see them — yet removing the worktree deletes them (stock
+ * `git worktree remove` does the same; this is inherent to worktree removal,
+ * not something --force introduces). Anything `copy:` or `link:` created is
+ * excluded: it either still exists in the primary checkout or is a symlink
+ * whose target is untouched, so naming it would be noise on every removal.
+ *
+ * Warns; never blocks. A project whose `setup:` ran `npm ci` has a legitimate
+ * `node_modules` here on every single removal, and blocking on that would just
+ * teach the user to always pass --force.
+ */
+function unprovisionedIgnoredPaths(worktreePath, config) {
+    const status = git(['status', '--porcelain', '--ignored=matching', '-uall'], worktreePath);
+    if (!status.ok)
+        return [];
+    return status.stdout
+        .split(/\r?\n/)
+        .filter(line => line.startsWith('!! '))
+        .map(line => line.slice(3).trim().replace(/^"|"$/g, ''))
+        .filter(target => target !== WORKTREE_STATE_FILE_POSIX)
+        .filter(target => !isProvisionedPath(target, config));
+}
+async function cmdRemove(ctx) {
+    const which = ctx.args?.[1];
+    const force = ctx.flags.force === true;
+    if (!which) {
+        return { success: false, message: 'Usage: flo worktree remove <branch|path> [--force]', exitCode: 1 };
+    }
+    const repoRoot = findProjectRoot({ cwd: ctx.cwd });
+    const entries = listWorktrees(repoRoot);
+    // Match by branch first, then by path. The path comparison is realpath-based,
+    // so a symlinked tempdir on macOS still matches; the needle resolves once.
+    const resolvedCandidate = resolveForCompare(path.resolve(ctx.cwd, which));
+    const match = entries.find(entry => entry.branch === which || resolveForCompare(entry.path) === resolvedCandidate);
+    if (!match) {
+        return { success: false, message: `Not a registered worktree of this repo: ${which}`, exitCode: 1 };
+    }
+    if (match.primary) {
+        return { success: false, message: 'Refusing to remove the primary working tree.', exitCode: 1 };
+    }
+    if (!force) {
+        // `-uall` so an untracked directory is not collapsed to one line — see userChanges().
+        const status = git(['status', '--porcelain', '-uall'], match.path);
+        const dirty = status.ok ? userChanges(status.stdout) : [];
+        if (dirty.length > 0) {
+            return {
+                success: false,
+                message: `Worktree has uncommitted changes: ${match.path}\n  ${dirty.slice(0, 5).join('\n  ')}\nCommit them, or re-run with --force.`,
+                exitCode: 1,
+            };
+        }
+    }
+    // Always `--force` at the git layer. `userChanges()` above is the real gate and
+    // has already refused anything the user would miss; git's own check cannot tell
+    // moflo's untracked `.moflo/worktree.json` from user work, so without this every
+    // worktree this command created would be unremovable without `--force`.
+    const doomed = unprovisionedIgnoredPaths(match.path, loadMofloConfig(repoRoot).worktree);
+    const removed = git(['worktree', 'remove', '--force', match.path], repoRoot);
+    if (!removed.ok) {
+        return { success: false, message: `git worktree remove failed: ${removed.stderr}`, exitCode: 1 };
+    }
+    if (ctx.flags.json === true) {
+        console.log(JSON.stringify({ removed: match.path, branch: match.branch, discardedIgnored: doomed }));
+        return { success: true, exitCode: 0 };
+    }
+    console.log(`Removed worktree: ${match.path}`);
+    if (doomed.length > 0) {
+        console.log(`  also discarded ${doomed.length} gitignored path(s) that were not provisioned: ` +
+            `${doomed.slice(0, 5).join(', ')}${doomed.length > 5 ? ', …' : ''}`);
+    }
+    return { success: true, exitCode: 0 };
+}
+// =============================================================================
+// Command definition
+// =============================================================================
+const HELP = `Usage: flo worktree <command>
+
+Git worktrees as provisioned workspaces (moflo.yaml \`worktree:\` block):
+  add <branch> [--from <ref>] [--no-provision] [--json]
+                           Create a worktree at <repo-parent>/<repo>-worktrees/<branch>
+                           and provision it (copy / link / setup)
+  list [--json]            List this repo's worktrees and their provisioning state
+  remove <branch|path> [--force] [--json]
+                           Remove a worktree (refuses a dirty tree without --force)
+
+With no \`worktree:\` block in moflo.yaml, \`add\` creates the worktree and
+provisions nothing.`;
+const worktreeCommand = {
+    name: 'worktree',
+    description: 'Create, list, and remove provisioned git worktrees',
+    aliases: ['wt'],
+    options: [
+        { name: 'from', description: 'Base ref for the new branch (default: origin/HEAD)', type: 'string' },
+        {
+            name: 'provision',
+            description: 'Run copy/link/setup after creating the worktree (--no-provision to skip)',
+            type: 'boolean',
+            default: true,
+        },
+        { name: 'force', description: 'Remove even with uncommitted changes', type: 'boolean' },
+        { name: 'json', description: 'Emit machine-readable JSON', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'flo worktree add feature/1481-provisioning', description: 'Create + provision a worktree' },
+        { command: 'flo worktree list', description: 'Show every worktree and its state' },
+        { command: 'flo worktree remove feature/1481-provisioning', description: 'Clean up when the PR is merged' },
+    ],
+    action: async (ctx) => {
+        const sub = ctx.args?.[0];
+        switch (sub) {
+            case 'add':
+                return cmdAdd(ctx);
+            case 'list':
+                return cmdList(ctx);
+            case 'remove':
+                return cmdRemove(ctx);
+            default:
+                console.log(HELP);
+                return { success: !sub, exitCode: sub ? 1 : 0 };
+        }
+    },
+};
+export default worktreeCommand;
+export { worktreeCommand };
+//# sourceMappingURL=worktree.js.map

package/dist/src/cli/config/moflo-config.js

@@ -190,6 +190,39 @@ function coerceMemoryBackend(raw) {
     }
     return DEFAULT_CONFIG.memory.backend;
 }
+/**
+ * Coerce a `worktree.copy` / `worktree.link` entry to a string array (#1481).
+ * Both keys accept a bare string for the common single-entry case; anything
+ * that is neither a string nor an array of strings is dropped rather than
+ * throwing — a malformed entry must never stop a consumer's config loading.
+ */
+function coercePathList(raw) {
+    const list = typeof raw === 'string' ? [raw] : Array.isArray(raw) ? raw : undefined;
+    if (!list)
+        return undefined;
+    const cleaned = list
+        .filter((v) => typeof v === 'string')
+        .map(v => v.trim())
+        .filter(v => v.length > 0);
+    return cleaned.length > 0 ? cleaned : undefined;
+}
+/**
+ * Parse the optional `worktree:` block (#1481). Returns `undefined` when the
+ * block is absent or contains nothing usable, so "not configured" stays
+ * distinguishable from "configured empty". Unknown sub-keys are ignored.
+ */
+function parseWorktreeConfig(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const block = raw;
+    const dir = typeof block.dir === 'string' && block.dir.trim().length > 0 ? block.dir.trim() : undefined;
+    const copy = coercePathList(block.copy);
+    const link = coercePathList(block.link);
+    const setup = typeof block.setup === 'string' && block.setup.trim().length > 0 ? block.setup.trim() : undefined;
+    if (!dir && !copy && !link && !setup)
+        return undefined;
+    return { ...(dir && { dir }), ...(copy && { copy }), ...(link && { link }), ...(setup && { setup }) };
+}
 /**
  * Parse raw config object into typed config, merging with defaults.
  */
@@ -265,6 +298,10 @@ function mergeConfig(raw, root) {
                 return typeof v === 'string' && v.trim().length > 0 ? v.trim() : undefined;
             })(),
         },
+        // #1481 — optional worktree provisioning. The whole block stays `undefined`
+        // when absent so an existing consumer `moflo.yaml` is unaffected, and so
+        // `flo worktree add` can distinguish "not configured" from "configured empty".
+        worktree: parseWorktreeConfig(raw.worktree),
         hooks: {
             pre_edit: raw.hooks?.pre_edit ?? raw.hooks?.preEdit ?? DEFAULT_CONFIG.hooks.pre_edit,
             post_edit: raw.hooks?.post_edit ?? raw.hooks?.postEdit ?? DEFAULT_CONFIG.hooks.post_edit,
@@ -508,6 +545,26 @@ memory:
   #   worktrees never produce. Conductor recipe: set hydrate_from AND snapshot_to
   #   to the SAME absolute path. Overridable per-process via MOFLO_SNAPSHOT_TO.
 
+# Worktree provisioning (#1481) — makes "flo worktree add" (and "/flo -wt")
+# produce a RUNNABLE workspace, not just a valid checkout. Entirely optional:
+# with this block absent, a new worktree is created and nothing is provisioned.
+# worktree:
+#   dir: ../myrepo-worktrees
+#     Where worktrees are created. Defaults to <repo-parent>/<repo>-worktrees.
+#   copy: [".env", ".env.*"]
+#     Gitignored files a fresh checkout lacks, copied from the primary checkout.
+#     Sources must live inside the primary checkout. NOTE: this relocates secret
+#     material to a directory OUTSIDE the repo and outside its .gitignore — keep
+#     the worktree dir out of any repo you commit.
+#   link: ["node_modules"]
+#     Symlinked (junctioned on Windows) from the primary checkout. Opt-in with no
+#     default: a symlinked root node_modules is fragile under npm workspaces —
+#     prefer "setup: npm ci" if your project uses them.
+#   setup: "npm ci"
+#     Run inside the new worktree after copy/link, with MOFLO_WORKTREE_INDEX in
+#     its environment (a small integer unique among live worktrees) so a project
+#     with fixed dev-server ports can offset them per workspace.
+
 # Hook toggles (all on by default — disable to slim down)
 hooks:
   pre_edit: true               # Track file edits for learning

package/dist/src/cli/services/worktree-provision.js

@@ -0,0 +1,400 @@
+/**
+ * Worktree provisioning (#1481).
+ *
+ * `/flo -wt` and `flo worktree add` create a git worktree; on its own that is a
+ * valid checkout and an unrunnable workspace — no `node_modules`, none of the
+ * gitignored `.env` files, and no notion that a second worktree's dev servers
+ * will collide with the first on fixed ports. This service closes that gap,
+ * driven by the optional `worktree:` block in `moflo.yaml`.
+ *
+ * Every platform-sensitive decision lives here rather than in the command, so
+ * the Windows-vs-POSIX branches are reachable from a unit test (Rule #1):
+ *   - paths built with `path.*`, never separator concatenation
+ *   - directory links are junctions on Windows (no admin/developer mode needed,
+ *     and the target must be absolute), plain symlinks on POSIX
+ *   - copies via `fs.cpSync`; no `cp`/`ln -s`/`mkdir -p`/`find` shell-outs
+ *   - `setup` runs through a shell on both platforms (it is a user-authored
+ *     command string, not an argv array) — see `runSetup`
+ *   - containment checks realpath BOTH sides before comparing (#1145: macOS
+ *     `/var/folders` vs `/private/var/folders` otherwise false-positives)
+ */
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, symlinkSync, } from 'node:fs';
+import path from 'node:path';
+import { atomicWriteFileSync } from '../shared/utils/atomic-file-write.js';
+import { globToRegExp } from '../guidance/retriever.js';
+/** Relative path of the per-worktree state file, from the worktree root. */
+export const WORKTREE_STATE_FILE = path.join('.moflo', 'worktree.json');
+/**
+ * The same path in git's spelling. `git status --porcelain` reports forward
+ * slashes on every platform, so a caller comparing against porcelain output
+ * needs this form rather than the host-separator one above.
+ */
+export const WORKTREE_STATE_FILE_POSIX = '.moflo/worktree.json';
+/**
+ * Turn a branch name into a single flat directory name. Both separators are
+ * replaced: a branch is always `/`-delimited, but a caller may hand us a
+ * Windows-style string, and `\` is invalid in an NTFS directory name anyway.
+ */
+export function slugifyBranch(branch) {
+    return branch.replace(/[\\/]/g, '-');
+}
+/**
+ * Resolve where a worktree for `branch` belongs.
+ *
+ * Default: `<repo-parent>/<repo-basename>-worktrees/<slugged-branch>` — a
+ * sibling of the checkout, so it is never inside the repo (and so never picked
+ * up by the repo's own tooling). `configuredDir` overrides the parent directory
+ * and is resolved relative to `repoRoot` when relative.
+ */
+export function computeWorktreePath(repoRoot, branch, configuredDir) {
+    const parent = configuredDir
+        ? path.resolve(repoRoot, configuredDir)
+        : path.join(path.dirname(repoRoot), `${path.basename(repoRoot)}-worktrees`);
+    return path.join(parent, slugifyBranch(branch));
+}
+/**
+ * Smallest non-negative integer not already taken. Reusing a freed slot (rather
+ * than incrementing a counter) keeps the index small and stable, which matters
+ * because consumers offset fixed ports from it — an unbounded counter would
+ * eventually push a derived port out of range.
+ */
+export function allocateIndex(existing) {
+    const taken = new Set(existing.filter(n => Number.isInteger(n) && n >= 0));
+    let candidate = 0;
+    while (taken.has(candidate))
+        candidate++;
+    return candidate;
+}
+/**
+ * Resolve a path as far as it exists. `realpathSync` throws on a missing path,
+ * but a containment check must still work for a destination that has not been
+ * created yet — so walk up to the nearest existing ancestor, resolve that, and
+ * re-append the remainder.
+ */
+function realpathBestEffort(target) {
+    let current = path.resolve(target);
+    const trailing = [];
+    // Bounded by the path depth: each iteration removes one segment, and
+    // `path.dirname` is a fixed point at the filesystem root.
+    for (;;) {
+        if (existsSync(current))
+            return path.join(realpathSync(current), ...trailing.reverse());
+        const parent = path.dirname(current);
+        if (parent === current)
+            return path.resolve(target);
+        trailing.push(path.basename(current));
+        current = parent;
+    }
+}
+/**
+ * A canonical key for path identity: realpath'd, and case-folded on the two
+ * platforms whose filesystems are case-insensitive by default.
+ *
+ * Exported so a caller scanning a list resolves its needle ONCE and compares
+ * keys, rather than realpathing both sides on every iteration. Case-folding is
+ * what makes plain string equality safe here — `C:\Repo` and `C:\repo` are the
+ * same directory on Windows, and `/Users/x/Repo` and `/Users/x/repo` are the
+ * same directory on stock APFS.
+ */
+export function resolveForCompare(target) {
+    const resolved = realpathBestEffort(target);
+    return process.platform === 'win32' || process.platform === 'darwin'
+        ? resolved.toLowerCase()
+        : resolved;
+}
+/**
+ * Is `candidate` inside `root`? Both sides go through
+ * {@link resolveForCompare} first — the #1145 shape, where an unresolved
+ * `/var/folders/...` compared against a resolved `/private/var/folders/...` on
+ * macOS made two identical paths look different.
+ */
+export function isInside(root, candidate) {
+    const resolvedRoot = resolveForCompare(root);
+    const resolvedCandidate = resolveForCompare(candidate);
+    if (resolvedCandidate === resolvedRoot)
+        return true;
+    const rel = path.relative(resolvedRoot, resolvedCandidate);
+    // No `rel.length > 0` guard: `path.relative` returns '' for two spellings of
+    // the SAME directory that the equality check above missed, and treating that
+    // as "not inside" would break every identity test built on this.
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+/**
+ * Expand one `copy:` entry against the primary checkout.
+ *
+ * Glob support is deliberately narrow — a single `*` in the final segment, so
+ * `.env.*` works — because the alternative is either a shell-out (`find` does
+ * not exist on Windows) or a full tree walk on a pattern the user thought was
+ * cheap. A pattern needing more than this returns nothing rather than silently
+ * matching a subset; the caller reports it as skipped.
+ */
+function expandCopyEntry(primaryRoot, entry) {
+    const normalized = entry.split(/[\\/]/).filter(Boolean);
+    if (normalized.length === 0)
+        return [];
+    const last = normalized[normalized.length - 1];
+    if (!last.includes('*')) {
+        const full = path.join(primaryRoot, ...normalized);
+        return existsSync(full) ? [full] : [];
+    }
+    const dir = path.join(primaryRoot, ...normalized.slice(0, -1));
+    if (!existsSync(dir))
+        return [];
+    // Reuse the guidance retriever's translator rather than hand-rolling one: it
+    // is anchored, escapes every metacharacter, and was already hardened for the
+    // `docs/*.md` matching `docsXmd` bug. Its `*` becomes `[^/]*`, which is exact
+    // here because these patterns match bare readdir NAMES, never a path.
+    const pattern = globToRegExp(last);
+    return readdirSync(dir)
+        .filter(name => pattern.test(name))
+        .sort()
+        .map(name => path.join(dir, name));
+}
+/**
+ * Does a config entry escape `root` before any symlink resolution?
+ *
+ * Deliberately LEXICAL, unlike {@link isInside}. "Did the user write a path that
+ * climbs out of the tree" is a property of the string they wrote, and resolving
+ * it first gets the answer wrong in the normal case: on a re-add, the worktree's
+ * `node_modules` is already a symlink into the primary checkout, so realpathing
+ * the destination reports it as outside the worktree and rejects a link that is
+ * exactly the one provisioning just made. A primary checkout whose own
+ * `node_modules` is a symlink (pnpm, a shared store) fails the same way.
+ */
+function escapesRoot(root, entry) {
+    const rel = path.relative(root, path.resolve(root, entry));
+    return rel.startsWith('..') || path.isAbsolute(rel);
+}
+/**
+ * Copy the configured gitignored material into the new worktree.
+ *
+ * Sources are guarded on both ends: each must resolve inside the primary
+ * checkout (so `../secrets` is rejected), and the destination is always the
+ * worktree we just created. A missing source is skipped rather than fatal —
+ * `.env.local` legitimately does not exist on every machine.
+ */
+function runCopy(primaryRoot, worktreePath, entries) {
+    const steps = [];
+    for (const entry of entries) {
+        if (!isInside(primaryRoot, path.resolve(primaryRoot, entry))) {
+            steps.push({
+                kind: 'copy',
+                target: entry,
+                status: 'failed',
+                detail: 'resolves outside the primary checkout',
+            });
+            continue;
+        }
+        const matches = expandCopyEntry(primaryRoot, entry);
+        if (matches.length === 0) {
+            steps.push({ kind: 'copy', target: entry, status: 'skipped', detail: 'no match' });
+            continue;
+        }
+        for (const source of matches) {
+            const dest = path.join(worktreePath, path.relative(primaryRoot, source));
+            try {
+                mkdirSync(path.dirname(dest), { recursive: true });
+                cpSync(source, dest, { recursive: true });
+                steps.push({ kind: 'copy', target: path.relative(primaryRoot, source), status: 'done' });
+            }
+            catch (error) {
+                steps.push({
+                    kind: 'copy',
+                    target: path.relative(primaryRoot, source),
+                    status: 'failed',
+                    detail: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    return steps;
+}
+/**
+ * The `fs.symlinkSync` type argument for a directory link on this platform.
+ *
+ * Windows gets a junction: unlike a `'dir'` symlink it needs no admin rights or
+ * developer mode. Exported and pure so the Windows branch is assertable from a
+ * unit test on any host — the alternative, spying on an ESM `fs` export, is not
+ * possible, and gating the assertion on a Windows runner would leave the branch
+ * unverified on the two CI legs that run most often.
+ */
+export function linkTypeForPlatform(platform) {
+    return platform === 'win32' ? 'junction' : undefined;
+}
+/**
+ * Link the configured paths from the primary checkout into the new worktree.
+ * The target is resolved to an ABSOLUTE path before the call on every platform:
+ * a relative target silently produces a broken junction on Windows.
+ */
+function runLink(primaryRoot, worktreePath, entries) {
+    const steps = [];
+    const linkType = linkTypeForPlatform(process.platform);
+    for (const entry of entries) {
+        const source = path.resolve(primaryRoot, entry);
+        const dest = path.resolve(worktreePath, entry);
+        // Guard BOTH ends against an escaping entry: `link: ["../x"]` would
+        // otherwise source from outside the checkout and write the link outside the
+        // worktree. Lexical on purpose — see escapesRoot().
+        if (escapesRoot(primaryRoot, entry) || escapesRoot(worktreePath, entry)) {
+            steps.push({
+                kind: 'link',
+                target: entry,
+                status: 'failed',
+                detail: 'resolves outside the primary checkout or the worktree',
+            });
+            continue;
+        }
+        if (!existsSync(source)) {
+            steps.push({ kind: 'link', target: entry, status: 'skipped', detail: 'no such path' });
+            continue;
+        }
+        // lstat, not existsSync: a broken symlink left by an earlier run still
+        // occupies the name, and clobbering it is not ours to decide.
+        let occupied = false;
+        try {
+            lstatSync(dest);
+            occupied = true;
+        }
+        catch {
+            occupied = false;
+        }
+        if (occupied) {
+            steps.push({ kind: 'link', target: entry, status: 'skipped', detail: 'already exists' });
+            continue;
+        }
+        try {
+            mkdirSync(path.dirname(dest), { recursive: true });
+            symlinkSync(source, dest, linkType);
+            steps.push({ kind: 'link', target: entry, status: 'done' });
+        }
+        catch (error) {
+            steps.push({
+                kind: 'link',
+                target: entry,
+                status: 'failed',
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return steps;
+}
+/**
+ * Run the configured `setup` command inside the new worktree.
+ *
+ * `shell: true` on BOTH platforms, unlike the daemon-spawning code this repo
+ * models elsewhere. That rule ("shell on Windows, detached on POSIX") is about
+ * spawning a known binary with an argv array; `setup` is a user-authored shell
+ * command *string* from `moflo.yaml` — `npm ci && npm run build` is a legitimate
+ * value, and it needs `cmd.exe` or `/bin/sh` to mean anything. Running it
+ * without a shell would exec a file literally named `npm ci && npm run build`.
+ * On Windows a shell is required regardless, since `npm` there is `npm.cmd`.
+ * Trust boundary: the same as a `package.json` script — the project's own config.
+ *
+ * `jsonMode` sends the child's stdout to our stderr so a `--json` caller still
+ * gets parseable JSON on stdout.
+ */
+function runSetup(worktreePath, command, index, jsonMode) {
+    const result = spawnSync(command, {
+        cwd: worktreePath,
+        shell: true,
+        stdio: jsonMode ? ['ignore', 2, 2] : 'inherit',
+        env: { ...process.env, MOFLO_WORKTREE_INDEX: String(index) },
+    });
+    if (result.error) {
+        return { kind: 'setup', target: command, status: 'failed', detail: result.error.message };
+    }
+    if (result.status !== 0) {
+        return {
+            kind: 'setup',
+            target: command,
+            status: 'failed',
+            detail: `exited with code ${result.status ?? 'null'}`,
+        };
+    }
+    return { kind: 'setup', target: command, status: 'done' };
+}
+/**
+ * Provision a freshly created worktree: copy, then link, then setup.
+ *
+ * Order matters — `setup` (typically `npm ci`) may depend on the `.env` files
+ * `copy` brings in, and must not race the `link` that would otherwise supply
+ * `node_modules`. A failed step never unwinds the worktree: it is a valid
+ * checkout either way, and deleting a tree the user may have started working in
+ * is far worse than leaving it under-provisioned.
+ */
+export function provisionWorktree(opts) {
+    const { primaryRoot, worktreePath, branch, index, config, jsonMode = false } = opts;
+    const steps = [];
+    if (config?.copy?.length)
+        steps.push(...runCopy(primaryRoot, worktreePath, config.copy));
+    if (config?.link?.length)
+        steps.push(...runLink(primaryRoot, worktreePath, config.link));
+    if (config?.setup)
+        steps.push(runSetup(worktreePath, config.setup, index, jsonMode));
+    const provisioned = steps.every(step => step.status !== 'failed');
+    writeWorktreeState(worktreePath, { branch, index, primaryRoot, provisioned });
+    return { provisioned, steps };
+}
+/**
+ * Did `copy:`/`link:` put this worktree-relative path there?
+ *
+ * Lives here, next to {@link provisionWorktree}, because answering it needs the
+ * same glob translation provisioning used: a raw config entry is not a filename.
+ * Comparing `.env.*` literally against the `.env.local` git reports never
+ * matches, which would blame provisioning's own files on the user.
+ *
+ * Every ancestor prefix is tested, so a directory entry (glob or literal) also
+ * claims the files inside it — `git status -uall` reports those individually.
+ *
+ * @param target a path in git's spelling (forward slashes), relative to the worktree
+ */
+export function isProvisionedPath(target, config) {
+    const entries = [...(config?.copy ?? []), ...(config?.link ?? [])]
+        .map(entry => entry.split(/[\\/]/).filter(Boolean).join('/'))
+        .filter(Boolean);
+    if (entries.length === 0)
+        return false;
+    const segments = target.split('/').filter(Boolean);
+    for (const entry of entries) {
+        const matcher = entry.includes('*') ? globToRegExp(entry) : null;
+        for (let depth = 1; depth <= segments.length; depth++) {
+            const prefix = segments.slice(0, depth).join('/');
+            if (matcher ? matcher.test(prefix) : prefix === entry)
+                return true;
+        }
+    }
+    return false;
+}
+/** Write `.moflo/worktree.json` into a worktree. Atomic — the daemon may read it. */
+export function writeWorktreeState(worktreePath, state) {
+    const statePath = path.join(worktreePath, WORKTREE_STATE_FILE);
+    mkdirSync(path.dirname(statePath), { recursive: true });
+    atomicWriteFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+/**
+ * Read a worktree's moflo state. `null` means moflo did not create this tree —
+ * which is exactly how `flo worktree list` reports an externally-created
+ * worktree as unprovisioned, so a malformed file is treated the same as a
+ * missing one rather than failing the listing.
+ */
+export function readWorktreeState(worktreePath) {
+    const statePath = path.join(worktreePath, WORKTREE_STATE_FILE);
+    if (!existsSync(statePath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(statePath, 'utf8'));
+        if (typeof parsed.branch !== 'string' || !Number.isInteger(parsed.index))
+            return null;
+        return {
+            branch: parsed.branch,
+            index: parsed.index,
+            primaryRoot: typeof parsed.primaryRoot === 'string' ? parsed.primaryRoot : '',
+            provisioned: parsed.provisioned === true,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=worktree-provision.js.map

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.12.12';
+export const VERSION = '4.13.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.12.12",
+  "version": "4.13.0",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -99,7 +99,7 @@
     "@typescript-eslint/parser": "^8.65.0",
     "eslint": "^10.8.0",
     "glob": "^11.1.0",
-    "moflo": "^4.12.11",
+    "moflo": "^4.12.12",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"