@hominis/fireforge 0.55.0 → 0.60.0

package/CHANGELOG.md

@@ -1,5 +1,232 @@
 # Changelog
 
+## 0.60.0
+
+A rework of the whole tool. The two ways of storing a fork stay (patch mode and source mode), and the daily commands (`status`, `lint`, `typecheck`, `check`, `build`, `test`, `run`) mean the same and take the same flags in both. Source mode no longer routes work through a host daemon: there are no jobs, slots, supervisor or proof ledger. The code base is about 47,000 lines instead of 164,000, and the command line has 65 commands and subcommands with 92 distinct flags, against 125 and 259. Upgrading needs configuration changes and one full rebuild; [`docs/migrating.md`](docs/migrating.md) lists every removed command, flag and key with its replacement, and the steps for each mode.
+
+### Workflow
+
+- `fireforge.json` takes `"mode": "patches"` (the default) or `"mode": "source"` with a `source` block (`root`, `metadataRoot`, `pristineCommit`). `setup --mode` creates either.
+- `download` imports the pinned archive as one commit into a pristine repository per pin under `~/.fireforge/pristine/`, the same commit on every host, and checks the archive's SHA-256 against `firefox.sha256` or Mozilla's `SHA256SUMS` every time. In patch mode `engine/` is a checkout of that commit.
+- Source mode builds and tests in workspaces from a per-host pool under `~/.fireforge/workspaces/`. A command leases one for its duration (preferring the one its checkout used last, so the object directory stays warm), brings it to the checkout's `src/` by writing only the paths that differ, and releases it. Parallel sessions are git worktrees, each leasing its own workspace. When all are leased a command waits, naming the holders, up to `--wait-lock` (default two hours).
+- Materialization changes an engine file only when it holds bytes FireForge can account for; anything else is reported as `materialize-drift` with `workspace repair <name>` as the fix.
+- Commands that read owned changes (`status`, `verify`, `lint`, `export`) read `src/` and the pristine repository directly, with no capture, snapshot or slot.
+- Two host locks apply in both modes: `display` (one browser window at a time) and `build` (`buildSlots` concurrent compiles, from `~/.fireforge/host.json`, default 1).
+- Every lint, policy and typecheck rule is defined over the owned changes, so a rule means the same whichever mode produced them. In source mode the files Furnace deploys are judged with the owned files, one group per component, and the patch-size rules judge components of upstream changes; created files answer to `file-too-large`.
+- Leasing a pool workspace deploys the checkout's components after materializing it, and `typecheck` reads its projects with the engine at `engine/` beside the project's files, so a `jsconfig.json` in the engine that names project files (the paths Furnace writes among them) resolves wherever the workspace is.
+- A pristine repository 0.56 stored for the same archive is used as it is; the archive imports as the same commit in both versions.
+- `gate` replaces `prove`: on a clean committed tree it runs `check`, a build, and the declared lanes, stress runs, negative controls and smoke starts in one workspace, reports every entry, and moves `refs/fireforge/verified` fast-forward only when all pass and every declared acceptance is recorded. A commit that changes only `gate.documents` paths needs `check` alone.
+- The object directory is `obj-fireforge` inside every engine and belongs to the path it was configured at. `workspace add --from` clones a workspace's engine without its builds, and `build` removes an object directory configured for another path and builds from nothing; `build --rewrite-mozinfo` is gone, because a relocated object directory keeps reading and linking from the directory it was built in.
+
+### Commands
+
+- `migrate` upgrades a 0.56 project in place, in either mode: the `fireforge.json` keys, the override records, `waivers.json` and `policy.json`, the merge driver and `MOZ_OBJDIR` lines, as one journaled change on a committed tree that ends with `verify`. It lists everything it rewrote or dropped and stops before writing when anything needs a decision. `migrate --to-source` is the conversion of a patch queue to source mode.
+- `status --groups` lists every group by the ID that waivers, scope rules and reserved exceptions name it by. In source mode an ID is the component, the `exportQueue` group, `created-<directory>` or the Furnace component, used as written; nothing is prefixed, and an export's numbering is no part of it.
+- New: `workspace list|add|remove|repair`, `override`, `restore`, `migrate`, `merge-driver install`, `gate`, `gate accept`, `gate status`, `patch set`, `config get|set`, `version`.
+- `export` captures edits into a new patch in patch mode (`--all` replaces `export-all`) and writes the generated patch queue in source mode (`--out`), proven to replay to the tree the checkout builds.
+- `rebase --to <version>` downloads the version, writes the pin and moves the project: patch mode re-applies the queue with reduced context (`--continue`, `--abort`, `--dry-run`, `--force`); source mode merges every owned file three ways and leaves conflicts as git leaves them. It replaces `source set`, `download --force` plus `rebase`, and `authored refresh`.
+- `test` dispatches mochitest files one browser each by default (`--no-shard`, `--standalone`), runs negative controls with `--control <diff> --expect <assertion>`, and takes `--env`. Leftovers of earlier runs of the workspace are reaped and foreign port holders waited for without a flag.
+- `check` gains a `token-lint` step and runs its engine steps in one workspace. `check.extraSteps` commands are argument vectors with a default 600-second timeout and an `engine` flag.
+- `patch set` edits a patch's description, tier, lint waivers and staged dependencies in one transaction.
+- `furnace apply` replaces `furnace deploy`; `furnace create --tests <harness>` and `furnace override --css-only` replace their previous flags.
+- `doctor --recover` undoes changes an interrupted command left half-made.
+- Exit code 143 (`TERMINATED`) for SIGTERM and SIGHUP.
+
+### Configuration
+
+- `sources` becomes `mode` plus `source`. `proof` becomes `gate` with `build`, `documents`, `lanes`, `stress`, `controls`, `runs` and `acceptance`; a smoke start in `runs` is structured (`smokeExit`, `headless`, `args`, `consoleAllowFile`, `validate`).
+- `patchLint.rules` sets the severity of any rule and replaces `jsdocClassMethods`, `chromeScriptJsDoc` and `testAssertionFloor`. `patchLint.waivers` declares waivers per group in either mode. `patchPolicy.scopeRules` selects groups by a `group` regular expression.
+- `exportQueue.groups[].tier` and `exportQueue.componentTiers` carry size tiers into a generated queue. `wire.domTarget` names the chrome document `wire --dom` includes into. `test.harnessFailurePatterns` names output that means the browser failed before any test ran.
+- `license` defaults to `EUPL-1.2`. `patchPolicy.mutationMode` takes `error` or `warn`. `history` is removed. `doctor` probes `externalToolchains`.
+- `patches/patches.json` is written as version 2 (file names, categories and touched files derived; one Firefox stamp for the queue). A version 1 manifest is read and converted on the next write.
+- A mozconfig template that sets `MOZ_OBJDIR` is refused.
+
+### Removed
+
+- `authored` (every subcommand), `host`, `slot`, `job`, `prove`, `tree`, `park`, `export-all`, `source set`, `lint cache`, `patch body|stage|reserve|tier|lint-ignore|staged-dependency`, `furnace deploy|init|list|scan|preview|refresh|sync|chrome-doc`.
+- `slots`, `proof`, `test.canaryPath`, `test.canaryTimeoutSeconds`, `test.reapOrphans`, `test.lockMode`, `test.furnaceApply`, `check.timeout`, `check.timeouts`, `check.status.failOnUnknown`, `patchLint.prettier`, `patchLint.forwardRegistration`.
+- Most flags of the remaining commands, among them `test --headless` (the default), `--reap-orphans`, `--auto-ports`, `--furnace-apply`, `--canary`, `--perf-samples`, `--pgid-file`, `status --fail-on`, `lint --report`, `--since`, `export --category`, `--lint-ignore`, `--skip-lint`, every `--force-unsafe` and `--yes` on queue operations, and the `doctor --repair-*` family.
+- The `.fireforge/logs/` run logs of `build`; `test` keeps its latest ten run logs in the workspace and `--keep-log` copies one.
+
+### Fixes
+
+- Regenerating a patch body in `resolve`, `import --continue` and `rebase` keeps the patch's deletions, and writes only that patch's own work where other patches change the same file.
+- `re-export` puts an edit to a file several patches change into the last selected patch and adjusts the later patches so they still apply; a patch whose files hold no edit keeps its body byte for byte.
+- Resuming an import no longer replaces files of the patches before the failed one, and an import refuses a queue that changed since the paused run.
+- Engine writes of import, discard, reset and rebase happen in one transaction, so an error, a signal or a crash leaves the old state or the new one. Undoing a journal no longer writes through symlinks.
+- `workspace repair` and `workspace add --from` carry or reset the materialization ledger with the engine, so a repaired or cloned workspace never skips a write.
+- The build baseline is captured before the build runs, so an edit made during a build is not recorded as built.
+- Patch bodies are byte-exact on every host: files that are not valid UTF-8 are written as binary sections, Latin-1 and CRLF patch files round-trip, and git's C-quoted paths are read correctly.
+- A crash, a hang, a cut-off suite or a file that never started or finished never reads as a test pass, whatever mach's exit code or summary says.
+- `jar.mn` entries inserted after a flagged entry keep the surrounding indentation, test manifests are recognised by name and by the `moz.build` that lists them, and conditional `moz.build` lists are edited in place.
+- Lint no longer reports false findings on real fork code in the JavaScript and CSS rules; one parser setup serves both languages.
+
+### Docs
+
+- New `docs/getting-started.md`, `source-workflow.md`, `workspaces.md`, `quality.md`, `gate.md`, `authoring.md` and `migrating.md`. `authored-sources.md`, `jobs-and-slots.md`, `proof.md`, `verification-trees.md` and `run-logs.md` are removed. The process lifecycle for contributors is `contributing/lifecycle.md`.
+
+## 0.56.0
+
+### Source mode
+
+A second workflow, enabled by a `sources` block in `fireforge.json`. Owned files are ordinary tracked source, edited in any checkout or `git worktree`. Patches become generated review artifacts, and builds and tests run as jobs in private slots. A queue project becomes a source-mode project only through `authored migrate`. The queue workflow stays supported and frozen apart from fixes. Direct `export`, `import`, `build`, `test`, `run` and the other legacy commands refuse in a source-mode project, each naming the command that does its work there (`run` → `job run --run`), or saying that none exists.
+
+- `authored capture` takes what a commit of the checkout would hold. Ignored files are left out, ignored files under `src` are refused by name, and changed tracked files outside the selection are refused unless `--allow-dirty-root`. Snapshots are immutable Git trees whose identity has no host, path or tool version in it, and the editing checkout's index and HEAD never move.
+- `authored override` declares a first upstream edit (`--component` and `--classification` have defaults). `authored restore-upstream` and `authored override --delete` refuse to lose uncommitted edits without `--discard`. `authored prune` releases old retained snapshots, newest kept by ref age (the reflog dates a packed ref), from a linked worktree too; a snapshot whose age cannot be read is never released and is listed as `undated`.
+- Plain `git merge`, `rebase` and `cherry-pick` merge two first touches of one upstream file against its pristine blob through a merge driver, installed by `authored override` or `authored merge-install`. The pristine blob stands in only when the ancestor commit lacks the path, taking that commit from Git's `%S` label or, on Git before 2.44, from the merge, rebase or multi-commit cherry-pick in progress; a committed empty ancestor, several merge bases or an ancestor it cannot identify (on Git before 2.44, a single-commit cherry-pick or revert) leave Git's conflict. Authored merges and `authored refresh` work with Git before 2.44, whose `merge-file` has no `--diff-algorithm`.
+- `authored lint`, `typecheck` and `verify` give static feedback from a private snapshot view with no slot, job or namespace. `lint`, `typecheck`, `verify` and `status` use the same path in an editing checkout. A bare `typecheck` there runs strict source typing and leaves `typecheck.projects` to `job run --check`, so a green bare `typecheck` is narrower than a job's. Strict typing covers created and undeclared generated files, not upstream overrides.
+- `authored pristine fetch` creates a donor outside the checkout from a repository or from the pinned archive, with the same commit on every host, on a queue project too. An archive import holds everything the archive holds and refuses otherwise.
+- `authored migrate --verify` proves an overlay reconstructs its queue before publishing it, leaves nothing behind on failure, and writes `fireforge.fragment.json` and `src/.gitattributes`. The pin defaults to an archive donor's commit, then the recorded base commit, and `pinReproducible` says whether another host can rebuild the donor.
+- `authored export-queue --snapshot --out` writes a patch queue that `fireforge import` replays byte for byte, with a replay proof before it publishes. Each upstream component is one `001-` patch; created files follow as `002-` patches grouped by the new `fireforge.json#exportQueue.groups` globs, then by directory within `exportQueue.maxGroupBytes` (1 MiB). An edit to one file changes one patch, a new group renames nothing, and `patches.json` names the snapshot once as `source.snapshot`. `authored refresh` writes conflict files and records them as `conflictFiles`.
+- An ADR's `allowed.files` may list created files. `doctor` and the missing-engine remedies understand a checkout with no `engine/`, and static commands use the host's template as donor.
+- Path-valued output options (`build --keep-log`, `lint --report`, `test --perf-samples`, `test --profile-file`, `--map-out`, `--declarations-out`) cannot write into a slot.
+- Exporting a pristine tree streams `git archive` into `tar` and verifies every file, about 25 times faster on a 5,000-file tree.
+- In a source-mode checkout, `token coverage`, `furnace diff` and `furnace validate` refuse and name `job run --check` rather than judging the pristine donor in `engine/`, and `doctor` leaves out the engine branch, baseline, working-tree, mach, Watchman, engine ESLint and Furnace engine-state rows, so it neither fails the donor nor suggests repairs source mode refuses. `docs/authored-sources.md` lists the source-mode equivalent of every refused command.
+- An interrupted materialization recovers when a path turned from a file into a directory, or back, between the engine writes and the ledger.
+
+### Host setup, jobs and slots
+
+- `fireforge host init --slots N --from-engine <engine>` readies a machine: coordinator, frozen toolchain, slots and their qualification. It can be rerun, never edits a project file, and prints the mozconfig change a first run needs (`--enable-bootstrap` to `--disable-bootstrap`). `--slots 0` sets up the coordinator alone. `--cpu`, `--memory`, `--max-slots`, `--browsers`, `--cache <target>=<path>` and `--release-secrets <directory>` state host facts; capacity otherwise comes from the host. Under `--json` it writes one document and an error envelope when blocked.
+- `fireforge job run [--check] [--build ui|full|none] [--test <path>...] [--slot auto]` captures the checkout, runs it in a slot, waits and prints one verdict line. With no flags it means `--check`; `--test` implies a UI build. On a host with no build it refuses and exits 1, naming `job run --build full` and `job run --build full --test <path>`. Any other job nothing can run is refused at submit with the command to run. Further flags: `--headed`, `--no-shard`, `--standalone`, `--env`, `--upload-dir`, `--mach-arg`, `--keep-awake`, `--no-keep-awake`, `--hold-front`, `--throttle`, `--release`, `--path`, `--owner`, `--timeout`.
+- Jobs survive the caller. The supervisor acknowledges a submit only after a durable journal write, runs each job in its own process group with CPU, memory, build, browser and display admission, and seals receipts atomically. Admission is work-conserving, and a waiting job reports why in `blockedBy`, including quarantined slots and the restore that clears them. A build gets 75% of the CPU budget as `-j`.
+- A red, refused or cancelled job returns its slot to the pool, audited on next use. Quarantine is for uncertain process ownership, a failed audit, an unrestored control or an interrupted prepare, and a process that outlives its phase keeps the slot locked until its quarantine is on disk. `slot restore <name>` resets a slot to pristine plus its snapshot under its own lock, keeps the objdir and costs a full build. `job host-clear` clears host quarantine after a census; `--forget-group <group>` clears a group whose number now belongs to something else.
+- A cancel or deadline keeps signalling until the process is gone; preparation and sealing have a 30-minute deadline. A damaged journal row moves to `journal.damaged.jsonl` without stopping the host, and a supervisor that cannot start says why at once. One still running with no election after 30 seconds, as a process held back by macOS privacy controls is, is stopped, and `Coordinator did not start` names it, in the error and in `supervisor.log`, with the folder that needs access.
+- A build that can touch compiled output clears the full-build anchor before it launches. A trusted build is bound to a stat signature of its package, checked at launch and seal; a package that moved costs the slot its anchor. A process with a working directory or open file in a slot is found at seal and admission audit.
+- Slots are `cp -c -R -p` clones of a per-pin pristine template and take minutes. `slot create --from <built-slot>` clones source and objdir together and keeps the anchor when the toolchain matches. `slots.dependencyCaches` declares dependency trees beyond the root `node_modules` (including `engine/node_modules`); each installed tree is also stored per lockfile in `<namespace>/dependency-trees/` (the four most recent per target), and a job whose lockfile differs from its slot's restores the tree for its own lockfile before it runs, so one checkout's `slot refresh-deps` never breaks another checkout's queued jobs; it refuses, naming `slot refresh-deps`, only when no slot was ever given that lockfile. A target has to be a canonical path owning nothing of a slot's runtime or engine source, inside `engine/` only a `node_modules` upstream does not track, and `refresh-deps` deletes only its own targets. A tree with npm's install record is held to an npm lockfile whatever its directory is called; any other tree is identified by its bytes, and saying so is part of installing it. A declared tree's `.bin` links resolve inside that tree. A job leaves `AS` unset when the deriving engine's assembler is its C compiler, so configure derives it from the frozen `CC` with its SDK and target flags. A slot's package signature ignores the `.purgecaches` marker the browser removes at startup. `slot remove`, `slot list`, `slot audit`, `slot prepare`, `slot qualify-native` complete the set.
+- The toolchain is derived from an engine's configure output, frozen under `~/.fireforge/toolchains/<digest>/` and recorded in the namespace. Per-job checks compare a stat signature; bytes are read at qualification and at a final gate. The compiled anchor binds only native tools and the Mach recipe. `slot qualify-native` runs real `mach configure` as an ordinary job. `MACOS_SDK_DIR` is exported and the generated mozconfig states `--with-onnx-runtime` through a variable, so it holds no host path; a configure that lost what the deriving engine selected is refused.
+- `job run --release` builds `package --recipe release` from `build.release` (a captured overlay and declared secrets) in its own object directory, emptied first so every release is built from clean, leaving the development build alone. `build.release.outputs` lists paths in that object directory (`dist/*.app`, `dist/*.dmg`, `dist/host/bin/mar`), which the job copies to its output directory beside `release.json`; a declared output the build did not produce reads red. That directory counts toward storage: a release with no room for it above the disk floor is refused at submit, and its size is recorded in the slot's reservation.
+- A slot whose source declares `build.release` qualifies Mach's `taskgraph` site beside `mach`, `common` and `build`, since `mach package` resolves its DMG tools through `mach taskgraph`, which provisions that site with hash-pinned pip. A native step runs only on the recorded sites: a site nobody qualified reads red by name, and a source whose site roster differs from the slot's record is refused before the job runs, naming `slot qualify-native <name>`. Qualification provisions afresh a site it did not record and removes one the source no longer declares. The compiled anchor does not bind the site, so requalifying keeps the full-build anchor.
+- A step with a window waits with `blockedBy: display: <reason>` while no display is active: graphics off, every display asleep, or a closed lid with no external display. A docked laptop with its lid closed runs them. A supervisor outside the login session refuses them at submit and holds a recovered one with the same `blockedBy`. `holdFront` and `--hold-front` keep the phase's browser frontmost and read red if that could not be confirmed. `throttle: background | utility` runs a test under a fixed `taskpolicy` clamp.
+- `check.extraSteps[].footprint` declares a step static so `check` stays parallel. `$FIREFORGE_CAPTURED_FILES` lists captured files for project checks.
+- `job wait`, `job status` and `job run` exit by the job's state: 16 failed, 17 cancelled or interrupted (including an executor killed from outside), 18 wait timeout. A red's reason carries the step's last complaint. Refusals carry the codes `unknown-job`, `ambiguous-job`, `unknown-slot`, `invalid-log-range`, `job-cannot-run` and `executor-mismatch`, with the next action in the text. A flag value that is not a whole number is exit 8 everywhere.
+- `job`, `slot`, `host`, `authored` and `prove` share one output rule: text by default, and `--json` writes one document carrying `schemaVersion`. A queue project is told to migrate before any of them captures source. `job list` and `job cancel` work by ID for any job. Reads never start a supervisor.
+- The supervisor is a detached child of the first client that needs one, inheriting its login session and macOS privacy grants. It and its jobs do not inherit a client's environment or working directory (it runs in the namespace, not in a removable worktree or a privacy-watched folder), and its socket does not follow a client's `TMPDIR`. Job `run` steps always use a fresh profile.
+- A step's evidence records `hostLoadPeak`, the highest one-minute load average while it ran, on a red step too; no identity or proof reads it. A failed job's verdict line shows it as `host-load-peak=`, and a test step's reason ends with `(started=<n>/<m> first-unstarted=<path>)` when its verdict says where the run stopped.
+- A quiet phase starts only once the host's one-minute load is below the quiet limit (`host init --quiet-load <n>`, by default the CPU capacity), waiting as `blockedBy: host-load: ...` and ending `interrupted` if its step deadline passes first. A quiet step that goes red while its load peak, less its own admitted CPU, reached the limit ends `interrupted`, with no verdict against the step; a pass under load stands. Quiet applies per step: a `--perf-samples` test step or a request that sets `quiet` itself runs alone, while beside any other quiet step a static check (`check`, `typecheck`, `lint`, `verify`, `status`) that claims no build, browser or display may start as long as the load, with its CPU, stays under the limit. When a quiet step ends, jobs that waited are admitted before the job's next quiet step drains the host again. A job waiting on a quiet phase names the holding job, its step and how long it has held the host.
+- A test or run step records what changed on the host under it as `hostState` (`networkLost`, and on macOS `lidClosed`, `displaySlept` and, for a step with a window, `input`), each the seconds into the step it was first seen; no identity or proof reads it. A failed or interrupted job's verdict line shows it as `host-state=<entry>@<s>,…`. A tunnel interface's address does not count as a network. A red step ends `interrupted` instead when the network went away, when the lid closed or the display slept under a quiet step, or when keyboard or pointer input reached a step with a window; a pass stands.
+- `fireforge host upgrade [--from <package>] [--previous]` pins one FireForge build per host: it is copied into the namespace with its production dependencies, run once to take its executor fingerprint, checked byte for byte before every supervisor start, and kept with the previous build for rollback. Every supervisor runs the pinned build whichever checkout starts it, `prove` measures evidence against it, and checkouts of other builds submit normally with a one-line note. A host with no pinned build runs the supervisor from the starting client's package. A submit refuses (`executor-mismatch`, exit 1, naming both builds and `host upgrade`) when the client speaks another coordinator protocol than the pinned build, or, on a host with no pinned build, when the running supervisor was started from another build. Jobs submitted while a host switches builds wait with `blockedBy: Waiting for the host to switch to FireForge <version>` until the old supervisor goes idle and starts the pinned one. The endpoint records the supervisor's executor digest, package, version and protocol. Reads, waits and cancellation work across builds.
+- A run or test option that names a file the step writes (`--capture-console`, `--screenshot`, `--keep-log`, `--coverage`, `--pgid-file`, `--perf-samples`) takes `{artifacts}/<path>`, the step's output directory.
+- `job watch` is the source-mode `watch`: on every save that changes what a capture holds, it captures, submits the job `job run` would with the same flags (`--build ui|full|none`, `--test`, `--check`, `--headed`, `--repeat`, `--shuffle`, `--slot`, `--path`, `--debounce <ms>`) and prints its verdict line, on one kept slot so the object directory stays warm. A newer change cancels the running job (`--no-supersede` lets it finish), saves in between become one pending capture, and an unchanged snapshot submits nothing. It uses Watchman per captured directory when it answers and Node's recursive `fs.watch` otherwise; gitignored files, editor temporaries and `engine/` never start a capture. Ctrl-C cancels the running job and exits with the code of the last job that ran to its own end. Watch jobs are ordinary jobs, and their evidence counts.
+- A harness helper that outlives its harness in its own session, such as xpcshell's `moz-http2.js` after "no tests to run", is stopped with the job when its command line names the slot. A process carrying the phase's marker with no foothold in the slot is reported as detached; one holding the slot still quarantines it. `fireforge test` refuses a path that is not a test (`note=not-a-test`) before any build or harness starts.
+- A process killed at a phase's end gets up to 2 seconds to leave the process table before its slot is quarantined, so a cancel on a loaded host does not quarantine a clean slot.
+- A slot refused as still in use names the holding process's command, its parent and the path it holds.
+- `slot restore --stop-orphans` stops the orphaned processes holding a slot (no running job and no interactive shell above them) with SIGTERM, then SIGKILL, printing each pid and command, and refuses by name while any other holder remains; a plain restore refused over orphans names the flag. A job refused for want of a build that exists only in a quarantined slot names that slot, its reason and `slot restore <name>`.
+- A slot remembers each self-detached process a phase left running (by pid and birth, at most 32, in `detached.json`), and every later admission audit and `slot audit` checks them again: one that has since taken a working directory or open file in the slot, or names it in its command line, quarantines it with `process <pid> (<command>) left detached by job <id>, now holds <path>`; one that has exited or whose pid now belongs to another process is forgotten. `slot restore` clears the record, and clones and replicas do not inherit it.
+- When jobs queue for the one slot holding the build they need, the supervisor copies that build into an idle slot no queued job needs (both slots locked, only with free disk above twice the object directory) and relocates it with a `qualify-native` job, so two slots serve. `host init --replicate-depth <n>` sets how many waiting jobs per holding slot trigger it (default 2, `0` off). `blockedBy` and `slot list` show a replication in progress; a failed one leaves the destination `needs=full-build` and never touches the source. `slot qualify-native` relocates an object directory copied in from another slot even when the slot's Mach sites are already qualified.
+- A job still running carries `progress`: its current step and label (prove's obligation ID), the time in that step and overall, and how each finished step ended. `job status`, `job list` and `prove status` show it, and a step takes an optional display-only `label`.
+- While `job run`, `job wait`, `job watch`, `prove` and `prove run --wait` wait, they print a line to stderr when the job enters a step and when a step ends, with nothing repeated and nothing printed under `--json`.
+- `job cancel` records who cancelled (owner, cwd, pid, time) as `cancelledBy`, shown as `cancelled-by=` on the verdict line, and cancelling another owner's job is refused without `--force`. The default job owner is `<worktree>@<branch>` (`<worktree>@<short commit>` when detached, `user@host` outside Git); `FIREFORGE_OWNER` and `--owner` win.
+- Each step samples free disk on the namespace and slot volumes. A failed, interrupted or cancelled job whose step saw free space fall below the low-disk threshold (the larger of `host init --disk-low-gib`, default 10, and 3% of the volume) carries `hostDisk`, shows `host-disk-low=<GiB>@<s>`, and says in its reason that the red may come from disk pressure, naming what slots and artifacts hold. `fireforge host status` reports free disk against that threshold, the space slots and artifacts use, and the pinned, previous and running FireForge builds.
+- Job artifacts are bounded by `host init --artifact-max-gib` (default 10) and `--artifact-max-age-days` (default 14), removing only finished jobs' artifacts and never the newest 3 per owner. The supervisor prunes on start and hourly while idle, and `fireforge host prune [--max-gib] [--max-age-days] [--dry-run]` prunes on demand and prints what it freed.
+- A window step waiting for the host's one display says `Waiting for the display, held by job <id> step <n>`. On macOS a window step records `foreground-lost@<s>` in `host-state` when another application was in front of its own browser, read with `lsappinfo` (annotation only; unknown on other platforms), and a harness can read `FIREFORGE_DISPLAY_LEASE` and `FIREFORGE_DISPLAY_STATE`, a JSON file with the lease and whether the foreground is its own.
+- `job run --test` takes `--repeat <n>`, `--shuffle <seed>`, `--coverage`, `--perf-samples`, `--keep-log` and `--profile-file`; a file a step writes lands in the job's artifacts, and the command prints where.
+- `job run --run [--build ui|full|none] [--profile <dir>] [-- <browser args>]` opens the browser on this checkout from a slot, streams its output until the window closes, and cancels the job on Ctrl-C. `--profile` keeps a profile between interactive runs; it must be absolute and outside every slot, the coordinator namespace and tracked source, and every other run starts from a fresh profile. A job with an interactive run is never proof evidence.
+- `job status`, `wait`, `logs` and `cancel` take a unique prefix of a job ID of at least 8 hex characters; an ambiguous prefix is refused, listing the IDs it matches.
+- `job logs --step <n>` reads one step's output, numbered from 0 as in the job's artifacts, with offsets from that step's start. Asked for no range, a failed job's log opens on its red step (the last red one when the job went on past reds), or that step's last chunk, with a note naming the step and how to read the others. Each step's output starts with a marker line naming its index.
+- `slot create` qualifies the new slot's native sites, as `host init` does, when the host has a toolchain; a red qualification fails the command. When it cannot qualify, or under `--no-qualify`, it warns that native jobs refuse on the slot, says why and names `slot qualify-native <name>`.
+- `slot refresh-deps` reads only `fireforge.json` and the declared lockfiles, which must be committed; other uncommitted paths are taken at their committed bytes. It serves slots on another pin than the checkout's, reading a lockfile the pin itself holds at the slot's pin.
+- A job's `--jobs`/`-j` value (`--jobs N`, `--jobs=N`, `-j N`, `-jN`) is read once: what the job reserves is what the command runs with, a value above the host's CPUs or above 1 on a test step is refused, and giving it twice is refused at submit.
+- A slot's package signature covers the targets of links in the package that point into the objdir or outside the slot, so a changed target is caught without relinking; links into the engine source are left to the slot audit.
+- A distribution Python under `/usr` makes the toolchain cover the interpreter and its `sys.path` directories, never the whole prefix. On Linux the process census runs `ps` in a form procps accepts, so jobs end with a clean census instead of quarantining their slot, and the slot-user audit and the end-of-job foothold check read procfs, so a host without `lsof` (a minimal distribution or a container) can run jobs.
+- The memory a slot reserves is checked against the coordinator's recorded memory (`host init --memory`, by default 80% of physical memory). A cached tool digest is reused only once the file's stamp has settled, so two writes within one coarse clock tick are not read as one. A Prettier or ESLint config inside a slot's `.fireforge` directory is refused even when the slot lives under the system temporary directory.
+
+### Proof
+
+- `fireforge prove --tier task|gate [--base <ref>]` captures, plans, runs what has no evidence yet and reports (`--no-wait` returns once submitted). `prove status` is the same plan as a query, and `prove plan` shows the job it would submit. `prove --slot <name>` (and `prove plan --slot`) composes its jobs for that slot and runs them there, as `job run --slot` does.
+- A plan records its base's tree. The default base is the merge-base with the main branch (a gate defaults to `refs/fireforge/verified` when it is an ancestor), and completion recomputes the plan, so a narrower `--base` cannot claim it.
+- Task tier: scoped static, a build by route, changed tests and direct consumers. Gate tier: lanes, stress, controls, runs, acceptance, `proof.gate.mode` and a final check, declared in the validated `proof` block. A control with `always: true` applies to every gate, including a candidate with no difference from its base. A lane or run can declare `validate`, a closed command (`node <script>` or a captured script) run after the harness in the same phase, such as one judging a run's `--capture-console {artifacts}/console.txt`. `prove --tier gate --lane <id>` runs one declared obligation and the build it needs, with the evidence a full gate run of it leaves.
+- Evidence is keyed by source, step fingerprint and build identity across jobs and slots, so one flake reruns only its step. A proof is compared with the tools as they are now: at task tier by kind (an ESLint upgrade re-runs lint and leaves browser tests standing), at a gate under one identity.
+- A candidate answers to the union of its base's `proof` and its own: additions apply at once, removals apply until the removing commit is itself verified, and a changed `proof`, `check`, `patchLint`, `patchPolicy` or `typecheck` section adds `accept:proof-config`, as does a changed file the gate names as a judge: a validator's script, a control's diff, a file an extra check step's command names, or a type shim. What those files import is not followed. `proof.mainBranch` comes from history.
+- `prove accept` and `prove waive` record a person's decision bound to the source and tier. `acceptance[].evidence` makes `accept` refuse until those obligations pass on this source. `waive` needs `--allow-machine` and refuses an acceptance; a gate's claim and `publish` refuse waived obligations without `--allow-waived`. Verdict `complete-with-waivers`.
+- `prove publish` moves `refs/fireforge/verified` by compare-and-swap when the commit's exact tree has complete evidence, and records waivers at `refs/fireforge/verified-waivers/<commit>`; `--allow-rewrite` recovers from rewritten history.
+- A gate candidate that differs from its verified base only in documents at the project root (none-route paths, outside the source metadata, the declared inputs, `package.json` and its lockfile, with nothing that decides the gate changed) carries the base's evidence to every obligation but `check`, which still runs on the candidate. Carried obligations print `carried-from=<commit>`, `publish` takes them and records the origin at `refs/fireforge/verified-carries/<commit>`, and a chain of documents commits carries from that origin. A named `--base` and a waived base carry nothing; a waiver never carries. When the verified base is not documents-only from the candidate, the carry starts at the nearest first-parent ancestor (within 50) whose own gate evidence is complete, clean and current, published or not, so a peer's ledger commit on top of a finished gate costs one check.
+- An override record that only rebased onto a new pin (its `base.commit`, `base.pin` or `base.blob` moved, with the same bytes under `src/` and the same kind, classification, component, ADR and mode) does not make its path changed, so a gate after `authored refresh` does not refuse overridden upstream `test_*.html` files with `proof-unclassified-test`. The pin change still forces the full build and the lanes.
+- A deleted test is listed by both tiers with the lanes that held it. A changed test nothing would run refuses, a control must touch what changed, and more direct consumers than `proof.consumerLimit` refuses by name. `check.maxWarnings.lint` is the one line on lint warnings for `prove`, `check` and `authored lint`.
+- A gate runs `check` first, before the build, so a static red costs no build or lane, and its job goes on past a red step (the request's `continueOnFailure`), so one run gives every obligation a verdict. After a red build, the lanes and runs that need its package are `blocked` (a new obligation state, rerun by the next `prove`), not red. Each red is audited as the next job's admission would audit it, and one that leaves the slot untrusted still ends the job. The job ends `failed` with each red and blocked step in `stepVerdicts`, and every step that passed is sealed as evidence.
+- A changed component test is planned at the engine path Furnace deploys it to, so it needs an obligation that runs that path; one Furnace deploys nowhere refuses with `proof-unclassified-test`.
+- A changed file a manifest lists under `support-files`, `head` or `tail` (globs, `../`, engine-root paths, `[DEFAULT]` or per test, `.toml` and `.ini`) selects that manifest's tests, and a gate counts it as owning the lanes that hold them, so a committed fixture is no longer `proof-unclassified-test`. `prove --test` refuses a path that is not a test, test directory or manifest (`proof-not-a-test`), naming the tests that read a support file.
+- A negative control matches an xpcshell red by its task name or its `Assert` message, with or without the `- <actual> <op> <expected>` details. A control that reddened elsewhere names every label it saw, and the control step's verdict uses the same matching as the proof decision.
+- `prove` and `prove status` attribute each red to the commits between the plan's base and `HEAD` that touched what it reads (failing tests from the results file; lint, type and check files from the step log), each marked as on main or this change; with none, the red reads as uncommitted, older than the range, or not located to a file. A gate comparing with the verified ref says up front when main has commits since that ref whose reds may not be yours. JSON carries `range` and `attribution`.
+- `typecheck`, checkJs and `typecheck --explain` take the TypeScript compiler API from `typescript` when it carries one and from `@typescript/typescript6` otherwise, so a project on TypeScript 7, whose `typescript` ships no compiler API, keeps them by installing that package beside it.
+- Task-tier `prove` adds a `types` obligation when a changed JS or TS file, deleted ones included, falls inside a `typecheck.projects` jsconfig: it runs `typecheck --project <jsconfig>` for those projects, the pass the gate's `check` runs, and every project after a full-build route or a changed jsconfig or type shim. `typecheck --project` can be repeated. `authored typecheck` says on stderr when such a project holds a file in scope that it checks authored sources only, naming what predicts the gate's pass.
+- `prove --sample <n>` runs a deterministic sample of task-tier consumers over `proof.consumerLimit`: every consumer beside the change, one per lane, then one per lane or directory in turn, seeded by the changed paths so a rerun reuses its evidence. The report says `sampled N of M consumers` and lists what did not run, the verdict is `sampled`, and a sample never stands for a gate (`proof-sample-gate`). `proof-consumer-limit` names `--sample`.
+- `prove` (every subcommand), `job run`, `job watch` and `host init` take `--allow-dirty-root`, as `authored` and `feedback` do, so the capture refusal names a flag the command accepts.
+
+### Breaking changes
+
+- **Config.** `fireforge.json` refuses unknown keys at the root and in every block, with a did-you-mean hint. `binaryName` must match `^[a-z][a-z0-9-]*$`, and `name` and `vendor` reject control characters. `fireforge config` validates the whole document on every write, and `--force` no longer allows unknown keys. `furnace.json` refuses absolute `ftlBasePath`, `scanPaths`, `typecheckJsconfig`, `typecheckTagMap` and override `basePath`.
+- **Tag map.** The generated tag map types each widget as `HTMLElement & import(...)`, so `furnace validate --max-warnings 0` reports `tag-map-drift` after upgrading. Run `fireforge furnace types` and commit the regenerated file.
+- **Builds and tests without a record.** A build-less `test` with no recorded build refuses (`note=no-build-baseline`); `--allow-stale-build` proceeds and stamps `baseline=none`. A record whose commit is gone, as after `download --force`, counts as no record: `build` and `test --build` print a notice and run a full build. A pre-test build whose record cannot be written stops the run (`note=baseline-write-failed`). A checkout built outside FireForge needs the flag.
+- **`package`.** It no longer applies Furnace or regenerates the mozconfig. It refuses a control-built binary outright, and refuses a build that does not match the tree unless `--allow-stale-build` is passed. `run` warns about both.
+- **Negative controls.** `--negative-control` dispatches the selection unmutated first. `control=caught` requires that baseline to be green; a red one reports `control=inconclusive note=baseline-red`. A compiled control costs a second build. In `--results`, the baseline moves to `controlBaseline`, and `files` and `unfinished` hold `run >= 1` only.
+- **Verdict classifier.** A non-zero harness exit after a green summary passes only with recognized noise, whatever the request names. An exit-0 run must show a positive check count and a completed suite, every started test ended, and with a raw log every requested file ended with no unexpected or unfinished test (`unfinished=<n>` on the verdict line). An exit-0 run with no count or summary is `reason=crash` and is retried, so a negative control reads it as inconclusive. A summary counting zero checks is `no-tests`. Exit 9 and 15 read as signals. Harness markers count only where the harness writes them, so a test's own output cannot satisfy or fail them; a browser run's `TEST-START | Shutdown` is not an unfinished test.
+- **`test.reapOrphans`.** `"reap"` and `--reap-orphans` terminate only helpers a killed FireForge run recorded in `.fireforge/harness-helpers/`, once that run is gone; they no longer signal what the preflight census finds. Census survivors are reported and left alone. The new value `"owned"`, which source mode requires, behaves the same.
+- **Typing.** `typecheck` and per-patch checkJs report TS2305 and TS2306 for imports that resolve to patch-owned or `paths`-mapped files, so a renamed or removed export fails in its importers. This can surface errors that were hidden. `typecheck --no-cache` is accepted and ignored, and `typecheck --source-files` refuses an entry that matches nothing. `lint --per-patch` fails when no patch could be linted.
+- **Locks and Git.** `NODE_ENV=test` or `VITEST` in the environment no longer disables the engine session lock in a real CLI. Every Git call FireForge makes ignores global and system Git config, global and XDG excludes, hooks and signing, and pins diff settings, so the engine baseline indexes all upstream files and generated patches are byte-stable whatever your Git config says.
+- **Public API.** `src/index.ts` exports no job, slot, proof or authored API; the CLI is the interface. The package ships only the declarations `index.d.ts` reaches.
+
+### Test harness
+
+- `fireforge test` walks the engine once per lock hold, so a peer's edit the runtime already serves no longer voids a coverage claim. A stale run is refused before it waits out a browser or port.
+- Verdicts stamp `display=`, `power-source=` and `host-slept=true`, and report the worst host across dispatches. `check --only/--skip` adds `selection=narrowed`. Flags that only shape a build refuse before the lock.
+- Stale-compiled detection anchors on libxul and covers assembly, table and generator inputs.
+- `test --coverage <dir>` collects per-process JavaScript LCOV with startup and flush receipts and a bounded browser shutdown barrier. Missing or empty coverage vetoes a green result.
+- A harness startup timeout lists the port and browser-wait lines printed before it. `test --doctor` probes its own port and rejects a listener outside the browser it launched. `--kill-stale-marionette` only touches an orphaned browser from this checkout.
+- The post-build audit walks `dist/` once and skips paths unchanged since the previous build. `fireforge tree create` clones no longer leave every index entry stat-dirty. `run --temp-profile` prints its profile path.
+- Verdicts stamp `host-load-peak=<n>` and `host-load-peak-at=<s>`: the one-minute load average is sampled every 30 s while a suite runs, so a rise between its edges shows, and a peak of at least 4 sets `host-cpu-warning=true`. A sharded or repeated run reports its highest peak. Absent on Windows.
+- A request naming a directory or manifest is counted against the tests the raw log's `suite_start` records announced, so a harness timeout that leaves files unjudged reports `started=<n>/<m> first-unstarted=<path> started-source=raw` instead of a bare `reason=test-failures`. Skip-if files count as accounted for; `--start-at` and `--end-at` turn the count off.
+
+### Processes and locks
+
+- Process ownership samples one asynchronous `ps` snapshot per tick (procfs on Linux), so a job's tracker never blocks the supervisor.
+- `exec` keeps a clean exit 0 when a background process holds a pipe and reports `pipesHeld`. A timeout gives SIGTERM its grace before SIGKILL, so `git` can release `index.lock`.
+- A self-detached descendant is terminated only when its command line names a directory the run owns, and the job supervisor is never terminated by a run.
+- A lock stays held while a process group started by a SIGKILLed holder still runs. Only the head of the waiter queue reaps, an unreadable owner record is never reaped, and on macOS a reused holder PID is detected by birth. Slot and election locks are numbered claims, so concurrent takeover of a dead holder cannot leave two holders.
+- `tree exec` forwards SIGTERM and SIGHUP to its child; `tree create` skips credential-shaped root entries.
+
+### Patch queue
+
+- `discard` accepts several paths from one status scan, prunes directories it empties, and refuses when a manifest row omits a file its patch touches. `discard`, `reset`, `rebase` and `rebase --abort` save a recovery snapshot under `refs/fireforge/recovery/`.
+- `import`, `resolve`, `reset`, `discard`, `export-all`, `rebase`, `register`, `wire` and `token add` hold the engine-session lock (shared for `--dry-run`) and honour `--wait-lock`; in a source-mode project `register`, `wire` and `token add` write the source tree and take none.
+- `download --force` downloads, extracts and indexes the new tree beside `engine/`, then takes the engine-session lock to swap it in, refusing when `engine/` changed since you confirmed. `download` honours `--wait-lock`.
+- `resolve` and `rebase --continue` no longer write a cumulative diff for a patch sharing a file with another patch.
+- `patch move-files <from> <to>` drops forward-import declarations the move makes unused. `re-export --adjacent-ignore-from <file>`.
+- Export recovery rereads state under its lock and restores renumbered filenames before the original manifest. Hunk parks accept plain unified diffs and refuse malformed selections before mutation.
+- Narrowed, empty or skipped `check` runs cannot discharge a full-gate proof.
+
+### Furnace
+
+- New `furnace types [--check]` writes the `typecheckJsconfig` paths and the `typecheckTagMap` declaration, and works in a source-mode editing checkout, where a configured `engine/<path>` is written to `<sources.root>/<path>`. In source mode `furnace validate` reports `jsconfig-paths-drift` and `tag-map-drift` as errors against the committed copies, and `typecheck` in a job leaves them as they are, so a stale committed copy fails the gate. Both findings name `furnace types` rather than `furnace deploy`.
+- `furnace deploy --owner` is repeatable. A multi-component deploy rolls back each failing component and never reverts one already committed; a killed mutation leaves a recovery marker that the next mutation or `doctor` turns into `pendingRepair`.
+- `test --build --furnace-apply reached` counts components whose engine copy was erased and pulls in stale `composes` dependencies. A peer's mid-run edit to a component the run did not deploy is a warning.
+- `furnace rename` leaves an existing test file of the new name in place, and `furnace chrome-doc` does not treat a commented-out jar line as registered. Component removal preserves unrelated shared test content and registrations.
+
+### Lint, types and tokens
+
+- `token lint` in source mode judges every CSS file of the captured snapshot (created, overridden and generated), as source-mode `lint` does.
+- `test-needs-assertion` detects real assertion calls through the AST. Per-patch prettier covers only the patch's own modules. Authored `lint` rejects `--per-patch`, `--report` and `--notices` and refuses a path that matches nothing.
+- `lint --since` refuses a revision that names no commit in `engine/` (exit 8) and fails when Git cannot list the changes (exit 4), instead of tagging every finding cumulative so `--only-introduced` passed.
+- A checkJs patch whose `paths` target is too large to fingerprint lints without the cache instead of replaying an earlier verdict.
+- Per-patch lint and `fireforge check` no longer crash on a real `node_modules`: installed trees are identified by path and bytes, and read again only when their stat signature moves. A tools-identity failure misses the cache with a warning. A final gate still reads every byte.
+- `register` accepts `EXTRA_JS_MODULES.<ns>` lists, `token add` refuses values that would break the CSS, and `wire --after` matches whole names. Token-variant previews warn about later equal-specificity cascade overrides.
+- `patchLint.checkJsCompilerOptions`, `patchLint.rawColorAllowlist` and `patchPolicy.requireDescription` are documented in `docs/configuration.md`.
+
+### Other fixes
+
+- A read-only command's private Git index keeps the original's time, so a same-size edit made in the second its file was staged is no longer read as unchanged. `lint --per-patch` could report that patch's files as absent.
+- The engine guard no longer turns off because of an untracked nested repository, FIFO or socket; only a tree with no repository or commit warns and passes. An unreadable shared-lock record is no longer read as gone.
+- `readJson` keeps `constructor`, `prototype` and `__proto__` keys, and `--json` detection ignores flags after `--`.
+- `source set` clears a pinned checksum when the version or product changes.
+- Two runs started within the same millisecond write separate run logs instead of interleaving into one file.
+- `fireforge check` keeps a step's stdout only for the steps whose summary parses it, capped, instead of holding every step's whole output in memory.
+- Token variant scans blank quoted values with a linear scanner instead of a regular expression that went quadratic on a line with an unclosed quote and many escaped quotes. Every spawn wrapper passes `shell: false` explicitly, so no caller option can route its arguments through a shell.
+- CI runs the static checks, then the suite in four shards balanced by weight (files that start real jobs weigh more), and `quality (ubuntu)` merges their coverage and applies the same thresholds and per-module pins; the Ubuntu smoke leg no longer reruns that suite, and `node-floor` runs Node 22 and 24 in four shards each. The release workflow runs that pipeline before it publishes, and `prepublishOnly` (`scripts/prepublish-gate.mjs`) skips the full gate only for the commit it verified plus the version bump, running it everywhere else.
+- Docs: `docs/authored-sources.md`, `docs/jobs-and-slots.md` and `docs/proof.md` cover source mode. The lifecycle invariants moved to `contributing/lifecycle-invariants.md`.
+
+### Dependencies
+
+- magic-string 1.4.5, @types/estree 1.0.10, @types/node 26.6.6 (a development dependency: the shipped declarations need no Node types), eslint 10.14.0, eslint-plugin-jsdoc 65.4.5, knip 6.44.1, typescript-eslint 8.72.1, vite 8.3.6, vitest and @vitest/coverage-v8 5.1.0, with lockfile updates. FireForge builds and typechecks with TypeScript 7.0 (`@typescript/native`); `typescript` is `@typescript/typescript6`, the 6.0 compiler API that typescript-eslint and FireForge's own type checks run on. CodeQL actions 4.39.3.
+
 ## 0.55.0
 
 ### Test harness
@@ -260,27 +487,27 @@
 
 ### Performance
 
-- The worktree ownership scan behind `status`, `verify`, `doctor`, `import` and `discard` runs four git processes instead of one or more per managed file. On the Hominis tree (1,606 managed files) that was 1,625 spawns. `status --ownership` went from 13 to 16 s down to 5.7 s, and `verify` from 15 s to 7.6 s. Output is byte-identical to 0.47.1.
+- The worktree ownership scan behind `status`, `verify`, `doctor`, `import` and `discard` runs four git processes instead of one or more per managed file. `status --ownership` went from 13 to 16 s down to 5.7 s, and `verify` from 15 s to 7.6 s. Output is byte-identical to 0.47.1.
 - The batched untracked listing uses `ls-files -z`, so a non-ASCII name inside a collapsed directory is no longer expanded to a quoted path that names no file.
 
 ### Typecheck and checkJs
 
-- The per-test-file checkJs programs share one parse of each lib, shim and helper file per run. On the Hominis queue (467 programs) the pass went from 66 to 85 s down to 22 to 25 s, with identical findings. This speeds up `typecheck` and every `lint --per-patch`, `export` or `re-export` that misses the lint cache.
+- The per-test-file checkJs programs share one parse of each lib, shim and helper file per run. The pass went from 66 to 85 s down to 22 to 25 s, with identical findings. This speeds up `typecheck` and every `lint --per-patch`, `export` or `re-export` that misses the lint cache.
 - `fireforge typecheck` keeps incremental build info per project in `.fireforge/typecheck/`, keyed so a shim, compiler or FireForge change never replays a stale verdict. New `typecheck --no-cache` checks from scratch and writes nothing. Nothing is written under `engine/`.
-- On the Hominis tree `typecheck` went from 93.8 s to 30.2 s.
+- `typecheck` went from 93.8 s to 30.2 s.
 - For the record: the projects are not run in a worker pool. They took 6 of the 93.8 s; the per-file checkJs pass was the cost.
 
 ### Re-export
 
-- A one-patch `re-export` roots its checkJs program at the patches it re-exports, as `lint --per-patch --patches` already did, instead of type-checking the whole queue. Cross-patch imports still resolve. On Hominis a cold `re-export <patch> --dry-run` went from 76.7 s to 8.0 s.
+- A one-patch `re-export` roots its checkJs program at the patches it re-exports, as `lint --per-patch --patches` already did, instead of type-checking the whole queue. Cross-patch imports still resolve. A cold `re-export <patch> --dry-run` went from 76.7 s to 8.0 s.
 - The queue lint context parses each patch once instead of once per created file: 3 to 4.4 s down to 0.3 s on 401 patches. Shared by `lint --per-patch`, `re-export`, `export` and `typecheck`.
 - `re-export` names its lint scope before the wait and prints a line when it builds a checkJs program. The elapsed time now includes the context build.
 
 ### Patch queue and lint
 
-- New opt-in `patchLint.forwardRegistration: "extended"` widens `forward-registration` beyond test-manifest `support-files` to jar.mn lines, moz.build path tokens, test-manifest sections and `head`, and `customElements.js` chrome URLs. On the Hominis queue it finds 937 edges across 6 patches. The default (`"support-files"`) is unchanged. Each finding prints a `patch staged-dependency --add --kind registration` command, tested to quiet the queue without leaving `staged-dependency-unused` behind.
+- New opt-in `patchLint.forwardRegistration: "extended"` widens `forward-registration` beyond test-manifest `support-files` to jar.mn lines, moz.build path tokens, test-manifest sections and `head`, and `customElements.js` chrome URLs. The default (`"support-files"`) is unchanged. Each finding prints a `patch staged-dependency --add --kind registration` command, tested to quiet the queue without leaving `staged-dependency-unused` behind.
 - New public `findForwardRegistrations(patchesDir, { scope })` returns the same census as structured records.
-- New `lint --per-patch --notices summary|full`. `summary` prints one line per check instead of every NOTICE row (about 430 on a green Hominis queue). `full` stays the default and is unchanged. Errors, warnings and `--report` JSON are unaffected.
+- New `lint --per-patch --notices summary|full`. `summary` prints one line per check instead of every NOTICE row. `full` stays the default and is unchanged. Errors, warnings and `--report` JSON are unaffected.
 
 ### Programmatic API
 

package/README.md

@@ -4,14 +4,17 @@
 [![license](https://img.shields.io/npm/l/@hominis/fireforge)](LICENSE.md)
 [![node](https://img.shields.io/node/v/@hominis/fireforge)](package.json)
 
-FireForge is a CLI tool for maintaining Firefox-based browser forks. It downloads Firefoxs source code, lets you export changes as patches, helps apply them and has some neat/mad code quality enforcement, built by taking a lot of learnings from the existing Firefox source code and trying to make the process as robust as can be. Ideally, FireForge makes everything from managing custom UI components to enforcing some rudimentary typechecking much easier, but I'll be honest, there is only so much one can do, so understanding upstream is advised, especially once future updates come into the mix. ~~I cannot guarantee how reliably these will apply, but I did try to assist in that process as much as I can by learning from prior Firefox versions which had major changes made to them, though this is of course still no guarantee for future success or that the methods will remain reliable. Beware of that.~~ Edit 16.07.2026: I have now upgraded and downgraded and sidegraded, really all the graded, across all the versions in many scenarios with modifications so far removed from upstream that I think it's fair to say upgrading is fairly reliable.
+FireForge is a CLI tool for maintaining Firefox-based browser forks. It downloads Firefoxs source code, ~~lets you export changes as patches, helps apply them~~ keeps your changes as ordinary source in Git, builds and tests said changes in their own separate slots, writes patches whenever you need that feature (and still supports the old patch-based workflow) and has some neat and/or mad code quality enforcement, built by taking a lot of learnings from modifying the existing Firefox source code and trying to make the process as robust as can be. Ideally, FireForge makes everything from managing custom UI components to enforcing some rudimentary typechecking much easier, but I'll be honest, there is only so much one can do, so understanding upstream is advised, especially once future updates come into the mix. Thankfully, the Firefox team did create some great docs. ~~I cannot guarantee how reliably these will apply, but I did try to assist in that process as much as I can by learning from prior Firefox versions which had major changes made to them, though this is of course still no guarantee for future success or that the methods will remain reliable. Beware of that.~~ Edit 16.07.2026: I have now upgraded and downgraded and sidegraded, really all the graded, across all the versions in many scenarios with modifications so far removed from upstream that I think it's fair to say upgrading is fairly reliable.
 
-Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon](https://github.com/dothq/melon).
+Edit 08.11.2026: Source mode is now the standard way to use FireForge with patch-based development still being an option but not adviced. It works, is reliable and easy to understand (export diffs, apply to engine), but simply doesn't scale for parallel work. With source mode, changes now live as plain files under `src/`, every build and test runs as a job in its own cloned slot, and `fireforge prove` tells you what something still needs before it can land. Patches can still be used in conjuction with source mode, by the way, FireForge generates them from your source whenever you want an easier format to publish, hand to CI or roll back to.
+
+Original patch mode was inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon](https://github.com/dothq/melon).
 
 ## What It Does
 
-- **Patch based** Edit Firefox inside the `engine/` directory, then export changes into `.patch` files with manifest metadata.
-- **Source rebasing** Reapply your patches onto newer Firefox source trees, including ESR, Beta, and Developer Edition archives, resolve rejects and re-export the queue against the new baseline, hopefully...
+- **Source mode** Keep your changes as ordinary tracked files in Git. Edit them in any checkout or `git worktree`, run builds and tests as jobs in their own separate slots and let `prove` work out what a change still needs.
+- **Patch mode** Edit inside `engine/` and export `.patch` files with manifest metadata. In source mode the patches are generated from your source (`authored export-queue`), one per component, so you can publish a readable queue, let CI import or roll back to the queue workflow.
+- **Source rebasing** `authored refresh` three-way merges your source onto the new pin and hands you only the real conflicts. Patch mode still rebases the queue the old way.
 - **Firefox source and build helpers** Download, bootstrap, build, run, test, package, smoke-check, etc.
 - **Wiring and registration** Add chrome scripts, DOM fragments, modules, styles, tests and manifest entries through commands built by learning from existing Firefox conventions.
 - **Furnace components** Create or override `MozLitElement` widgets easily to add new or adapt existing UI components to your needs.
@@ -36,7 +39,7 @@ npm init -y
 npm install --save-dev @hominis/fireforge
 ```
 
-Then initialise and build:
+Then initialise and build once (every project starts out in patch mode, so this first `run` still opens straight from `engine/`):
 
 ```bash
 npx fireforge setup
@@ -47,9 +50,34 @@ npx fireforge build
 npx fireforge run
 ```
 
-After setup you should have a `fireforge.json`, an `engine/` directory containing Firefox source and a `patches/` directory containing the patch manifest. From there, the usual loop is to change code inside the `engine/` directory, export these changes, then verify the queue still applies cleanly.
+After setup you should have a `fireforge.json`, an `engine/` directory containing Firefox source and a `patches/` directory containing the patch manifest. That is a patch mode project, which is where every project starts. To switch it to source mode, migrate via the following commands:
+
+```bash
+npx fireforge authored migrate --out ../migration --verify
+# merge fireforge.fragment.json into fireforge.json, copy src/ and .fireforge-sources/ in, remove patches/
+npx fireforge authored merge-install
+npx fireforge host init --slots 2 --from-engine ./engine
+```
+
+## Source Mode Workflow
 
-## Regular Workflow
+The new workflow for parallel work.
+
+```bash
+npx fireforge job run --build full                                # once per fresh slot
+npx fireforge authored override browser/themes/shared/tabs.css   # first edit of an upstream file
+$EDITOR src/browser/themes/shared/tabs.css
+npx fireforge authored lint                                       # quick static feedback, no slot needed
+npx fireforge job run --test browser/themes/test/browser_tabs.js  # build what changed, run the test in a slot
+npx fireforge job watch --test <path>                             # rebuild and retest on every save
+npx fireforge job run --run                                       # open the browser on this checkout
+npx fireforge prove                                               # what this change needs, and whether it has it
+npx fireforge prove --tier gate && npx fireforge prove publish    # before you push
+```
+
+## Patch Mode Workflow
+
+The original patch-based workflow that I fell in love with but had to accept was not scalable is retained. In a source mode project its commands (`export`, `import`, `build`, `test` and friends) refuse and tell you what to use instead.
 
 ```bash
 npx fireforge status
@@ -61,13 +89,17 @@ npx fireforge build
 npx fireforge test browser/base/content/test/browser/
 ```
 
-Use `fireforge --help` for the full set of commands, and
-[`docs/patch-workflow.md`](docs/patch-workflow.md) for what the loop actually
-guarantees.
-
 ## Rebasing Firefox Source
 
-When Mozilla publishes a new Firefox source release you need to update the configured version/product, download the new source code and reapply the patches:
+When Mozilla publishes a new Firefox release, source mode fetches the new pristine tree and proposes a merge you review before adopting it:
+
+```bash
+npx fireforge authored pristine fetch --out ~/.fireforge/pristine/next --pin new-pin.json
+npx fireforge authored refresh --snapshot old.json --pristine-repository <old pristine> \
+  --new-pristine-repository ~/.fireforge/pristine/next --new-pin new-pin.json --out ../refresh
+```
+
+In patch mode you update the configured version/product, download the new source code and reapply the patches:
 
 ```bash
 npx fireforge source set --version 145.0.0esr --product firefox-esr --sha256 <archive-sha256>
@@ -79,7 +111,7 @@ If a patch fails, fix the reject inside the `engine/` directory, then run `npx f
 
 ## Furnace
 
-Furnace is our solution for UI components. It can track stock widgets, create new fork-owned widgets and override existing ones. The files still land inside the Firefox source directory and end up as part of the regular patches to export.
+Furnace is our solution for UI components. It can track stock widgets, create new fork-owned widgets and override existing ones. Component sources stay under `components/`, in source mode they are composed into each sessions engine and in patch mode they land inside the Firefox source directory and subseqeuntly are exported as part of your patches.
 
 ```bash
 npx fireforge furnace scan
@@ -90,14 +122,15 @@ npx fireforge furnace status
 npx fireforge furnace preview
 ```
 
-Use `fireforge furnace --help` for the full set of component commands, and
-[`docs/furnace.md`](docs/furnace.md) for shared CSS fragments and typed
-cross-module imports.
+In source mode `deploy` happens inside jobs and `furnace types` keeps the generated typecheck files in your checkout current. Use `fireforge furnace --help` for the full set of component commands, and [`docs/furnace.md`](docs/furnace.md) for shared CSS fragments and typed cross-module imports.
 
 ## Documentation
 
 [`docs/`](docs/README.md) holds the reference material:
 
+- [Authored sources](docs/authored-sources.md) — source mode: overrides, capture, migration, exporting a queue, refreshing the pin
+- [Jobs and slots](docs/jobs-and-slots.md) — `host init`, `job run`, slots, capacity and recovery
+- [Proof](docs/proof.md) — `prove`: obligations, evidence, accept and waive, the verified ref
 - [Patch workflow](docs/patch-workflow.md) — export, re-export, queue maintenance, per-patch lint, CI gating
 - [Testing](docs/testing.md) — `fireforge test` scope, modes, build freshness, the verdict line
 - [Furnace](docs/furnace.md) — components, shared CSS fragments, typed imports
@@ -105,7 +138,7 @@ cross-module imports.
 - [Configuration](docs/configuration.md) — `fireforge.json`, design tokens, lock waits, environment variables
 - [Exit codes](docs/exit-codes.md) and [machine-readable output](docs/machine-output.md) — the contract for scripts and CI
 - [Run logs](docs/run-logs.md) — what `test` and `build` leave behind
-- [Lifecycle invariants](docs/lifecycle-invariants.md) — locking, rollback and signal handling internals
+- [Lifecycle invariants](contributing/lifecycle-invariants.md) — locking, rollback and signal handling internals
 
 ## Roadmap
 
@@ -114,6 +147,7 @@ cross-module imports.
 - **Update manifests** Generate update server manifests for auto-updates.
 - **Nightly source support** Requires implementing `hg clone` support via mozilla-central. ESR, Beta, and Developer Edition source archives are supported through `fireforge source set`.
 - **E2E Github Actions** Requires either a higher tier of Githubs offering, an external VPS or another provider entirely. In any case, full end-to-end testing is currently run solely locally.
+- **Remote workers** Slots on other machines, so jobs can run where the cores are.
 
 ## Licence