@juzser/blacksmith 0.3.0 → 0.5.0

package/factory/orchestrator/dist/harness.js

@@ -1,10 +1,13 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parse as parseYaml } from 'yaml';
-import { loadBudgetPolicy } from './budgets.js';
+import { agentNameFor, templateFileFor } from './agentNames.js';
+import { loadBudgetPolicy, roleCapTokens } from './budgets.js';
+import { epicBudgetPolicies } from './epicBudget.js';
 import { SmithError } from './errors.js';
 import { AGENTS_DIR, HARNESS_POLICY_PATH, REPO_ROOT } from './paths.js';
 import { INSPECTED_FILE_TOOLS, loadGuardrailPolicy } from './policy.js';
+import { epicOfTaskId } from './taskId.js';
 import { loadTaxonomy } from './taxonomy.js';
 /**
  * The worker harness port: *how* a turn runs, named at last.
@@ -298,7 +301,7 @@ export function roleAccess(role, guardrails = loadGuardrailPolicy()) {
 }
 /** Where a role's prompt template lives, and whether it is there. */
 function templateFor(role, agentsDir) {
-    const file = path.join(agentsDir, `${role}.md`);
+    const file = path.join(agentsDir, templateFileFor(role));
     return { file, exists: existsSync(file) };
 }
 function serves(harness, role) {
@@ -347,17 +350,22 @@ function resolveSchema(name, harnessName) {
     }
     return { name, file };
 }
-function capTokensFor(role, access, budgets) {
-    // Only these three named roles carry a cap in budgets.yml today — every
-    // other role (security-reviewer, merger, tester, uiux, planner, scribe)
-    // has none, and null says so rather than inventing a number nobody set.
-    if (access === 'judge')
-        return budgets.task.judges.capTokens;
-    if (role === 'coder')
-        return budgets.task.coder.capTokens;
-    if (role === 'researcher')
-        return budgets.task.researcher.capTokens;
-    return null;
+function capTokensFor(role, budgets) {
+    // budgets.yml prices each role on its own line, sized for the policy's
+    // effort tier. A role it prices nowhere (merger, uiux, scribe, wave-runner)
+    // gets null, which says so rather than inventing a number nobody set.
+    return roleCapTokens(budgets, role);
+}
+/**
+ * budgets.yml sized for the effort tier of the epic `taskId` belongs to — the
+ * tier `cap_tokens` (and so the runner's `over_budget`) is judged at. A bare
+ * task id names no epic, and is priced at effort.yml's default tier.
+ */
+function budgetsForTask(taskId, planOpts) {
+    const epicId = epicOfTaskId(taskId);
+    return epicId === null
+        ? loadBudgetPolicy()
+        : epicBudgetPolicies(planOpts === undefined ? {} : { planOpts })(epicId);
 }
 function substitute(template, values, harness) {
     return template.replace(PLACEHOLDER_RE, (_match, token) => {
@@ -471,7 +479,7 @@ export function planWorkerTurn(request, options = {}) {
         throw new HarnessError('harness.unknown-tier', `"${request.tier}" is not a model tier. It is one of ${MODEL_TIERS.join(', ')}.`, { tier: request.tier });
     }
     if (request.promptFile === undefined || request.promptFile === '') {
-        throw new HarnessError('harness.missing-prompt', 'A worker turn needs a prompt file. This port renders invocations, not prompts — write the prompt first (`smith prompt record`), then plan the turn that carries it.', { role });
+        throw new HarnessError('harness.missing-prompt', 'A worker turn needs a prompt file. This port renders invocations, not prompts — write the prompt first (`bs prompt record`), then plan the turn that carries it.', { role });
     }
     const name = request.harness ?? policy.defaultHarness;
     const harness = policy.harnesses.find((h) => h.name === name);
@@ -509,7 +517,7 @@ export function planWorkerTurn(request, options = {}) {
         return {
             ...base,
             kind: 'in-process',
-            subagentType: role,
+            subagentType: agentNameFor(role),
             template: templateRelative,
         };
     }
@@ -536,11 +544,11 @@ export function planWorkerTurn(request, options = {}) {
     const roleArgs = access === 'judge' ? harness.judgeArgs : harness.workerArgs;
     const rawArgs = [...harness.args, ...roleArgs, ...(schema !== null ? harness.schemaArgs : [])];
     const args = rawArgs.map((arg) => substitute(arg, values, harness.name));
-    const budgets = options.budgets ?? loadBudgetPolicy();
+    const budgets = options.budgets ?? budgetsForTask(taskId, options.planOpts);
     const budget = {
         timeout_ms: harness.timeoutMs,
         max_output_bytes: harness.maxOutputBytes ?? HARNESS_DEFAULT_MAX_OUTPUT_BYTES,
-        cap_tokens: capTokensFor(role, access, budgets),
+        cap_tokens: capTokensFor(role, budgets),
     };
     return {
         ...base,

package/factory/orchestrator/dist/hookDecision.js

@@ -2,7 +2,7 @@
 // without holding the rest of the orchestrator.
 //
 // `.claude/hooks/guard.sh` fires on every Bash/Write/Edit/MultiEdit/
-// NotebookEdit call an agent makes, which makes whatever it execs the most
+// NotebookEdit/Agent/Task call an agent makes, which makes whatever it execs the most
 // frequently run code in this repo by orders of magnitude. It used to exec
 // `dist/cli.js policy hook`; cli.ts imports the whole orchestrator at module
 // scope, `db/projector.js` and so drizzle-orm among it, and that graph cost
@@ -11,8 +11,49 @@
 // `policyHook.ts` be an entry point whose imports are only what deciding
 // actually needs, while `cli.ts` keeps `smith policy hook` by calling the
 // same function rather than a second copy of it.
-import { detectCurrentBranch, detectRepoRoot, evaluateCommand, loadGuardrailPolicy, } from './policy.js';
+import { accessSync, constants, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { roleOfAgentType } from './agentNames.js';
+import { parseDeclaredArtifactLine } from './declaredArtifactLine.js';
+import { JUDGE_ROLES } from './judgeRoles.js';
+import { detectCurrentBranch, detectRepoRoot, evaluateCommand, isProtectedBranchName, loadGuardrailPolicy, } from './policy.js';
 import { activeSandboxFor } from './sandbox.js';
+const JUDGE_ROLE_NAMES = new Set(JUDGE_ROLES);
+/**
+ * A judge-role subagent dispatch must carry `Declared artifact: <absolute path>`
+ * in its prompt, because judge-stop.sh reads the prompt (never a brief file) to
+ * know what the judge owes. Same parser as judge-stop, so what is accepted here
+ * is what it reads. Any other role, prefix or missing type is allowed silently.
+ */
+function decideAgentDispatch(input) {
+    const type = typeof input?.subagent_type === 'string' ? input.subagent_type : '';
+    // Same mapping as judge-stop: `bs-reviewer`, `blacksmith:bs-reviewer` and the
+    // bare pre-prefix names all reach the role. Another plugin's namespace
+    // (`other:reviewer`) is not a Blacksmith agent, so it is skipped, not stripped.
+    const colon = type.indexOf(':');
+    if (colon !== -1 && type.slice(0, colon) !== 'blacksmith')
+        return null;
+    const role = roleOfAgentType(type);
+    if (role === null || !JUDGE_ROLE_NAMES.has(role))
+        return null;
+    const prompt = typeof input?.prompt === 'string' ? input.prompt : '';
+    const declared = parseDeclaredArtifactLine(prompt);
+    if (declared !== null && path.isAbsolute(declared))
+        return null;
+    const found = declared === null
+        ? ''
+        : ` The prompt has "${declared}", which is relative; the path must be absolute.`;
+    return {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: `A "${role}" dispatch must declare the artifact it writes. The prompt needs a line reading exactly ` +
+                '`Declared artifact: <absolute path>` on its own line, not indented, and in the prompt itself ' +
+                `(judge-stop reads the prompt, not a brief file the agent reads).${found} ` +
+                '`judge dispatch` prints the line to paste, as `expected_line`.',
+        },
+    };
+}
 /**
  * Reads one PreToolUse payload and answers with the envelope to print, or
  * `null` to print nothing.
@@ -32,8 +73,13 @@ import { activeSandboxFor } from './sandbox.js';
  * again: the first is failure, the second is a real allow, and only guard.sh's
  * fail-closed handling of a non-zero exit may turn "failure" into a denial.
  */
-export function decideHookPayload(raw, fallbackCwd) {
+export function decideHookPayload(raw, fallbackCwd, 
+/** Where judge leases live; the live `state/sandboxes` unless a test points elsewhere. */
+leaseDir) {
     const payload = JSON.parse(raw);
+    if (payload.tool_name === 'Agent' || payload.tool_name === 'Task') {
+        return decideAgentDispatch(payload.tool_input);
+    }
     const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : '';
     const command = typeof payload.tool_input?.command === 'string' ? payload.tool_input.command : '';
     // A `Write`/`Edit`/`MultiEdit` payload carries no command; its target is
@@ -44,34 +90,99 @@ export function decideHookPayload(raw, fallbackCwd) {
     // handed. Same shape as `command`: a missing or non-string field reads as
     // absent, never as a guess.
     const filePath = typeof payload.tool_input?.file_path === 'string' ? payload.tool_input.file_path : null;
-    // Branch and repo root come from where the command would actually run, which
-    // the PreToolUse payload carries as `cwd`. Resolving them from this binary's
-    // own checkout instead would be wrong in the case this factory spends most of
-    // its time in: guard.sh always execs the main clone's dist, while the session
-    // issuing the command is usually inside a per-task git worktree on a
-    // different branch. That gap is not academic — `git rebase` on
-    // smith/<epic>/integration is a rule-5 denial, and the merge queue performs
-    // rebases from a worktree standing on exactly that branch while the main
-    // clone stands elsewhere. The old bash hook got this right for free by
-    // running `git rev-parse` in its own inherited cwd; the port has to ask for
-    // it. `fallbackCwd` covers a payload without the field (a hand-driven
-    // invocation, or an older client), and a cwd outside any repo resolves to
-    // ''/null, which denies an out-of-bounds removal rather than allowing it.
+    // Branch and repo root come from where the command would actually run.
+    // Resolving them from this binary's own checkout would be wrong in the case
+    // this factory spends most of its time in: guard.sh always execs the main
+    // clone's dist, while the session issuing the command is usually inside a
+    // per-task git worktree on a different branch. That gap is not academic —
+    // `git rebase` on smith/<epic>/integration is a rule-5 denial, and the merge
+    // queue performs rebases from a worktree standing on exactly that branch
+    // while the main clone stands elsewhere. `fallbackCwd` covers a payload
+    // without the field (a hand-driven invocation, or an older client), and a
+    // cwd outside any repo resolves to ''/null, which denies an out-of-bounds
+    // removal rather than allowing it.
+    //
+    // The payload's `cwd` is where the SESSION stands, though, and a command can
+    // move before it acts. `cd <worktree> && git merge main` from a session in
+    // the main clone runs on the worktree's side branch, so judging it on `main`
+    // is a false deny; `cd <main clone> && git merge x` from a worktree session
+    // is the matching false allow. So one narrow shape — `shortcutDirectories`
+    // — is judged in its target alone, dropping `cwd`; that is the ONLY way this
+    // function can ever be more lenient than judging `cwd`, so the shape is an
+    // allowlist and anything it cannot read with certainty (including a target
+    // that is not on a named branch of a repo) falls back. The fallback judges
+    // `cwd` plus every directory the command names, and the command is denied
+    // if ANY of them denies it, so it is never more lenient than `cwd` alone.
+    // A command naming no directory change is judged on `cwd` alone, as before.
     const cwd = typeof payload.cwd === 'string' && payload.cwd !== '' ? payload.cwd : fallbackCwd;
-    const context = {
-        toolName,
-        command,
-        branch: detectCurrentBranch(cwd),
-        repoRoot: detectRepoRoot(cwd),
-        // Resolved from the same `cwd`, and for the same reason: the lease is keyed
-        // by the worktree a judge was handed, and `cwd` is the only thing in a
-        // PreToolUse payload that says where the command will run. No lease is the
-        // ordinary case and costs one directory read.
-        sandbox: activeSandboxFor(cwd),
-        filePath,
-    };
-    const decision = evaluateCommand(context, loadGuardrailPolicy());
-    if (decision.allowed) {
+    const policy = loadGuardrailPolicy();
+    // The lease binds the session a judge was handed, so it is read from `cwd`
+    // whatever the command does next: reading it only from the cd target would
+    // let `cd <elsewhere> && curl …` leave the sandbox in one hop. A lease over
+    // a target is checked too, so moving INTO a leased worktree is bound by it.
+    // No lease is the ordinary case and costs one directory read.
+    const sessionLease = activeSandboxFor(cwd, leaseDir);
+    const locate = (dir) => ({
+        dir,
+        branch: detectCurrentBranch(dir),
+        repoRoot: detectRepoRoot(dir),
+    });
+    const certain = MOVES_RE.test(command) ? shortcutDirectories(command, cwd)?.map(locate) : null;
+    // `HEAD` is what a detached worktree's branch reads as — not a name a
+    // protected-branch rule can ever match, and guardrails.md requires the
+    // shortcut's target to sit on a named branch.
+    const places = certain?.every((p) => p.branch !== '' && p.branch !== 'HEAD' && p.repoRoot !== null) === true
+        ? certain
+        : fallbackDirectories(command, cwd).map(locate);
+    let reason = null;
+    let firingRuleId = null;
+    let firingDir = null;
+    for (const { dir, branch, repoRoot } of places) {
+        const targetLease = dir === cwd ? null : activeSandboxFor(dir, leaseDir);
+        for (const sandbox of distinctLeases(sessionLease, targetLease)) {
+            const context = { toolName, command, branch, repoRoot, sandbox, filePath };
+            const decision = evaluateCommand(context, policy);
+            // guard.sh only ever surfaced one reason: each rule block()ed and exited
+            // immediately on its own match, sequentially, so the first rule in
+            // guard.sh's 1-6 order to fire is the only one an agent ever saw.
+            // evaluateCommand's checks array preserves that order, so violations[0]
+            // of the first denying evaluation reproduces guard.sh's visible
+            // behaviour even though evaluateCommand (policy check's diagnostic
+            // output) reports every rule that tripped.
+            if (!decision.allowed) {
+                const violation = decision.violations[0];
+                reason = violation?.reason ?? 'guardrails.yml denied this command.';
+                firingRuleId = violation?.ruleId ?? null;
+                firingDir = dir;
+                break;
+            }
+        }
+        if (reason !== null)
+            break;
+    }
+    // Rule 3 denying on the fallback (`certain === null`) because cwd itself is
+    // protected is a guess dressed as fact when the command also named another
+    // directory that is NOT protected: the fallback ran only because the shape
+    // could not be read for certain, not because cwd is provably where this
+    // runs. Swap in a reason that says so and names the readable shapes, so the
+    // same merge can go through rewritten. Every other case — no named
+    // directory, or a named directory that is protected too — keeps the
+    // original reason unchanged.
+    if (reason !== null &&
+        firingRuleId === 'merge-into-protected' &&
+        certain == null &&
+        firingDir === cwd) {
+        const namedUnprotected = places.some((p) => p.dir !== cwd &&
+            p.branch !== '' &&
+            p.branch !== 'HEAD' &&
+            p.repoRoot !== null &&
+            !isProtectedBranchName(p.branch, policy));
+        if (namedUnprotected) {
+            const cwdBranch = places.find((p) => p.dir === cwd)?.branch ?? '';
+            reason = fallbackMergeReason(cwdBranch);
+        }
+    }
+    if (reason === null) {
         // Allow prints NOTHING, on purpose, and this is not a cosmetic choice.
         // Claude Code reads an explicit `permissionDecision: "allow"` from a hook
         // as "skip the permission system for this call" — it outranks the
@@ -87,15 +198,6 @@ export function decideHookPayload(raw, fallbackCwd) {
         // load-bearing the way the old hook's was.
         return null;
     }
-    // guard.sh only ever surfaced one reason: each rule block()ed and exited
-    // immediately on its own match, sequentially, so the first rule in guard.sh's
-    // 1-6 order to fire is the only one an agent ever saw. evaluateCommand's
-    // checks array preserves that same order, so violations[0] reproduces
-    // guard.sh's exact visible behaviour even though evaluateCommand (policy
-    // check's diagnostic output) reports every rule that tripped, not just the
-    // first.
-    const first = decision.violations[0];
-    const reason = first ? first.reason : 'guardrails.yml denied this command.';
     return {
         hookSpecificOutput: {
             hookEventName: 'PreToolUse',
@@ -104,3 +206,273 @@ export function decideHookPayload(raw, fallbackCwd) {
         },
     };
 }
+/**
+ * Rule 3's fallback reason for the one case where "you are on {branch}"
+ * states a guess as fact: the command named another directory, that
+ * directory is NOT protected, and the only reason cwd was judged at all is
+ * that the command's shape was not one `shortcutDirectories` can read for
+ * certain — see its own doc comment for the two shapes it accepts. Says so
+ * plainly, and names those shapes, rather than telling an agent already
+ * standing on a side branch to "check out a side branch instead".
+ */
+function fallbackMergeReason(cwdBranch) {
+    return (`this command's shape is not one the guard can read for certain, so it ` +
+        `was also judged against your session's own directory, which is on ` +
+        `${cwdBranch}, a protected branch; git merge/pull is denied there. The ` +
+        `guard reads \`cd <dir> && git <cmd> …\` — <dir> absolute or starting ` +
+        `with \`./\`, joined only by \`&&\`, each command merge, pull or another ` +
+        `read-safe git subcommand (not checkout or switch) — or a single ` +
+        `\`git -C <dir> merge …\`; plain words only, no pipes, \`;\`, redirects, ` +
+        `quotes or variables. Write it that way and the same merge is judged in ` +
+        `<dir> alone.`);
+}
+/**
+ * The one shape judged in its target alone, or `null` to fall back. An
+ * allowlist, because this is the only path that drops `cwd` and so the only
+ * one that can allow what `cwd` alone would deny:
+ *
+ *   - `cd <target> && <cmd> && <cmd> …`: a cd, then plain words joined by
+ *     nothing but `&&` — so everything after runs in the target or not at
+ *     all. A relative target must start with `./` or `../` (or be `.`/`..`),
+ *     since a bare name is looked up on CDPATH first.
+ *   - `git -C <target> <plain words>`, alone.
+ *
+ * A plain word is unquoted and uses only `PLAIN_WORD_RE`'s characters: no
+ * `;`, `|`, `&`, newline, backslash, `$`, backtick, quote, parens, glob or
+ * redirection. The target may also be one whole single- or double-quoted
+ * span. Every `&&`-joined command after the target must be a `git`
+ * invocation whose subcommand sits in `GIT_SUBCOMMAND_ALLOWLIST` —
+ * positively, not a denylist of mover words: any plain word could be a shell
+ * alias or function (zsh's autopushd defines `-` and `1`..`9` as `cd`
+ * shortcuts), so nothing short of "must be a git builtin that cannot run a
+ * command in another repo" is sound. `checkout` and `switch` are excluded
+ * even though they only ever touch the repo they run in: either can move the
+ * target onto a different branch mid-command, and the branch judged is read
+ * once, before the command runs — `cd <W> && git checkout main && git merge
+ * x` would be judged on W's branch before the checkout, not the `main` it
+ * actually merges onto. Git builtins cannot be shadowed by a git alias; a
+ * shell alias named `git` itself is out of scope. A mover flag
+ * (`MOVER_FLAG_RE`), a short option bundling `x` or `s`
+ * (`hasDangerousShortOption` — rebase `-x`/`-kx`, an arbitrary command; merge
+ * or checkout `-s`, a strategy or search run off PATH as `git-<name>`), or a
+ * long option starting `--e`/`--s` (`hasDangerousLongOption` — `--exec`,
+ * `--strategy`, and their `=value` forms) still forfeits, and so does a git
+ * location override anywhere. Returns the target lexically and physically
+ * when the two differ (a cd is logical, git's chdir physical), and the
+ * caller falls back too if any of them is not on a named branch of a repo.
+ */
+function shortcutDirectories(command, cwd) {
+    // No `.trim()`/split reliance below this line for a security decision: both
+    // read NBSP, BOM and form-feed as whitespace and drop them, while a shell's
+    // IFS does not — so a target's trailing NBSP would parse away to a clean,
+    // different directory than the one the shell actually enters.
+    if (NON_ASCII_RE.test(command))
+        return null;
+    if (GIT_LOCATION_RE.test(command) || /[\r\n]/.test(command.trim()))
+        return null;
+    const segments = command
+        .trim()
+        .split('&&')
+        .map((segment) => segment.trim().split(/[ \t]+/));
+    const [first = [], ...rest] = segments;
+    let target;
+    let after;
+    if (first.length === 2 && first[0] === 'cd' && rest.length > 0) {
+        target = first[1] ?? '';
+        after = rest.flat();
+        if (!/^\.{1,2}(?:\/|$)|^\//.test(unquote(target) ?? ''))
+            return null;
+        if (!rest.every((segment) => segment[0] === 'git' && GIT_SUBCOMMAND_ALLOWLIST.has(segment[1] ?? '')))
+            return null;
+    }
+    else if (segments.length === 1 && first[0] === 'git' && first[1] === '-C' && first.length > 3) {
+        target = first[2] ?? '';
+        after = first.slice(3);
+        if (!GIT_SUBCOMMAND_ALLOWLIST.has(after[0] ?? ''))
+            return null;
+    }
+    else {
+        return null;
+    }
+    const plain = (word) => PLAIN_WORD_RE.test(word) && !MOVER_WORDS.has(word) && !MOVER_FLAG_RE.test(word);
+    if (!after.every(plain))
+        return null;
+    if (after.some((word) => hasDangerousShortOption(word) || hasDangerousLongOption(word)))
+        return null;
+    if (!PLAIN_WORD_RE.test(target) && !/^'[^']*'$|^"[^"]*"$/.test(target))
+        return null;
+    return literalDirectories(target, cwd);
+}
+/** Every directory a command names, plus `cwd` — the fail-closed fallback. */
+function fallbackDirectories(command, cwd) {
+    const dirs = [cwd];
+    for (const [, word = ''] of command.matchAll(TARGET_RE)) {
+        // A relative hop is resolved against every directory found so far, so
+        // `cd a && cd b` still reaches `a/b`: an extra candidate costs nothing
+        // but a possible denial, and a missed one is a hole.
+        for (const base of [...dirs]) {
+            for (const target of literalDirectories(word, base) ?? []) {
+                if (!dirs.includes(target))
+                    dirs.push(target);
+            }
+        }
+    }
+    return dirs;
+}
+/**
+ * Anything that could put a command somewhere other than where it started.
+ * Deliberately loose — `echo cd` or `git commit -C HEAD` match too — because
+ * a match only forfeits the no-move path, never a check.
+ */
+const MOVES_RE = /(?:^|[\s;&|(])(?:cd|pushd|popd)(?=$|[\s;&|)])|\s-C(?:\s|$)|[()`]/;
+/** A word the shortcut reads as itself: nothing the shell would expand, split or redirect. */
+const PLAIN_WORD_RE = /^[A-Za-z0-9_./:@%+,=-]+$/;
+/**
+ * Anything outside printable ASCII (tab allowed as a separator), forfeiting
+ * the shortcut before any `.trim()`/split touches the command — see
+ * `shortcutDirectories`'s note on why those cannot be trusted past this
+ * point.
+ */
+const NON_ASCII_RE = /[^\t\x20-\x7E]/;
+/**
+ * Git builtins the shortcut may follow a `cd`/`-C` target with: read-only or
+ * ordinary write commands that act on the repo they are invoked in, never on
+ * another one, and that cannot themselves move the target onto a different
+ * branch than the one just read. Deliberately excludes indirect executors
+ * that run a git command somewhere else (`for-each-repo`, `submodule`),
+ * anything that rewrites history destructively outside a plain invocation
+ * (`filter-branch`, `filter-repo`, `worktree`, `bisect`), and `checkout`/
+ * `switch` — either can move the target's branch mid-command, after
+ * `shortcutDirectories`' caller has already read it once, so a later command
+ * in the same chain would be judged on the branch the target left rather
+ * than the one it moved to. A git builtin cannot be shadowed by a git alias,
+ * which is what makes this allowlist sound.
+ */
+const GIT_SUBCOMMAND_ALLOWLIST = new Set([
+    'status',
+    'log',
+    'diff',
+    'show',
+    'add',
+    'commit',
+    'merge',
+    'rebase',
+    'push',
+    'fetch',
+    'pull',
+    'branch',
+    'reset',
+    'rev-parse',
+    'tag',
+    'stash',
+]);
+/**
+ * A short option (`-x`, `-kx`, `-x./s`) that bundles `x` or `s` among its
+ * option letters, read up to the first non-letter (a stuck argument, `=`, or
+ * end of word) — `git rebase -x <cmd>`/`-kx<cmd>` runs an arbitrary command,
+ * and `git merge -s <strategy>`/`git checkout -s` (`-s` is a bundlable short
+ * flag on several subcommands) can run `git-<strategy>` off PATH. A plain
+ * number (`-5`) is exempt, since `git log -5` is common and harmless.
+ */
+function hasDangerousShortOption(word) {
+    if (!word.startsWith('-') || word.startsWith('--'))
+        return false;
+    if (/^-\d+$/.test(word))
+        return false;
+    const letters = /^-([A-Za-z]+)/.exec(word)?.[1] ?? '';
+    return letters.includes('x') || letters.includes('s');
+}
+/**
+ * A long option that could be `--exec`/`--exec=…` (rebase, arbitrary command)
+ * or `--strategy`/`--strategy-option=…` (merge/rebase, runs `git-<name>` off
+ * PATH) by prefix rather than exact match, since either can carry `=value`.
+ * Over-forfeits `--edit`, `--squash`, and the like on purpose: forfeiting
+ * only falls back to the full check, never widens what the shortcut allows.
+ */
+function hasDangerousLongOption(word) {
+    return word.startsWith('--e') || word.startsWith('--s');
+}
+/** Commands that can move the shell, or run a command string somewhere else. */
+const MOVER_WORDS = new Set([
+    'cd',
+    'pushd',
+    'popd',
+    'eval',
+    'source',
+    '.',
+    'exec',
+    'command',
+    'builtin',
+    'env',
+    'sudo',
+    'xargs',
+    'find',
+    'sh',
+    'bash',
+    'zsh',
+    'dash',
+    'ksh',
+]);
+/** Flags that move a command (`-C`, `--chdir`, `--directory`) or configure git (`-c`). */
+const MOVER_FLAG_RE = /^(?:-C|-c$|--chdir|--directory)/;
+/** Git location overrides: they point git at another repo whatever the cwd. */
+const GIT_LOCATION_RE = /GIT_DIR|GIT_WORK_TREE|GIT_COMMON_DIR|--git-dir|--work-tree/;
+/** One word: double-quoted, single-quoted, or bare up to a separator. */
+const WORD = `("[^"]*"|'[^']*'|[^\\s;&|<>()]+)`;
+/** Every `cd`/`pushd <word>` and every `-C <word>`, wherever it sits. */
+const TARGET_RE = new RegExp(`(?:(?:^|[\\s;&|(])(?:cd|pushd)|\\s-C)\\s+${WORD}`, 'g');
+/**
+ * `word` with its quotes removed, or `null` when it is quoted any other way
+ * than one whole span: `"a"/"b"` is two spans the shell splices, and reading
+ * it as one quoted `a"/"b` names a different directory.
+ */
+function unquote(word) {
+    if (/^'[^']*'$/.test(word) || /^"[^"]*"$/.test(word))
+        return word.slice(1, -1);
+    return /["'\\]/.test(word) ? null : word;
+}
+/**
+ * `word` as an existing, enterable directory resolved against `base` —
+ * lexically (where a logical `cd` lands) and physically (where git's chdir
+ * lands, `..` after a symlink included), both when they differ — or `null`
+ * when it is not a literal path: an expansion (`$`, backtick, `~`), a glob, a
+ * flag or `-`, an escape, a quote this does not read, or a path that does not
+ * resolve. A cd there fails and runs nothing after its `&&`, and this is not
+ * the place to guess what it meant.
+ */
+function literalDirectories(word, base) {
+    const bare = unquote(word);
+    if (bare === null || bare === '' || bare.startsWith('-') || /[$`~*?[\]\\]/.test(bare)) {
+        return null;
+    }
+    const lexical = path.resolve(base, bare);
+    try {
+        // `native` is realpath(3); the JS realpathSync resolves `..` lexically first.
+        const physical = realpathSync.native(path.isAbsolute(bare) ? bare : `${base}/${bare}`);
+        if (!statSync(physical).isDirectory())
+            return null;
+        accessSync(physical, constants.X_OK);
+        if (lexical === physical || !isDirectory(lexical))
+            return [physical];
+        return [lexical, physical];
+    }
+    catch {
+        return null;
+    }
+}
+function isDirectory(dir) {
+    try {
+        return statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** The leases to judge under — `[null]` for none, so one unleased evaluation still runs. */
+function distinctLeases(session, target) {
+    if (session === null)
+        return [target];
+    if (target === null || target.worktreeDir === session.worktreeDir)
+        return [session];
+    return [session, target];
+}

package/factory/orchestrator/dist/integration.js

@@ -1,8 +1,8 @@
 import { SmithError } from './errors.js';
-import { appendEvent } from './events.js';
+import { appendEvent, validateEventEnvelope } from './events.js';
 import { runGit as git } from './git.js';
 import { run } from './testgate.js';
-import { integrationBranchName, RESERVED_TASK_ID } from './worktree.js';
+import { epicBranchPrefix, integrationBranchName, RESERVED_TASK_ID } from './worktree.js';
 /**
  * D-42/P9-26, second half. Moving the worktrees outside the project root
  * (worktree.ts) fixes the tool that went red; it does not fix the reason
@@ -36,13 +36,15 @@ function branchHead(projectDir, branch) {
     }
 }
 /**
- * The current head of `smith/<epic>/integration`, or null when the epic has
- * no integration branch (never planned, never dispatched, wrong --epic).
- * Read here rather than inside epic.ts so the verdict stays git-free and
- * purely a fold over events — the CLI passes the sha in.
+ * The current head of `<prefix>/<epic>/integration` (`bs/` for a new epic,
+ * `smith/` for one that already integrates there — epicBranchPrefix decides
+ * which), or null when the epic has no integration branch (never planned,
+ * never dispatched, wrong --epic). Read here rather than inside epic.ts so
+ * the verdict stays git-free and purely a fold over events — the CLI passes
+ * the sha in.
  */
 export function integrationHeadSha(projectDir, epicId) {
-    return branchHead(projectDir, integrationBranchName(epicId));
+    return branchHead(projectDir, integrationBranchName(epicId, epicBranchPrefix(projectDir, epicId)));
 }
 /** Last-wins fold: the most recent recorded check for this epic, or null. */
 export function latestIntegrationCheck(events, epicId) {
@@ -75,8 +77,18 @@ export function latestIntegrationCheck(events, epicId) {
  * one thing this must never do is write down a pass that nothing earned.
  */
 export async function runIntegrationCheck(input, ctx, opts = {}) {
+    // Refused before the check suite below spends a full run on it: a bad
+    // --causal-parent used to surface only at the append this function makes
+    // once the suite has already finished (D-42's shape, one level up — the
+    // waste here is CPU time, not a git mutation, but the same envelope
+    // `appendEvent` would refuse anyway, so refuse it first).
+    await validateEventEnvelope({
+        session_id: ctx.sessionId,
+        event_type: INTEGRATION_CHECK_EVENT,
+        causal_parent: ctx.causalParent,
+    }, opts);
     const { epicId, projectDir } = input;
-    const branch = integrationBranchName(epicId);
+    const branch = integrationBranchName(epicId, epicBranchPrefix(projectDir, epicId));
     // testgate.run([]) returns pass: true for an empty list — correct there
     // (a task claiming no checks has nothing to short-circuit), and a silent
     // forgery here. "No checks configured" must never read back as "the