@juzser/blacksmith 0.2.0 → 0.4.0

package/factory/orchestrator/dist/hookDecision.js

@@ -11,6 +11,8 @@
 // `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 { accessSync, constants, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
 import { detectCurrentBranch, detectRepoRoot, evaluateCommand, loadGuardrailPolicy, } from './policy.js';
 import { activeSandboxFor } from './sandbox.js';
 /**
@@ -32,7 +34,9 @@ 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);
     const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : '';
     const command = typeof payload.tool_input?.command === 'string' ? payload.tool_input.command : '';
@@ -44,34 +48,72 @@ 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;
+    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) {
+                reason = decision.violations[0]?.reason ?? 'guardrails.yml denied this command.';
+                break;
+            }
+        }
+        if (reason !== null)
+            break;
+    }
+    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 +129,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 +137,253 @@ export function decideHookPayload(raw, fallbackCwd) {
         },
     };
 }
+/**
+ * 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/impact.js

@@ -216,6 +216,11 @@ function consumes(names, symbol) {
 /**
  * A promise against the diff of the file it names. A file the diff does not
  * hold was not touched, so its exports are as they were: kept.
+ *
+ * That inference is only sound because `collectExportDiffs` never drops a
+ * promised file: whatever it cannot read it hands over as `unverifiable`
+ * rather than leaving out. Absent therefore means untouched here, and can go
+ * on meaning it only while that stays true on the other side.
  */
 function verdictOn(file, diffs) {
     const diff = diffs.find((entry) => entry.file === file);
@@ -322,13 +327,30 @@ export function exportImpact(graph, diffs, claims, keepsExports = []) {
  * `ls-tree` before `show` on purpose — a file added on this branch is absent
  * from the integration branch, and asking `show` for it would raise an error
  * that means "new file", which is not an error at all.
+ *
+ * `keepsExports` is here because silence means two different things downstream.
+ * A changed file this scanner does not speak for — a `.yml`, a lockfile, a
+ * `.vue` — is left out, and for a file nobody named that is right: reporting
+ * every one of them as a hole is the noise the header refuses to make. But
+ * `verdictOn` reads a promised file's absence as "not touched, so kept", and
+ * for a file the diff dropped that inference is false — the task changed it,
+ * nobody read it, and the strongest verdict in this module is minted over a
+ * file that was never opened. A promise is a question that was explicitly
+ * asked, so it gets an explicit answer: unreadable here is `unverifiable`,
+ * which `verdictOn` turns into `unverified` and the header's "reported, never
+ * fatal" covers. Skipped stays skipped for everything else.
  */
-export function collectExportDiffs(worktreeDir, changedFiles) {
+export function collectExportDiffs(worktreeDir, changedFiles, keepsExports = []) {
     const integrationBranch = integrationBranchFor(worktreeDir);
+    const promised = new Set(keepsExports);
     const diffs = [];
     for (const file of changedFiles) {
-        if (!DEFAULT_SOURCE_EXTENSIONS.includes(extname(file)))
+        if (!DEFAULT_SOURCE_EXTENSIONS.includes(extname(file))) {
+            if (promised.has(file)) {
+                diffs.push({ file, removed: [], added: [], signatureChanged: [], unverifiable: true });
+            }
             continue;
+        }
         const listed = runGit(worktreeDir, [
             'ls-tree',
             '-r',

package/factory/orchestrator/dist/integration.js

@@ -1,5 +1,5 @@
 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';
@@ -75,6 +75,16 @@ 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);
     // testgate.run([]) returns pass: true for an empty list — correct there