@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/bin/lib/real-home-guard.cjs

@@ -0,0 +1,419 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * #3712 — refuse to let an in-process test run reach the developer's REAL home.
+ *
+ * NAMED `real-home-guard`, NOT `test-home-guard`: this is a SOURCE module, and a
+ * source filename matching Node's `test-*` convention gets COLLECTED and EXECUTED
+ * as a test by the remote runner, which never imports it and throws immediately
+ * on load — proven against the unmodified `next` tip 622f43353 (linux-node24,
+ * 37199 passed / 1 failed, failure at `src/test-home-guard.cts`). Meanwhile
+ * `scripts/run-tests.cjs` only globs `tests/**\/*.test.cjs`, so GitHub CI never
+ * sees the failure and stays green while the remote push-gate runner goes red.
+ * Any name works except one matching `test-*`, `*-test`, `*_test`, `*.test.*`,
+ * or `test.*`.
+ *
+ * A runtime kind may declare a global `home` override that is resolved from
+ * `os.homedir()` rather than from the caller's `configDir` (today: codex's
+ * skills kind, `home: ".agents"`, ADR-1239 / #2088 — Codex auto-discovers
+ * global skills from `$HOME/.agents/skills`). Sandboxing `configDir`/`targetDir`
+ * therefore does NOT contain such a kind, and no `assertDestWithinConfigHome`
+ * check can see it: that gate confines a destSubpath to whatever root it is
+ * handed, and here the root IS the escaped home.
+ *
+ * The live defect: an in-process caller that forgot to sandbox HOME installed —
+ * and, via `_removeGsdEntries` / `_syncGsdDir`, PRUNED — inside the real
+ * `~/.agents/skills`, deleting every `gsd-*` skill (observed 71 -> 0, a foreign
+ * `cloudflare` skill surviving) while the suite still exited 0. It is silent
+ * because the runtime's own config home is untouched, so the manifest keeps
+ * reporting a healthy install.
+ *
+ * This lives in its own module because SIX writers resolve a kind `home` and then
+ * write or destroy what is under it. Four are reachable today —
+ * `installRuntimeArtifacts` and `uninstallRuntimeArtifacts` (install-engine.cts)
+ * and `applySurface` (surface.cts); guarding only the install path, as the first
+ * cut of this fix did, left the other two as live bypasses. Two more are
+ * descriptor-dependent and guarded against a future descriptor change rather than
+ * a present escape: `installOpencodeFamilySkills`, which sits behind the
+ * combined-family early return and honors `skillsKindEntry.home` (no
+ * combined-family runtime declares one), and `installAgentsKindStandalone`, which
+ * honors `agentsKindEntry.home` and prunes it (antigravity's global agents kind declares one since #3738; it was the first agents-kind override).
+ * The sixth is `migrateLegacyDevPreferencesToSkill`, which resolves the skills
+ * kind's `home` and writes `SKILL.md` under it. It CREATES rather than prunes,
+ * which is why the first pass of this fix missed it, and it runs from
+ * `_runLegacyInstallMigrations` — i.e. BEFORE `installRuntimeArtifacts`' own
+ * assertion — so it carries its own call.
+ *
+ * DETECTION — three signals, in order:
+ *
+ *   1. `NODE_TEST_CONTEXT` is set by `node --test` and inherited by children, and
+ *      is absent from normal installs outside a Node test context, so ordinary
+ *      production installs are untouched. Precisely: an install spawned BENEATH a
+ *      `node --test` process with an un-sandboxed HOME is refused — that is the
+ *      point, and it is also why this is not stated as "never affects installs".
+ *      `GSD_TEST_MODE` is NOT usable: several in-process test files — including
+ *      the one that caused #3712 — never set it, so gating on it would miss the
+ *      exact case this guard exists for.
+ *   2. `os.userInfo().homedir` reads the passwd entry and ignores `$HOME`, while
+ *      `os.homedir()` prefers `$HOME`. They disagree exactly when a caller
+ *      redirected HOME and agree when one forgot. This is the PRIMARY signal and
+ *      the only one used whenever a passwd entry is readable. It is asked about
+ *      the DESTINATION, not about HOME state: a destination outside the passwd
+ *      home is allowed, and one inside it is refused UNLESS it sits beneath a
+ *      HOME that was sandboxed away from the passwd home. That last exemption is
+ *      not a softening — on Windows the temp root is inside the user's home, so
+ *      without it every sandboxed run is refused (#3725). Both halves are
+ *      required; see `derivesFromSandboxedHome`.
+ *   3. `SANDBOX_MARKER` — consulted ONLY when the passwd entry cannot be read.
+ *
+ * FAILS CLOSED, with one named exception. If the passwd entry is unreadable
+ * (some CI images) we cannot establish that HOME is sandboxed, so a home-override
+ * kind is refused rather than allowed — UNLESS the marker below names the home in
+ * effect. That branch is a deliberate weakening, not a closed door: with no passwd
+ * entry there is nothing that could contradict a marker naming the real home, so a
+ * caller that sandboxed to its own real home would be believed. The alternative is
+ * refusing every run on such a host. Everything else in that branch answers NO
+ * when it cannot tell — see `sameDirectory`. The cost of a false refusal is a failed test naming its own fix;
+ * the cost of a false allow is silent, unrecoverable deletion of a developer's
+ * skills.
+ *
+ * The marker carries the sandbox PATH, not a boolean, and is checked only in that
+ * unreadable-passwd branch — deliberately, because a boolean checked first is not
+ * proof of anything. An ambient or stale `=1` inherited from a parent process, or
+ * left set by an earlier in-process test, would have disarmed the guard entirely
+ * even when HOME plainly equalled the passwd home. Requiring the value to EQUAL
+ * the home now in effect means a leftover marker from some other directory cannot
+ * vouch for this call.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Set by tests/helpers.cjs `sandboxHome()` to the sandboxed home PATH. Only
+ * consulted when the passwd entry is unreadable; see the module docblock.
+ */
+const SANDBOX_MARKER = 'GSD_TEST_HOME_SANDBOX';
+/**
+ * Are these two paths the same directory on disk?
+ *
+ * Compared by FILESYSTEM IDENTITY — `st_dev` + `st_ino` — not by pathname.
+ * `path.resolve()` normalizes separators and `..` but resolves neither symlinks
+ * nor case, and `realpathSync` returns a canonical *pathname*, which two routes to
+ * one directory can still disagree on (a Linux bind mount is the standard case).
+ * `statSync` follows symlinks and reports the inode itself, so a case-variant
+ * HOME, a symlinked HOME, and a bind-mounted HOME all compare equal.
+ *
+ * Fails CLOSED, and "closed" here means returning FALSE. The sole caller is the
+ * passwd-less marker branch, which READS a true as permission to proceed:
+ *
+ *     if (marker && sameDirectory(marker, osMod.homedir())) return;   // allows
+ *
+ * So "cannot tell" must answer NO. An earlier revision returned true for the
+ * unknown/unknown case (both stats failing with something other than
+ * ENOENT/ENOTDIR — EACCES, EPERM, EIO) on the reasoning that "cannot tell" should
+ * make the caller refuse; that reasoning was inverted with respect to this
+ * caller, and it turned an unreadable-stat environment into an unconditional
+ * bypass for anyone who set the marker to any value at all. Reported in review of
+ * #3725. Only two things now answer yes: the same resolved pathname, or two
+ * readable identities that match.
+ */
+function sameDirectory(a, b) {
+    if (node_path_1.default.resolve(a) === node_path_1.default.resolve(b))
+        return true;
+    const ia = identify(a);
+    const ib = identify(b);
+    if (ia.kind === 'ok' && ib.kind === 'ok')
+        return ia.dev === ib.dev && ia.ino === ib.ino;
+    return false;
+}
+function identify(p) {
+    try {
+        const st = node_fs_1.default.statSync(p);
+        return { kind: 'ok', dev: st.dev, ino: st.ino };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return { kind: 'absent' };
+        return { kind: 'unknown' };
+    }
+}
+/**
+ * @param operation - the writer being guarded, for the error message
+ *   (e.g. `installRuntimeArtifacts`), so a failure names its own call site.
+ * @param runtime - canonical runtime id, for the error message.
+ * @param kinds - resolved layout kinds; only those carrying `home` can escape.
+ * @param deps - test seam. The guard's own trigger condition is "HOME equals the
+ *   passwd home", which cannot be reproduced without pointing at the developer's
+ *   real home, so it is injected rather than simulated. Mirrors the `deps.os`
+ *   seam in scripts/live-config-guard.cjs.
+ * @throws {Error} when a global `home` override cannot be shown to be sandboxed.
+ */
+/**
+ * Stamped on every Error this module throws.
+ *
+ * A refusal happens before any LAYOUT-DRIVEN write — legacy install migrations
+ * run first and are rolled back on their own path — so it is not a partial
+ * codex-skills install and must not trigger that rollback. `bin/install.js`'s
+ * pre-config rollback
+ * deletes and recreates every snapshotted `gsd-*` directory in the resolved
+ * skills root, which for an un-sandboxed codex install IS the real
+ * `~/.agents/skills`. Without this marker the guard's own refusal would provoke
+ * the mutation it exists to prevent. Found by review, not by CI.
+ */
+const REFUSAL_FLAG = 'gsdTestHomeGuardRefusal';
+/**
+ * Static remediation line, shared by every refusal this module raises. Hoisted to
+ * module scope because `resolveThroughLinks` refuses too and sits outside
+ * `assertTestHomeSandboxed`'s body, where this used to be a local.
+ */
+const SANDBOX_FIX_HINT = `Fix the TEST, not this guard: sandbox HOME and USERPROFILE BEFORE resolving the ` +
+    `layout, for the duration of the call — use sandboxHome(t, dir) from tests/helpers.cjs ` +
+    `(see #3712).`;
+function refusal(message) {
+    const err = new Error(message);
+    err[REFUSAL_FLAG] = true;
+    return err;
+}
+/** Did `err` come from this guard refusing before any write happened? */
+function isTestHomeGuardRefusal(err) {
+    return Boolean(err && typeof err === 'object' && err[REFUSAL_FLAG]);
+}
+function assertTestHomeSandboxed(operation, runtime, kinds, deps = {}) {
+    const osMod = deps.os ?? node_os_1.default;
+    const env = deps.env ?? process.env;
+    if (!env['NODE_TEST_CONTEXT'])
+        return; // a real install
+    const overriding = (kinds ?? []).filter((k) => k && k.home);
+    if (overriding.length === 0)
+        return; // nothing can escape
+    let passwdHome = null;
+    try {
+        passwdHome = osMod.userInfo().homedir || null;
+    }
+    catch {
+        passwdHome = null;
+    }
+    const fix = SANDBOX_FIX_HINT;
+    const realHome = passwdHome === null ? { kind: 'unknown' } : identify(passwdHome);
+    if (realHome.kind === 'ok') {
+        let effectiveHome = null;
+        try {
+            effectiveHome = osMod.homedir() || null;
+        }
+        catch {
+            effectiveHome = null;
+        }
+        // The question is NOT "is HOME sandboxed right now" — it is "does this
+        // destination land in the real home, other than by deriving from a sandbox
+        // beneath it". The first half alone is not enough: a layout resolved BEFORE
+        // sandboxHome() captures the real `~/.agents` in `kind.home`, and applySurface
+        // takes an already-resolved layout, so a HOME-state check returns "sandboxed"
+        // while the stale destination still points at the real home.
+        //
+        // The second half is not optional either — see `derivesFromSandboxedHome`.
+        // Containment in the real home is not by itself evidence of danger on a
+        // platform whose temp root lives inside the home.
+        for (const kind of overriding) {
+            const declared = node_path_1.default.resolve(node_path_1.default.join(kind.home, kind.destSubpath ?? ''));
+            // Both questions are asked of the path the write will REACH, not the one
+            // it was spelled as; see resolveThroughLinks.
+            const dest = resolveThroughLinks(declared);
+            if (!isInside(dest, realHome))
+                continue;
+            if (derivesFromSandboxedHome(dest, effectiveHome, realHome, passwdHome))
+                continue;
+            throw refusal(`${operation}("${runtime}") was called under a test runner with a destination inside ` +
+                `your REAL home. The "${kind.kind}" kind declares a global home override, so it ` +
+                `resolves from os.homedir() and NOT from the sandboxed configDir — this call would ` +
+                `write inside ${dest} (and install, uninstall and surface-apply also PRUNE GSD ` +
+                `entries there).\nThe real home it was ` +
+                `compared against is ${passwdHome} — if that is not your home, this ` +
+                `refusal is the bug and not the call.\n${fix}`);
+        }
+        return;
+    }
+    // The real home cannot be identified, so containment against it cannot be
+    // evaluated at all. Fall back to the weaker signal: a marker naming the home
+    // currently in effect. Only reachable on hosts with no readable passwd entry,
+    // where the alternative is refusing every such run.
+    //
+    // TWO things are required, not one. An earlier revision returned as soon as the
+    // marker matched the effective HOME, which attested that a caller sandboxed HOME
+    // but said NOTHING about where these destinations resolve — so a layout captured
+    // BEFORE sandboxHome(), still naming the real `~/.agents`, was waved straight
+    // through on a passwd-less host. That is the same stale-layout shape the primary
+    // branch above refuses by design, and it made the marker a bypass for exactly
+    // the case the guard exists for. Reported in Codex review of #3725.
+    //
+    // The marker must also IDENTIFY: `sameDirectory` answers yes for two identical
+    // unidentifiable pathnames (see its docblock), and that is not enough to place a
+    // destination against.
+    const marker = env[SANDBOX_MARKER];
+    const markerId = marker ? identify(marker) : { kind: 'unknown' };
+    if (marker && markerId.kind === 'ok' && sameDirectory(marker, osMod.homedir())) {
+        const stale = overriding.find((kind) => !isInside(resolveThroughLinks(node_path_1.default.resolve(node_path_1.default.join(kind.home, kind.destSubpath ?? ''))), markerId));
+        if (!stale)
+            return;
+        throw refusal(`${operation}("${runtime}") was called under a test runner on a host with no identifiable ` +
+            `passwd home. HOME was sandboxed and recorded, but the "${stale.kind}" kind resolves to ` +
+            `${resolveThroughLinks(node_path_1.default.resolve(node_path_1.default.join(stale.home, stale.destSubpath ?? '')))}, ` +
+            `which is NOT beneath that sandbox — so this layout was resolved before the sandbox and still ` +
+            `names another home. A recorded sandbox vouches for HOME, never for a destination that does ` +
+            `not derive from it.\n${fix}`);
+    }
+    throw refusal(`${operation}("${runtime}") was called under a test runner and this environment has no ` +
+        `identifiable passwd home, so GSD cannot establish where the real home is. The ` +
+        `"${overriding[0]?.kind}" kind declares a global home override, which resolves from ` +
+        `os.homedir() and would write inside whatever real home that is (and, for the pruning ` +
+        `writers, delete GSD entries there). Refusing rather than guessing.\n${fix}`);
+}
+/**
+ * The path `dest` will actually resolve to when it is written.
+ *
+ * `dest` usually does not exist yet — that is the point, it is about to be
+ * created — so `realpathSync` cannot be called on it directly. Walk up to the
+ * nearest ancestor that DOES exist, canonicalize that, and re-append the tail.
+ *
+ * Without this the sandbox exemption below is escapable: with HOME sandboxed to
+ * `$REAL/tmp-home` and `$REAL/tmp-home/.agents` a symlink (or Windows junction)
+ * onto the real `$REAL/.agents`, the lexical ancestor
+ * walk reaches the sandbox and the write is allowed — straight into the real
+ * home. Identity comparison alone does not close it, because each ancestor is
+ * identified in isolation and the alias sits BETWEEN dest and the sandbox.
+ * Found by review, not by CI.
+ *
+ * KNOWN LIMITATION — a subordinate BIND MOUNT of the real `~/.agents` at
+ * `<sandbox>/.agents` is NOT closed by this. A bind mount is not a link:
+ * `realpathSync` keeps the mount-point spelling, so the canonical destination
+ * still reads as "beneath the sandbox" while the write reaches the real
+ * directory. `sameDirectory` above already records that realpath cannot unify
+ * bind-mounted spellings; this inherits that limit. Closing it needs mount-table
+ * introspection, which is not portable, and the setup — deliberately mounting the
+ * one directory this guard protects into a sandbox inside the home — is not a
+ * shape any caller here produces. A cross-process swap of a checked directory
+ * between this call and the write (TOCTOU) is likewise out of reach and not
+ * claimed.
+ *
+ * Canonicalization itself fails CLOSED — see the errno split below. A component
+ * that EXISTS but cannot be resolved is refused, because falling back to the
+ * lexical spelling is the exact ALLOW an unresolvable alias needs.
+ */
+function resolveThroughLinks(dest) {
+    const tail = [];
+    let cur = node_path_1.default.resolve(dest);
+    for (;;) {
+        try {
+            return node_path_1.default.join(node_fs_1.default.realpathSync(cur), ...tail);
+        }
+        catch (err) {
+            // Same errno split `identify` already draws, and deliberately the same one:
+            // both functions are asking "does this path exist as named?", so they must
+            // not disagree. ENOENT/ENOTDIR mean NOT THERE — the expected case, since a
+            // fresh install resolves a destination that does not exist yet and realpath
+            // fails on the leaf and on every not-yet-created ancestor. That is what this
+            // walk is FOR, so keep walking.
+            //
+            // Any other errno means the component EXISTS but could not be canonicalized —
+            // EACCES/EPERM on a directory whose mode changed, ELOOP on a symlink cycle,
+            // EIO on a failing mount. Falling through to the lexical spelling there is a
+            // FAIL-OPEN that precisely inverts this function's purpose: an aliased
+            // `<sandbox>/.agents` that cannot be resolved keeps its sandbox spelling,
+            // satisfies the nested-sandbox exemption, and the write is ALLOWED straight
+            // into the real home. The module documents that it fails CLOSED with exactly
+            // ONE named exception (the marker branch); a swallowed canonicalization error
+            // was a second, unnamed one. Refuse instead. (Codex review of #3725.)
+            const code = err?.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw refusal(`A component of the destination could not be canonicalized, so this guard cannot ` +
+                    `tell whether the write would reach your REAL home.\nFailed on: ${cur} ` +
+                    `(${code ?? 'unknown error'})\nSymlinks and junctions are resolved BEFORE the ` +
+                    `decision, because an aliased "<sandbox>/.agents" would otherwise read as confined ` +
+                    `while pointing at the real one. A component that cannot be resolved is refused ` +
+                    `rather than assumed safe.\n${SANDBOX_FIX_HINT}`);
+            }
+            const parent = node_path_1.default.dirname(cur);
+            if (parent === cur)
+                return node_path_1.default.resolve(dest);
+            tail.unshift(node_path_1.default.basename(cur));
+            cur = parent;
+        }
+    }
+}
+/**
+ * Is `dest` inside a HOME that has been sandboxed away from the passwd home?
+ *
+ * Asked only once `dest` is already known to be inside the real home, and it is
+ * what makes that fact non-fatal on Windows: there `os.tmpdir()` is
+ * `%USERPROFILE%\AppData\Local\Temp` by default (Node honors `TEMP`/`TMP`,
+ * so this is the usual case rather than a guarantee) — so in practice every
+ * sandbox a test creates is a descendant of the real home. Containment in the
+ * real home is therefore true of the correctly-sandboxed case and the dangerous
+ * one alike, and cannot separate them by itself. POSIX conceals this, because
+ * `/tmp` and `/var/folders` both sit outside `$HOME`. All six Windows shards of
+ * #3725 failed on legitimately sandboxed destinations before this conjunct
+ * existed.
+ *
+ * TWO conditions carry the decision, and neither suffices alone:
+ *
+ *   - the passwd home is NOT beneath that HOME — see the comment on that check;
+ *     without it a HOME that merely spells the real home more widely (`/Users`,
+ *     `C:\Users`) is mistaken for a sandbox.
+ *   - `dest` is beneath that sandboxed HOME — otherwise this decays into the
+ *     "is HOME sandboxed?" check the module docblock rejects, and a layout
+ *     resolved before the sandbox walks straight through.
+ *
+ * The first check below — HOME differs from the passwd home — is a cheap fast
+ * path, NOT an independent condition: `isInside` is reflexive, so whenever HOME
+ * identifies the passwd home the second check already returns false on its own.
+ * Removing it changes no outcome; it is kept to answer the common case without
+ * an ancestor walk. Raised in review of #3725 against prose that claimed the
+ * three were independent.
+ *
+ * Fails CLOSED: an unreadable or unidentifiable HOME returns false, so the
+ * caller refuses rather than exempting a destination it cannot place.
+ */
+function derivesFromSandboxedHome(dest, effectiveHome, realHome, passwdHome) {
+    if (effectiveHome === null)
+        return false;
+    const eff = identify(effectiveHome);
+    if (eff.kind !== 'ok')
+        return false;
+    if (eff.dev === realHome.dev && eff.ino === realHome.ino)
+        return false;
+    // A sandbox sits BENEATH the real home (the Windows temp shape) — never above
+    // it. A destination's ancestor chain is linear, so "inside the real home AND
+    // inside the effective HOME" admits two arrangements, not one: the intended
+    // `effectiveHome ⊂ realHome`, and `realHome ⊂ effectiveHome` — HOME pointed at
+    // `/Users`, `/home`, or `C:\Users`. The second is not a sandbox, it is the real
+    // home reached by a wider spelling, and without this it exempts a stale
+    // destination. Reported in review of #3725 as the one leaking cell of a
+    // six-row truth table.
+    if (isInside(passwdHome, eff))
+        return false;
+    return isInside(dest, eff);
+}
+/**
+ * Is `child` at or beneath the directory identified by `rootId`?
+ *
+ * Walks `child`'s ancestors comparing filesystem identity rather than string
+ * prefixes, because `child` typically does not exist yet (that is the point — it
+ * is about to be created) while its ancestors do. A prefix test would miss a
+ * case-variant or symlinked spelling of the same ancestor, which is the exact
+ * class this guard exists to catch.
+ */
+function isInside(child, rootId) {
+    let cur = node_path_1.default.resolve(child);
+    for (;;) {
+        const id = identify(cur);
+        if (id.kind === 'ok' && id.dev === rootId.dev && id.ino === rootId.ino)
+            return true;
+        const parent = node_path_1.default.dirname(cur);
+        if (parent === cur)
+            return false;
+        cur = parent;
+    }
+}
+module.exports = { assertTestHomeSandboxed, isTestHomeGuardRefusal, SANDBOX_MARKER };

package/gsd-core/bin/lib/refactor-trigger-command-router.cjs

@@ -379,42 +379,18 @@ function resolveLedgerWindow(cwd, padded, file, line, kind, reasonText, windowsO
 }
 // ─── evaluate ────────────────────────────────────────────────────────────────
 const EVALUATE_USAGE = 'Usage: gsd-tools refactor evaluate --phase <N> [--since <ref>] [--raw]';
-function handleEvaluate(args, cwd, raw, c, complexity, git, windowsOverride) {
-    const rest = args.slice(2);
-    const phaseCheck = requirePhaseArg(rest, complexity, EVALUATE_USAGE);
-    if (!phaseCheck.ok)
-        return phaseCheck.result;
-    // Step 3: resolve PHASE_DIR + anchor (phaseStartCommit, or --since override).
-    const resolved = resolvePhaseDirForArg(cwd, phaseCheck.phase);
-    if (resolved === null) {
-        c.output({ verdict: complexity.VERDICT.SKIPPED, reason: complexity.REASON.REFACTOR_INVALID_PHASE, phase: phaseCheck.phase }, raw);
-        return undefined;
-    }
-    const { phaseDir, padded } = resolved;
-    const sinceFlag = readFlag(rest, '--since');
-    const sinceOverride = sinceFlag.present && !sinceFlag.flagShaped ? sinceFlag.value.trim() : '';
-    const sinceRef = sinceOverride !== '' ? sinceOverride : git.phaseStartCommit(cwd, phaseDir);
-    if (sinceRef === null) {
-        c.output({ verdict: complexity.VERDICT.SKIPPED, reason: complexity.REASON.REFACTOR_GIT_UNAVAILABLE, phase: padded }, raw);
-        return undefined;
-    }
-    const touched = git.changedFilesSince(cwd, sinceRef);
-    if (touched === null) {
-        c.output({ verdict: complexity.VERDICT.SKIPPED, reason: complexity.REASON.REFACTOR_GIT_UNAVAILABLE, phase: padded }, raw);
-        return undefined;
-    }
-    // Step 4: empty touched set.
-    if (touched.length === 0) {
-        c.output({ verdict: complexity.VERDICT.BELOW_THRESHOLD, reason: complexity.REASON.REFACTOR_NO_TOUCHED_FILES, phase: padded }, raw);
-        return undefined;
-    }
-    // Step 5: filter with isAnalyzablePath; read each survivor. A read failure
-    // (or a path that escapes the project root) skips that one file with a
-    // reason and the run continues — never aborts the evaluation.
+/**
+ * Step 5 of `evaluate`: filter `touched` with `isAnalyzablePath`, read each
+ * survivor and classify it into `analyzed`. A read failure (or a path that
+ * escapes the project root) skips that one file with
+ * `REFACTOR_FILE_UNREADABLE` and the loop continues — never aborts the
+ * evaluation. Only files that were SUCCESSFULLY analyzed feed
+ * `successfullyAnalyzedFiles` — an unreadable file must never wipe that
+ * file's baseline history via nextBaseline's "file in analyzedFiles but
+ * function missing" prune rule.
+ */
+function analyzeTouchedFiles(cwd, touched, complexity) {
     const analyzed = [];
-    // Only files that were SUCCESSFULLY analyzed feed nextBaseline's prune set
-    // — an unreadable file must never wipe that file's baseline history via
-    // the "file in analyzedFiles but function missing" prune rule.
     const successfullyAnalyzedFiles = [];
     for (const relFile of touched) {
         if (!complexity.isAnalyzablePath(relFile))
@@ -441,16 +417,18 @@ function handleEvaluate(args, cwd, raw, c, complexity, git, windowsOverride) {
             successfullyAnalyzedFiles.push(relFile);
         }
     }
-    // Step 6.
-    const planningDirPath = planningDir(cwd);
-    const baselineRead = complexity.readBaseline(planningDirPath);
-    const evalConfig = readEvalConfig(cwd);
-    const evaluation = complexity.evaluateCandidates({
-        analyzed,
-        baseline: baselineRead.baseline,
-        threshold: evalConfig.threshold,
-        jumpDelta: evalConfig.jumpDelta,
-    });
+    return { analyzed, successfullyAnalyzedFiles };
+}
+/**
+ * Steps 7-9 of `evaluate`: write the proposal artifact when TRIGGERED, write
+ * the next baseline (failure is reported but never fails the command),
+ * record the strict-mode ledger window when applicable, and assemble the
+ * final result object. Pure orchestration over the side-effecting helpers —
+ * every degrade path (artifact write throw, baseline write failure, ledger
+ * unavailable) keeps its existing reason code and result shape.
+ */
+function finalizeEvaluation(opts) {
+    const { cwd, phaseDir, padded, planningDirPath, complexity, evaluation, evalConfig, baselineRead, analyzed, successfullyAnalyzedFiles, windowsOverride, } = opts;
     // Step 7.
     let artifactWritten = false;
     let artifactPath = null;
@@ -518,6 +496,54 @@ function handleEvaluate(args, cwd, raw, c, complexity, git, windowsOverride) {
         result.ledger_note = ledgerNote;
     if (warnings.length > 0)
         result.warnings = warnings;
+    return result;
+}
+function handleEvaluate(args, cwd, raw, c, complexity, git, windowsOverride) {
+    const rest = args.slice(2);
+    const phaseCheck = requirePhaseArg(rest, complexity, EVALUATE_USAGE);
+    if (!phaseCheck.ok)
+        return phaseCheck.result;
+    // Step 3: resolve PHASE_DIR + anchor (phaseStartCommit, or --since override).
+    const resolved = resolvePhaseDirForArg(cwd, phaseCheck.phase);
+    if (resolved === null) {
+        c.output({ verdict: complexity.VERDICT.SKIPPED, reason: complexity.REASON.REFACTOR_INVALID_PHASE, phase: phaseCheck.phase }, raw);
+        return undefined;
+    }
+    const { phaseDir, padded } = resolved;
+    const sinceFlag = readFlag(rest, '--since');
+    const sinceOverride = sinceFlag.present && !sinceFlag.flagShaped ? sinceFlag.value.trim() : '';
+    const sinceRef = sinceOverride !== '' ? sinceOverride : git.phaseStartCommit(cwd, phaseDir);
+    if (sinceRef === null) {
+        c.output({ verdict: complexity.VERDICT.SKIPPED, reason: complexity.REASON.REFACTOR_GIT_UNAVAILABLE, phase: padded }, raw);
+        return undefined;
+    }
+    const touched = git.changedFilesSince(cwd, sinceRef);
+    if (touched === null) {
+        c.output({ verdict: complexity.VERDICT.SKIPPED, reason: complexity.REASON.REFACTOR_GIT_UNAVAILABLE, phase: padded }, raw);
+        return undefined;
+    }
+    // Step 4: empty touched set.
+    if (touched.length === 0) {
+        c.output({ verdict: complexity.VERDICT.BELOW_THRESHOLD, reason: complexity.REASON.REFACTOR_NO_TOUCHED_FILES, phase: padded }, raw);
+        return undefined;
+    }
+    // Step 5: filter, read, and classify each touched file.
+    const { analyzed, successfullyAnalyzedFiles } = analyzeTouchedFiles(cwd, touched, complexity);
+    // Step 6.
+    const planningDirPath = planningDir(cwd);
+    const baselineRead = complexity.readBaseline(planningDirPath);
+    const evalConfig = readEvalConfig(cwd);
+    const evaluation = complexity.evaluateCandidates({
+        analyzed,
+        baseline: baselineRead.baseline,
+        threshold: evalConfig.threshold,
+        jumpDelta: evalConfig.jumpDelta,
+    });
+    // Steps 7-9: artifact write, baseline persistence, strict-mode ledger.
+    const result = finalizeEvaluation({
+        cwd, phaseDir, padded, planningDirPath, complexity, evaluation, evalConfig,
+        baselineRead, analyzed, successfullyAnalyzedFiles, windowsOverride,
+    });
     c.output(result, raw);
     return undefined;
 }