fn-4 hardening: the 18-defect backlog, three gated rounds

CHANGELOG.md

@@ -657,6 +657,43 @@ below are both part of that coordination, and the latter BLOCKS this release.
 
 ### Fixed
 
+- **Every scan-issue row now states a condition that is true for the
+  producer that emitted it** (fn-4.12 — the PR #459 codex r13 sweep, run
+  over every OTHER scanner's producers; the app's visible row label is
+  derived from `scanner_errors[].kind` alone, so a kind shared with a
+  different condition prints a false diagnosis). All ADDITIONS to the same
+  extensible enumeration (`schema_version` stays 4); no wire STRING is
+  renamed, but the kind a given condition reports under moves, so consumers
+  keying kinds to conditions must re-key: **(1)** a configured dev root
+  refused by the search-root safety policy — persisted, or via `--dev-root`
+  — is now `"policy_refused_root"` ("refused by the search-root safety
+  policy"); it was `"container_refused"`, whose label "not a configured
+  search root" contradicted the row's own detail ("configured dev root
+  refused: …"). **(2)** a configured dev root with a volume mounted exactly
+  at it is now `"mounted_volume_root"`, whose label names the one remedy a
+  re-scan honors (the walk re-reads the kernel mount table every scan).
+  **(3)** a dev root or `~/Library/Caches` sweep root standing as a regular
+  file, FIFO, socket or device is now `"non_directory_root"`; it was
+  `"symlink_root"`, which sent the user hunting for a link that was not
+  there — `"symlink_root"` now means a symlink and nothing else, in every
+  scanner. **(4)** a git worktree or repository admin directory withheld
+  because git's cleanup would modify paths not all inside ONE configured
+  dev root is the NEW `"mutation_scope_refused"` ("git cleanup is not
+  contained in one dev root — not offered"); it was `"container_refused"`
+  while the worktree in question IS inside a configured root. A worktree
+  outside EVERY configured root keeps `"container_refused"` — there the
+  label is exactly the condition. **(5)** a BARE-errno EPERM (raw
+  `lstat`/`open` probes) is now neutral `"unreadable"` everywhere, with the
+  detail saying the cause could not be established; it was `"tcc_denied"`
+  in the dev-root walk and the orphaned-caches sweep — printing the "Grant
+  access…" (Full Disk Access) remedy on a guess — while the temp scanner
+  already classified the same errno as unknowable (a bare errno carries no
+  provenance; TCC, SIP and other filesystem refusals are indistinguishable
+  in it). A chain-proven EPERM — recovered from a Cocoa error's
+  `NSUnderlyingErrorKey` chain — still reports `"tcc_denied"` with the
+  grant hint, which is the one place the claim is establishable. The two
+  scanners that disagreed on bare EPERM now share one recorded rule
+  (`DirectorySizer.denial(forFailedProbe:)`).
 - **A scan could hang before it started, with the spinner up and no way to
   stop it.** The first thing a scan does after marking itself in progress is
   refresh the free-space figures in the header. That refresh was unbounded:

CONTRIBUTING.md

@@ -45,6 +45,15 @@ CacheCategory(
    `--confirm` — preview safely with `--cli clean <slug> --dry-run`)
 5. Submit a PR with a clear description
 
+> **A green tally is not a green run.** A trapping construct (`as!`, `try!`,
+> a force-unwrap, an out-of-range subscript) kills the whole test process,
+> and every `Executed N tests … 0 failures` line printed BEFORE the kill
+> stays in the log — one truncated run showed a passing tally while ~26
+> later suites never executed (fn-4.14). When reading a `swift test` log,
+> trust only the process EXIT CODE and the final executed COUNT compared
+> against the expected baseline, never a greppable `0 failures` line.
+> `StrandFenceTests` fences the trapping shapes out of test sources.
+
 ## Documentation
 
 Full technical documentation is in [docs/v1/](docs/v1/):

PROTOCOL.md

@@ -246,8 +246,8 @@ refreshes.
   "scanner_errors": [
     {
       "scanner_id": "build_artifacts",
-      "kind": "container_refused",
-      "detail": "dev root is not a usable container: the filesystem root",
+      "kind": "policy_refused_root",
+      "detail": "configured dev root refused: the filesystem root",
       "path": "/"
     },
     {
@@ -292,7 +292,7 @@ refreshes.
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `scanner_id` | string | yes | Which scanner reported (or failed validation) |
-| `kind` | string | yes | One of: `"container_refused"`, `"mounted_volume_root"`, `"mounted_volume_root_at_registration"`, `"policy_refused_root"`, `"symlink_root"`, `"non_directory_root"`, `"tcc_denied"`, `"permission_denied"`, `"unreadable"`, `"enumeration_truncated"`, `"config_invalid"`, `"tool_unavailable"`, `"malformed_outcome"`, `"scan_did_not_finish"`. The list is EXTENSIBLE — consumers must tolerate unknown kinds |
+| `kind` | string | yes | One of: `"container_refused"`, `"mounted_volume_root"`, `"mounted_volume_root_at_registration"`, `"policy_refused_root"`, `"mutation_scope_refused"`, `"symlink_root"`, `"non_directory_root"`, `"tcc_denied"`, `"permission_denied"`, `"unreadable"`, `"enumeration_truncated"`, `"config_invalid"`, `"tool_unavailable"`, `"malformed_outcome"`, `"scan_did_not_finish"`. The list is EXTENSIBLE — consumers must tolerate unknown kinds |
 | `detail` | string | yes | Human-readable description |
 | `path` | string | conditional | Present for the FILESYSTEM kinds; ABSENT for the NON-FILESYSTEM kinds — `"malformed_outcome"`, `"config_invalid"`, `"tool_unavailable"` and `"scan_did_not_finish"` — where no filesystem location exists and a fake path is therefore never invented |
 | `grant_hint` | string | no | Present only when `kind == "tcc_denied"` — the same user-side remedy (Full Disk Access) as category and `scanner_items` rows, since macOS denies CLI processes silently |
@@ -309,16 +309,18 @@ scan outcome while the corrupt value persists — the fallback is never
 silent. It carries no `path` because a config parse failure has no honest
 filesystem location. A configured root that was REJECTED by policy (the
 filesystem root, a volume root/mount point, `$HOME`) is a different thing
-and reports honestly WITH its offending path, under `container_refused` for
-the dev-root scanners and under `policy_refused_root` for `ephemeral_tmp`.
+and reports honestly WITH its offending path, under `policy_refused_root`
+for every scanner that resolves configured roots (dev-root scanners since
+fn-4.12; `ephemeral_tmp` since PR #459).
 
 A `mounted_volume_root` row means a REGISTERED root has another volume
 mounted exactly at its path, so whatever is there belongs to that volume
 rather than to the root. It is deliberately NOT `container_refused`: the
 root is configured and admissible, nothing rejected it, and the condition is
 one the user clears — eject or unmount the volume, then re-scan. Emitted
-today by `ephemeral_tmp`, which answers from the kernel's mount table before
-any syscall touches the root.
+today by `ephemeral_tmp` and (since fn-4.12) by the dev-root walk behind
+`build_artifacts`/`git_worktrees`; each answers from the kernel's mount
+table, re-read every scan, before any syscall touches the root.
 
 A `mounted_volume_root_at_registration` row means the same condition was
 already true when the runtime was CONSTRUCTED, so that root was never
@@ -336,18 +338,33 @@ deliberately NOT `container_refused`: a scanner builds its guard from its
 own roots, so a root that reaches this refusal was configured, and
 `container_refused` reads as "you did not configure this". `detail` names
 the clause that fired; there is no single remedy across the clauses.
-Emitted today by `ephemeral_tmp`, whose roots (`/private/tmp` and the two
-per-user `confstr` containers) are not user-configurable at all.
+Emitted today by `ephemeral_tmp` (whose roots — `/private/tmp` and the two
+per-user `confstr` containers — are not user-configurable at all) and,
+since fn-4.12, by dev-root resolution and the dev-root walk behind
+`build_artifacts`/`git_worktrees`, which previously spelled the same
+refusals `container_refused` against their own contradicting details.
+
+A `mutation_scope_refused` row means a DISCOVERED deletable candidate (a
+git worktree, or a repository's orphaned worktree admin data) was withheld
+because the destructive git operation's whole mutation scope — the paths
+git itself would modify plus the parent repository whose records name them
+— is not contained in ONE configured dev root. The candidate itself is
+often INSIDE a configured root, which is why this is deliberately NOT
+`container_refused`: that kind's fixed row label ("not a configured search
+root") was a false diagnosis for these producers. `path` names the withheld
+candidate; `detail` names which path broke the containment. No remedy is
+claimed — where the out-of-scope data sits is the user's layout. Emitted
+today by `git_worktrees` (fn-4.12).
 
 A `non_directory_root` row means a search root EXISTS and is not a symlink,
 but is not a directory either — a regular file, FIFO, socket or device
 stands where a directory is required, and nothing was traversed. It is
 deliberately NOT `symlink_root`: that kind renders as the fixed sentence
 "symlinked — not searched", which sends the user hunting for a link that is
-not there. `detail` names the object's actual kind. Emitted today by
-`ephemeral_tmp`, whose `symlink_root` is therefore now a symlink and
-nothing else; the other scanners still spell both conditions
-`symlink_root`.
+not there. `detail` names the object's actual kind. Emitted by every scanner with a
+root gate (`ephemeral_tmp` since PR #459; the dev-root walk,
+`orphaned_caches` and dev-root resolution since fn-4.12), so `symlink_root`
+now means a symlink and nothing else, everywhere it is emitted.
 
 A `tool_unavailable` row means the scan could not run an external tool it
 depends on, so it produced NO results — today: `git_worktrees` could not

Sources/Cacheout/CLIHandler.swift

@@ -474,7 +474,7 @@ struct CLIHandler {
         context: ScanContext
     ) async -> CollectedScanEvents {
         var collected = CollectedScanEvents()
-        let session = runtime.scanValidatedSession(
+        let session = await runtime.scanValidatedSession(
             scannerIDs: scannerIDs, context: context
         )
         collected.snapshot = session.snapshot
@@ -1140,8 +1140,10 @@ struct CLIHandler {
         // The policy's own verdict, surfaced as a usage error (the CLI
         // attack case: `--dev-root /`). `.configInvalid` cannot occur on the
         // replacement path — nothing was parsed out of the defaults suite.
+        // `.policyRefusedRoot` since fn-4.12 — the resolution pipeline's
+        // refusal kind for a CONFIGURED (here: flag-declared) root.
         if let refused = resolution.issues.first(
-            where: { $0.kind == .containerRefused }
+            where: { $0.kind == .policyRefusedRoot }
         ) {
             return .failure(CLIAddressError(message:
                 "\(devRootFlag) \(refused.url?.path ?? "") is not a usable "
@@ -2896,8 +2898,33 @@ struct CLIHandler {
 
         // Replace the process image; argv[0] becomes the resolved path so the
         // re-exec'd process' Bundle.main is the real app bundle.
-        var argv: [UnsafeMutablePointer<CChar>?] = CommandLine.arguments.map { strdup($0) }
-        argv[0] = strdup(resolved)
+        //
+        // NIL IS argv's TERMINATOR, SO A FAILED COPY IS NOT A LOST ARGUMENT —
+        // IT IS A DIFFERENT COMMAND (PR #461 merge gate r4, P1). This is the
+        // same defect the spawn path carried, in the sibling exec path, and
+        // the fence that now guards `GitCommandRunner` could not see it
+        // because that fence reads one file. `map { strdup($0) }` wrote a
+        // failed allocation's nil straight into the vector: a failed copy of
+        // element k truncates the command there, so `cacheout install-helper`
+        // invoked through the documented Homebrew symlink re-execs into a
+        // no-subcommand `cacheout` — and because the process image is already
+        // replaced by then, nothing can report it.
+        //
+        // The `defer` is registered BEFORE the vector is filled, so a failure
+        // part-way frees what was already copied; on a successful `execv` it
+        // never runs, because there is no longer a process to run it in.
+        var argv: [UnsafeMutablePointer<CChar>?] = []
+        defer { argv.forEach { free($0) } }
+        for text in [resolved] + CommandLine.arguments.dropFirst() {
+            guard let copy = strdup(text) else {
+                printError(
+                    "Warning: could not re-exec bundled binary at \(resolved): "
+                        + "out of memory copying arguments — not re-exec'd"
+                )
+                return
+            }
+            argv.append(copy)
+        }
         argv.append(nil)
         execv(resolved, argv)
         // execv only returns on failure — continue and let SMAppService report.