@pmelab/gtd 26.1.0 → 27.0.0

package/src/cli/Program.ts

@@ -42,6 +42,7 @@ import {
   type NextMatch,
   type StatusChange,
   selectPath,
+  EXIT_OK,
 } from "../wire/index.js"
 import {
   currentRest,
@@ -94,13 +95,16 @@ import {
   type ArtifactOut,
   type CommandRequirements,
   type JsonMode,
+  type SuccessExit,
 } from "./Output.js"
 export {
   SelectorUsageError,
   type ArtifactOut,
   type CommandRequirements,
   type JsonMode,
+  type SuccessExit,
 } from "./Output.js"
+import { runStraysCommand } from "./Strays.js"
 import { runHistoryFetchCommand, runHistoryListCommand, runHistoryShowCommand } from "./History.js"
 
 /**
@@ -161,6 +165,13 @@ export type Command =
   | { readonly kind: "historyList" }
   | { readonly kind: "historyShow"; readonly ref: string }
   | { readonly kind: "historyFetch"; readonly remote: string }
+  | {
+      readonly kind: "strays"
+      /** Each side of `<base>..<tip>`; an empty side is `HEAD`, as git reads it. */
+      readonly base: string
+      readonly tip: string
+      readonly globs: readonly string[]
+    }
   | {
       readonly kind: "judgeRun"
       readonly provider?: "fixed" | "jev" | "llm"
@@ -1149,6 +1160,7 @@ export const needsOf = (kind: Command["kind"]): Needs => {
     case "install":
     case "loop":
     case "judgeRun":
+    case "strays":
       return "none"
     case "check":
     case "uncheck":
@@ -1166,18 +1178,27 @@ export const standaloneKinds = (): readonly Command["kind"][] => [
   "install",
   "loop",
   "judgeRun",
+  "strays",
 ]
 
 /**
  * Dispatches to the named `run*Command` handler for every `Command.kind` —
  * the counterpart of `Cli.ts`'s `parseArgv`, which has already validated
- * every field a handler receives. A command choosing its own exit code is
- * unrepresentable: every branch returns `Effect<void>`, and `Cli.ts`'s
- * `runCli` supplies `EXIT_OK` once, after this Effect succeeds.
+ * every field a handler receives. Only `strays` chooses its exit code; every
+ * other branch returns `Effect<void>` and resolves to `EXIT_OK`.
  */
+const dispatchCommand = (
+  command: Command,
+  json: JsonMode,
+  out: ArtifactOut,
+): Effect.Effect<SuccessExit, Error, CommandRequirements> => {
+  if (command.kind === "strays") return runStraysCommand(command, json, out)
+  return Effect.as(dispatchVoidCommand(command, json, out), EXIT_OK)
+}
+
 // fallow-ignore-next-line complexity
 const dispatchVoidCommand = (
-  command: Command,
+  command: Exclude<Command, { kind: "strays" }>,
   json: JsonMode,
   out: ArtifactOut,
 ): Effect.Effect<void, Error, CommandRequirements> => {
@@ -1255,8 +1276,8 @@ export const runCommand = (
   command: Command,
   json: JsonMode,
   out: ArtifactOut,
-): Effect.Effect<void, Error, CommandRequirements> => {
-  const dispatch = dispatchVoidCommand(command, json, out)
+): Effect.Effect<SuccessExit, Error, CommandRequirements> => {
+  const dispatch = dispatchCommand(command, json, out)
   if (needsOf(command.kind) !== "state") return dispatch
   return Effect.gen(function* () {
     const git = yield* GitService
@@ -1278,6 +1299,6 @@ export const runCommand = (
     for (const warning of config.warnings) {
       yield* narrator.warn(`gtd: warning: ${formatDiagnostic(warning)}`)
     }
-    yield* dispatch
+    return yield* dispatch
   })
 }

package/src/cli/Strays.test.ts

@@ -0,0 +1,88 @@
+import { Effect } from "effect"
+import { describe, expect, it } from "vitest"
+import { EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_STRAYS_FOUND } from "../wire/index.js"
+import { InMemRepo, makeCapturingCliIo } from "../testkit/index.js"
+import { runCli } from "./index.js"
+
+const seed = (): InMemRepo => {
+  const repo = new InMemRepo()
+  repo.writeFile("README.md", "x\n")
+  repo.commitAllWithPrefix("base")
+  repo.updateRef("base", "HEAD")
+  repo.writeFile("src/a.ts", "a\n")
+  repo.writeFile("notes/b.md", "b\n")
+  repo.writeFile("notes/c.md", "c\n")
+  repo.commitAllWithPrefix("work")
+  return repo
+}
+
+const strays = async (repo: InMemRepo, ...args: string[]) => {
+  const { io, result } = makeCapturingCliIo(repo)
+  await Effect.runPromise(runCli(["node", "gtd.js", "strays", ...args], io))
+  return result()
+}
+
+describe("gtd strays — stderr commentary", () => {
+  it("quiet: only the N of M summary", async () => {
+    const { stderr, exitCode } = await strays(seed(), "base..HEAD", "src/**")
+    expect(stderr).toBe("gtd strays: 2 of 3 touched files outside the allowlist\n")
+    expect(exitCode).toBe(EXIT_STRAYS_FOUND)
+  })
+
+  it("--verbose: one stray: line per path, then the summary", async () => {
+    const { stderr } = await strays(seed(), "base..HEAD", "src/**", "--verbose")
+    expect(stderr).toBe(
+      'stray: "notes/b.md"\nstray: "notes/c.md"\ngtd strays: 2 of 3 touched files outside the allowlist\n',
+    )
+  })
+
+  it("a path with a line break and an escape reaches stderr JSON-quoted", async () => {
+    const repo = seed()
+    repo.writeFile("x\n\x1b[2J", "x\n")
+    repo.commitAllWithPrefix("odd")
+    const { stderr } = await strays(repo, "base..HEAD", "src/**", "--verbose")
+    expect(stderr).toContain('stray: "x\\n\\u001b[2J"\n')
+    expect(stderr).not.toContain("\x1b")
+  })
+
+  it("clean run: the single all-inside line", async () => {
+    const { stderr, exitCode } = await strays(seed(), "base..HEAD", "src/**", "notes/*")
+    expect(stderr).toBe("gtd strays: no strays — 3 touched files, all inside the allowlist\n")
+    expect(exitCode).toBe(EXIT_OK)
+  })
+})
+
+describe("gtd strays --json=<index>", () => {
+  it("--json=0 prints the first stray, exit 10", async () => {
+    const { stdout, exitCode } = await strays(seed(), "base..HEAD", "src/**", "--json=0")
+    expect(stdout).toBe("notes/b.md\n")
+    expect(exitCode).toBe(EXIT_STRAYS_FOUND)
+  })
+
+  it("--json=0 on a clean range prints nothing, exit 0", async () => {
+    const { stdout, exitCode } = await strays(seed(), "base..HEAD", "src/**", "notes/*", "--json=0")
+    expect(stdout).toBe("")
+    expect(exitCode).toBe(EXIT_OK)
+  })
+
+  it("an index past the end prints nothing and keeps exit 10", async () => {
+    const { stdout, exitCode } = await strays(seed(), "base..HEAD", "src/**", "--json=5")
+    expect(stdout).toBe("")
+    expect(exitCode).toBe(EXIT_STRAYS_FOUND)
+  })
+})
+
+describe("gtd strays — unknown revisions", () => {
+  it.each([
+    ["nope..HEAD", "nope"],
+    ["HEAD..nope", "nope"],
+    ["HEAD..--output=x", "--output=x"],
+  ])("%s: exit 1, empty stdout, no file written", async (range, side) => {
+    const repo = seed()
+    const { stdout, stderr, exitCode } = await strays(repo, range)
+    expect(stdout).toBe("")
+    expect(stderr).toContain(`unknown revision '${side}'`)
+    expect(exitCode).toBe(EXIT_RUNTIME_ERROR)
+    expect(repo.readFile("x")).toBeUndefined()
+  })
+})

package/src/cli/Strays.ts

@@ -0,0 +1,56 @@
+import { Effect } from "effect"
+import { GitService, GtdError, Narrator, type GitOperations } from "../platform/index.js"
+import { strayPaths } from "../step/index.js"
+import { EXIT_OK, EXIT_STRAYS_FOUND } from "../wire/index.js"
+import {
+  SelectorUsageError,
+  writeSelection,
+  type ArtifactOut,
+  type JsonMode,
+  type SuccessExit,
+} from "./Output.js"
+
+// `^{commit}` peels to a commit: a tree or blob would make `git diff` print paths not anchored at the repo root.
+const resolveSide = (git: GitOperations, side: string): Effect.Effect<string, Error> =>
+  git
+    .resolveRef(`${side}^{commit}`)
+    .pipe(Effect.mapError(() => new GtdError(`gtd strays: unknown revision '${side}'`)))
+
+/** stdout carries the array alone; the summary is ungated stderr so a quiet run still explains its exit code, the per-path lines are narration. */
+export const runStraysCommand = (
+  command: {
+    readonly base: string
+    readonly tip: string
+    readonly globs: readonly string[]
+  },
+  json: JsonMode,
+  out: ArtifactOut,
+): Effect.Effect<SuccessExit, Error, GitService | Narrator> =>
+  Effect.gen(function* () {
+    const git = yield* GitService
+    const narrator = yield* Narrator
+    const base = yield* resolveSide(git, command.base)
+    const tip = yield* resolveSide(git, command.tip)
+    const touched = yield* git.diffPaths(base, tip)
+    const strays = strayPaths(touched, command.globs)
+    const total = touched.length
+
+    if (json.kind === "select") {
+      // An index past the end is absent here, not a usage error: it must not mask the exit 0/10 verdict.
+      yield* writeSelection(out, strays, json.path).pipe(
+        Effect.catchIf(
+          (error) => error instanceof SelectorUsageError && /^\d+$/.test(json.path),
+          () => Effect.void,
+        ),
+      )
+    } else out.write(`${JSON.stringify(strays)}\n`)
+
+    // JSON-quoted: a path is author-controlled and must not carry terminal escapes.
+    for (const path of strays) yield* narrator.narrate(`stray: ${JSON.stringify(path)}`)
+    yield* narrator.warn(
+      strays.length === 0
+        ? `gtd strays: no strays — ${total} touched files, all inside the allowlist`
+        : `gtd strays: ${strays.length} of ${total} touched files outside the allowlist`,
+    )
+    return strays.length === 0 ? EXIT_OK : EXIT_STRAYS_FOUND
+  })

package/src/platform/Git.test.ts

@@ -1,6 +1,12 @@
+import { execFileSync } from "node:child_process"
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { NodeContext } from "@effect/platform-node"
 import { Cause, Effect, Exit } from "effect"
 import { describe, expect, it } from "vitest"
-import { InvalidRefError, resolvedRefOrCorrupted } from "./Git.js"
+import { GitService, InvalidRefError, resolvedRefOrCorrupted } from "./Git.js"
+import { Host } from "./index.js"
 import { gitTiers, runGitServiceContract, runGitScriptContract } from "../testkit/index.js"
 
 /**
@@ -45,3 +51,92 @@ for (const makeTier of gitTiers) {
     runGitScriptContract(makeTier)
   })
 }
+
+describe("diffPaths [Live]", () => {
+  it("stays repo-root-relative with diff.relative=true and a subdirectory cwd", async () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-diffpaths-")))
+    try {
+      const git = (...args: string[]) =>
+        execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: "pipe" }).trim()
+      git("init")
+      git("config", "user.email", "test@test.com")
+      git("config", "user.name", "Test")
+      git("config", "commit.gpgsign", "false")
+      git("config", "diff.relative", "true")
+      mkdirSync(join(root, "sub"))
+      writeFileSync(join(root, "sub", "a.txt"), "a")
+      writeFileSync(join(root, "top.txt"), "t")
+      git("add", "-A")
+      git("commit", "-m", "one")
+      const base = git("rev-parse", "HEAD")
+      writeFileSync(join(root, "sub", "a.txt"), "b")
+      writeFileSync(join(root, "top.txt"), "u")
+      git("add", "-A")
+      git("commit", "-m", "two")
+      const tip = git("rev-parse", "HEAD")
+      const paths = await Effect.runPromise(
+        Effect.flatMap(GitService, (g) => g.diffPaths(base, tip)).pipe(
+          Effect.provide(GitService.Live),
+          Effect.provide(Host.layer({ root: join(root, "sub"), home: root, env: {} })),
+          Effect.provide(NodeContext.layer),
+        ),
+      )
+      expect([...paths].sort()).toEqual(["sub/a.txt", "top.txt"])
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  // An exported GIT_DIR/GIT_WORK_TREE would send this test's commits to the real repo;
+  // the pinned config keeps a global commit.gpgsign or missing identity from failing them.
+  const cleanEnv = {
+    ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_"))),
+    GIT_CONFIG_COUNT: "3",
+    GIT_CONFIG_KEY_0: "commit.gpgsign",
+    GIT_CONFIG_VALUE_0: "false",
+    GIT_CONFIG_KEY_1: "user.email",
+    GIT_CONFIG_VALUE_1: "test@test.com",
+    GIT_CONFIG_KEY_2: "user.name",
+    GIT_CONFIG_VALUE_2: "Test",
+  }
+
+  it("reports a submodule pointer bump whatever diff.ignoreSubmodules and .gitmodules ignore say", async () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-diffpaths-sm-")))
+    try {
+      const run = (cwd: string, ...args: string[]) =>
+        execFileSync("git", args, { cwd, encoding: "utf8", stdio: "pipe", env: cleanEnv }).trim()
+      const source = join(root, "source")
+      const repo = join(root, "super")
+      mkdirSync(source)
+      mkdirSync(repo)
+      run(source, "init")
+      writeFileSync(join(source, "f.txt"), "1")
+      run(source, "add", "-A")
+      run(source, "commit", "-m", "s1")
+      run(repo, "init")
+      run(repo, "config", "diff.ignoreSubmodules", "all")
+      run(repo, "-c", "protocol.file.allow=always", "submodule", "add", source, "sub")
+      run(repo, "config", "-f", ".gitmodules", "submodule.sub.ignore", "all")
+      run(repo, "add", "-A")
+      run(repo, "commit", "-m", "one")
+      const base = run(repo, "rev-parse", "HEAD")
+      const clone = join(repo, "sub")
+      writeFileSync(join(clone, "f.txt"), "2")
+      run(clone, "add", "-A")
+      run(clone, "commit", "-m", "s2")
+      run(repo, "add", "--force", "sub")
+      run(repo, "commit", "-m", "two")
+      const tip = run(repo, "rev-parse", "HEAD")
+      const paths = await Effect.runPromise(
+        Effect.flatMap(GitService, (g) => g.diffPaths(base, tip)).pipe(
+          Effect.provide(GitService.Live),
+          Effect.provide(Host.layer({ root: repo, home: root, env: {} })),
+          Effect.provide(NodeContext.layer),
+        ),
+      )
+      expect([...paths]).toEqual(["sub"])
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})

package/src/platform/Git.ts

@@ -94,6 +94,15 @@ export interface GitReaderOperations {
   readonly changedPaths: (
     base?: string,
   ) => Effect.Effect<ReadonlyArray<{ readonly path: string; readonly status: string }>, Error>
+  /**
+   * Paths whose content differs between the trees of `base` and `tip`: added,
+   * modified and deleted alike; a rename reports both paths (no rename
+   * detection); a submodule pointer change reports the submodule path whatever
+   * `diff.ignoreSubmodules` or `.gitmodules` `ignore` say. Repo-root-relative
+   * whatever the cwd or `diff.relative` config; never reads the index or the
+   * working tree. Fails when either side does not resolve.
+   */
+  readonly diffPaths: (base: string, tip: string) => Effect.Effect<ReadonlyArray<string>, Error>
 }
 
 export interface GitWriterOperations {
@@ -382,6 +391,21 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
 
     readFileAtRef: (ref: string, path: string) => exec("git", "show", `${ref}:${path}`),
 
+    diffPaths: (base: string, tip: string) =>
+      exec(
+        "git",
+        "diff",
+        "--name-only",
+        "-z",
+        "--no-renames",
+        "--no-relative",
+        "--ignore-submodules=none",
+        "--end-of-options",
+        base,
+        tip,
+        "--",
+      ).pipe(Effect.map(splitNul)),
+
     changedPaths: (base?: string) =>
       Effect.gen(function* () {
         const ref = base ?? "HEAD"

package/src/step/index.ts

@@ -3,3 +3,4 @@ export { accessRefusal } from "./accessRefusal.js"
 export { planStart } from "./planStart.js"
 export type { GitWrite, LandStep, Outcome } from "./LandStep.js"
 export type { Landing, RepoSnapshot } from "./RepoSnapshot.js"
+export { strayPaths } from "./strayPaths.js"

package/src/step/strayPaths.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest"
+import { strayPaths } from "./index.js"
+
+describe("strayPaths", () => {
+  it("returns the paths no glob matches, sorted", () => {
+    expect(strayPaths(["src/a.ts", "z.md", "a.md"], ["src/**"])).toEqual(["a.md", "z.md"])
+  })
+
+  it("an empty allowlist returns every touched path", () => {
+    expect(strayPaths(["b", "a"], [])).toEqual(["a", "b"])
+  })
+
+  it("an empty touched list returns []", () => {
+    expect(strayPaths([], ["src/**"])).toEqual([])
+    expect(strayPaths([], [])).toEqual([])
+  })
+})

package/src/step/strayPaths.ts

@@ -0,0 +1,8 @@
+import { globMatches } from "../wire/index.js"
+
+/** Globs use the `access.write` dialect (`globMatches`). */
+export const strayPaths = (
+  touched: ReadonlyArray<string>,
+  allow: ReadonlyArray<string>,
+): ReadonlyArray<string> =>
+  touched.filter((path) => !allow.some((glob) => globMatches(path, glob))).sort()

package/src/testkit/FakeGitOperations.ts

@@ -76,6 +76,8 @@ const makeGitReaderOps = (repo: InMemRepo, root: string): GitReaderOperations =>
     Effect.succeed(repo.subjectHistory(pageSize, skip, head)),
 
   changedPaths: (base?: string) => Effect.succeed(repo.changedPathsWorktree(base)),
+
+  diffPaths: (base: string, tip: string) => tryCatch(() => repo.diffPaths(base, tip)),
 })
 
 const failOn = (output: string | undefined): void => {

package/src/testkit/GitTiers.ts

@@ -409,6 +409,7 @@ export const CONTRACT_COVERED_OPERATIONS: ReadonlySet<keyof GitOperations> = new
   "subjectHistory",
   "readFileAtRef",
   "changedPaths",
+  "diffPaths",
   "commitAllWithPrefix",
   "softResetTo",
   "commitAsIs",
@@ -434,7 +435,7 @@ const PATHOLOGICAL_PATHS: ReadonlyArray<{ label: string; path: string }> = [
 ]
 
 /**
- * Exercise all 21 `GitOperations` methods identically against `makeTier()` —
+ * Exercise every `GitOperations` methods identically against `makeTier()` —
  * called once per tier by `src/platform/Git.test.ts`. A capability-gated group
  * (`t.capabilities.X`) is skipped, not faked, on a tier that can't support it.
  */
@@ -480,6 +481,7 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
         g.readFileAtRef("HEAD", "second.txt"),
         g.changedPaths(),
         g.changedPaths("HEAD~1"),
+        g.diffPaths("HEAD~1", "HEAD"),
       ]),
     )
     expect(await t.observe.snapshot()).toBe(before)
@@ -988,6 +990,70 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
     })
   })
 
+  describe("diffPaths", () => {
+    const sorted = (paths: ReadonlyArray<string>) => [...paths].sort()
+
+    it("reports added, modified and deleted paths between two commits", async () => {
+      t.seed.commit("chore: seed", { "mod.txt": "one", "del.txt": "bye" })
+      const base = t.observe.resolveRef("HEAD")
+      t.seed.writeFile("mod.txt", "two")
+      t.seed.stageAll()
+      t.seed.commitDeletion("del.txt", "chore: delete")
+      t.seed.commit("feat: add", { "add.txt": "new", "mod.txt": "two" })
+      const tip = t.observe.resolveRef("HEAD")
+      const paths = await runGit(t, (g) => g.diffPaths(base, tip))
+      expect(sorted(paths)).toEqual(["add.txt", "del.txt", "mod.txt"])
+    })
+
+    it("reports both paths of a rename", async () => {
+      t.seed.commit("chore: seed", { "old.txt": "same content unique-marker\n" })
+      const base = t.observe.resolveRef("HEAD")
+      t.seed.deleteFile("old.txt")
+      t.seed.commit("refactor: rename", { "new.txt": "same content unique-marker\n" })
+      const tip = t.observe.resolveRef("HEAD")
+      expect(sorted(await runGit(t, (g) => g.diffPaths(base, tip)))).toEqual(["new.txt", "old.txt"])
+    })
+
+    it("omits a file changed then restored between the endpoints", async () => {
+      t.seed.commit("chore: seed", { "flip.txt": "one" })
+      const base = t.observe.resolveRef("HEAD")
+      t.seed.commit("chore: change", { "flip.txt": "two" })
+      t.seed.commit("chore: restore", { "flip.txt": "one" })
+      const tip = t.observe.resolveRef("HEAD")
+      expect(await runGit(t, (g) => g.diffPaths(base, tip))).toEqual([])
+    })
+
+    it("never reports staged, unstaged or untracked changes", async () => {
+      t.seed.commit("chore: seed", { "a.txt": "a", "b.txt": "b" })
+      const base = t.observe.resolveRef("HEAD")
+      t.seed.writeFile("a.txt", "staged")
+      t.seed.stageAll()
+      t.seed.writeFile("b.txt", "unstaged")
+      t.seed.writeFile("untracked.txt", "u")
+      expect(await runGit(t, (g) => g.diffPaths(base, "HEAD"))).toEqual([])
+    })
+
+    it("is [] for diffPaths(x, x)", async () => {
+      const head = t.observe.resolveRef("HEAD")
+      expect(await runGit(t, (g) => g.diffPaths(head, head))).toEqual([])
+    })
+
+    for (const { label, path } of PATHOLOGICAL_PATHS) {
+      it(`reports a path containing ${label}, verbatim`, async () => {
+        const base = t.observe.resolveRef("HEAD")
+        t.seed.commit("feat: pathological", { [path]: "content" })
+        expect(await runGit(t, (g) => g.diffPaths(base, "HEAD"))).toEqual([path])
+      })
+    }
+
+    it("fails when either side does not resolve", async () => {
+      const bad = await runGitExit(t, (g) => g.diffPaths("totally-invalid-ref-xyz", "HEAD"))
+      expect(Exit.isFailure(bad)).toBe(true)
+      const badTip = await runGitExit(t, (g) => g.diffPaths("HEAD", "totally-invalid-ref-xyz"))
+      expect(Exit.isFailure(badTip)).toBe(true)
+    })
+  })
+
   describe("changedPaths", () => {
     it("unions a tracked modification, a tracked deletion, and an untracked addition, deduplicated by path", async () => {
       t.seed.commit("chore: seed", { "modme.txt": "orig", "delme.txt": "bye" })

package/src/testkit/InMemRepo.ts

@@ -270,6 +270,13 @@ export class InMemRepo {
     return diffTrees(baseTree, worktreeTree)
   }
 
+  diffPaths(base: string, tip: string): string[] {
+    for (const ref of [base, tip]) {
+      if (this.resolveRef(ref) === null) throw new Error(`Invalid ref: ${ref}`)
+    }
+    return diffTrees(this.treeAt(base), this.treeAt(tip)).map((e) => e.path)
+  }
+
   /** The worktree content of `path`, or `undefined` when absent. A LIVE read — never a snapshot. */
   readFile(path: string): string | undefined {
     return this.worktree.get(path)

package/src/testkit/Layers.test.ts

@@ -2,7 +2,8 @@ import { Effect } from "effect"
 import { describe, expect, it } from "vitest"
 import { ConfigDiscovery, LEGACY_RC_FILES, walkUp } from "../workflow/index.js"
 import { InMemRepo } from "./index.js"
-import { testLayers } from "./Layers.js"
+import { ambientFlagEnv, testLayers } from "./Layers.js"
+import { Host } from "../platform/index.js"
 
 // The in-memory `ConfigDiscovery` counterpart walks the SAME root→home chain
 // and looks for the SAME `LEGACY_RC_FILES` as `ConfigDiscovery.Live` — both
@@ -56,3 +57,35 @@ describe("the in-memory ConfigDiscovery counterpart", () => {
     expect(found).toEqual([`${HOME}/${LEGACY_RC_FILES[1]}`])
   })
 })
+
+describe("ambient GTD_FLAG_* reaches the in-memory Host", () => {
+  const hostEnv = (ambient: Record<string, string>, env?: Record<string, string>) => {
+    const before = { ...process.env }
+    Object.assign(process.env, ambient)
+    return Effect.runPromise(
+      Effect.map(Host, (h) => h.env).pipe(
+        Effect.provide(testLayers(new InMemRepo(), env ? { env } : {})),
+        Effect.ensuring(
+          Effect.sync(() => {
+            for (const k of Object.keys(ambient)) {
+              if (before[k] === undefined) delete process.env[k]
+              else process.env[k] = before[k]
+            }
+          }),
+        ),
+      ),
+    )
+  }
+
+  it("carries the ambient flag, and explicit env wins", async () => {
+    expect((await hostEnv({ GTD_FLAG_ALPHA: "1" }))["GTD_FLAG_ALPHA"]).toBe("1")
+    const env = await hostEnv({ GTD_FLAG_ALPHA: "1" }, { GTD_FLAG_ALPHA: "0" })
+    expect(env["GTD_FLAG_ALPHA"]).toBe("0")
+  })
+
+  it("picks only GTD_FLAG_* keys", () => {
+    expect(ambientFlagEnv({ GTD_FLAG_X: "1", PATH: "/bin", GTD_FLAG_U: undefined })).toEqual({
+      GTD_FLAG_X: "1",
+    })
+  })
+})

package/src/testkit/Layers.ts

@@ -216,6 +216,21 @@ const missingToolCommands: ToolCommands["Type"] = {
 export const gitTestLayer = (repo: InMemRepo, root = "/repo"): Layer.Layer<GitService> =>
   Layer.succeed(GitService, fakeGitOperations(repo, root))
 
+/**
+ * The one sanctioned leak of the real `process.env` into the in-memory `Host`:
+ * the runner's `GTD_FLAG_*` state, so a flag-on `npm test` state exercises the
+ * flag in memory as it does live. A test asserting one flag side sets the flag
+ * itself; explicit env wins.
+ */
+export const ambientFlagEnv = (
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(env).filter(
+      (e): e is [string, string] => e[0].startsWith("GTD_FLAG_") && e[1] !== undefined,
+    ),
+  )
+
 /** Every layer `makeProgram` needs — `CommandRequirements`'s return type here IS the guarantee: a new port added there fails this function's typecheck instead of silently under-providing. */
 export function testLayers(
   repo: InMemRepo,
@@ -231,7 +246,12 @@ export function testLayers(
     // symlinks against): both sides of `assertRunningFromRepoRoot`'s
     // comparison collapse to `root` when given anything, exactly like the
     // fake's `root` "resolving" to itself before this port existed.
-    Host.layer({ root, home, env: opts.env ?? {}, realPath: () => Effect.succeed(root) }),
+    Host.layer({
+      root,
+      home,
+      env: { ...ambientFlagEnv(), ...opts.env },
+      realPath: () => Effect.succeed(root),
+    }),
     ConfigService.Live,
     makeInMemoryConfigDiscovery(repo, root),
     Narrator.layer(opts.narrate ?? (() => {}), opts.verbose ?? true),

package/src/testkit/TestRepo.ts

@@ -19,7 +19,7 @@ export interface TestRepoOptions {
   readonly workflow: WorkflowModule
   /** Committed alongside the config, before any process starts. */
   readonly files?: Readonly<Record<string, string>>
-  /** The environment gtd sees; the real `process.env` is never read. */
+  /** The environment gtd sees; the real `process.env` is never read, except ambient `GTD_FLAG_*` (explicit env wins). */
   readonly env?: Readonly<Record<string, string>>
 }
 

package/src/wire/ExitCodes.test.ts

@@ -5,16 +5,24 @@ import {
   EXIT_RUNTIME_ERROR,
   EXIT_SIGINT,
   EXIT_SIGTERM,
+  EXIT_STRAYS_FOUND,
   EXIT_USAGE_ERROR,
 } from "./index.js"
 
 describe("EXIT_CODES", () => {
-  it("is frozen at exactly {0, 1, 2, 130, 143} — a new code breaks every driver", () => {
-    expect(EXIT_CODES).toEqual(new Set([0, 1, 2, 130, 143]))
+  it("is frozen at exactly {0, 1, 2, 10, 130, 143} — a new code breaks every driver", () => {
+    expect(EXIT_CODES).toEqual(new Set([0, 1, 2, 10, 130, 143]))
   })
 
   it("each named constant is a member of the set", () => {
-    for (const code of [EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR, EXIT_SIGINT, EXIT_SIGTERM]) {
+    for (const code of [
+      EXIT_OK,
+      EXIT_RUNTIME_ERROR,
+      EXIT_USAGE_ERROR,
+      EXIT_STRAYS_FOUND,
+      EXIT_SIGINT,
+      EXIT_SIGTERM,
+    ]) {
       expect(EXIT_CODES.has(code)).toBe(true)
     }
   })