@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.2

package/docs/RELEASE_CHECKLIST.md

@@ -1,13 +1,81 @@
 # ForgeLoop Release Checklist
 
-This is the current release checklist for `@cassiomc1/forgeloop`. It is a
-preparation and verification checklist; it does not authorize publication.
+This is the current release checklist for the PolyForm Noncommercial-licensed
+`@cassiomc1/forgeloop` package. It is a preparation and verification checklist;
+it does not authorize publication.
 
-## ForgeLoop 1.14.0 candidate scope
+## Bounded 2.0.0-rc.2 publication
 
-The 1.14.0 candidate carries the protocol, routing, provider, documentation,
-and package changes present in current `main`. The candidate must keep these
-boundaries explicit:
+The owner approved short verification and an RC fallback on 2026-10-13. This
+candidate is published only to npm `next`; stable `latest` remains blocked while
+`soleSQLiteWriter` is false. A release candidate does not assert completed
+migration acceptance or production readiness.
+
+After npm rejected restricted RC1 publication with `E402`, the owner authorized
+public core-package access. RC2 preserves the immutable RC1 tag; the MCP
+companion is not published and retains restricted access.
+
+`npm run release:quick` is the RC PR and publishing check. Each check group has
+an enforced three-minute timeout; timeout or failure refuses release. It runs
+source equivalence, writer inventory drift detection, essential SQLite boundary
+and package-policy tests, lint, dependency policy, documentation conformance,
+packed CLI/API/MCP smoke checks, hygiene, and secret scanning. This approved RC
+path replaces a new local `verify:prepush` run. It does not replace the ordinary
+or stable-release validation policy.
+
+`scripts/check-rc-release.mjs` requires all 593 runtime/schema/integration files
+to match baseline `14008f58f8ad255692997ce3fff359591fb695d1`. Root package
+metadata may change only its RC version, the three approved RC scripts, and owner-authorized public access.
+Resolved dependency locks must be unchanged apart from local package versions;
+MCP metadata may only admit the explicit RC peer and bind the local core version.
+Changed runtime or dependency bytes refuse this fast path.
+
+The baseline Windows full-suite receipt is GitHub run `38483385848`, successful
+on that exact source. Publishing verifies its repository, workflow, source SHA,
+and completed success status through the authenticated GitHub API. Current
+Linux/packaged smoke and local macOS short checks are separate evidence. No new
+full-coverage, full-platform, physical power-loss, or statistically qualified
+p95 result is claimed by the short path. The existing 1,000-task parity run
+`38483369676` is retained for review; no fresh 200-repeat benchmark is dispatched.
+
+The writer inventory covers every current `src` JavaScript module and records
+imports plus potential write sites. Alias, computed-path, external-caller, and
+transitive-authority review remain incomplete. The inventory explicitly keeps
+`wholeConsumerClosure: false`; it prevents drift and does not authorize setting
+`soleSQLiteWriter` to true.
+
+RC release sequence: reviewed PR checks pass, merge preserving baseline
+ancestry, tag `v2.0.0-rc.2`, dispatch `npm-publish.yml` with channel `next` and
+confirmation `PUBLISH PUBLIC PACKAGE`, then verify npm version, Git commit,
+tarball integrity, and provenance. Stable publishing retains full checks and
+additionally refuses incomplete sole-writer acceptance.
+
+## ForgeLoop 2.0.0 candidate scope
+
+The 2.0.0 candidate is not release-ready while SQLite migration plan §10 has
+open consumer-closure, current-source performance, or platform evidence. Keep
+all acceptance boxes open until their evidence is bound to the exact candidate
+revision.
+
+The 2.0.0 candidate carries the SQLite storage transition alongside the
+existing protocol, routing, provider, documentation, and package surfaces. The
+existing checklist remains applicable to those surfaces; SQLite release
+acceptance additionally requires every item below:
+
+- [ ] All plan §9 acceptance rows are current for the exact candidate SHA,
+      including an accepted 1,000-task hosted parity run with exact output,
+      validated workers, clean observer admission, cleanup, and lower native
+      p95 for both operations.
+- [ ] Plan §10 consumer closure is complete and `soleSQLiteWriter` is true
+      based on source audit and tests; fail-closed migration boundaries remain
+      in place until that evidence exists.
+- [ ] Migration, crash recovery, legacy-unbound handoff, attachment recovery,
+      backup, restore, rollback, and SQLite integrity checks pass on the exact
+      candidate.
+- [ ] Required Linux, macOS, Windows, supported Node runtime, MCP, API, and
+      package workflows pass at the exact candidate SHA.
+- [ ] Release identity and npm version availability are verified, and the
+      matching tag workflow completes its verification job before publishing.
 
 - [ ] README catalog and architecture fallback identify
       `ENG/flutter-development-eng.md` and explain that the specialist is
@@ -41,9 +109,10 @@ boundaries explicit:
 - [ ] Lifecycle, evidence, completion, and publication remain independent of
       Repository Index and persistent-host health.
 
-This branch prepares the candidate and its pull request. npm publication,
-tagging, GitHub Release, deployment, and merge remain separately authorized
-actions.
+This checklist does not authorize publication by itself. The owner authorized
+conditional npm publication through the GitHub workflow; the action remains
+prohibited until every release gate passes. Tagging, GitHub Release,
+deployment, and live data migration remain separate actions.
 
 ## CI minimization validation
 
@@ -76,7 +145,9 @@ actions.
 ## Contract and package identity
 
 - [ ] `package.json` and `package-lock.json` contain the same package version.
-- [ ] The package metadata declares the intended SPDX license (`MIT`).
+- [ ] The package metadata declares the intended license
+      (`PolyForm-Noncommercial-1.0.0`), includes the official license text,
+      and retains public core-package publication access.
 - [ ] `PROTOCOL_VERSION` and the integration API version remain compatible.
 - [ ] `npm run release:identity` passes for the candidate version.
 - [ ] No release tag or registry version collision exists.

package/docs/SELF_HOSTED_TESTS.md

@@ -0,0 +1,121 @@
+# Self-hosted Node validation
+
+Node validation uses the following repository-specific runners. Platform and
+Node-version matrix rows remain explicit; moving a job does not remove a check.
+
+| Platform | Runner label | Execution location |
+| --- | --- | --- |
+| macOS arm64 | `forgeloop-macos-local` | Local macOS LaunchAgent |
+| Windows x64 | `forgeloop-windows-remote` | Windows service on the requested remote host |
+| Linux x64 | `forgeloop-linux-remote` | Docker Linux container on that Windows host |
+
+Publishing jobs retain their existing hosted execution and manual confirmation.
+Their Node tests run in a preceding remote `verify` job. Classification and the
+final PR result aggregation remain hosted; they do not run the product test
+suite. CodeQL, dependency review and release-note publication retain their
+existing execution locations.
+
+`PR Core` also supports manual dispatch on a pushed candidate branch. Dispatch
+selects every validation category, so validation does not require a PR event
+or revision-range payload. PR invocations keep their existing path routing.
+The native Repository Index matrix waits for the preceding Linux checks to
+finish and runs one platform row at a time. Expanded Node compatibility waits
+for its minimum-runtime check and also runs one row at a time. Native rows still
+run after an earlier test failure to retain diagnostic coverage; final required
+validation reports preceding failures.
+
+Dispatch Windows full suite, expanded Node compatibility, and PR Core
+sequentially when validating the shared Windows/Linux host. The Windows job
+checks that the requested host IP is present and logs only the Docker runner's
+container ID, image ID, running state and hostname. Core Linux jobs record their
+platform, architecture, hostname and checked-out revision. Match the Linux
+hostname to the Windows Docker inspection before claiming the requested
+execution location. These identity checks remain unverified until the candidate
+workflows actually execute.
+
+PR repository-hygiene validation runs in the guarded remote Linux `lint` job,
+including documentation-only changes. Its checkout and Node prerequisites run
+for every admitted PR; JavaScript lint and dependency installation retain their
+path conditions. Hosted classification computes routing outputs only.
+
+Required ruleset check names remain unchanged. The historical
+`tarball smoke (ubuntu-latest)` context now executes in the remote Linux
+container; the check name is retained for ruleset compatibility.
+
+## Admission
+
+This is a public repository. An operator-owned copy of
+`scripts/ci-runner-admission.mjs` runs through
+`ACTIONS_RUNNER_HOOK_JOB_STARTED` before checkout. The shell wrappers and admission
+module live outside the job checkout and runner application directory. Keep
+those deployed copies synchronized when changing the policy.
+
+Admission requires matching repository metadata and allows only `push`,
+`workflow_dispatch`, `schedule`, `release`, and pull requests whose base and head
+both belong to this repository. Fork pull requests, `pull_request_target`,
+unknown events, missing metadata and invalid event files fail before job steps.
+Workflow job conditions independently exclude fork pull requests. Fork test
+validation requires a separate isolated execution environment; these machines
+do not run fork contributions.
+
+The hook does not sandbox admitted code. Repository write access is therefore a
+trust boundary. The Linux runner container has no Windows filesystem mounts or
+Docker socket mount. Its workspace and GitHub-managed runner credentials stay
+inside the dedicated container. Native macOS and Windows jobs run with their
+configured local accounts.
+
+## Installed locations and status
+
+Local macOS:
+
+```sh
+cd /Users/cassio/.local/share/forgeloop-ci/macos
+./svc.sh status
+```
+
+Windows PowerShell:
+
+```powershell
+Get-Service actions.runner.cassiomc1-forgeloop.forgeloop-windows-remote
+docker inspect forgeloop-linux-remote --format '{{json .State}}'
+docker logs --tail 40 forgeloop-linux-remote
+```
+
+The Windows runner is installed at `C:\forgeloop-ci\windows`. Its deployed hook
+is `C:\forgeloop-ci\hooks\windows-admission.ps1`. Isolated runtimes live below
+`C:\forgeloop-ci\runtime`; the runner environment includes portable Node, Git,
+Bash and unzip. Runner service credentials are managed by Windows; no account
+password belongs in repository files, job logs or shell scripts.
+
+The Linux image is built from `.github/runner/Dockerfile` using the repository
+root as its build context:
+
+```sh
+docker build -f .github/runner/Dockerfile -t forgeloop-actions-linux:2.337.0 .
+```
+
+The Node base image is pinned by digest. The GitHub runner archive is checked
+against its published SHA-256 before extraction. System dependency packages are
+resolved by the official runner dependency installer at build time; rebuilding
+is not a claim of byte-identical package resolution. The deployed image and
+runner version must be recorded with validation evidence.
+
+Docker Desktop credential helpers can fail in a noninteractive WinRM session.
+The dedicated `C:\forgeloop-ci\docker-config` uses an empty public Docker Hub auth
+entry and the already-installed Docker Desktop CLI plugin directory. Commands
+using that configuration target the existing Linux engine explicitly. They do
+not modify the user's Docker credential store.
+
+Registration tokens expire and must be obtained through an authorized GitHub
+operator. Pass them transiently through `ACTIONS_RUNNER_INPUT_TOKEN`; do not
+store registration tokens in Docker image layers, repository scripts or a
+container's persistent environment. A stopped or offline runner is not evidence
+that its checks passed.
+
+## Verification boundary
+
+Runner registration, admission probes, a native SQLite smoke, quick suites,
+full core suites, MCP/package checks and GitHub workflow execution are separate
+evidence dimensions. Record the source fingerprint and exact command for each
+run. A workflow routing edit becomes externally verified only after GitHub
+executes the affected jobs on these runners.

package/docs/documentation-manifest.json

@@ -199,18 +199,6 @@
       ],
       "packaged": true
     },
-    {
-      "path": "LICENSE-DOCS.md",
-      "id": "documentation-license",
-      "class": "legal",
-      "audience": [
-        "maintainer"
-      ],
-      "canonicalFor": [
-        "documentation-license"
-      ],
-      "packaged": true
-    },
     {
       "path": ".github/copilot-instructions.md",
       "id": "copilot-adapter",
@@ -1287,6 +1275,19 @@
       ],
       "packaged": true
     },
+    {
+      "path": "ENG/python-development-eng.md",
+      "id": "guide-python",
+      "class": "guide",
+      "audience": [
+        "harness",
+        "maintainer"
+      ],
+      "canonicalFor": [
+        "guide-python"
+      ],
+      "packaged": true
+    },
     {
       "path": "ENG/swift-development-eng.md",
       "id": "guide-swift",
@@ -1392,6 +1393,18 @@
         "provider-source-boundary"
       ],
       "packaged": true
+    },
+    {
+      "path": "docs/SELF_HOSTED_TESTS.md",
+      "id": "self-hosted-tests",
+      "class": "operational",
+      "audience": [
+        "maintainer"
+      ],
+      "canonicalFor": [
+        "self-hosted-node-validation"
+      ],
+      "packaged": true
     }
   ]
 }

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.14.0",
-  "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
+  "version": "2.0.0-rc.2",
+  "description": "Evidence-first engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cassiomc1/forgeloop.git"
   },
   "homepage": "https://github.com/cassiomc1/forgeloop#readme",
-  "license": "MIT",
+  "license": "PolyForm-Noncommercial-1.0.0",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
   "engines": {
-    "node": ">=20"
+    "node": ">=24.19.0"
   },
   "bin": {
     "forgeloop": "src/cli.js"
@@ -28,7 +28,6 @@
     "benchmarks/repository-index/README.md",
     "benchmarks/repository-index/run-hot-path.mjs",
     "benchmarks/repository-index/run-persistent-transport.mjs",
-    ".forgeloop/forgeloop.gitignore",
     "AGENTS.md",
     "CLAUDE.md",
     "GUIDE_ROUTER.md",
@@ -45,8 +44,6 @@
     "CONTRACT_COVERAGE.md",
     "PROJECT_PROFILE.md",
     "THIRD_PARTY_NOTICES.md",
-    "LICENSE",
-    "LICENSE-DOCS.md",
     ".cursor",
     ".github/copilot-instructions.md",
     "README.md",
@@ -68,6 +65,7 @@
     "docs/STRUCTURAL_QUALITY.md",
     "docs/DOCUMENTATION_GUIDE.md",
     "docs/RELEASE_CHECKLIST.md",
+    "docs/SELF_HOSTED_TESTS.md",
     "docs/PACKAGE_CONTENTS.md",
     "docs/PROVIDER_ARCHITECTURE.md",
     "docs/PROVIDERS.md",
@@ -121,7 +119,9 @@
     "!src/core/gates.js",
     "!src/core/decision-classification.js",
     "!src/core/workflow-compatibility.js",
-    "!src/core/cli-metadata.js"
+    "!src/core/cli-metadata.js",
+    "LICENSE",
+    "scripts/run-mcp-clean-tests.mjs"
   ],
   "scripts": {
     "test": "node scripts/run-tests.js",
@@ -166,11 +166,12 @@
     "benchmark:profiles:outliers": "node scripts/report-execution-profile-outliers.mjs",
     "benchmark:profiles:tail-analysis": "node scripts/report-tail-interpretation.mjs",
     "benchmark:profiles:regression": "node scripts/check-efficiency-regression.mjs",
-    "transactions:compact": "node scripts/compact-transactions.mjs",
     "complexity:check": "node scripts/check-complexity.mjs",
     "repository-index:manifest": "node scripts/verify-tgrep-manifest.mjs",
     "repository:hygiene": "node scripts/check-repository-hygiene.mjs",
     "task-discovery:benchmark": "node scripts/benchmark-task-discovery.mjs",
+    "storage:benchmark": "node scripts/benchmark-storage-sqlite.mjs",
+    "storage:benchmark:diagnosis": "node scripts/benchmark-diagnosis-parity.mjs",
     "verify:fast": "node scripts/run-validation.mjs --tier fast",
     "verify:local": "node scripts/run-validation.mjs --tier local",
     "verify:prepush": "node scripts/run-validation.mjs --tier prepush",
@@ -178,7 +179,11 @@
     "jev:smoke": "node scripts/jev-smoke.mjs",
     "benchmark:jev": "node scripts/benchmark-jev.mjs",
     "benchmark:jev:live": "node scripts/benchmark-jev.mjs --live",
-    "benchmark:test-intelligence": "node scripts/benchmark-test-intelligence.mjs"
+    "benchmark:test-intelligence": "node scripts/benchmark-test-intelligence.mjs",
+    "mcp:test:clean": "node scripts/run-mcp-clean-tests.mjs",
+    "release:quick": "node scripts/run-rc-release.mjs",
+    "release:rc:check": "node scripts/check-rc-release.mjs",
+    "storage:writer-inventory": "node scripts/storage-writer-inventory.mjs"
   },
   "devDependencies": {
     "c8": "^12.0.0",

package/schemas/task-bundle.schema.json

@@ -5,10 +5,15 @@
   "type": "object",
   "required": ["schemaVersion", "protocolVersion", "taskId", "artifacts"],
   "properties": {
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "enum": [1, 2] },
     "protocolVersion": { "const": 1 },
     "taskId": { "type": "string", "minLength": 1 },
-    "artifacts": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+    "artifacts": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "files": { "type": "array", "items": { "type": "object", "required": ["path", "size", "sha256"], "properties": { "path": { "type": "string", "minLength": 1 }, "size": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "additionalProperties": false } }
   },
+  "oneOf": [
+    { "properties": { "schemaVersion": { "const": 1 } } },
+    { "properties": { "schemaVersion": { "const": 2 } }, "required": ["files"] }
+  ],
   "additionalProperties": false
 }

package/scripts/generate-agent-protocol-summary.mjs

@@ -79,7 +79,7 @@ capability-family versions.`;
   const artifacts = Object.values(ARTIFACT_REGISTRY)
     .filter((artifact) => artifact.isPublic)
     .sort((left, right) => left.key.localeCompare(right.key))
-    .map((artifact) => [artifact.key, artifact.scope, artifact.path, artifact.schema, artifact.trustRole]);
+    .map((artifact) => [artifact.key, artifact.scope, artifact.logicalPath, `${artifact.canonicalStorage.path}${artifact.canonicalStorage.table ? ` :: ${artifact.canonicalStorage.table}` : ""}`, artifact.exportPath ?? "Copied separately", artifact.schema, artifact.trustRole]);
   const errors = Object.values(PUBLIC_ERROR_REGISTRY)
     .filter((error) => /^(E_(CLI|WORKSPACE|HANDOFF|RESPONSIBILITY|VERIFICATION_SCOPE|REVISION|ATTESTATION)_)/u.test(error.code))
     .sort((left, right) => left.code.localeCompare(right.code))
@@ -192,7 +192,7 @@ ${guideCatalog()}
 
 ## Public artifact registry
 
-${table(["Key", "Scope", "Path", "Schema", "Trust role"], artifacts)}
+${table(["Key", "Scope", "Logical identity", "Canonical storage", "Export path", "Schema", "Trust role"], artifacts)}
 
 ## Command catalog
 

package/scripts/run-mcp-clean-tests.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { cpSync, mkdirSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { installLockedMcp } from "./mcp-locked-install.mjs";
+import { runMcpTests } from "./run-mcp-tests.mjs";
+import { runNpm } from "./npm-command.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const temporary = mkdtempSync(path.join(os.tmpdir(), "forgeloop-mcp-clean-"));
+try {
+  const packed = JSON.parse(runNpm(["pack", "--json", "--pack-destination", temporary], { cwd: repositoryRoot, encoding: "utf8" }));
+  const coreTarball = path.join(temporary, packed[0].filename);
+  const root = path.join(temporary, "project");
+  mkdirSync(root);
+  execFileSync("tar", ["-xzf", coreTarball, "--strip-components=1", "-C", root]);
+  const mcpRoot = path.join(root, "integrations/mcp");
+  mkdirSync(mcpRoot, { recursive: true });
+  for (const relative of ["src", "bin", "tests", "README.md", "LICENSE"]) cpSync(path.join(repositoryRoot, "integrations/mcp", relative), path.join(mcpRoot, relative), { recursive: true });
+  for (const relative of ["tests/helpers", "tests/fixtures"]) cpSync(path.join(repositoryRoot, relative), path.join(root, relative), { recursive: true });
+  installLockedMcp({ target: mcpRoot, tarballs: [coreTarball] });
+  // Source fixtures and the installed package use the same locked external
+  // dependencies without borrowing the user's existing node_modules.
+  symlinkSync(path.join(mcpRoot, "node_modules"), path.join(root, "node_modules"), process.platform === "win32" ? "junction" : "dir");
+  process.exitCode = await runMcpTests({ root: mcpRoot });
+} finally {
+  rmSync(temporary, { recursive: true, force: true });
+}

package/src/adapters/agent-browser/provider.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { physicalTemporaryPath } from "../temporary-paths.js";
 
 import {
   E_BROWSER_VERIFICATION_ORIGIN_DENIED,
@@ -74,7 +75,7 @@ function assertBooleanObservation(data, label) {
 
 function isWithin(parent, child) {
   const relative = path.relative(path.resolve(parent), path.resolve(child));
-  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..");
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
 }
 
 function assertTempRootOutsideTarget(root, target) {
@@ -96,18 +97,20 @@ async function createCwd(tempRoot, fsImpl, target) {
   const root = tempRoot ?? os.tmpdir();
   if (typeof root !== "string" || !path.isAbsolute(root)) throw providerError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser tempRoot must be absolute");
   assertTempRootOutsideTarget(root, target);
+  const physicalRoot = await physicalTemporaryPath(root);
+  const physicalTarget = typeof target === "string" && path.isAbsolute(target) ? await physicalTemporaryPath(target) : target;
+  assertTempRootOutsideTarget(physicalRoot, physicalTarget);
   const make = fsImpl?.mkdtemp ?? mkdtemp;
-  const cwd = await make(path.join(root, "forgeloop-agent-browser-"));
-  try {
-    if (typeof cwd !== "string" || !path.isAbsolute(cwd)) {
-      throw providerError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser temporary cwd is invalid");
-    }
-    assertTempRootOutsideTarget(cwd, target);
-  } catch (error) {
-    try { await fsImpl?.rm?.(cwd, { recursive: true, force: true }); } catch { /* preserve the boundary failure */ }
-    throw error;
+  const cwd = await make(path.join(physicalRoot, "forgeloop-agent-browser-"));
+  if (typeof cwd !== "string" || !path.isAbsolute(cwd)) {
+    throw providerError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser temporary cwd is invalid");
   }
-  return cwd;
+  assertTempRootOutsideTarget(cwd, target);
+  const physicalCwd = await physicalTemporaryPath(cwd);
+  assertTempRootOutsideTarget(physicalCwd, physicalTarget);
+  // A rejected returned path is not owned cleanup authority. Only a validated
+  // private cwd reaches the caller's process execution and cleanup block.
+  return physicalCwd;
 }
 
 function screenshotRef(verificationId, digest) { return `agent-browser/${verificationId}/${digest}.png`; }

package/src/adapters/emulated-services/provider.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { physicalTemporaryPath } from "../temporary-paths.js";
 
 import {
   EMULATED_SERVICES_ERROR_CODES,
@@ -202,15 +203,21 @@ export function createEmulatedServicesProvider(options = {}) {
       const normalized = normalizeRequest(request, { fsImpl, targetRoot });
       validateSignal(normalized.signal);
       assertNotCancelled(normalized.signal);
-      const tempPrefix = path.join(tempRoot, "forgeloop-emulated-");
       let stateRoot = null;
       let managed = null;
       let result = null;
       let operationError = null;
       try {
-        stateRoot = await mkdtempImpl(tempPrefix);
-        assertAbsolutePath(stateRoot, "Emulated Services temporary state");
-        assertTempRootSafe(stateRoot, targetRoot);
+        const physicalRoot = await physicalTemporaryPath(tempRoot);
+        const physicalTarget = targetRoot ? await physicalTemporaryPath(targetRoot) : null;
+        assertTempRootSafe(physicalRoot, physicalTarget);
+        const candidate = await mkdtempImpl(path.join(physicalRoot, "forgeloop-emulated-"));
+        assertAbsolutePath(candidate, "Emulated Services temporary state");
+        assertTempRootSafe(candidate, targetRoot);
+        const physicalState = await physicalTemporaryPath(candidate);
+        assertTempRootSafe(physicalState, physicalTarget);
+        // Rejected paths do not grant recursive cleanup authority.
+        stateRoot = physicalState;
         const versionResult = await runBoundedEmulatedServicesCommand(executablePath, ["--version"], {
           cwd: stateRoot,
           env: filteredEnvironment(),

package/src/adapters/temporary-paths.js

@@ -0,0 +1,18 @@
+import path from "node:path";
+import { realpathWithTransientWindowsRetry } from "../core/filesystem.js";
+
+/** Resolve existing ancestors even when a configured target does not exist yet. */
+export async function physicalTemporaryPath(filename) {
+  let current = path.resolve(filename);
+  const missing = [];
+  while (true) {
+    try { return path.join(await realpathWithTransientWindowsRetry(current), ...missing); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const parent = path.dirname(current);
+      if (parent === current) throw error;
+      missing.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}