@ramon-sg/issue-flow 0.3.2 → 0.3.4

package/README.md

@@ -75,7 +75,7 @@ Qué hace, en orden:
    - Si el PR se mergeó y no queda trabajo sin pushear, ofrece borrar el worktree y la rama.
    - Si no, dice cómo retomar.
 
-**Permisos:** si el repo tiene [`claude-repo-guard`](https://github.com/ramon-sg/claude-repo-guard), Claude se abre en modo auto con su contexto (lo mismo que `claude:auto`). Con `--ask-permissions` se abre con tus settings, y con `--free` sin sandbox ni preguntas (como `claude:free`). Sin `claude-repo-guard`, se abre con tus settings. `--plan` devuelve esos mismos argumentos en `claudeArgs`. El atajo es `npm run issue:start:free 42`. Con npm, las opciones van después de `--` (`npm run issue:start -- 42 --free`); con pnpm, bun o yarn no hace falta. La tabla de cada administrador está en [Flujos](docs/flujos.md#administradores). `issue-flow issue start --help` explica cada opción.
+**Permisos:** si el repo tiene [`claude-repo-guard`](https://github.com/ramon-sg/claude-repo-guard), Claude se abre en modo auto con su contexto (lo mismo que `claude:auto`). Con `--ask-permissions` se abre con tus settings, con `--free` sin sandbox ni preguntas (como `claude:free`), y con `--free --no-repo-deny` también sin los `deny` del `.claude/settings.json` del repo, que vuelven al salir ([qué quita cada modo](docs/flujos/terminal.md#opciones)). Sin `claude-repo-guard`, se abre con tus settings. `--plan` devuelve esos mismos argumentos en `claudeArgs`. El atajo es `npm run issue:start:free 42`. Con npm, las opciones van después de `--` (`npm run issue:start -- 42 --free`); con pnpm, bun o yarn no hace falta. La tabla de cada administrador está en [Flujos](docs/flujos.md#administradores). `issue-flow issue start --help` explica cada opción.
 
 ### Con la nube y con otras herramientas
 
@@ -119,7 +119,7 @@ Lo propio de cada repo (instalar, armar la base, levantar Docker) son **pasos**
 ```
 
 - **Cuándo corren:** `issue start` corre el `setup` en cada worktree nuevo, después de copiar `.worktreeinclude`. El hook `session` lo corre al abrir Claude en un worktree. El `teardown` corre antes de borrar un worktree, con `prune` o al limpiar después del merge.
-- **De dónde salen:** siempre de la config del checkout principal, nunca de la del worktree. Así una rama no puede sumar comandos a su propio setup. En la nube no hay otro checkout: ahí la config es la de la rama de la sesión.
+- **De dónde salen:** del `.agents/flow.json` de `origin/<base>`, nunca del worktree. Así una rama no puede sumar comandos a su propio setup, y un checkout principal que quedó atrás no deja al worktree sin su `install`. Si los pasos del checkout principal son otros, `issue-flow` lo avisa. Sin `origin/<base>`, o si ahí el archivo no es válido, usa los del checkout principal. Sin pasos, `worktree setup` e `issue start` dicen de qué archivo los leyeron. En la nube no hay otro checkout: ahí la config es la de la rama de la sesión. El teardown sigue usando la config del checkout principal.
 - **Pueden correr más de una vez:** `issue start` y el hook `session` corren el `setup` del mismo worktree, así que un paso sin `once` tiene que poder repetirse.
 - **`trusted`:** el paso corre solo si el código del worktree está en `origin/<base>` y no tiene cambios. Es para un install, que corre los scripts de `package.json` de esa rama. En la nube corre siempre, porque la máquina es descartable.
 - **`once`:** el paso no se repite una vez que funcionó (deja una marca en el git dir del worktree).

package/dist/cli-flags.d.ts

@@ -50,6 +50,9 @@ export declare const OPTIONS: {
     readonly free: {
         readonly type: "boolean";
     };
+    readonly "no-repo-deny": {
+        readonly type: "boolean";
+    };
     readonly plan: {
         readonly type: "boolean";
     };

package/dist/cli-flags.js

@@ -14,6 +14,7 @@ export const OPTIONS = {
     "no-launch": { type: "boolean" },
     "ask-permissions": { type: "boolean" },
     free: { type: "boolean" },
+    "no-repo-deny": { type: "boolean" },
     plan: { type: "boolean" },
     cloud: { type: "boolean" },
     here: { type: "boolean" },
@@ -38,6 +39,7 @@ export const COMMAND_FLAGS = {
         "no-launch",
         "ask-permissions",
         "free",
+        "no-repo-deny",
         "plan",
         "cloud",
         "here",

package/dist/cli.js

@@ -82,8 +82,10 @@ export function ownFlags(command, flags) {
 function permissionsOf(flags) {
     if (flags["ask-permissions"] && flags.free)
         throw new UsageError("use --ask-permissions or --free, not both.");
+    if (flags["no-repo-deny"] && !flags.free)
+        throw new UsageError("--no-repo-deny goes with --free.");
     if (flags.free)
-        return "free";
+        return flags["no-repo-deny"] ? "free-no-repo-deny" : "free";
     return flags["ask-permissions"] ? "ask" : "default";
 }
 /**
@@ -99,18 +101,18 @@ function startArgs(flags, rest) {
         throw new UsageError("issue start needs one issue number.");
     if (flags.resume !== undefined && flags.new)
         throw new UsageError("--resume does not go with --new.");
-    const conflicting = flags.branch || flags["dry-run"] || flags.yes || flags.resume !== undefined || flags.new;
+    const conflicting = flags.branch || flags["dry-run"] || flags.yes || flags.resume !== undefined || flags.new || flags["no-repo-deny"];
     if (flags.plan && conflicting)
-        throw new UsageError("--plan does not go with --branch, --dry-run, --yes, --resume nor --new.");
+        throw new UsageError("--plan does not go with --branch, --dry-run, --yes, --resume, --new nor --no-repo-deny.");
     cloudArgs(flags);
     return Number(text);
 }
 /** The flags that do not go together with each way of starting, besides each other. */
 const EXCLUSIVE = {
-    cloud: ["branch", "plan", "ask-permissions", "free"],
-    here: ["branch", "plan", "ask-permissions", "free"],
+    cloud: ["branch", "plan", "ask-permissions", "free", "no-repo-deny"],
+    here: ["branch", "plan", "ask-permissions", "free", "no-repo-deny"],
     teleport: ["plan", "new", "no-launch"],
-    adopt: ["branch", "plan", "resume", "new", "ask-permissions", "free"],
+    adopt: ["branch", "plan", "resume", "new", "ask-permissions", "free", "no-repo-deny"],
 };
 /**
  * Checks `--cloud`, `--here`, `--teleport` and `--adopt`: at most one, and none with the

package/dist/commands/adapter.js

@@ -22,11 +22,11 @@ import { canonicalPath, dockerCleanup } from "../docker.js";
 import { checkoutRoot, currentBranch, locateRepo } from "../git.js";
 import { issueOfBranch } from "../issue-text.js";
 import { inPath } from "../launch.js";
-import { UsageError, warn } from "../output.js";
+import { warn } from "../output.js";
 import { releasePortClaims } from "../ports.js";
 import { copyWorktreeIncludes } from "../start-place.js";
 import { StartError } from "../start-state.js";
-import { runSetup, teardownWorktree } from "../worktree-steps.js";
+import { checkOnly, runSetup, teardownWorktree } from "../worktree-steps.js";
 import { issueStart } from "./issue-start.js";
 import { stepPlace } from "./worktree.js";
 /** Orca's CLI, which knows which issue a workspace came from; `ISSUE_FLOW_ORCA_CLI` changes it. */
@@ -162,9 +162,7 @@ function linkedPlace(options, out) {
  * @example await adapterSetup(options, out)
  */
 export async function adapterSetup(options, out) {
-    const names = options.config.worktrees.setup.map((step) => step.name);
-    if (options.only !== null && !names.includes(options.only))
-        throw new UsageError(`--only expects a setup step of .agents/flow.json (${names.join(", ") || "it has none"}): ${options.only}`);
+    checkOnly(stepPlace(options, out), options.only);
     const place = linkedPlace(options, out);
     if (place === null)
         return 0;

package/dist/commands/claude-hooks.js

@@ -111,7 +111,7 @@ export async function worktreeCreate(input, config, cwd, out) {
             throw new StartError(`could not make the worktree ${path}: ${add.err}`);
         copyWorktreeIncludes(mainRoot, path, stderrOnly);
     }
-    await runSetup({ root: path, mainRoot, base, config, out: stderrOnly, remote: false }, null);
+    await runSetup({ root: path, mainRoot, base, config, out: stderrOnly, remote: false }, null, true);
     out.stdout(`${path}\n`);
     return 0;
 }

package/dist/commands/issue-start.js

@@ -17,6 +17,7 @@ import { inPath, launchSession, permissionArgs, teleportSession } from "../launc
 import { emitJson, warn } from "../output.js";
 import { findOpenPlan, findPlan } from "../plan-doc.js";
 import { proposeBranches } from "../propose.js";
+import { liftRepoDeny, restoreRepoDeny } from "../repo-deny.js";
 import { lockWorktree, unlockWorktree } from "../session-lock.js";
 import { afterSession, choosePlace, copyWorktreeIncludes, prepareBranch, publish } from "../start-place.js";
 import { chooseAdopted, fetchOrigin, finishHere, launchCloud, placeAdopted, placeCloud, placeHere, prCloudSession, prepareHere, readAdopted, renameAdopted, withoutFresh, } from "../start-modes.js";
@@ -245,6 +246,31 @@ function question(state) {
         };
     return { text: "Start the issue?", declined: "did nothing." };
 }
+/**
+ * Before opening Claude: puts back the repo's deny rules a session whose terminal was
+ * closed left out, and with `--free --no-repo-deny` takes them out for this one. With
+ * another session in the worktree it touches nothing, as it may be using them.
+ * @param state - The start.
+ * @param lock - The worktree lock.
+ * @returns What to put back, or null if nothing was taken out.
+ */
+function liftForSession(state, lock) {
+    const { out, commonDir, branch } = state;
+    const wanted = state.options.permissions === "free-no-repo-deny";
+    if (lock.shared) {
+        if (wanted)
+            warn(out, "another session uses this worktree: the repo's deny rules stay.");
+        return null;
+    }
+    const leftover = restoreRepoDeny(commonDir, branch, state.workDir, null);
+    if (leftover !== null)
+        warn(out, leftover);
+    if (!wanted)
+        return null;
+    const { message, saved } = liftRepoDeny(state.workDir, commonDir, branch);
+    out.stdout(`${message}\n`);
+    return saved;
+}
 /**
  * Opens Claude in the place, locking a worktree meanwhile, and then offers the cleanup.
  * Without `claude` or with `--no-launch`, says how to open it.
@@ -264,6 +290,7 @@ async function openSession(state) {
     process.once("exit", release);
     forgetTypedAhead();
     const permissions = permissionArgs(options.permissions, state.workDir, state.mainRoot).args;
+    const lifted = liftForSession(state, lock);
     if (options.teleport) {
         out.stdout(`Bringing the cloud session${state.cloudSession === null ? "" : ` (${state.cloudSession})`}. To resume it later: claude --resume\n`);
         teleportSession(state.workDir, permissions, state.cloudSession);
@@ -278,6 +305,11 @@ async function openSession(state) {
             color: issueColor(state.labels, options.config.colors)?.color ?? null,
             permissions,
         }, (text) => warn(out, text));
+    if (lifted !== null) {
+        const problem = restoreRepoDeny(state.commonDir, state.branch, state.workDir, lifted);
+        if (problem !== null)
+            warn(out, problem);
+    }
     release();
     process.off("exit", release);
     await afterSession(state, lock);

package/dist/commands/session.js

@@ -90,7 +90,7 @@ export async function session(options, out) {
     if (remote)
         cloudSession(root, say);
     if (root !== mainRoot || remote)
-        await runSetup(place, null);
+        await runSetup(place, null, true);
     const unstarted = !remote && root !== mainRoot ? unstartedIssue(root) : null;
     if (unstarted !== null)
         say(`issue #${unstarted} was not started: its branch is not published and has no draft PR. Before working, run the start-issue skill (${unstarted}).`);

package/dist/commands/worktree.js

@@ -12,11 +12,11 @@ import { resolve } from "node:path";
 import { canonicalPath, dockerCleanup } from "../docker.js";
 import { checkoutRoot, git, isClean, locateRepo, safeToDelete, worktrees } from "../git.js";
 import { forgetSession } from "../launch.js";
-import { UsageError, warn } from "../output.js";
+import { warn } from "../output.js";
 import { claimPortBase, nextPortBase, portBase } from "../ports.js";
 import { isStale, LOCK_REASON } from "../session-lock.js";
 import { StartError } from "../start-state.js";
-import { runSetup, teardownWorktree } from "../worktree-steps.js";
+import { checkOnly, runSetup, teardownWorktree } from "../worktree-steps.js";
 /** The reason `claude --worktree` locks the worktrees it makes while its session lives. */
 const CLAUDE_LOCK_REASON = "claude session";
 /**
@@ -57,10 +57,9 @@ export function stepPlace(options, out) {
  * @example await worktreeSetup(options, out)
  */
 export async function worktreeSetup(options, out) {
-    const names = options.config.worktrees.setup.map((step) => step.name);
-    if (options.only !== null && !names.includes(options.only))
-        throw new UsageError(`--only expects a setup step of .agents/flow.json (${names.join(", ") || "it has none"}): ${options.only}`);
-    return (await runSetup(stepPlace(options, out), options.only)) ? 0 : 1;
+    const place = stepPlace(options, out);
+    checkOnly(place, options.only);
+    return (await runSetup(place, options.only)) ? 0 : 1;
 }
 /**
  * `worktree teardown [--path <dir>]`: cleans a worktree before deleting it (its steps, its

package/dist/launch.d.ts

@@ -3,8 +3,12 @@ import { type StartMode } from "./issue-text.js";
 export declare const AUTO_MODE_FILE = ".claude/repo-guard.auto-mode.json";
 /** Folder, inside the shared `.git`, with one file per branch holding its session id. */
 export declare const SESSIONS_DIR = "issue-flow-sessions";
-/** How Claude asks for permissions: chosen by the flags, or the default. */
-export type Permissions = "default" | "ask" | "free";
+/**
+ * How Claude asks for permissions: chosen by the flags, or the default. `free-no-repo-deny`
+ * is `--free --no-repo-deny`: the same arguments as `free`, and `issue start` also takes the
+ * repo's deny rules out while Claude runs (see repo-deny.ts).
+ */
+export type Permissions = "default" | "ask" | "free" | "free-no-repo-deny";
 /** The arguments of the permission mode, and how the summary names it. */
 export interface PermissionArgs {
     args: string[];
@@ -53,7 +57,16 @@ export declare function sessionExists(id: string): boolean;
  */
 export declare function savedSession(commonDir: string, branch: string): string | null;
 /**
- * Forgets a branch's session id, once its work is gone.
+ * The note `--no-repo-deny` keeps while the repo's deny rules are out, next to the
+ * branch's session id.
+ * @param commonDir - The shared `.git`.
+ * @param branch - The branch.
+ * @returns The path.
+ * @example noteFile("/repo/.git", "feat/42-x") // "/repo/.git/issue-flow-sessions/feat+42-x.repo-deny.json"
+ */
+export declare function noteFile(commonDir: string, branch: string): string;
+/**
+ * Forgets a branch's session id (and its `--no-repo-deny` note), once its work is gone.
  * @param commonDir - The shared `.git`.
  * @param branch - The branch.
  * @example forgetSession("/repo/.git", "feat/42-x")

package/dist/launch.js

@@ -1,8 +1,8 @@
 /**
  * @file Opens Claude for an issue in the same terminal. The permission mode follows
  * `claude-repo-guard` when the repo has it: auto mode with its classifier context by
- * default, plain `claude` with `--ask-permissions`, and no sandbox nor questions with
- * `--free`. Each branch keeps its session id, so starting the issue again resumes it.
+ * default, plain `claude` with `--ask-permissions`, no sandbox nor questions with `--free`,
+ * and also without the repo's deny rules with `--free --no-repo-deny`. Each branch keeps its session id, so starting the issue again resumes it.
  * Ported from `launch_session` and `run_claude` in Abastio's `scripts/start-issue.sh`.
  */
 import { randomUUID } from "node:crypto";
@@ -32,7 +32,12 @@ export function permissionArgs(permissions, workDir, mainRoot) {
     if (permissions === "free")
         return {
             args: ["--settings", NO_SANDBOX, "--dangerously-skip-permissions"],
-            label: "none: no sandbox and no questions (--free)",
+            label: "none: no sandbox and no questions; deny rules still apply (--free)",
+        };
+    if (permissions === "free-no-repo-deny")
+        return {
+            args: ["--settings", NO_SANDBOX, "--dangerously-skip-permissions"],
+            label: "none: no sandbox, no questions and no deny rules of the repo; yours still apply (--free --no-repo-deny)",
         };
     if (permissions === "ask")
         return { args: [], label: "your settings (--ask-permissions)" };
@@ -96,13 +101,25 @@ export function savedSession(commonDir, branch) {
     return id !== "" && sessionExists(id) ? id : null;
 }
 /**
- * Forgets a branch's session id, once its work is gone.
+ * The note `--no-repo-deny` keeps while the repo's deny rules are out, next to the
+ * branch's session id.
+ * @param commonDir - The shared `.git`.
+ * @param branch - The branch.
+ * @returns The path.
+ * @example noteFile("/repo/.git", "feat/42-x") // "/repo/.git/issue-flow-sessions/feat+42-x.repo-deny.json"
+ */
+export function noteFile(commonDir, branch) {
+    return `${sessionFile(commonDir, branch)}.repo-deny.json`;
+}
+/**
+ * Forgets a branch's session id (and its `--no-repo-deny` note), once its work is gone.
  * @param commonDir - The shared `.git`.
  * @param branch - The branch.
  * @example forgetSession("/repo/.git", "feat/42-x")
  */
 export function forgetSession(commonDir, branch) {
     rmSync(sessionFile(commonDir, branch), { force: true });
+    rmSync(noteFile(commonDir, branch), { force: true });
 }
 /**
  * Runs Claude in the terminal; its exit code does not matter, what follows runs anyway.

package/dist/repo-deny.d.ts

@@ -0,0 +1,54 @@
+/** The repo's Claude settings, relative to the checkout. */
+export declare const REPO_SETTINGS = ".claude/settings.json";
+/** What it takes to put the rules back. */
+export interface Lifted {
+    /** The file as it was. */
+    original: string;
+    /** The file as issue-flow left it, without the rules. */
+    lifted: string;
+}
+/**
+ * The settings without `permissions.deny` (and without `permissions` if nothing else is
+ * left in it), or null if they have no rules to take out.
+ * @param text - The settings file.
+ * @returns The new text, or null.
+ * @throws SyntaxError if the file is not JSON.
+ * @example withoutDeny('{"permissions":{"deny":["Edit(/x)"]}}') // "{}\n"
+ */
+export declare function withoutDeny(text: string): string | null;
+/**
+ * The settings with the original's deny rules added back (keeping any the text has).
+ * @param text - The settings now.
+ * @param original - The settings with the rules.
+ * @returns The new text.
+ * @throws SyntaxError if either is not JSON.
+ * @example withDeny("{}", '{"permissions":{"deny":["Edit(/x)"]}}') // '{\n  "permissions": {\n    "deny": [\n      "Edit(/x)"\n    ]\n  }\n}\n'
+ */
+export declare function withDeny(text: string, original: string): string;
+/**
+ * Takes the `deny` rules out of the worktree's settings and hides the change from git. A
+ * note in the shared `.git` keeps the original in case the process dies before it puts
+ * them back; the caller keeps what it returns and puts them back from that.
+ * @param workDir - The worktree.
+ * @param commonDir - The shared `.git`.
+ * @param branch - The branch.
+ * @returns What happened, for the person, and what to put back (null if nothing was taken).
+ * @example liftRepoDeny(wt, "/repo/.git", "feat/42-x").message
+ */
+export declare function liftRepoDeny(workDir: string, commonDir: string, branch: string): {
+    message: string;
+    saved: Lifted | null;
+};
+/**
+ * Puts the rules back in the worktree's settings. From `saved` when the caller kept it (the
+ * note is in reach of the session, so it is only trusted after a process that died); else
+ * from the branch's note, if there is one. If Claude changed the file meanwhile, the rules
+ * go back on top of its change, with a warning to review it.
+ * @param commonDir - The shared `.git`.
+ * @param branch - The branch.
+ * @param workDir - The worktree, never taken from the note.
+ * @param saved - What liftRepoDeny returned, or null to read the note.
+ * @returns A warning, or null if there was nothing to say.
+ * @example restoreRepoDeny("/repo/.git", "feat/42-x", wt, null) // null
+ */
+export declare function restoreRepoDeny(commonDir: string, branch: string, workDir: string, saved: Lifted | null): string | null;

package/dist/repo-deny.js

@@ -0,0 +1,128 @@
+/**
+ * @file `--free --no-repo-deny`: takes the `deny` rules out of the worktree's
+ * `.claude/settings.json` while Claude runs, and puts them back when it exits. Claude adds
+ * the `deny` of every settings file it loads and `--dangerously-skip-permissions` respects
+ * them, so a flag cannot drop them; and `--setting-sources user,local` drops them but also
+ * the repo's `CLAUDE.md`, skills, agents and MCP servers. Editing the worktree's own copy
+ * keeps all that, and leaves the main checkout and the other worktrees alone.
+ *
+ * While the rules are out, `git update-index --skip-worktree` hides the change from
+ * `git status` and `git add`, so it never lands in a commit. A note in the shared `.git`
+ * keeps the original, so a session whose terminal was closed is put back on the next
+ * `issue start` of the branch.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { git } from "./git.js";
+import { noteFile } from "./launch.js";
+/** The repo's Claude settings, relative to the checkout. */
+export const REPO_SETTINGS = ".claude/settings.json";
+/**
+ * The settings without `permissions.deny` (and without `permissions` if nothing else is
+ * left in it), or null if they have no rules to take out.
+ * @param text - The settings file.
+ * @returns The new text, or null.
+ * @throws SyntaxError if the file is not JSON.
+ * @example withoutDeny('{"permissions":{"deny":["Edit(/x)"]}}') // "{}\n"
+ */
+export function withoutDeny(text) {
+    const settings = JSON.parse(text);
+    const deny = settings.permissions?.deny;
+    if (!Array.isArray(deny) || deny.length === 0)
+        return null;
+    const { deny: _dropped, ...permissions } = settings.permissions ?? {};
+    const { permissions: _old, ...rest } = settings;
+    const result = Object.keys(permissions).length === 0 ? rest : { ...rest, permissions };
+    return `${JSON.stringify(result, null, 2)}\n`;
+}
+/**
+ * The settings with the original's deny rules added back (keeping any the text has).
+ * @param text - The settings now.
+ * @param original - The settings with the rules.
+ * @returns The new text.
+ * @throws SyntaxError if either is not JSON.
+ * @example withDeny("{}", '{"permissions":{"deny":["Edit(/x)"]}}') // '{\n  "permissions": {\n    "deny": [\n      "Edit(/x)"\n    ]\n  }\n}\n'
+ */
+export function withDeny(text, original) {
+    const settings = JSON.parse(text);
+    const deny = JSON.parse(original).permissions?.deny ?? [];
+    const now = Array.isArray(settings.permissions?.deny) ? settings.permissions.deny : [];
+    const merged = [...deny, ...now.filter((rule) => !deny.includes(rule))];
+    return `${JSON.stringify({ ...settings, permissions: { ...settings.permissions, deny: merged } }, null, 2)}\n`;
+}
+/**
+ * Takes the `deny` rules out of the worktree's settings and hides the change from git. A
+ * note in the shared `.git` keeps the original in case the process dies before it puts
+ * them back; the caller keeps what it returns and puts them back from that.
+ * @param workDir - The worktree.
+ * @param commonDir - The shared `.git`.
+ * @param branch - The branch.
+ * @returns What happened, for the person, and what to put back (null if nothing was taken).
+ * @example liftRepoDeny(wt, "/repo/.git", "feat/42-x").message
+ */
+export function liftRepoDeny(workDir, commonDir, branch) {
+    const file = join(workDir, REPO_SETTINGS);
+    if (!existsSync(file))
+        return { message: `the repo has no ${REPO_SETTINGS}: there are no deny rules to take out.`, saved: null };
+    const original = readFileSync(file, "utf8");
+    let lifted;
+    try {
+        lifted = withoutDeny(original);
+    }
+    catch {
+        return { message: `${REPO_SETTINGS} is not valid JSON: its deny rules stay.`, saved: null };
+    }
+    if (lifted === null)
+        return { message: `${REPO_SETTINGS} has no deny rules: nothing to take out.`, saved: null };
+    const saved = { original, lifted };
+    const note = noteFile(commonDir, branch);
+    mkdirSync(dirname(note), { recursive: true });
+    writeFileSync(note, `${JSON.stringify(saved)}\n`);
+    writeFileSync(file, lifted);
+    git(workDir, ["update-index", "--skip-worktree", REPO_SETTINGS]);
+    return { message: `took out the deny rules of ${REPO_SETTINGS} for this session; they come back when Claude exits.`, saved };
+}
+/**
+ * Puts the rules back in the worktree's settings. From `saved` when the caller kept it (the
+ * note is in reach of the session, so it is only trusted after a process that died); else
+ * from the branch's note, if there is one. If Claude changed the file meanwhile, the rules
+ * go back on top of its change, with a warning to review it.
+ * @param commonDir - The shared `.git`.
+ * @param branch - The branch.
+ * @param workDir - The worktree, never taken from the note.
+ * @param saved - What liftRepoDeny returned, or null to read the note.
+ * @returns A warning, or null if there was nothing to say.
+ * @example restoreRepoDeny("/repo/.git", "feat/42-x", wt, null) // null
+ */
+export function restoreRepoDeny(commonDir, branch, workDir, saved) {
+    const note = noteFile(commonDir, branch);
+    let from = saved;
+    if (from === null) {
+        if (!existsSync(note))
+            return null;
+        try {
+            from = JSON.parse(readFileSync(note, "utf8"));
+        }
+        catch {
+            rmSync(note, { force: true });
+            return `could not read ${note}; check the deny rules of ${REPO_SETTINGS} with git diff.`;
+        }
+    }
+    rmSync(note, { force: true });
+    if (!existsSync(workDir))
+        return null;
+    const file = join(workDir, REPO_SETTINGS);
+    git(workDir, ["update-index", "--no-skip-worktree", REPO_SETTINGS]);
+    const now = existsSync(file) ? readFileSync(file, "utf8") : null;
+    if (now === from.lifted || now === null) {
+        writeFileSync(file, from.original);
+        return null;
+    }
+    try {
+        writeFileSync(file, withDeny(now, from.original));
+    }
+    catch {
+        return `Claude left ${REPO_SETTINGS} as invalid JSON, so its deny rules could not be put back: fix it and add them before committing (git diff ${REPO_SETTINGS}).`;
+    }
+    return `Claude changed ${REPO_SETTINGS} during the session: its deny rules are back on top of that change; review it with git diff ${REPO_SETTINGS}.`;
+}

package/dist/usage.d.ts

@@ -2,9 +2,9 @@
  * @file The usage text of the CLI, printed with `--help` and after a usage error.
  */
 /** Usage text. */
-export declare const USAGE = "Usage:\n  issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]\n  issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]\n  issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]\n                             [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]\n  issue-flow worktree setup [--only <step>]\n  issue-flow worktree teardown [--path <dir>]\n  issue-flow worktree ports [--next]\n  issue-flow worktree cleanup [--path <dir>]\n  issue-flow worktree prune [--only <dir>] [--yes] [-R owner/repo]\n  issue-flow pr worktree <n> [--no-setup] [-R owner/repo] [-- [<command>...]]\n  issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]\n  issue-flow session\n  issue-flow hook worktree-create | worktree-remove\n  issue-flow apply [--yes] [--dry-run] [--json] [--recipe <name>,...]\n  issue-flow doctor [--json]\n  issue-flow labels sync [--update] [--dry-run] [--json] [-R owner/repo]\n\nThe slug comes from the issue's \"Slug de rama\" block, then from Claude, then from the title,\nand the branch from the repo's template (an older \"Rama sugerida\" block is used if it fits).\n--missing adds the slug block to every open issue without a block, after confirming.\n\nissue start makes the branch in a worktree (or, with --branch, in this checkout), the\nstart commit, the push, the draft PR and the assignment, after confirming, and opens\nClaude: in auto mode if the repo has claude-repo-guard, with your settings with\n--ask-permissions, and with no sandbox nor questions with --free. --plan prints the branch\nand the prompt as JSON and changes nothing. issue start --help explains each flag.\n\n--cloud confirms here and opens a Claude cloud session that starts the issue there.\n--here, inside a cloud session, starts it in this checkout and opens nothing. --teleport\nbrings the cloud session noted in the PR to the worktree. --adopt starts it in the\nworktree another tool (Orca, Paseo) just made, without asking nor opening Claude.\n\nworktree runs the steps of \"worktrees\" in .agents/flow.json: setup prepares this worktree,\nteardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block\nof ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees\nwhose PR was merged or closed. session is the SessionStart hook of Claude Code.\n\npr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with\n--, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup\nwhen they make a worktree (its steps and, if it came from an issue, issue start --adopt),\nissue to start one by hand, and archive before they delete it. hook implements Claude\nCode's WorktreeCreate and WorktreeRemove for claude --worktree.\n\napply leaves the repo as this version needs it: .agents/flow.json (the first time, with\nthe recipes its files suggest), issue-flow at this version and github-rest and the scripts\nif missing in package.json, and the hooks; it changes no other version, and refuses a newer\nissue-flow or a range. doctor checks them. npx agent-kitchen apply runs apply at the version\nit picks, along with the skills, claude-cloud and claude-repo-guard. init and upgrade still\nrun apply, with a warning, until 0.4.0.\n\nlabels sync makes in GitHub the labels the flow wants (\"labels\" in .agents/flow.json: the\nissue types and P1 to P4 by default) that the repo lacks. Names ignore case and are never\nrenamed nor deleted; --update also fixes the color and description of those that differ.";
+export declare const USAGE = "Usage:\n  issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]\n  issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]\n  issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]\n                             [--ask-permissions | --free [--no-repo-deny]] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]\n  issue-flow worktree setup [--only <step>]\n  issue-flow worktree teardown [--path <dir>]\n  issue-flow worktree ports [--next]\n  issue-flow worktree cleanup [--path <dir>]\n  issue-flow worktree prune [--only <dir>] [--yes] [-R owner/repo]\n  issue-flow pr worktree <n> [--no-setup] [-R owner/repo] [-- [<command>...]]\n  issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]\n  issue-flow session\n  issue-flow hook worktree-create | worktree-remove\n  issue-flow apply [--yes] [--dry-run] [--json] [--recipe <name>,...]\n  issue-flow doctor [--json]\n  issue-flow labels sync [--update] [--dry-run] [--json] [-R owner/repo]\n\nThe slug comes from the issue's \"Slug de rama\" block, then from Claude, then from the title,\nand the branch from the repo's template (an older \"Rama sugerida\" block is used if it fits).\n--missing adds the slug block to every open issue without a block, after confirming.\n\nissue start makes the branch in a worktree (or, with --branch, in this checkout), the\nstart commit, the push, the draft PR and the assignment, after confirming, and opens\nClaude: in auto mode if the repo has claude-repo-guard, with your settings with\n--ask-permissions, with no sandbox nor questions with --free, and also without the repo's\ndeny rules with --free --no-repo-deny. --plan prints the branch and the prompt as JSON and\nchanges nothing. issue start --help explains each flag.\n\n--cloud confirms here and opens a Claude cloud session that starts the issue there.\n--here, inside a cloud session, starts it in this checkout and opens nothing. --teleport\nbrings the cloud session noted in the PR to the worktree. --adopt starts it in the\nworktree another tool (Orca, Paseo) just made, without asking nor opening Claude.\n\nworktree runs the steps of \"worktrees\" in .agents/flow.json: setup prepares this worktree,\nteardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block\nof ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees\nwhose PR was merged or closed. session is the SessionStart hook of Claude Code.\n\npr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with\n--, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup\nwhen they make a worktree (its steps and, if it came from an issue, issue start --adopt),\nissue to start one by hand, and archive before they delete it. hook implements Claude\nCode's WorktreeCreate and WorktreeRemove for claude --worktree.\n\napply leaves the repo as this version needs it: .agents/flow.json (the first time, with\nthe recipes its files suggest), issue-flow at this version and github-rest and the scripts\nif missing in package.json, and the hooks; it changes no other version, and refuses a newer\nissue-flow or a range. doctor checks them. npx agent-kitchen apply runs apply at the version\nit picks, along with the skills, claude-cloud and claude-repo-guard. init and upgrade still\nrun apply, with a warning, until 0.4.0.\n\nlabels sync makes in GitHub the labels the flow wants (\"labels\" in .agents/flow.json: the\nissue types and P1 to P4 by default) that the repo lacks. Names ignore case and are never\nrenamed nor deleted; --update also fixes the color and description of those that differ.";
 /** Usage text of `issue start`, printed with `issue start --help`. */
-export declare const START_USAGE = "Usage: issue-flow issue start <n> [flags]\n\nStarts issue <n>: the branch (in a worktree, or in this checkout with --branch), the empty\nstart commit, the push, the draft PR and the assignment, after confirming; then it opens\nClaude there.\n\nFlags:\n  --dry-run            show what it would do and change nothing\n  -y, --yes            do it without asking\n  --branch             in this checkout instead of a worktree\n  --resume <branch>    take that branch of the issue\n  --new                make another branch, even if the issue has one\n  --no-launch          leave everything ready and do not open Claude\n  --namer claude|title who names the branch when the issue has no slug block\n  -R owner/repo        another repo than the checkout's\n  --plan               print the branch and the prompt as JSON, and change nothing\n  --cloud              open a Claude cloud session that starts the issue there\n  --here               inside a cloud session, start it in this checkout\n  --teleport           bring the cloud session noted in the PR to the worktree\n  --adopt              start it in the worktree Orca or Paseo just made\n  -h, --help           this help\n\nPermissions of the Claude it opens (one at most):\n  (none)               auto mode if the repo has claude-repo-guard, else your settings\n  --ask-permissions    your settings: Claude asks before what they do not allow\n  --free               no sandbox and no questions, as claude:free\n\nFrom the repo's scripts (issue:start, and issue:start:free, which adds --free):\n  npm run issue:start:free 42           npm passes a number on as it is\n  npm run issue:start -- 42 --free      but keeps the flags for itself, unless after --\n  pnpm issue:start 42 --free            pnpm, bun and yarn pass everything on\n  bun run issue:start 42 --free\n  yarn issue:start 42 --free\nA -- does no harm with any of them: issue-flow drops it.\n\nissue:start:free does not go with --ask-permissions, --cloud, --here nor --adopt: use\nissue:start for those.";
+export declare const START_USAGE = "Usage: issue-flow issue start <n> [flags]\n\nStarts issue <n>: the branch (in a worktree, or in this checkout with --branch), the empty\nstart commit, the push, the draft PR and the assignment, after confirming; then it opens\nClaude there.\n\nFlags:\n  --dry-run            show what it would do and change nothing\n  -y, --yes            do it without asking\n  --branch             in this checkout instead of a worktree\n  --resume <branch>    take that branch of the issue\n  --new                make another branch, even if the issue has one\n  --no-launch          leave everything ready and do not open Claude\n  --namer claude|title who names the branch when the issue has no slug block\n  -R owner/repo        another repo than the checkout's\n  --plan               print the branch and the prompt as JSON, and change nothing\n  --cloud              open a Claude cloud session that starts the issue there\n  --here               inside a cloud session, start it in this checkout\n  --teleport           bring the cloud session noted in the PR to the worktree\n  --adopt              start it in the worktree Orca or Paseo just made\n  -h, --help           this help\n\nPermissions of the Claude it opens (one at most):\n  (none)               auto mode if the repo has claude-repo-guard, else your settings\n  --ask-permissions    your settings: Claude asks before what they do not allow\n  --free               no sandbox and no questions, as claude:free\n  --no-repo-deny       with --free: also without the deny rules of the repo's settings\n\nWhat each one takes away, and what stays:\n  (none), --ask-permissions\n                       take nothing away: the sandbox, the questions your settings ask\n                       and every deny rule stay.\n  --free               takes away the sandbox and the questions. Every deny rule stays:\n                       yours (~/.claude), the repo's (.claude/settings.json) and the\n                       local ones (.claude/settings.local.json).\n  --free --no-repo-deny\n                       also takes the deny rules out of the worktree's\n                       .claude/settings.json while Claude runs, and puts them back when it\n                       exits; git does not see the change meanwhile. Your deny rules and the\n                       local ones stay, and so do the repo's hooks, attribution, CLAUDE.md,\n                       skills, agents and MCP servers. If Claude changes that file, the\n                       rules go back on top of its change, with a warning to review it. If\n                       the terminal closes first, the next issue start of the issue puts\n                       them back.\n\nFrom the repo's scripts (issue:start, and issue:start:free, which adds --free):\n  npm run issue:start:free 42           npm passes a number on as it is\n  npm run issue:start -- 42 --free      but keeps the flags for itself, unless after --\n  pnpm issue:start 42 --free            pnpm, bun and yarn pass everything on\n  bun run issue:start 42 --free\n  yarn issue:start 42 --free\nA -- does no harm with any of them: issue-flow drops it.\n\nissue:start:free does not go with --ask-permissions, --cloud, --here nor --adopt: use\nissue:start for those. --no-repo-deny goes after it, as any flag:\n  npm run issue:start:free -- 42 --no-repo-deny\n  pnpm issue:start:free 42 --no-repo-deny";
 /**
  * The usage text for a command: its own if it has one, else the whole CLI's.
  * @param words - The command's words, as given (`["issue", "start", "42"]`).

package/dist/usage.js

@@ -6,7 +6,7 @@ export const USAGE = `Usage:
   issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]
   issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]
   issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]
-                             [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]
+                             [--ask-permissions | --free [--no-repo-deny]] [--namer claude|title] [-R owner/repo]
   issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]
   issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]
   issue-flow worktree setup [--only <step>]
@@ -29,8 +29,9 @@ and the branch from the repo's template (an older "Rama sugerida" block is used
 issue start makes the branch in a worktree (or, with --branch, in this checkout), the
 start commit, the push, the draft PR and the assignment, after confirming, and opens
 Claude: in auto mode if the repo has claude-repo-guard, with your settings with
---ask-permissions, and with no sandbox nor questions with --free. --plan prints the branch
-and the prompt as JSON and changes nothing. issue start --help explains each flag.
+--ask-permissions, with no sandbox nor questions with --free, and also without the repo's
+deny rules with --free --no-repo-deny. --plan prints the branch and the prompt as JSON and
+changes nothing. issue start --help explains each flag.
 
 --cloud confirms here and opens a Claude cloud session that starts the issue there.
 --here, inside a cloud session, starts it in this checkout and opens nothing. --teleport
@@ -85,6 +86,24 @@ Permissions of the Claude it opens (one at most):
   (none)               auto mode if the repo has claude-repo-guard, else your settings
   --ask-permissions    your settings: Claude asks before what they do not allow
   --free               no sandbox and no questions, as claude:free
+  --no-repo-deny       with --free: also without the deny rules of the repo's settings
+
+What each one takes away, and what stays:
+  (none), --ask-permissions
+                       take nothing away: the sandbox, the questions your settings ask
+                       and every deny rule stay.
+  --free               takes away the sandbox and the questions. Every deny rule stays:
+                       yours (~/.claude), the repo's (.claude/settings.json) and the
+                       local ones (.claude/settings.local.json).
+  --free --no-repo-deny
+                       also takes the deny rules out of the worktree's
+                       .claude/settings.json while Claude runs, and puts them back when it
+                       exits; git does not see the change meanwhile. Your deny rules and the
+                       local ones stay, and so do the repo's hooks, attribution, CLAUDE.md,
+                       skills, agents and MCP servers. If Claude changes that file, the
+                       rules go back on top of its change, with a warning to review it. If
+                       the terminal closes first, the next issue start of the issue puts
+                       them back.
 
 From the repo's scripts (issue:start, and issue:start:free, which adds --free):
   npm run issue:start:free 42           npm passes a number on as it is
@@ -95,7 +114,9 @@ From the repo's scripts (issue:start, and issue:start:free, which adds --free):
 A -- does no harm with any of them: issue-flow drops it.
 
 issue:start:free does not go with --ask-permissions, --cloud, --here nor --adopt: use
-issue:start for those.`;
+issue:start for those. --no-repo-deny goes after it, as any flag:
+  npm run issue:start:free -- 42 --no-repo-deny
+  pnpm issue:start:free 42 --no-repo-deny`;
 /** The usage text of each command that has its own, by its words. */
 const OWN_USAGE = { "issue start": START_USAGE };
 /**

package/dist/worktree-steps.d.ts

@@ -1,5 +1,6 @@
-import type { FlowConfig } from "./config.js";
+import { type FlowConfig } from "./config.js";
 import { type Output } from "./output.js";
+import { type Step } from "./worktree-config.js";
 /** Folder, in the worktree's git dir, with a mark per `once` step that worked. */
 export declare const SETUP_MARKS_DIR = "issue-flow-setup";
 /** Where the steps run, and with what. */
@@ -30,17 +31,43 @@ export declare function trustedCode(root: string, base: string): boolean;
  * @example stepEnv(place, 21430).ISSUE_FLOW_PORT_BASE // "21430"
  */
 export declare function stepEnv(place: StepPlace, port: number | null): Record<string, string>;
+/** The setup steps a worktree runs, and where they were read. */
+export interface SetupSteps {
+    steps: Step[];
+    source: string;
+    warning: string | null;
+}
+/**
+ * The setup steps: those of `.agents/flow.json` in `origin/<base>`, which a worktree made
+ * from it has; none if the file is not there. In a cloud session, without `origin/<base>`,
+ * or with a file there that is not valid, those of the checkout's config. The warning says
+ * when the main checkout's steps differ, or why they were used.
+ * @param place - Where.
+ * @returns The steps, where they come from and a warning, or null.
+ * @example setupSteps(place).source // "origin/main:.agents/flow.json"
+ */
+export declare function setupSteps(place: StepPlace): SetupSteps;
+/**
+ * Checks that `--only` names one of the setup steps.
+ * @param place - Where.
+ * @param only - The step, or null.
+ * @throws UsageError if it names no step.
+ * @example checkOnly(place, "deps")
+ */
+export declare function checkOnly(place: StepPlace, only: string | null): void;
 /**
  * Prepares a worktree with the setup steps: one (`only`) or all, in order. In the main
  * checkout it does nothing, except in a cloud session, whose checkout is not a worktree. It
  * fixes the block of ports first, so the steps (and the apps after them) agree on it.
- * Never stops on a failed step: it says what to run and goes on.
+ * Never stops on a failed step: it says what to run and goes on. Without steps it says so,
+ * unless `quiet` (the session hooks, which run at every start).
  * @param place - Where.
  * @param only - The step to run, or null for all.
+ * @param quiet - True to say nothing when there are no steps.
  * @returns True if every step that ran worked.
  * @example await runSetup(place, null)
  */
-export declare function runSetup(place: StepPlace, only: string | null): Promise<boolean>;
+export declare function runSetup(place: StepPlace, only: string | null, quiet?: boolean): Promise<boolean>;
 /**
  * Cleans a worktree before it is deleted: its apps and then its teardown steps (if the
  * folder still exists), so a step that drops a database finds nobody connected; then its

package/dist/worktree-steps.js

@@ -1,7 +1,9 @@
 /**
  * @file Runs the steps of `worktrees.setup` and `worktrees.teardown` in a worktree. The
- * steps come from the main checkout's config, not the worktree's, so a branch cannot add
- * commands to its own setup. A `trusted` step (an install, which runs the lifecycle scripts
+ * setup steps come from `.agents/flow.json` in `origin/<base>`, not from the worktree, so a
+ * branch cannot add commands to its own setup, and a main checkout nobody pulled does not
+ * leave a new worktree without its install. The teardown steps come from the main
+ * checkout's config. A `trusted` step (an install, which runs the lifecycle scripts
  * of `package.json`) runs only if the worktree's code is in `origin/<base>` and has no
  * changes; a `once` step leaves a mark when it works and is not repeated. Two setups of one
  * worktree at a time (the tool's and the session hook's) take turns with a lock. Each step
@@ -12,11 +14,14 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
+import { CONFIG_PATH, isObject } from "./config-base.js";
+import { DEFAULT_CONFIG } from "./config.js";
 import { dockerCleanup, sanitizeLabel } from "./docker.js";
 import { git, isClean } from "./git.js";
-import { warn } from "./output.js";
+import { UsageError, warn } from "./output.js";
 import { claimPortBase, portBase, releasePortClaims, sha256 } from "./ports.js";
 import { stopApps } from "./stop-apps.js";
+import { worktreesSection } from "./worktree-config.js";
 /** Folder, in the worktree's git dir, with a mark per `once` step that worked. */
 export const SETUP_MARKS_DIR = "issue-flow-setup";
 /** The lock of the setup, in the worktree's git dir. */
@@ -78,6 +83,58 @@ function runStep(place, step, env) {
     warn(place.out, `step "${step.name}" failed${result.status === null ? "" : ` (exit ${result.status})`}; run '${step.run}' in ${place.root}.`);
     return false;
 }
+/**
+ * The setup steps: those of `.agents/flow.json` in `origin/<base>`, which a worktree made
+ * from it has; none if the file is not there. In a cloud session, without `origin/<base>`,
+ * or with a file there that is not valid, those of the checkout's config. The warning says
+ * when the main checkout's steps differ, or why they were used.
+ * @param place - Where.
+ * @returns The steps, where they come from and a warning, or null.
+ * @example setupSteps(place).source // "origin/main:.agents/flow.json"
+ */
+export function setupSteps(place) {
+    const local = place.config.worktrees.setup;
+    const ref = `origin/${place.base}`;
+    const fallback = { steps: local, source: `the main checkout's ${CONFIG_PATH}` };
+    // NOTE: a cloud session has no other checkout: its steps are those of the session's branch.
+    if (place.remote || !git(place.mainRoot, ["rev-parse", "-q", "--verify", `${ref}^{commit}`]).ok)
+        return { ...fallback, warning: null };
+    const source = `${ref}:${CONFIG_PATH}`;
+    const shown = git(place.mainRoot, ["show", source]);
+    let steps;
+    try {
+        if (!shown.ok)
+            steps = DEFAULT_CONFIG.worktrees.setup;
+        else {
+            const raw = JSON.parse(shown.out);
+            steps = worktreesSection(isObject(raw) ? raw.worktrees : undefined, DEFAULT_CONFIG.worktrees).setup;
+        }
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { ...fallback, warning: `${source} is not valid: ${reason}; using the main checkout's steps.` };
+    }
+    const differ = JSON.stringify(steps) !== JSON.stringify(local);
+    return {
+        steps,
+        source,
+        warning: differ ? `the setup steps come from ${source}; the main checkout's differ (is it behind? pull it).` : null,
+    };
+}
+/**
+ * Checks that `--only` names one of the setup steps.
+ * @param place - Where.
+ * @param only - The step, or null.
+ * @throws UsageError if it names no step.
+ * @example checkOnly(place, "deps")
+ */
+export function checkOnly(place, only) {
+    if (only === null)
+        return;
+    const names = setupSteps(place).steps.map((step) => step.name);
+    if (!names.includes(only))
+        throw new UsageError(`--only expects a setup step of ${CONFIG_PATH} (${names.join(", ") || "it has none"}): ${only}`);
+}
 /**
  * Takes the setup's lock: a folder with the pid. A lock of a process that is gone is taken
  * over, and so is one without a pid that is some seconds old (its process died before
@@ -126,17 +183,24 @@ function alive(pid) {
  * Prepares a worktree with the setup steps: one (`only`) or all, in order. In the main
  * checkout it does nothing, except in a cloud session, whose checkout is not a worktree. It
  * fixes the block of ports first, so the steps (and the apps after them) agree on it.
- * Never stops on a failed step: it says what to run and goes on.
+ * Never stops on a failed step: it says what to run and goes on. Without steps it says so,
+ * unless `quiet` (the session hooks, which run at every start).
  * @param place - Where.
  * @param only - The step to run, or null for all.
+ * @param quiet - True to say nothing when there are no steps.
  * @returns True if every step that ran worked.
  * @example await runSetup(place, null)
  */
-export async function runSetup(place, only) {
+export async function runSetup(place, only, quiet = false) {
     const { root, mainRoot, config, out } = place;
     if (root === mainRoot && !place.remote)
         return true;
-    const chosen = config.worktrees.setup.filter((step) => only === null || step.name === only);
+    const found = setupSteps(place);
+    if (found.warning !== null)
+        warn(out, found.warning);
+    if (found.steps.length === 0 && !quiet)
+        warn(out, `no setup steps in ${found.source}; nothing ran.`);
+    const chosen = found.steps.filter((step) => only === null || step.name === only);
     const ports = config.worktrees.ports;
     const port = ports === null ? null : await claimPortBase(ports, root, null);
     if (ports !== null && port === null)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramon-sg/issue-flow",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Issue-to-PR workflow for any repo: names each issue's branch, creates its worktree, opens the draft PR and launches Claude Code, locally and in Claude's cloud.",
   "license": "MIT",
   "type": "module",

package/schema.json

@@ -76,7 +76,7 @@
           "default": ".claude/worktrees"
         },
         "setup": {
-          "description": "Steps that prepare a worktree, in order. They come from the main checkout's config, never the worktree's.",
+          "description": "Steps that prepare a worktree, in order. They come from this file in origin/<base> (the main checkout's if origin has none to read), never the worktree's.",
           "type": "array",
           "items": {
             "type": "object",