@pmelab/gtd 63.0.0 → 64.0.0

package/src/edge/Edge.test.ts

@@ -185,7 +185,7 @@ describe("currentRun", () => {
     expect(run.episode.base).toBe(boundary)
     expect(run.episode.commits.map((c) => c.message.split("\n")[0])).toEqual([
       "gtd(human): idle → building",
-      "gtd(check): pin → building",
+      "gtd(check): gtd:pin → building",
       "gtd(agent): building → checking",
     ])
   })
@@ -205,7 +205,7 @@ describe("currentRun", () => {
     await land(repo, { "a.txt": "a\n" })
     await land(repo, { "b.txt": "b\n" })
     const closing = await land(repo, { "c.txt": "c\n" })
-    expect(repo.lastCommitSubject()).toBe("gtd(check): unpin → idle")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): gtd:unpin → idle")
     const next = await land(repo, { "d.txt": "d\n" })
     const run = await provide(currentRun, repo)
     expect(run.startParentHash).toBe(closing)
@@ -217,7 +217,7 @@ describe("currentRun", () => {
     const before = headOf(repo)
     const opening = await enter(repo, "side")
     expect(repo.lastCommitMessage(opening)).toBe(
-      `gtd(human): fixing\n\nGtd-Workflow: side\nGtd-Var: base=\nGtd-Var: reviewer=nobody\nGtd-Format: 3`,
+      `gtd(human): fixing\n\nGtd-Workflow: side\nGtd-Var: base=\nGtd-Var: reviewer=nobody\nGtd-Format: 4`,
     )
     const fixed = await land(repo, { "fix.txt": "x\n" })
     const run = await provide(currentRun, repo)
@@ -250,7 +250,7 @@ export const again = workflow(async () => {
     const before = headOf(repo)
     const opening = await enter(repo, "again")
     expect(repo.lastCommitMessage(opening)).toBe(
-      `gtd(human): idle\n\nGtd-Workflow: again\nGtd-Format: 3`,
+      `gtd(human): idle\n\nGtd-Workflow: again\nGtd-Format: 4`,
     )
     const fixed = await land(repo, { "fix.txt": "x\n" })
     const run = await provide(currentRun, repo)
@@ -264,6 +264,29 @@ export const again = workflow(async () => {
     ])
   })
 
+  it("a format 3 pin commit naming the default's initial step bounds nothing either", async () => {
+    const repo = repoWith(`import { agent, human, workflow } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle", { message: "idle-message" })
+}
+
+export const again = workflow(async () => {
+  await human("idle", { message: "idle-message" })
+  await agent("fixing", "fix-prompt")
+})
+`)
+    const before = headOf(repo)
+    repo.seedCommit("gtd(human): idle\n\nGtd-Workflow: again\nGtd-Format: 3")
+    const opening = headOf(repo)
+    repo.writeFile(".gtd/process.gtdpin", "gtdpin 1 gtd in-memory\n")
+    repo.seedCommit("gtd(check): pin → idle\n\nGtd-Pin: add\nGtd-Format: 3")
+    const run = await provide(currentRun, repo)
+    expect(run.workflow).toBe("again")
+    expect(run.startHash).toBe(opening)
+    expect(run.startParentHash).toBe(before)
+  })
+
   it("collects every process commit's Gtd-Cost, attributing a model-less one to UNATTRIBUTED_MODEL", async () => {
     const repo = repoWith(LINEAR)
     commit(
@@ -395,7 +418,7 @@ export const again = workflow(async () => {
     it("is undefined at a pin commit, which is no turn", async () => {
       const repo = repoWith(LINEAR)
       await land(repo, { "a.txt": "a\n" })
-      expect(repo.lastCommitSubject()).toBe("gtd(check): pin → building")
+      expect(repo.lastCommitSubject()).toBe("gtd(check): gtd:pin → building")
       expect((await provide(currentRun, repo)).headTurn).toBeUndefined()
     })
 
@@ -403,7 +426,7 @@ export const again = workflow(async () => {
       const repo = repoWith(LINEAR)
       await land(repo, { "a.txt": "a\n" })
       await land(repo)
-      expect(repo.lastCommitMessage()).toBe("gtd(agent): building\n\nGtd-Format: 3")
+      expect(repo.lastCommitMessage()).toBe("gtd(agent): building\n\nGtd-Format: 4")
       const run = await provide(currentRun, repo)
       expect(run.headTurn).toEqual({ state: "building", actor: "agent", empty: true, step: false })
     })
@@ -544,7 +567,7 @@ describe("summaryRun", () => {
     expect(summary.trace).toEqual([
       { state: "building", hash: building, actor: "human" },
       { state: "checking", hash: checking, actor: "agent" },
-      { state: "unpin", hash: headOf(repo, `${closing}~1`), actor: "agent" },
+      { state: "gtd:unpin", hash: headOf(repo, `${closing}~1`), actor: "agent" },
       { state: "idle", hash: closing, actor: "check" },
     ])
   })
@@ -831,7 +854,7 @@ export const review = workflow(async () => {
   it("is the base the resting step names", async () => {
     const repo = repoWith(LOOP)
     const first = await land(repo, { "a.txt": "a\n" })
-    expect(repo.lastCommitSubject()).toBe("gtd(check): pin → checkpoint")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): gtd:pin → checkpoint")
     expect(reviewBaseFor(await provide(currentRest, repo))).toBe(first)
     await land(repo, { "b.txt": "b\n" })
     expect(reviewBaseFor(await provide(currentRest, repo))).toBe(first)
@@ -1306,7 +1329,7 @@ describe("finishing landings keep history", () => {
     await land(repo, { "b.txt": "b\n" })
     repo.writeFile("c.txt", "c\n")
     const landing = await landingOf(repo)
-    expect(landing.to).toBe("unpin")
+    expect(landing.to).toBe("gtd:unpin")
     expect(landing.keepHistory).toBeUndefined()
     expect(landing.spec.version).toBeUndefined()
   })
@@ -1522,13 +1545,16 @@ describe("historyTrail", () => {
       tip,
     ])
     expect(trail.steps[2]).toMatchObject({
-      subject: "gtd(agent): checking → unpin",
+      subject: "gtd(agent): checking → gtd:unpin",
       actor: "agent",
       from: "checking",
-      to: "unpin",
+      to: "gtd:unpin",
       verdicts: [],
     })
-    expect(trail.steps[3]).toMatchObject({ subject: "gtd(check): unpin → idle", actor: "check" })
+    expect(trail.steps[3]).toMatchObject({
+      subject: "gtd(check): gtd:unpin → idle",
+      actor: "check",
+    })
     expect(trail.steps[0]).toMatchObject({ actor: "human", to: "building" })
   })
 

package/src/edge/Edge.ts

@@ -1,4 +1,4 @@
-import { Effect, Option } from "effect"
+import { Effect, Option, Path } from "effect"
 import {
   Narrator,
   GitService,
@@ -42,6 +42,7 @@ import {
   treeFromRecord,
   type EpisodeCommit,
   type JudgeVerdict,
+  LEGACY_PIN_STATES,
   type PinChange,
   PIN_STATES,
   type ReachedStep,
@@ -62,7 +63,6 @@ import {
 
 import { GTD_VERSION } from "../install/index.js"
 import { keptRef, processHistoryRef } from "../platform/index.js"
-import { isAbsolute, relative, resolve, sep } from "node:path"
 import { accessRefusal, type Landing, type RepoSnapshot } from "../step/index.js"
 
 export { UNATTRIBUTED_MODEL }
@@ -337,8 +337,14 @@ const subjectIsBoundary = (def: WorkflowDefinition, subject: string): boolean =>
   const parsed = parseCommitMessage(subject).parsed
   if (parsed === undefined || !ACTORS.has(parsed.actor)) return true
   if (parsed.actor === "human" && parsed.from === undefined) return false
-  // A pin commit's subject can name the first step; it bounds nothing.
-  if (parsed.actor === "check" && parsed.from === PIN_STATES.add) return false
+  // A pin commit's subject can name the first step; it bounds nothing. The
+  // subject alone carries no format, so either spelling counts.
+  if (
+    parsed.actor === "check" &&
+    (parsed.from === PIN_STATES.add || parsed.from === LEGACY_PIN_STATES.add)
+  ) {
+    return false
+  }
   return parsed.to === def.initial
 }
 
@@ -421,7 +427,14 @@ const computeProcessRun = (
     runOf(history, locateEpisode(def, history)),
   )
 
-type ConfigRequirements = GitService | ConfigService | ConfigDiscovery | Narrator | Workspace | Host
+type ConfigRequirements =
+  | GitService
+  | ConfigService
+  | ConfigDiscovery
+  | Narrator
+  | Workspace
+  | Host
+  | Path.Path
 
 /** The run alone, never replaying — `gtd abandon` must work even when replay would refuse, short of a history it cannot read. */
 export const currentRun: Effect.Effect<ProcessRun, Error, ConfigRequirements> = Effect.gen(
@@ -1564,10 +1577,16 @@ export interface HistoryTrail {
  * repository cannot be read at a ref, so it is left out. A file only the old
  * config read needs no check: whichever file imported it differs too.
  */
-const inRepoConfigPaths = (root: string, files: readonly string[]): readonly string[] => {
-  const paths = new Set<string>()
-  for (const file of files) paths.add(relative(root, resolve(root, file)).split(sep).join("/"))
-  return [...paths].filter((p) => p !== "" && !p.startsWith("..") && !isAbsolute(p)).sort()
+const inRepoConfigPaths = (
+  path: Path.Path,
+  root: string,
+  files: readonly string[],
+): readonly string[] => {
+  const found = new Set<string>()
+  for (const file of files) {
+    found.add(path.relative(root, path.resolve(root, file)).split(path.sep).join("/"))
+  }
+  return [...found].filter((p) => p !== "" && !p.startsWith("..") && !path.isAbsolute(p)).sort()
 }
 
 const configRefusal = (
@@ -1589,7 +1608,8 @@ const differingConfigPaths = (
 ) =>
   Effect.gen(function* () {
     const differing: string[] = []
-    for (const path of inRepoConfigPaths(root, Object.keys(config.fingerprint))) {
+    const configPaths = inRepoConfigPaths(yield* Path.Path, root, Object.keys(config.fingerprint))
+    for (const path of configPaths) {
       const atTip = yield* Effect.orElseSucceed(git.readFileAtRef(hash, path), () => undefined)
       if (atTip !== workspace.readSync(path)) differing.push(path)
     }

package/src/emit/SteeringMode.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { Effect } from "effect"
+import { Effect, Layer, Path } from "effect"
 import { resolveMode, validateScriptFor, type ModeResolution } from "./SteeringMode.js"
 import { Host } from "../platform/index.js"
 import { steeringFormatFor } from "../steering/index.js"
@@ -16,7 +16,9 @@ const envVarsLayer = Host.layer({ root: "/repo", home: "/repo", env: { PATH: "/u
 
 const runScript = (resolved: ModeResolution, file: string) => {
   if (resolved.kind !== "resolved") throw new Error("expected a resolved mode")
-  return Effect.runPromise(validateScriptFor(resolved, file).pipe(Effect.provide(envVarsLayer)))
+  return Effect.runPromise(
+    validateScriptFor(resolved, file).pipe(Effect.provide(Layer.merge(envVarsLayer, Path.layer))),
+  )
 }
 
 describe("resolveMode", () => {

package/src/emit/SteeringMode.ts

@@ -1,6 +1,5 @@
-import { join } from "node:path"
-import { Effect } from "effect"
-import { Host } from "../platform/index.js"
+import { Effect, Path } from "effect"
+import { Host, type HostOps } from "../platform/index.js"
 import {
   isSeededValidateCommand,
   knownModes,
@@ -191,8 +190,11 @@ const modeCommandSteps = (resolved: ResolvedMode, file: string): readonly EmitSt
 }
 
 /** `<Host.scratchDir>/gtd-mode-sample-<mode>-<pid>.md` — an absolute literal baked in at emit time, never a shell variable. `<pid>` avoids collisions between concurrent `gtd` processes. Never a `/tmp` literal or `mktemp` (`tests/tooling/no-tmp-assumption.test.ts` scans for both). */
-const scratchSamplePath = (scratchDir: string, mode: StateMode): string =>
-  join(scratchDir, `gtd-mode-sample-${mode}-${process.pid}.md`)
+const scratchSamplePath = (
+  path: Path.Path,
+  { scratchDir, pid }: HostOps,
+  mode: StateMode,
+): string => path.join(scratchDir, `gtd-mode-sample-${mode}-${pid}.md`)
 
 /**
  * The contradiction round-trip/skip-notice steps for `resolved`'s `mode:`.
@@ -204,13 +206,12 @@ const scratchSamplePath = (scratchDir: string, mode: StateMode): string =>
  */
 const modeContradictionSteps = (
   resolved: ResolvedMode,
-): Effect.Effect<readonly EmitStep[], Error, Host> =>
+): Effect.Effect<readonly EmitStep[], Error, Host | Path.Path> =>
   Effect.gen(function* () {
     if (resolved.formatCommand === undefined) return []
     const { capabilities } = resolved
     if (capabilities.format !== undefined && capabilities.liveValidate !== undefined) {
-      const { scratchDir } = yield* Host
-      const samplePath = scratchSamplePath(scratchDir, resolved.mode)
+      const samplePath = scratchSamplePath(yield* Path.Path, yield* Host, resolved.mode)
       const formatCommand = withFileVar(resolved.formatCommand, samplePath)
       return [
         {
@@ -245,7 +246,7 @@ export interface ValidateScript {
 export const validateScriptFor = (
   resolved: ResolvedMode,
   file: string,
-): Effect.Effect<ValidateScript, Error, Host> =>
+): Effect.Effect<ValidateScript, Error, Host | Path.Path> =>
   Effect.gen(function* () {
     const steps: EmitStep[] = [
       ...(yield* modeContradictionSteps(resolved)),

package/src/gherkin/messages.test.ts

@@ -45,7 +45,7 @@ describe("restDescription", () => {
         "  last commits:",
         "    chore: initial commit",
         "    gtd(agent): plan → sign-off",
-        "    gtd(check): pin → sign-off",
+        "    gtd(check): gtd:pin → sign-off",
         '  actors never used: "repair" (scenario), "ready" (Background)',
       ].join("\n"),
     )

package/src/gherkin/module-config.feature

@@ -20,6 +20,6 @@ Feature: a scenario runs a workflow module from disk
     And the commit subjects end with:
       """
       gtd(agent): plan → sign-off
-      gtd(check): pin → sign-off
+      gtd(check): gtd:pin → sign-off
       """
 

package/src/gherkin/testkit.feature

@@ -43,7 +43,7 @@ Feature: testkit drives any workflow against the real engine
     And the commit subjects end with:
       """
       gtd(human): plan
-      gtd(check): pin → plan
+      gtd(check): gtd:pin → plan
       gtd(agent): plan → check
       gtd(check): check → ready
       gtd(judge): ready → ship
@@ -107,7 +107,7 @@ Feature: testkit drives any workflow against the real engine
     When gtd starts workflow "tiny"
     And the process is driven
     Then the process rests at "plan"
-    And the last commit subject is "gtd(check): pin → plan"
+    And the last commit subject is "gtd(check): gtd:pin → plan"
 
   Scenario: a prompt asserted beside a script is checked at every visit, before the step acts
     Given step "check" is prompted with "npm test"

package/src/install/Version.ts

@@ -1,9 +1,4 @@
-import { existsSync } from "node:fs"
-import { createRequire } from "node:module"
-import { dirname, join } from "node:path"
-import { fileURLToPath } from "node:url"
-
-const _require = createRequire(import.meta.url)
+import { NodeRuntime, nodeSyncIo } from "../platform/index.js"
 
 // A source-relative literal (`../../package.json`) breaks the built single-file
 // bundle: bundling doesn't rewrite `import.meta.url` per original module, so a
@@ -11,13 +6,19 @@ const _require = createRequire(import.meta.url)
 // dist/ vs src/ — they differ (dist/gtd.bundle.mjs is always one level below
 // repo root; src/install/Version.ts is two). Walking up from wherever this module
 // actually runs from resolves correctly in both the unbundled (vitest/tsc) and
-// bundled (dist/gtd.bundle.mjs) case.
-const findPackageJson = (fromUrl: string): string => {
-  let dir = dirname(fileURLToPath(fromUrl))
+// bundled (dist/gtd.bundle.mjs) case. URLs, not Path: this runs at import,
+// before any Effect service exists.
+const readPackageJson = (fromUrl: string): string => {
+  let dir = new URL(".", fromUrl)
   for (let i = 0; i < 5; i++) {
-    const candidate = join(dir, "package.json")
-    if (existsSync(candidate)) return candidate
-    dir = dirname(dir)
+    const candidate = new URL("package.json", dir)
+    try {
+      const source = nodeSyncIo.readText(NodeRuntime.fileURLToPath(candidate))
+      if (source !== undefined) return source
+    } catch {
+      // Unreadable counts as absent, as it did for `existsSync`.
+    }
+    dir = new URL("..", dir)
   }
   throw new Error(`package.json not found by walking up from ${fromUrl}`)
 }
@@ -30,4 +31,4 @@ export const PIN_KEY = Symbol.for("@pmelab/gtd/pin")
 const pinned = (globalThis as { [PIN_KEY]?: { readonly version: string } })[PIN_KEY]?.version
 
 export const GTD_VERSION: string =
-  pinned ?? (_require(findPackageJson(import.meta.url)) as { version: string }).version
+  pinned ?? (JSON.parse(readPackageJson(import.meta.url)) as { version: string }).version

package/src/platform/Host.ts

@@ -1,6 +1,6 @@
-import { realpathSync } from "node:fs"
-import { homedir, tmpdir } from "node:os"
 import { Context, Effect, Layer } from "effect"
+import { homedir, tmpdir } from "./NodeRuntime.js"
+import { nodeSyncIo } from "./NodeSync.js"
 
 const toError = (e: unknown): Error => (e instanceof Error ? e : new Error(String(e)))
 
@@ -8,35 +8,88 @@ export interface HostOps {
   readonly root: string
   readonly home: string
   readonly env: Readonly<Record<string, string | undefined>>
-  /** `env["TMPDIR"]` when set, `node:os`'s `tmpdir()` otherwise — never a `/tmp` literal or `mktemp` (`tests/tooling/no-tmp-assumption.test.ts` scans for both). */
+  /** `env["TMPDIR"]` when set, the host's temp dir otherwise — never a `/tmp` literal or `mktemp` (`tests/tooling/no-tmp-assumption.test.ts` scans for both). */
   readonly scratchDir: string
   /** The real, symlink-resolved form of `path` — used to compare a possibly-symlinked cwd (macOS `/tmp` → `/private/tmp`) against git's own resolution. */
   readonly realPath: (path: string) => Effect.Effect<string, Error>
+  /** Carried by every scratch or temp file name, so concurrent gtd runs never share one. */
+  readonly pid: number
+  /** `undefined` where the platform has no POSIX user ids. */
+  readonly uid: number | undefined
+  /** The command that runs this gtd again: its script under the running runtime, or `gtd` off `PATH` when there is none. */
+  readonly self: readonly [string, ...string[]]
+  /** Standard input read to its end, as UTF-8. */
+  readonly stdin: Effect.Effect<string, Error>
 }
 
-interface HostOpsInput {
-  readonly root: string
-  readonly home: string
-  readonly env: Readonly<Record<string, string | undefined>>
-  readonly scratchDir?: string
-  readonly realPath?: (path: string) => Effect.Effect<string, Error>
+/** The output half of the process's stdio, which the CLI writes before any layer is built. */
+export interface Stdio {
+  readonly stdout: (chunk: string | Uint8Array) => void
+  readonly stderr: (chunk: string) => void
+  readonly exit: (code: number) => void
+}
+
+/** The slice of Node's `process` the live host reads; a contract test hands in a fake one. */
+export type NodeProcess = Pick<
+  NodeJS.Process,
+  "argv" | "execPath" | "pid" | "getuid" | "stdin" | "stdout" | "stderr" | "exitCode"
+>
+
+type HostOpsInput = Pick<HostOps, "root" | "home" | "env"> & Partial<HostOps>
+
+/** `TMPDIR` when set and non-empty, else the host's own `fallback`. */
+export const scratchDirOf = (env: HostOps["env"], fallback: string): string => {
+  const dir = env["TMPDIR"]
+  return dir !== undefined && dir.length > 0 ? dir : fallback
+}
+
+const readAll = (stream: AsyncIterable<Buffer | string>): Effect.Effect<string, Error> =>
+  Effect.tryPromise({
+    try: async () => {
+      const chunks: Buffer[] = []
+      for await (const chunk of stream) chunks.push(Buffer.from(chunk))
+      return Buffer.concat(chunks).toString("utf8")
+    },
+    catch: toError,
+  })
+
+const makeHostOps = (opts: HostOpsInput, proc: NodeProcess): HostOps => {
+  const script = proc.argv[1]
+  return {
+    scratchDir: scratchDirOf(opts.env, tmpdir()),
+    realPath: (path: string) =>
+      Effect.try({ try: () => nodeSyncIo.realPath(path), catch: toError }),
+    pid: proc.pid,
+    uid: proc.getuid?.(),
+    self: script === undefined ? ["gtd"] : [proc.execPath, script],
+    // Lazy: touching `process.stdin` opens it, which the LSP and the pin hand-over must not see.
+    stdin: Effect.suspend(() => readAll(proc.stdin)),
+    ...opts,
+  }
 }
 
-const makeHostOps = (opts: HostOpsInput): HostOps => ({
-  root: opts.root,
-  home: opts.home,
-  env: opts.env,
-  scratchDir:
-    opts.scratchDir ??
-    (opts.env["TMPDIR"] !== undefined && opts.env["TMPDIR"]!.length > 0
-      ? opts.env["TMPDIR"]!
-      : tmpdir()),
-  realPath:
-    opts.realPath ??
-    ((path: string) => Effect.try({ try: () => realpathSync(path), catch: toError })),
+export const nodeStdio = (proc: NodeProcess = process): Stdio => ({
+  // `stdout.write` is asynchronous whenever stdout is a pipe or socket —
+  // passing a completion callback (and never force-closing, see `exit`
+  // below) keeps a queued remainder from being discarded, so a large
+  // artifact still reaches a slow reader even after a non-zero exit.
+  stdout: (chunk) => {
+    proc.stdout.write(chunk, () => {})
+  },
+  stderr: (chunk) => {
+    proc.stderr.write(chunk)
+  },
+  // Never `process.exit(code)`: that tears the process down out from under
+  // an undrained `stdout.write` above and truncates the artifact mid-pipe.
+  // Setting `exitCode` lets the event loop drain any queued write first.
+  exit: (code) => {
+    proc.exitCode = code
+  },
 })
 
+/** Every member not given in `opts` comes from Node: `proc`, its OS and its file system. */
 export class Host extends Context.Service<Host, HostOps>()("Host") {
-  static layer = (opts: HostOpsInput): Layer.Layer<Host> => Layer.succeed(Host, makeHostOps(opts))
+  static layer = (opts: HostOpsInput, proc: NodeProcess = process): Layer.Layer<Host> =>
+    Layer.succeed(Host, makeHostOps(opts, proc))
   static Live = Host.layer({ root: process.cwd(), home: homedir(), env: process.env })
 }

package/src/platform/NodePinFile.ts

@@ -0,0 +1,44 @@
+import { registerHooks } from "node:module"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+import { nodeSyncIo } from "./NodeSync.js"
+import type { PinFile } from "./PinFile.js"
+
+// `cwd`, as the engine's own root is: gtd runs only at the worktree root, and
+// a relocated `$GIT_DIR` leaves no `.git` to walk up to. A file that cannot be
+// read counts as no pin, so the launcher refuses it rather than crashing.
+export const livePinFile =
+  (cwd: string, path: string): PinFile =>
+  () => {
+    const file = join(cwd, path)
+    try {
+      const bytes = nodeSyncIo.readFile(file)
+      if (bytes !== undefined) return { path: file, bytes }
+    } catch {
+      return { path: file, bytes: new Uint8Array() }
+    }
+    try {
+      return { path: file, bytes: nodeSyncIo.gitBytes(cwd, ["show", `HEAD:${path}`]) }
+    } catch {
+      return undefined
+    }
+  }
+
+/**
+ * Runs a pin's module as this process's main program. Node refuses an unknown
+ * extension, so a load hook serves the unpacked source under the pin's own
+ * URL — `import.meta.url` stays a file in the repository.
+ */
+export const runPinModule = async (path: string, source: string): Promise<void> => {
+  const url = pathToFileURL(path).href
+  // A pin read from HEAD has no file behind its URL, which Node's own resolve refuses.
+  registerHooks({
+    resolve: (specifier, context, nextResolve) =>
+      specifier === url ? { url, shortCircuit: true } : nextResolve(specifier, context),
+    load: (requested, context, nextLoad) =>
+      requested === url
+        ? { format: "module", source, shortCircuit: true }
+        : nextLoad(requested, context),
+  })
+  await import(url)
+}

package/src/platform/NodeRuntime.ts

@@ -0,0 +1,19 @@
+import { createRequire, isBuiltin } from "node:module"
+import { homedir, tmpdir } from "node:os"
+import { fileURLToPath } from "node:url"
+import { stripVTControlCharacters } from "node:util"
+import { runInThisContext } from "node:vm"
+import { gunzipSync, gzipSync } from "node:zlib"
+
+// What the core needs of Node beyond the sync port: module loading, the
+// user's directories, file URLs and gzip. Each is a Node fact with no in-memory twin.
+
+export { createRequire, fileURLToPath, homedir, isBuiltin, stripVTControlCharacters, tmpdir }
+
+export const gzip = (source: string): Uint8Array => gzipSync(source, { level: 9 })
+
+export const gunzip = (bytes: Uint8Array): string => gunzipSync(bytes).toString("utf8")
+
+/** Compiles `source` as a script in this realm, reporting errors against `filename`. */
+export const compileScript = (source: string, filename: string): unknown =>
+  runInThisContext(source, { filename })

package/src/platform/NodeSync.ts

@@ -0,0 +1,64 @@
+import { execFileSync } from "node:child_process"
+import { createHash } from "node:crypto"
+import {
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+  type Stats,
+} from "node:fs"
+import type { FileInfo, SyncIo } from "./SyncIo.js"
+
+// A tree listing, or one committed file, can overflow execFileSync's 1 MB default.
+const MAX_BUFFER = 256 * 1024 * 1024
+
+const isAbsent = (e: unknown): boolean => {
+  const code = (e as NodeJS.ErrnoException).code
+  return code === "ENOENT" || code === "ENOTDIR"
+}
+
+const orAbsent = <A>(read: () => A): A | undefined => {
+  try {
+    return read()
+  } catch (e) {
+    if (isAbsent(e)) return undefined
+    throw e
+  }
+}
+
+const infoOf = (stats: Stats): FileInfo => ({
+  type: stats.isSymbolicLink()
+    ? "symlink"
+    : stats.isDirectory()
+      ? "directory"
+      : stats.isFile()
+        ? "file"
+        : "other",
+  uid: process.platform === "win32" ? undefined : stats.uid,
+})
+
+export const nodeSyncIo: SyncIo = {
+  readFile: (path) => orAbsent(() => readFileSync(path)),
+  readText: (path) => orAbsent(() => readFileSync(path, "utf8")),
+  writeText: (path, content) => writeFileSync(path, content, "utf8"),
+  makeDirectory: (path) => {
+    mkdirSync(path, { recursive: true })
+  },
+  rename: renameSync,
+  stat: (path) => orAbsent(() => infoOf(statSync(path))),
+  lstat: (path) => orAbsent(() => infoOf(lstatSync(path))),
+  readLink: (path) => readlinkSync(path, "utf8"),
+  realPath: (path) => realpathSync(path),
+  git: (cwd, args) => execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: MAX_BUFFER }),
+  gitBytes: (cwd, args) =>
+    execFileSync("git", args, { cwd, maxBuffer: MAX_BUFFER, stdio: ["ignore", "pipe", "ignore"] }),
+  hash: (algorithm, ...parts) => {
+    const hash = createHash(algorithm)
+    for (const part of parts) hash.update(part)
+    return hash.digest("hex")
+  },
+}