firedrill-run 2.2.4 → 3.0.0

package/README.md

@@ -1,35 +1,191 @@
-# Firedrill
+# Firedrill CLI
 
-Simulate AI agents with Firedrill. Your coding agent can operate simulations on
-your behalf. Start in your application's repository:
+Firedrill simulates your AI agent before it meets real users. Your agent runs on
+your machine as an ordinary local process. Firedrill keeps the reusable cloud
+resources: worlds, synthetic users, scenarios, hosted tools, evaluations and
+reports. The web app shows the same resources and progress as this CLI.
+
+Use the CLI yourself, or let a coding agent operate it for you. Local execution
+is not an operating-system sandbox. Approved commands run with your own user
+permissions.
+
+**Release candidate:** the proposed public package is `firedrill-run@3.0.0`.
+It is not published or approved for public activation yet. The existing
+unversioned package resolves to the older product. Do not use `@latest` to
+install this candidate. Once the owner approves and publishes this release,
+the intended commands are:
 
 ```sh
-npx firedrill-run
+npx --yes firedrill-run@3.0.0 init
+npx --yes firedrill-run@3.0.0 --help
 ```
 
-Choose any optional additions: CLI in this project or globally, a coding-agent
-MCP connection, Firedrill skills, and a TypeScript/Python SDK. Every step can be
-skipped; review before anything is installed. Then optionally sign in and select
-your project. `npx firedrill-run init` also offers the first-use additions before
-account setup. Return with `firedrill install`, or use `init --skip-install` to
-skip optional installation entirely. No simulation starts during setup.
+Until then, use only an explicitly supplied private candidate tarball.
+`firedrill --help` of that exact installed candidate is authoritative.
+
+## Requirements
+
+- Node.js `>=22.23.4 <23`.
+- macOS, Windows or Linux are source-supported targets. A release qualification
+  must name the actual OS/architecture used; support is not proof each platform
+  was exercised. Native keyring availability also depends on its platform build.
+- An OS credential store for persistent sign-in:
+  - macOS: Keychain;
+  - Windows: Credential Manager;
+  - desktop Linux: Secret Service (GNOME Keyring, KWallet or KeePassXC).
+
+Without a credential store, for example on a headless or remote Linux machine,
+use session-only sign-in. Credentials are never written to a file.
+Source snapshot and candidate-copy commands also need an external `python3`
+on PATH. Browser drivers need their own supported browser/driver installation.
+These are not included in the npm package. Ordinary cloud metadata commands
+do not require Docker or a bundled Python environment.
 
-Or install globally and use the `firedrill` command:
+## Sign in
 
 ```sh
-npm install --global firedrill-run
 firedrill init
 ```
 
-Requires Node.js 22 or later. This is the official short-name launcher for the
-Firedrill CLI. It invokes the exact declared CLI dependency in the same process;
-authentication and commands are supplied by that CLI. It does not run a
-local MCP server or bundle the private Firedrill runtime. Your application runs
-in your own repository or CI.
+`init` signs you in with WorkOS device authorization, or starts account creation.
+It then selects a workspace and checks this machine.
+
+- `--json --no-browser` prints the verification link and code instead of
+  opening a browser. A person approves in the browser.
+- `--session-only` keeps credentials in memory in a companion process. Keep that
+  terminal open while other `firedrill` commands use it. Stop it with Ctrl-C or
+  `firedrill logout`.
+- `--persistent` uses the OS credential store. This is the default when one is
+  available.
+- `--workspace <id>` selects a workspace without a prompt.
+
+`firedrill status` shows the account, workspace, credential mode, companion and
+local drivers. `firedrill logout` revokes terminal access and removes saved
+credentials.
+
+Terminal sign-in and remote MCP sign-in are separate authorizations. Account
+creation does not authorize execution or payment.
+
+## Simulate your agent
+
+| Step | Command |
+| --- | --- |
+| Register the agent: metadata only, no source, paths, commands or secrets | `firedrill register --descriptor descriptor.json --name "<name>"` |
+| Find reusable resources | `firedrill library --kind persona\|scenario\|evaluation [--search <prefix>]`, `firedrill tools catalog` |
+| Author a private draft | `firedrill library save --kind <kind> --file <path>` |
+| Declare a world (nothing starts) | `firedrill world save --agent <id> --file world.json` |
+| Review the plan and its cloud-work estimate | `firedrill plan --world <world-id>` |
+| Apply after approval | `firedrill apply <plan-id> --approve --follow` |
+| Enroll this machine once | `firedrill runner enroll` |
+| Run the drills on this machine | `firedrill run --plan local-plan.json --descriptor descriptor.json --campaign <campaign-id>` |
+| Watch progress | `firedrill watch <campaign> --follow` |
+| Read results and evidence | `firedrill report <campaign>`, `… quality`, `… drill <drill> [results \| effects \| conversation \| evidence]` |
+| Cancel | `firedrill simulation cancel <campaign> --approve-change` |
+
+What to expect at each step:
+
+- **Plan.** `plan` saves a review but starts no tools or drills and makes no
+  charge. It shows:
+  - pinned versions;
+  - how each dependency is reached;
+  - unmet requirements;
+  - the maximum cloud work.
+
+  Local target compute is never charged.
+- **Apply.** `apply` reserves the approved estimate and prepares the plan. When
+  preparation is ready, it creates the campaign. No target starts at this step.
+- **Run.** `run` shows the exact local plan: roots, argv, working directories,
+  environment variable names, readiness checks, driver and reset hooks. Nothing
+  runs until you approve that exact plan. In JSON mode, pass `--approve` only
+  after a person has approved it.
+- **Report.** The report keeps four things separate:
+  - execution state;
+  - the observed outcome;
+  - per-criterion quality;
+  - required checks.
+
+  Missing evidence is never a zero or a pass.
+
+## JSON mode
+
+Every command takes `--json`. In JSON mode the CLI:
+
+- never prompts;
+- opens no browser unless `--open` is given;
+- prints one `{"type", "data"}` object per line.
+
+Errors go to stderr with a nonzero exit code and a stable `code`.
+
+## Hosted tools outside a drill
+
+Start reviewed catalog tools in the cloud for a set time and use them from a
+local agent:
+
+```sh
+firedrill tools runnable
+firedrill tools start <version-id>... --seconds <n>
+firedrill tools sessions
+firedrill tools access <session-id> [--allow-writes]
+firedrill tools session <session-id> stop
+```
+
+- `start` shows a cost estimate first. After approval, run the printed
+  `--usage-quote <key> --approve-tool-change` command. It admits exactly the
+  quotes you approved.
+- `access` serves loopback MCP and JSON URLs. They are read-only unless
+  `--allow-writes` is given.
+
+Custom tool packages use `firedrill tools init`, `validate` and `push`. Pushing a
+private version does not publish it or prove it runs.
+
+## Remote MCP
+
+```sh
+firedrill mcp --agent codex|claude|other
+```
+
+This prints connection guidance for the management MCP server. The MCP client
+signs in through its own browser OAuth. Remote MCP manages cloud resources but
+cannot run anything on this machine.
+
+## Safety
+
+- Commands, argv, roots and hooks come only from the plan you approved. A later
+  change to argv or a hashed file voids that approval.
+- A plan never:
+  - disables TLS verification;
+  - adds a certificate authority;
+  - sets a proxy;
+  - injects a loader (`LD_*`, `DYLD_*`).
+
+  Secret configuration is never a fixed plan value.
+- Simulated dependencies are reached through per-drill loopback URLs. Short-lived
+  access stays in the CLI's memory and never reaches the target. Only `observed`
+  tool results are passed to the target. A pending or unknown outcome arrives as
+  an error with a recovery path.
+- Attached services are only checked for readiness and are never signalled.
+  Launched services run in their own process group and are stopped with it.
+- On Windows there are no process groups. Only each started process is stopped,
+  and processes it started may keep running.
+
+## Recovery
+
+- Commands that change cloud state print a request key. Rerun with
+  `--request <key>` to read the original result. That never applies or charges
+  twice.
+- A step whose outcome is unknown stays unknown and is never replayed under a new
+  key.
+- If the CLI stops during a run, a lost local process is not resumed. Inspect the
+  campaign with `watch` and `report`, and follow the recovery it returns.
+
+## Advanced commands
 
-For non-interactive package installation use `npx --yes firedrill-run`. Coding
-agents and CI should also use the CLI's documented `--json --non-interactive`
-inputs for the action they intend to run. First-use browser consent stays human.
+`firedrill help advanced` lists the remaining commands, including:
 
-[Documentation](https://docs.firedrill.run) ·
-[Connect your coding agent](https://firedrill.run/agents)
+- catalog tool management (`tools`);
+- tool sessions (`sessions`);
+- runner devices and grants (`runner`);
+- billing and usage (`billing`);
+- CI connections (`ci`);
+- team, workspace and settings;
+- `login`, `signup` and `workspace` as separate steps of `init`.

package/bin/firedrill.mjs

@@ -1,6 +1,30 @@
 #!/usr/bin/env node
-import { createRequire } from "node:module";
-import { pathToFileURL } from "node:url";
-
-const require = createRequire(import.meta.url);
-await import(pathToFileURL(require.resolve("@firedrill-run/cli/bin/firedrill.mjs")).href);
+// Keep this bootstrap plain JavaScript. An unsupported Node runtime must not
+// try to parse TypeScript before it can explain the required toolchain.
+const [major, minor, patch] = process.versions.node.split('.').map(Number);
+const supported = major === 22 && (minor > 23 || minor === 23 && patch >= 4);
+function report(code, message, exitCode = 1) {
+  process.stderr.write(process.argv.includes('--json')
+    ? JSON.stringify({ type: 'error', error: { code, message } }) + '\n'
+    : message + '\n');
+  process.exitCode = exitCode;
+}
+if (!supported) {
+  report('node_runtime_unsupported', 'Firedrill requires Node 22.23.4 or a later 22.x release. Update Node, then run the command again.');
+} else {
+  let entry;
+  try { entry = await import('../dist/cli/src/main.js'); }
+  catch (error) {
+    if (error?.code === 'platform_configuration_invalid') {
+      report('platform_configuration_invalid', 'Use FIREDRILL_PLATFORM=sim-dev for isolated hosted development with all FIREDRILL_LOCAL_* variables unset. Unset all platform variables to select the public platform. Unknown or mixed profiles are refused.', 2);
+    } else if (error?.code === 'local_platform_configuration_invalid') {
+      report('local_platform_configuration_invalid', 'Local development requires FIREDRILL_LOCAL_PLATFORM=1 and paired HTTP loopback API and app origins with explicit ports. Arbitrary service URLs are refused.', 2);
+    } else {
+      report('cli_installation_unavailable', 'The CLI could not load. Restore the Firedrill installation, then try again.');
+    }
+  }
+  if (entry) {
+    try { await entry.main(); }
+    catch { report('command_unconfirmed', 'The command could not finish. No success is implied. Inspect its original request before trying again.'); }
+  }
+}

package/dist/assembly.json

@@ -0,0 +1,13 @@
+{
+  "schema": "firedrill.cli-assembly.v1",
+  "package": "firedrill-run",
+  "version": "3.0.0",
+  "entry": "cli/src/main.js",
+  "helpers": [
+    "cli/runtime/source_snapshot.py",
+    "cli/runtime/candidate_copy.py"
+  ],
+  "shared": [
+    "contracts/world-command.js"
+  ]
+}

package/dist/cli/runtime/candidate_copy.py

@@ -0,0 +1,395 @@
+"""Original, data-only candidate export. Never imports or runs customer source.
+
+Only creates a new owned destination, or resumes that exact destination after
+checking every existing file. It never overwrites or deletes destination files.
+"""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import re
+import stat
+import struct
+import tempfile
+import zipfile
+import sqlite3
+from contextlib import closing
+
+
+class Refused(Exception):
+    pass
+
+
+def canonical(value):
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+
+
+def private_json(path, maximum):
+    before = os.lstat(path)
+    if (not stat.S_ISREG(before.st_mode) or before.st_uid != os.getuid() or before.st_mode & 0o077
+            or not 0 < before.st_size <= maximum):
+        raise Refused()
+    fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
+    try:
+        actual = os.fstat(fd)
+        if (actual.st_dev, actual.st_ino, actual.st_size, actual.st_mtime_ns) != (before.st_dev, before.st_ino, before.st_size, before.st_mtime_ns):
+            raise Refused()
+        with os.fdopen(os.dup(fd), "rb") as stream:
+            body = stream.read(maximum + 1)
+        after = os.fstat(fd)
+        if (after.st_size, after.st_mtime_ns, after.st_ctime_ns) != (actual.st_size, actual.st_mtime_ns, actual.st_ctime_ns):
+            raise Refused()
+        return json.loads(body)
+    finally:
+        os.close(fd)
+
+
+def receipt(path, value):
+    # A private cache file, never a customer destination. Atomic replacement
+    # retains recovery through a crash; source files use exclusive links below.
+    fd, temporary = tempfile.mkstemp(prefix="receipt-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb") as stream:
+            stream.write(canonical(value))
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+        parent = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+        try:
+            os.fsync(parent)
+        finally:
+            os.close(parent)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def safe_path(raw):
+    path = PurePosixPath(raw)
+    denied = {".git", ".hg", ".svn", ".aws", ".ssh", ".gcloud", "node_modules", ".venv", "venv", "__pycache__", ".next", ".turbo", "coverage", ".firedrill-simulation"}
+    if (not raw or len(raw) > 1024 or path.is_absolute() or path.as_posix() != raw or ".." in path.parts
+            or "\\" in raw or any(ord(one) < 32 or ord(one) == 127 for one in raw)
+            or ":" in path.parts[0] or denied.intersection(path.parts)
+            or any(one.startswith(".env") for one in path.parts)
+            or path.suffix.lower() in {".pem", ".key", ".p12", ".pfx", ".sqlite", ".sqlite3", ".db", ".kdbx"}
+            or path.name in {".npmrc", ".pypirc", ".netrc", "credentials.json", "id_rsa", "id_ed25519"}):
+        raise Refused()
+    return path
+
+
+def directories(root, parts, create=False):
+    current = os.dup(root)
+    try:
+        for part in parts:
+            if create:
+                try:
+                    os.mkdir(part, 0o700, dir_fd=current)
+                    os.fsync(current)
+                except FileExistsError:
+                    pass
+            new = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=current)
+            os.close(current)
+            current = new
+        return current
+    except BaseException:
+        os.close(current)
+        raise
+
+
+def matching(fd, expected):
+    before = os.fstat(fd)
+    if (not stat.S_ISREG(before.st_mode) or before.st_uid != os.getuid() or before.st_size != expected["size"]
+            or stat.S_IMODE(before.st_mode) != expected["mode"]):
+        raise Refused()
+    with os.fdopen(os.dup(fd), "rb") as stream:
+        if hashlib.file_digest(stream, "sha256").hexdigest() != expected["sha256"]:
+            raise Refused()
+    after = os.fstat(fd)
+    if (before.st_size, before.st_mtime_ns, before.st_ctime_ns) != (after.st_size, after.st_mtime_ns, after.st_ctime_ns):
+        raise Refused()
+
+
+class FileIndex:
+    """Disk-backed identity index. Each read retains at most one manifest row."""
+    def __init__(self, db):
+        self.db = db
+        self.count = 0
+        db.execute("CREATE TABLE files(path TEXT PRIMARY KEY, document TEXT NOT NULL, archive_seen INTEGER NOT NULL DEFAULT 0)")
+
+    def __len__(self):
+        return self.count
+
+    def __contains__(self, key):
+        return self.db.execute("SELECT 1 FROM files WHERE path=?", (key,)).fetchone() is not None
+
+    def get(self, key):
+        row = self.db.execute("SELECT document FROM files WHERE path=?", (key,)).fetchone()
+        return json.loads(row[0]) if row else None
+
+    def __getitem__(self, key):
+        result = self.get(key)
+        if result is None:
+            raise Refused()
+        return result
+
+    def add(self, value):
+        self.db.execute("INSERT INTO files(path,document) VALUES(?,?)", (value["path"], canonical(value).decode()))
+        self.count += 1
+
+    def items(self):
+        for path, document in self.db.execute("SELECT path,document FROM files ORDER BY path"):
+            yield path, json.loads(document)
+
+    def observe_archive(self, key):
+        if self.db.execute("UPDATE files SET archive_seen=1 WHERE path=? AND archive_seen=0", (key,)).rowcount != 1:
+            raise Refused()
+
+
+class FolderIndex:
+    def __init__(self, db):
+        self.db = db
+        self.count = 0
+        db.execute("CREATE TABLE folders(path TEXT PRIMARY KEY)")
+
+    def __len__(self):
+        return self.count
+
+    def __contains__(self, key):
+        return self.db.execute("SELECT 1 FROM folders WHERE path=?", (key,)).fetchone() is not None
+
+    def add(self, key):
+        self.db.execute("INSERT INTO folders(path) VALUES(?)", (key,))
+        self.count += 1
+
+    def overlaps_files(self):
+        return self.db.execute("SELECT 1 FROM folders JOIN files USING(path) LIMIT 1").fetchone() is not None
+
+
+def inspect_existing(root, files, folders, parts=(), seen=None):
+    seen = [0] if seen is None else seen
+    maximum = len(files) + len(folders)
+    with os.scandir(root) as entries:
+        for entry in entries:
+            name = entry.name
+            path = "/".join((*parts, name))
+            seen[0] += 1
+            if seen[0] > maximum:
+                raise Refused()
+            before = os.stat(name, dir_fd=root, follow_symlinks=False)
+            if stat.S_ISDIR(before.st_mode) and path in folders and before.st_uid == os.getuid():
+                child = os.open(name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=root)
+                try:
+                    inspect_existing(child, files, folders, (*parts, name), seen)
+                finally:
+                    os.close(child)
+            elif path in files and stat.S_ISREG(before.st_mode):
+                fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW, dir_fd=root)
+                try:
+                    matching(fd, files[path])
+                finally:
+                    os.close(fd)
+            else:
+                raise Refused()
+    return seen[0]
+
+
+def copy(args, db):
+    if os.name != "posix" or not hasattr(os, "O_NOFOLLOW") or not hasattr(os, "getuid"):
+        raise Refused()
+    cache = Path(args.cache)
+    if not cache.is_absolute() or cache != cache.resolve(strict=True):
+        raise Refused()
+    owned = cache.stat()
+    if not stat.S_ISDIR(owned.st_mode) or owned.st_uid != os.getuid() or owned.st_mode & 0o077:
+        raise Refused()
+    intent = private_json(cache / "intent.json", 65536)
+    document = private_json(cache / "manifest.json", 65536)
+    identity = document["identity"]
+    if (intent["schema"] != "firedrill.native-candidate-copy.v1" or identity["schema"] != "firedrill.agent-change-export.v1"
+            or document.get("schema") != "firedrill.candidate-manifest-pages.v1"
+            or not re.fullmatch(r"[a-f0-9-]{36}", document.get("page_set", ""))
+            or identity["change_id"] != intent["change"] or identity["baseline_id"] != intent["campaign"]
+            or identity["scope_sha256"] != intent["scope_sha256"] or identity["draft_sha256"] != intent["draft_sha256"]
+            or type(identity["file_count"]) is not int or not 1 <= identity["file_count"] <= identity["capacity"]["files"]
+            or type(document.get("pages")) is not int or document["pages"] != (identity["file_count"] + 99) // 100):
+        raise Refused()
+    files, folders, total, folder_bytes, count = FileIndex(db), FolderIndex(db), 0, 0, 0
+    manifest_hash = hashlib.sha256(b"[")
+    for page in range(1, document["pages"] + 1):
+        packet = private_json(cache / f"manifest-{document['page_set']}-{page}.json", 1024 * 1024)
+        entries = packet.get("entries")
+        if (packet.get("page") != page or not isinstance(entries, list) or not 1 <= len(entries) <= 100
+                or page < document["pages"] and len(entries) != 100):
+            raise Refused()
+        for one in entries:
+            if (not isinstance(one, dict) or set(one) != {"path", "size", "sha256", "mode"} or type(one["size"]) is not int
+                    or not 0 <= one["size"] <= identity["capacity"]["file_bytes"] or one["mode"] not in {0o644, 0o755}
+                    or not re.fullmatch("[0-9a-f]{64}", one["sha256"])):
+                raise Refused()
+            path = safe_path(one["path"])
+            if count:
+                manifest_hash.update(b",")
+            manifest_hash.update(canonical(one))
+            count += 1
+            if count > identity["file_count"]:
+                raise Refused()
+            files.add(one)
+            total += one["size"]
+            for parent in path.parents:
+                name = parent.as_posix()
+                if name != "." and name not in folders:
+                    folder_bytes += len(name.encode("utf-8")) + 64
+                    if folder_bytes > identity["capacity"]["directory_bytes"]:
+                        raise Refused()
+                    folders.add(name)
+    manifest_hash.update(b"]")
+    if (count != identity["file_count"] or manifest_hash.hexdigest() != identity["files_sha256"]
+            or total != identity["expanded_bytes"] or total > identity["capacity"]["expanded_bytes"] or folders.overlaps_files()):
+        raise Refused()
+    destination = Path(intent["destination"])
+    if not destination.is_absolute() or destination.name in {"", ".", ".."}:
+        raise Refused()
+    parent = destination.parent.resolve(strict=True)
+    if destination != parent / destination.name:
+        raise Refused()
+    archive = cache / "source.zip"
+    fd = os.open(archive, os.O_RDONLY | os.O_NOFOLLOW)
+    with os.fdopen(fd, "rb") as raw:
+        stored = os.fstat(raw.fileno())
+        if (not stat.S_ISREG(stored.st_mode) or stored.st_uid != os.getuid() or stored.st_mode & 0o077
+                or stored.st_size != identity["snapshot"]["size"] or stored.st_size > identity["capacity"]["archive_bytes"]
+                or hashlib.file_digest(raw, "sha256").hexdigest() != identity["snapshot"]["sha256"]):
+            raise Refused()
+        # Bound the central directory read before ZipFile allocates entries.
+        class Bounded:
+            def __init__(self, stream):
+                self.stream = stream
+            def __getattr__(self, name):
+                return getattr(self.stream, name)
+            def read(self, size=-1):
+                maximum = identity["capacity"]["directory_bytes"]
+                if size > maximum:
+                    raise Refused()
+                body = self.stream.read(maximum + 1 if size < 0 else size)
+                if len(body) > maximum:
+                    raise Refused()
+                if size >= 46 and body.startswith(b"PK\x01\x02"):
+                    at, count = 0, 0
+                    while body[at:at + 4] == b"PK\x01\x02":
+                        if len(body) - at < 46:
+                            raise Refused()
+                        name, extra, comment = struct.unpack_from("<HHH", body, at + 28)
+                        at += 46 + name + extra + comment
+                        count += 1
+                        if at > len(body) or count > len(files):
+                            raise Refused()
+                return body
+        raw.seek(0)
+        with zipfile.ZipFile(Bounded(raw)) as opened, tempfile.TemporaryDirectory(prefix=".firedrill-candidate-", dir=parent) as temporary:
+            members = opened.infolist()
+            if len(members) != len(files):
+                raise Refused()
+            staging = Path(temporary)
+            for member in members:
+                files.observe_archive(member.filename)
+                expected = files.get(member.filename)
+                mode = member.external_attr >> 16
+                if (expected is None or member.flag_bits & 1 or stat.S_IFMT(mode) not in {0, stat.S_IFREG}
+                        or (0o755 if mode & 0o111 else 0o644) != expected["mode"] or member.file_size != expected["size"]):
+                    raise Refused()
+                target = staging / safe_path(member.filename)
+                target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+                hashed, size = hashlib.sha256(), 0
+                with opened.open(member) as incoming, target.open("xb") as output:
+                    while chunk := incoming.read(1024 * 1024):
+                        size += len(chunk)
+                        if size > expected["size"]:
+                            raise Refused()
+                        hashed.update(chunk)
+                        output.write(chunk)
+                    output.flush()
+                    os.fsync(output.fileno())
+                if size != expected["size"] or hashed.hexdigest() != expected["sha256"]:
+                    raise Refused()
+                target.chmod(expected["mode"])
+            parentfd = os.open(parent, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+            try:
+                receipt_path = cache / "copy-receipt.json"
+                proof = {"schema": "firedrill.candidate-copy-receipt.v1", "request_key": intent["key"],
+                    "destination": str(destination), "source_id": identity["source_id"], "snapshot_sha256": identity["snapshot"]["sha256"],
+                    "files_sha256": identity["files_sha256"]}
+                if receipt_path.exists():
+                    previous = private_json(receipt_path, 65536)
+                    if any(previous.get(key) != value for key, value in proof.items()):
+                        raise Refused()
+                else:
+                    # Never use exist_ok, checkout, reset, rename or replacement
+                    # over a destination. A crash before the ownership receipt
+                    # leaves an unknown folder that must not be claimed later.
+                    os.mkdir(destination.name, 0o700, dir_fd=parentfd)
+                    os.fsync(parentfd)
+                    owned = os.stat(destination.name, dir_fd=parentfd, follow_symlinks=False)
+                    previous = {**proof, "device": owned.st_dev, "inode": owned.st_ino, "complete": False}
+                    receipt(receipt_path, previous)
+                root = os.open(destination.name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parentfd)
+                try:
+                    actual = os.fstat(root)
+                    if (actual.st_dev, actual.st_ino, actual.st_uid) != (previous["device"], previous["inode"], os.getuid()):
+                        raise Refused()
+                    inspect_existing(root, files, folders)
+                    for name, expected in files.items():
+                        path = PurePosixPath(name)
+                        containing = directories(root, path.parts[:-1], create=True)
+                        try:
+                            try:
+                                # Unlinking our private staged name immediately
+                                # removes the second link. No target file is
+                                # truncated even after interrupted publication.
+                                os.link(staging / name, path.name, dst_dir_fd=containing, follow_symlinks=False)
+                                os.unlink(staging / name)
+                                os.fsync(containing)
+                            except FileExistsError:
+                                fd = os.open(path.name, os.O_RDONLY | os.O_NOFOLLOW, dir_fd=containing)
+                                try:
+                                    matching(fd, expected)
+                                finally:
+                                    os.close(fd)
+                        finally:
+                            os.close(containing)
+                    if inspect_existing(root, files, folders) != len(files) + len(folders):
+                        raise Refused()
+                    if os.stat(destination.name, dir_fd=parentfd, follow_symlinks=False).st_ino != actual.st_ino:
+                        raise Refused()
+                    receipt(receipt_path, {**previous, "complete": True})
+                finally:
+                    os.close(root)
+            finally:
+                os.close(parentfd)
+    return {"schema": "firedrill.candidate-copy.v1", "destination": str(destination), "source_id": identity["source_id"],
+        "world_id": identity["world_id"], "agent_id": identity["agent_id"], "files_sha256": identity["files_sha256"],
+        "file_count": len(files), "target_executed": False, "original_files_changed": False}
+
+
+def run(args):
+    # No retained full source manifest in memory. Private temporary SQLite is
+    # an index only, never execution state and never copied into the candidate.
+    with tempfile.TemporaryDirectory(prefix="firedrill-copy-index-") as directory:
+        with closing(sqlite3.connect(Path(directory) / "index.sqlite")) as db:
+            db.execute("PRAGMA cache_size=-2048")
+            db.execute("PRAGMA temp_store=FILE")
+            db.execute("PRAGMA mmap_size=0")
+            return copy(args, db)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--cache", required=True)
+    args = parser.parse_args()
+    try:
+        result = run(args)
+        print(json.dumps({"ok": True, "data": result}))
+    except Exception:
+        print(json.dumps({"ok": False, "error": {"code": "candidate_copy_refused",
+            "message": "The exact candidate copy could not be confirmed. Existing destination files were not overwritten or removed. Inspect the retained copy request before resuming."}}))
+        raise SystemExit(1)