v1.4.2: keep candidate emission inside --emit-candidate (fixes #15)

[ipeterpetrus]

Fixes #15

What was wrong

finding() builds the candidate id as f"{cid}-{scope}-{digest[:8]}", carrying the analysed scope
verbatim, and emit_candidates() used that id directly as a directory name:
os.path.join(outdir, candidate_id). A scope is an opaque label that nothing validates as a path,
so the logical identity of a candidate was also its filesystem path.

Reproduced on main 2ee3cb2 before any change was designed. The sandbox emit root sat twelve
directories deep, and every file was located by resolving it on disk, never by reading the id:

--scope-id x/../../up              CANDIDATE 10   HYPOTHESIS.md 1 level above the emit root
--scope-id x/../../../../up4       CANDIDATE 10   3 levels above
--scope-id a/b/c/ + 12 x ../       CANDIDATE 10   9 levels above
history scope x/../../../hist      CANDIDATE 10   2 levels above
history scope a<NUL>b              rc 1, ValueError traceback from os.makedirs, no --json output
emit/<candidate dir> is a symlink  CANDIDATE 10   written through the link, outside the root

The repair: identity and storage are separate values

• candidate_storage_component(candidate_id) is now the only mapping from a logical id to a
  directory name.
  • An id that is already a single ordinary path component is used as its own name, byte for
    byte, so existing installations keep every path (trend-bash-default-…, …-agent-a-…).
  • An id is hashed if it contains / or \, is ., .. or empty, or starts with the reserved
    prefix as a case-insensitive volume compares names (UPPER-casing, as NTFS does). It is then
    stored as candidate-sha256-<sha256 of the complete id>. That name is deterministic, a single
    component, never a dot segment, and different ids get different names. Reserving the prefix
    means every stored name has exactly one logical source.
  • An id containing NUL, or text the filesystem encoding cannot represent, is refused rather
    than hashed.
• candidate_dir(root, candidate_id) is the emitter's own containment check. It applies no
  matter what the caller passes in: the candidate directory must be a direct child of the
  resolved output root, checked with path semantics (normpath, dirname) rather than a string
  prefix. A symlink, or a Windows junction where Python can detect one, already sitting at that
  name is refused, not followed.
• The scope and the candidate_id are never rewritten. candidate_ids, candidates_written,
  candidates_existing and candidates_failed still name logical ids, and HYPOTHESIS.md still
  states the logical candidate_id and scope_id. No output field is added and
  output_schema_version stays 2.
• A refused candidate appears in candidates_failed with a static reason ("not a single directory
  inside the output root"), which never echoes the input. If nothing else was written, the run
  reports INTERNAL_ERROR / exit 50 with --json output, no traceback, no temporary file and no
  lock left behind.

The production change is about 70 lines in tools/optimize.py, mostly docstrings: the helper, the
guard, and the three lines in emit_candidates() that use them.

Evidence

• The frozen matrix is committed before the code (docs/V142_COUNTEREXAMPLES.md §8, PATH_01–16)
  and has no deviations.
• tests/test_candidate_path.py runs the matrix:
  • main 2ee3cb2: 56 PASS / 36 FAIL;
  • this branch: 107 PASS / 0 FAIL on Python 3.10, 3.11 and 3.13 locally.
• The suite also carries thirteen mutants, each applied to a throwaway copy of tools/. Every one
  turns its oracle RED on the check it is named for, and a control run of the same oracles on the
  real source is GREEN:
  • raw id used as path
  • separators unmapped
  • NUL unchecked
  • containment check removed
  • unsafe ids collapsed to one name
  • safe ids hashed
  • digest salted per run
  • symlink check removed
  • reserved prefix matched case-sensitively
  • reserved prefix matched by casefold only
  • three ways of inspecting a path outside the root before the guard: lexists, access, and
    a pathlib open
• The inspection oracle records every path the emitter hands to the inspecting calls (wrapped)
  and to every open/create/rename/remove/listing (a sys.addaudithook hook). Each path must be the
  root, inside it, or one of its ancestors.
• Full repository: 18 suites, 1708 assertions, 0 failures. tests/test_oneliner_cleanup.sh:
  11/0. The README count is updated and a CI step is added for the new suite.
• PR v1.4.2: fail closed on optimizer evidence quality #13 gates re-run on this branch: R142_01–06, B1 recovery, invalid-UTF-8 trust boundary,
  valid-DEGRADED recovery, run-id conflict, true retry, zero carry and --accept-partial all
  unchanged.
• Issue Optimizer crashes and can leave a temp candidate when legacy run_id is non-string #14 behaviour is byte-for-byte unchanged: a non-string run_id still raises the same
  TypeError and leaves the same temporary file. It stays tracked there.

Cross-family review before this PR (Codex, three rounds)

• Round 1. NEEDS-FIX with two findings:
  • MEDIUM: the reserved prefix was case-sensitive, so a verbatim CANDIDATE-SHA256-<hex> is the
    hashed directory of a/b on a case-insensitive volume.
  • LOW: the oracles did not prove that nothing outside the root is inspected.
• Round 2. Both repairs PARTIAL:
  • casefold() still let candıdate-sha256-… (U+0131) through, and NTFS compares UPPER-cased
    names. The prefix is now reserved under upper().
  • The spy missed os.access and pathlib. It now has two nets.
• Round 3. Both CLOSED. No new CRITICAL, HIGH or MEDIUM finding; one LOW doc wording, fixed.
• The same review raised a pre-existing Windows directory junction as HIGH context.
  candidate_dir() refuses one through os.path.isjunction where the interpreter has it
  (3.12+). That line is untested (no Windows runner), and Windows below 3.12 stays a residual.

Every finding was reproduced before it was accepted. Details: docs/V142_COUNTEREXAMPLES.md §8.6.

Residual limits, stated rather than hidden

• Check-then-create race. The containment check and os.makedirs are two system calls. A
  process that can already write inside OUTDIR could swap a symlink in between them. Closing that
  race needs dir_fd/O_NOFOLLOW creation throughout, which is a different design.
• Planted HYPOTHESIS.md symlink. A symlink planted at HYPOTHESIS.md inside a real candidate
  directory is not candidate-controlled identity, and this PR does not address it.
• Lone UTF-16 surrogate. A scope holding one still crashes earlier, inside finding()'s own
  digest, before any path exists. That is identity hashing, not path handling, and deserves its
  own issue.
• Backslash ids are re-homed. An id containing \ was a single component on POSIX; it now
  moves to the hashed name so the storage rule is the same on every platform.
• Over-long names. An ordinary id longer than the filesystem's name limit still fails exactly
  as before (ENAMETOOLONG, controlled INTERNAL_ERROR).
• Folding is modelled, not measured. Python's upper()/casefold() model NTFS and macOS name
  comparison; neither has been run on a real case-insensitive volume in CI. They can only
  over-match, which hashes more ids.
• Windows junctions below Python 3.12 (see above).

Not in this PR

Version stays 1.4.1. There is no packaging, tag or release, no change to skills/, hooks/ or
the plugin manifests, and no work on issue #14 or PR #7.

🤖 Generated with Claude Code