Skip to content

A macOS rerun audits every CSA MCP registration, re-points a dead one in place after consent keeping every setting, and holds its server check (#179 Plan 2) - #201

Merged
kurtseifried merged 29 commits into
mainfrom
feat/registration-repair
Nov 17, 2026
Merged

kurtseifried merged 29 commits into
mainfrom
feat/registration-repair

Conversation

@kurtseifried

Copy link
Copy Markdown
Contributor

Agent: Claude Code. #179 Plan 2, macOS. Review brief first: plans/2026-11-15-registration-repair-review-brief.md. It holds 30 claims, each with a check, plus the review history and where the author is least sure.

What ships

On macOS, a rerun of macos-ai-tools.sh, macos-update.sh or macos-plugins.sh now:

  • lists in the plan, before you agree, every registration of the four CSA MCP servers in Claude Code (user and local scope), Claude Desktop, Codex and Gemini, and says what is wrong with each;
  • after you agree, re-points a dead one at the standard ~/.local/bin/<entry>. Only its command changes (plus args, in one pinned Python form), and every env var and other field is kept, with a backup at the file's mode;
  • leaves the rest, saying why: a working registration elsewhere (a developer's checkout), a launcher form (uv run, uvx, npx), an env that would point the release binary at another tree, a dead local-scope entry, a bare-name Desktop entry, and Desktop's config while Desktop runs. Each gets a to-do where somebody has to act;
  • holds the server check: verify sends one MCP initialize per server, but a rerun launches nothing until D5 is decided. verify --run checks by hand.

A second rerun changes nothing. It never creates or removes a registration, never runs a client CLI that writes, never puts a value on a command line, never breaks Claude Code's config lock, and never opens a token file.

The code: scripts/csa-mcp-registrations.py (new, stdlib only, Python 3.9–3.14), fetched from HEAD like the plugin lists, and eight byte-identical functions in the three macOS entry scripts. All four bash confirms and all four Confirm-Steps now answer no to end of input; the old bash form took Ctrl-D as yes.

Evidence

Decisions

  • D3, the CINO's, 2026-11-13, verbatim: "Ship macOS first (Recommended)". So this merges once reviewed and green, and the Windows halves are Handoff (Windows): #179's Windows halves — measure, then the CSA Python resolver and the gate .ps1 rebuild #184 (plans/2026-11-12-registration-repair-windows.md). The gap is not declared PLATFORM_ONLY; it is TODO.md P1 and a per-case SKIP.
  • D1, D2, D4 and D5 are unanswered, so each ships its safe default, one constant each: a working registration elsewhere is left and warned; a dead local-scope entry gets a rebuild-or-remove to-do; Desktop's config is not written while it runs; a rerun launches no server.
  • The AI's rulings (each in the brief, with its rule): never break Claude Code's lock; bare-name Desktop entries stay "not checked"; verify prints none of a server's own text; D6 shipped the gate fixes first.

Merge dependencies

Both are already merged:

  • CloudSecurityAlliance-Internal/CSA-Plugins#213 (2026-11-13): G2/G3. The Desktop config is written 0600, and skilljar keeps its credential off argv.
  • CloudSecurityAlliance-Internal/CSA-Plugins#215 (2026-11-15): G1. The gate's client probes run from an empty directory.

Not in this PR

Issues

Refs #179, #175, #176, #177, #184.

This PR closes no issue. Each one's "done when" goes beyond it:

kurtseifried and others added 29 commits November 15, 2026 11:25
… a server, that a running Claude Code keeps an external edit and takes a lock, and where each server keeps its token

Task 0 Step 1 of plans/2026-11-12-registration-repair.md: M0, M1 (isolated),
M3's isolated parts, M4, M6 and M7, all in isolated mktemp homes with a
security stub first on PATH and only the dummy csa-plan2-probe registered.
M2, M3's Desktop part and M5 are marked as awaiting the CINO's go-ahead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…aheads touch, and that Task 2 never breaks Claude Code's lock

Applies the measurement review's six docs-only findings:
- M5 names the real ~/.claude.json read, the token-path override keys, the
  Google client_secret.json files and any CSA_SKILLJAR_ENV_FILE.
- M2 says where the backup sits, when it stays, whose the preference is, and
  what the dummy's log records.
- M1's step 2 waits a bounded time, never breaks the lock, and skips Claude
  Code's config with a to-do naming the lock path. Recorded as the AI's
  decision under P1, with the departure from "the same protocol".
- M0 scopes the keyring search to src/ (re-run for all four) and lists each
  repo's main commit by name.
- M3 labels Codex's allowlist as a lower bound.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…in four clients and says which are dead, without reading a credential or writing a file

Plan 2 (#179), Task 1: `plan` only. Reads Claude Code (user and local scope,
CLAUDE_CONFIG_DIR honoured), Claude Desktop, Codex (`codex mcp list --json`)
and Gemini; classifies each CSA registration standard / dead / launcher /
elsewhere with the plan's verbatim reasons; prints `row<TAB>` lines and writes
a 0600 plan file holding fingerprints and env key NAMES, never a value or an
arg. Decisions at their safe defaults: D1 (a), D2 "todo", D4 (b), D5 empty.

Measurement branches applied (plans/reviews/2026-11-12-registration-repair-measurements.md):
- M3: A8 resolves a bare name on the inherited PATH for Claude Code, Codex
  and Gemini; Desktop's is unmeasured, so DESKTOP_PATH is None and a bare-name
  Desktop entry is left "not checked". M3's A12 bullet: an interpreter-shaping
  key in the installer's own env is a WARNING on a re-point row in Claude Code
  and Gemini (the clients that pass it on), not a block - it reaches the
  standard binary too, so leaving a dead entry protects nothing.
- M7: every client CLI call runs from a fresh empty directory (A11); Codex
  reports a trusted project's entry otherwise. Project files are never read.
- M0: TOKEN_PATH_KEYS; each finding records its token-moving keys by name.
- M1, M4, M6: not used by Task 1 (Tasks 2 and 3).

Resolved where the plan was open:
- SERVERS modules are the console-script targets' import paths. At the cited
  tags csa_skilljar.mcp.cli and csa_zendesk.server have no __main__, so
  `python -m` with them starts nothing; they are recognised, not endorsed.
- "Only logged" is a `log<TAB>` line; Task 4 routes it to the debug log.
- ps failing counts as "may be running": not written, worded as unknown.
- A relative command path is "not checked", never dead.
- The count line is pluralised ("1 client", "1 needs").

Tests: tests/test_mcp_registrations.py, 49 cases (the plan's 42 plus 7), and
--self-test applying Step 4's seven mutations, each caught by its named case.
Wired into check-all.sh (python3, --self-test, /usr/bin/python3 with CLT) and
lint.yml (ubuntu; macos under python3 and /usr/bin/python3).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d any linked directory, contains a hostile client to that client, and cannot be forged or left behind unshown

The review of fba8c54, applied in full:

1. The liveness probe runs `<interp> -I -B -c ...` with PYTHONDONTWRITEBYTECODE=1:
   without -B a fresh interpreter wrote a .pyc per imported module into its
   own stdlib. probe_writes_no_bytecode uses a private interpreter whose
   bytecode is redirected (-X pycache_prefix); its control proves the same
   interpreter does write without -B.
2. A10 compares the config's realpath with its expected path under the real
   HOME (or, for a CLAUDE_CONFIG_DIR elsewhere, under its parent), so a
   linked ~/.gemini, Desktop directory or CLAUDE_CONFIG_DIR is "a link" and
   is never written through. A HOME that is itself a link is not.
3. Each client is read and classified in its own try: a failure makes that
   client "not audited". A NUL in a command, arg or env is a malformed entry;
   deep JSON nesting is "nested too deeply". Errors report this script's own
   frame and type, never a message or a stdlib line.
4. Control characters in a project path, a command basename or an env key
   name are shown as `?` (label(), tilde(), keys_text(), and once more as
   each line is printed), so a config cannot forge a `row<TAB>` line.
5. The plan is printed and flushed after --out is written; if it cannot be
   shown (stdout closed, or a reader gone), the plan file is removed and the
   exit is 2, not 120.
6. Tests kill the surviving mutants: args in the plan file, the exception
   message printed, CODEX_HOME ignored, p.kill() in place of the group kill.
7. A BOM has its own reason. Comments record the count line's wording (the
   plan's template is plural; taken literally it prints "1 clients") and
   that a bare name not on the client's PATH is dead and re-pointed by
   design (the plan's #176 row, A8).

Tests: 58 cases (49 + 9); --self-test now applies 17 mutations, each caught by
its named case. Against fba8c54, nine of the new or changed cases fail.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…leaves no plan file, /tmp is not a config link, and no invisible character is printed or written into source

The re-review of 01e07cf, applied in full:

1. hostile_input_contained no longer depends on the build: Homebrew's 3.14.10
   parses 100,000-deep JSON where uv's 3.14.10 and Apple's 3.9.6 raise
   RecursionError. The CLI case accepts either outcome for Desktop; the new
   deep_nesting_is_not_audited forces a RecursionError in process and pins
   "its config is nested too deeply to read" on every interpreter.
2. _text() refuses a string UTF-8 cannot encode (a lone surrogate, which
   JSON's "\ud800" escape produces), so in a command, an arg or an env key it
   makes that client "not audited" instead of exit 2 for all four at the
   fingerprint.
3. Any failure removes --out, a plan file from an earlier run included, so
   "nothing was written" is true of it (discard()).
4. linked_config(): a config directly in a top-level directory anchors on
   that directory, so macOS's /tmp and /var links are the machine's, not the
   config's. The documented limit (a link above the config's own directory,
   outside HOME) is kept and restated.
5. clean() also replaces U+2028/U+2029, the bidi marks and controls (U+061C,
   U+200E/F, U+202A-E, U+2066-9) and lone surrogates.

Found while doing it: the edit tool decoded backslash-u escapes into the
characters themselves, so the previous working copy held literal bidi
controls and a U+2028 in both files, and 01e07cf's BOM test a literal U+FEFF.
All are now built from code points with chr(), and
no_invisible_characters_in_source refuses any in either file.

Tests: 64 cases (58 + 6); --self-test applies 22 mutations, each caught by its
named case. Passing on uv 3.14.10, Homebrew 3.14.10, Homebrew 3.15.2 and
Apple's 3.9.6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…opened a connection when launched as verify will launch it

M5 ran under the real HOME with the CINO's go-ahead ("Both, now (Recommended)",
2026-11-13). Each of the four servers was launched once, as Task 3 will
launch it. Its token files and their directories were only stat-ed, before
and after, and all were unchanged. lsof saw no remote connection from spawn
until the process group was killed. The answers took 0.49 to 1.84 s.

Branch: all four servers become candidates for D5 (c). VERIFY_ON_RERUN
stays Task 3's. M0's caveats are updated: no Claude Code user-scope
registration carries a token-path override key.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…top and its quit, and M3 records the six env keys and the PATH Desktop passes a server

M2 and M3's Desktop part ran with the CINO on 2026-11-13 ("Both, now
(Recommended)"), driven by the coordinating session.

The edited command survived 14 minutes of Desktop running and its quit.
Desktop kept its old command until it quit. A preference change was not
made, so whether one writes Desktop's old copy back is unmeasured, and D4
keeps its safe default (b). That is the AI's decision, under P1.

Desktop passed HOME, LOGNAME, PATH, SHELL and USER, plus the OS's and the
interpreter's own keys, with cwd /. Its PATH includes ~/.local/bin, but was
recorded at a start whose shell-environment extraction timed out, so it may
be the fallback. A8 resolves on it with that label.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ls which are inferred, and says the preference keys were compared

Wording fixes from the check of 401b4ae:
- Desktop's record says seven names were observed. LC_CTYPE and
  __CF_USER_TEXT_ENCODING are labelled consistently, as inferred to be the
  interpreter's and the OS's own.
- Task 3's Desktop env, which drops those two, is called a labelled
  approximation.
- M2 says that the preferences objects were compared key by key, with no
  key changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… not create, records only known transports, and cleans every invisible character by category

The third review of e62c775, applied in full:

1. An entry's `type` must be text a client could hold, or the entry is
   malformed (that client "not audited"); the plan file records only an
   allow-listed transport, "unknown" otherwise. Every other field was
   audited for the same gap: the fingerprint is now computed inside the
   per-client containment, and the plan file is written with
   ensure_ascii=True, so a project path or key name is recorded exactly but
   as escapes, and nothing a config spells reaches the file raw.
2. clean() and the source check judge by Unicode category (Cc, Cf, Zl, Zp,
   Cs, Co), so the zero-width set, soft hyphen, tag characters and private
   use are caught too. clean() replaces every Cc, tab and newline included,
   since those are what forge a row; the source check allows only tab and
   newline, and reads bytes so a CR is seen.
3, 4. --out must be a new file. An existing one (a config, an earlier plan,
   anything) is refused before the audit and left byte-identical, and the
   path of any client's config is refused by realpath even before that
   config exists. The write is mkstemp then os.link, so a file that appears
   after the check is not replaced. A failed run removes only the plan file
   it created (matched by device and inode). argparse errors return 2
   through the same path and touch nothing.

   Items 3 and 4 conflict on a plan file from an earlier run: 3 asks to
   remove it, 4 to never unlink a file this run did not create. Resolved
   under P1 (safety): such a file is refused and left, never opened and
   never removed. The entry scripts always pass a path in a fresh
   `mktemp -d` directory, so this never meets them.

Tests: 68 cases (64 + 4 net); --self-test applies 30 mutations, each caught by
its named case. Passing on uv 3.14.10, Homebrew 3.14.10, Homebrew 3.15.2 and
Apple's 3.9.6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…pells it, and a failed run never deletes a file swapped in for its plan

The fourth review of a9f9a94:

1. After the plan file is created, its device and inode are compared with
   lstat and stat of every client's config path; on a match the new file is
   removed and the run refused (exit 2). On a case-insensitive volume,
   `--out ~/.CLAUDE.json`, `~/.gemini/Settings.json` and
   `~/.codex/CONFIG.TOML` passed the realpath string comparison while the
   config was absent, and created the plan where the client reads its config.
   The name check stays first, so the ordinary spellings are refused before
   any file exists; a test now pins that order.
2. The plan file's identity is taken by fstat of the open temp file before
   the link, not by lstat of --out after it, so a file swapped in at --out in
   that gap is never deleted by a later failure.

Tests: 70 cases (68 + 2); --self-test applies 32 mutations, each caught by its
named case. Both new cases fail against a9f9a94. Passing on uv 3.14.10,
Homebrew 3.14.10, Homebrew 3.15.2 and Apple's 3.9.6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd a bare-name Desktop entry now says why it is not checked

The A8 Desktop PATH question, decided by the AI on 2026-11-13 under P1 (safety)
and correctness: M3's recorded Desktop PATH is not applied. It is one Mac's
PATH (nvm and pyenv directories) and possibly Desktop's fallback, so it cannot
stand for staff machines. A bare-name Desktop entry stays "not checked", which
writes nothing.

- scripts/csa-mcp-registrations.py: the DESKTOP_PATH comment and a one-line
  comment on A8's Desktop branch in classify() record the ruling.
- plans/reviews/2026-11-12-registration-repair-measurements.md: the M3
  Desktop A8 branch says "Not applied - AI ruling 2026-11-13, P1:
  machine-specific, possibly fallback PATH; bare-name Desktop entries stay
  'not checked'."

Departure from the plan's wording: the reason a person reads was the plan's
verbatim "not checked: Claude Desktop's PATH is not measured yet". M3 has
since measured one Mac's, so that is no longer true. It now reads "not
checked: Claude Desktop's PATH differs from machine to machine, so a bare
command name can't be resolved here" (P2, honesty of what we claim, which
ranks above the plan's text). The plan document keeps its original text at
A8 and Task 1, since the plan is not rewritten mid-run; this commit is the
record. tests/test_mcp_registrations.py pins the new text.

No behaviour changes. SCRIPT_VERSION bumped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…y in place, changing only its command, and only when the plan showed it

Plan 2 (plans/2026-11-12-registration-repair.md), Task 2: `csa-mcp-registrations.py apply
[--approved FILE]`. It re-audits, and acts on a re-point finding only when the plan file holds
the same (client, scope, project, name, fingerprint) as a re-point and the standard binary
classifies as not dead (its Python probed, never launched). It edits the client's own file,
never through a client CLI: `command`, and `args` only in the pinned `-m <module>` form, to [].
Every other field and every env value is kept, asserted in memory before the write and on
read-back after it. Writes: mkstemp in the same directory, fchmod to the original's mode before
a byte is written, fsync, stat check, backup (copy2, `<path>.bak-<14 digits>`), stat check,
os.replace, read-back (restore the backup on a mismatch), prune to 3 with
csa-claude-connectors.py's regex and count. An abandoned write leaves no backup and prunes
nothing. A symlinked config is refused again at write time. No env value is printed, logged,
put on argv or written to the plan file or the ledger.

Measurement branches applied (plans/reviews/2026-11-12-registration-repair-measurements.md):
- M1, "a lock is found": Claude Code's `<config>.lock` directory is taken with mkdir and held
  across the read, the checks, the backup, the replace and the read-back (milliseconds). A held
  lock is waited for at most CLAUDE_LOCK_WAIT (10 s) and NEVER broken (the measurement review's
  ruling); on timeout Claude Code's config is skipped with the to-do "Claude Code's config is
  locked; close Claude Code and run again (the lock is <path>)", and the other clients are still
  repaired. The ok line says Claude Code sessions started after the repair use it (M1: a running
  session keeps its command).
- M2: D4 keeps its safe default (b), WRITE_DESKTOP_WHILE_RUNNING = False. Desktop is checked in
  the re-audit (started since the plan) and again with a fresh `ps` just before its config is
  written (started during apply); either skips the write with "Quit Claude Desktop and run again"
  at order 10.
- M3: Desktop's one-Mac PATH stays unapplied (Task 1's ruling); nothing here resolves a bare
  name.

Departures from the plan's text, each the AI's decision:
- edit_json takes all of one file's approved changes at once (one read, one backup, one write),
  not one entry per call: backup names have one-second resolution, so two writes of one file in
  one run would share a backup name. Under P3, correctness.
- A finding the plan showed as left (e.g. Desktop was running) that is re-pointable at apply is
  not acted on: "the plan you agreed to left it as it was; not changed — run again". The plan
  keyed approval on presence in the file only; A4 says only what the plan showed is changed.
  Under P1.
- An unreadable, empty or foreign plan file approves nothing; each re-point says "not changed,
  because the plan you agreed to could not be read — run again" rather than the plan's "found
  after you agreed to the plan", which would be untrue there. Under P2.
- The ok line names the client as the plan rows do: "(user scope)" or "(local scope, <dir>)"
  for Claude Code, the bare client name for Desktop, Codex and Gemini. Under P4.
- The stat check compares the whole mode, not only inode, mtime and size: a chmod since the read
  changes no mtime, and the replace would put the old, looser mode back. Under P1. Pinned, with
  its own mutation.
- The backup name is claimed with O_EXCL|O_NOFOLLOW before copy2, and a backup more permissive
  than its file abandons the write (csa-claude-connectors.py only warns). Under P1.
- JSON is written with allow_nan=False, and a lone surrogate is written escaped as
  JSON.stringify writes it; ensure_ascii=False would otherwise fail on one. Under P3.
- Codex: the region between the table header and the next header is refused if it holds a
  multi-line string delimiter; the read-back compares `codex mcp get --json` after the write
  with what it showed before, command (and args) replaced, key order ignored (Codex's env map
  need not keep an order). Under P1/P3.
- The read-back restores the backup on any mismatch of the entry, as the plan says; it does not
  try to tell a bad write from another writer's.
- The check-all.sh and lint.yml step names now say the suite covers apply.

What re-serialising changes (also in the module docstring): every value, key order, the indent
(tabs too), the trailing newline or its absence and CRLF are kept; whitespace between tokens
becomes json.dumps's, a \u escape of a printable character is written as the character, a number
in Python's form (1.5e3 as 1500.0). mkstemp + os.replace drops extended attributes and ACLs.

Tests: 28 new cases (the 26 the plan names that were not already Task 1's, plus
backup_rule_matches_connectors and apply_by_hand_replans_and_applies), and 3 of Task 1's
extended to cover apply (dead_local_scope_todo_names_rebuild_or_remove, symlinked_config_refused,
desktop_running_skipped_with_quit_todo). All 31 fail against the script before this commit; 98
pass under python3 3.14 and /usr/bin/python3 3.9. --self-test gains 20 mutations, the plan's six
and one for each guard added; all 52 are caught by the case named for them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nfig's secrets, removes only its own lock, and refuses a config it would cut off or misread

The review of d39f719 (Plan 2 Task 2), its seven findings, with the coordinator's rulings:

1. (Medium) SIGTERM or SIGHUP mid-write left `.csa-registrations-*` (0600, holding the env
   values) and `.claude.json.lock`; the next run waited 10 s and skipped Claude Code. While
   apply runs, SIGTERM and SIGHUP now raise SystemExit, so every clean-up runs (exit 128+n,
   "stopped by a signal" on stderr); a signal the caller ignores (nohup's SIGHUP) stays ignored.
   Each apply also sweeps this tool's own temp files in each config's directory: only regular
   files owned by the user, named exactly as mkstemp names them here, and changed before the run
   began; never anything else, never through a linked directory. Tested with a real signal sent
   from outside at the write's "written" and "backed-up" points.
2. (Medium) Six guards had no test: Desktop state unknown at the write (D4), the backup's
   O_EXCL, a backup looser than its file, Codex's write-time link check (A10), allow_nan=False,
   and Codex's multi-line-string refusal. Each now has a case and a mutation. The reviewer's 20
   mutants, re-run on this tree: 18 caught, 1 no longer applies (its lock code was rewritten;
   "never release the lock" is now one of ours, caught), 1 survives by design (dropping the
   in-memory confinement assert: repointed() cannot break it unless itself broken, and "copy env
   through str()" shows the assert catches that). The re-run also showed one more real gap, the
   write-failure reason going through repr(e): pinned by write_failure_says_no_value.
3. (Low) A header look-alike inside a multi-line string above the real table could be edited.
   A Codex config with a `"""` or `'''` anywhere before the header is refused, with a to-do.
4. (Low) A hard-linked config would be silently detached by os.replace. Refused when
   st_nlink > 1 (JSON and Codex), with a to-do.
5. (Low) The lock was removed without checking it was still this run's. The write is abandoned
   (no backup left) if the lock has been held more than LOCK_HOLD_MAX = 5 s, wall clock as
   proper-lockfile measures staleness, or is no longer this run's; the lock is removed only if
   its device, inode and mtime are still the ones this run created.
6. (Low) The lock to-do now adds "; if Claude Code is not running, remove <lock path>".
7. (Info) The approval key binds the config's realpath, recorded per finding in the plan file;
   a plan row listed both as a re-point and as left counts as left.

Also: the module docstring declares `-0` written as `0`, and that a config holding a number no
JSON client reads back (1e999, NaN) is not rewritten.

Tests: 14 new cases (112 in all; 13 for these fixes plus the repr gap), and claude_lock_honoured
extended for the to-do. Against d39f719, the ten cases for new behaviour fail (nine new, and
claude_lock_honoured); the five for guards d39f719 already had pass there, and their mutations
are what prove them. --self-test:
23 new mutations, 75 in all, each caught by the case named for it. 112 pass under python3 3.14
and /usr/bin/python3 3.9.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d no copy of a config's secrets, and a second run never sweeps a running one's temp file

The re-review of b417a67 (Plan 2 Task 2), its eight findings, with the coordinator's rulings:

1. (Medium) A signal between `os.mkdir(<config>.lock)` and the return of __enter__ left the
   lock, so every later apply waited 10 s and refused. Any exception after this run's mkdir
   (which found no lock there) now removes it before propagating.
2. (Low) restore() caught only OSError, so a signal between its temp write and its replace left
   a 0600 temp holding the env values; and a signal straight after mkstemp left an empty temp.
   Temp files are now made by new_temp, which puts the name into a list the caller owns BEFORE
   the file exists (mkstemp's O_EXCL create, name first), so a failure at any point, the
   creating call included, can name and remove it. replace_file, restore and make_backup all
   clean up on BaseException; after the replace, the backup is kept as the copy of what was
   replaced.
3. (Low) A case patches mod.repointed to drop env, add a key, reorder, or change a value: the
   in-memory confinement check refuses each, where its mutant wrote the damage and printed ok.
4. (Low) Cases for four surviving mutants: the temp left on a lock refusal, the sweep's owner
   check, its linked-directory skip, and signal handlers not restored.
5. (Low) The sweep could delete a concurrent apply's live temp (it failed safe). Temp names now
   carry the pid of the run that made them, `.csa-registrations-<pid>-<8 chars>`, and the sweep
   leaves a file whose run is alive (unsure counts as alive; a reused pid only delays a removal).
   Documented in the module docstring and sweep_temps.
6. (Nit) TMP_NAME is matched whole (fullmatch): `$` also matched before a trailing newline.
7. (Nit) An interrupt (SIGINT) ran the clean-ups but printed a traceback and exited -2; it now
   prints "stopped by an interrupt, with what was reported done" and exits 130.
8. (Nit) identity() includes st_nlink: a hard link made after the read now abandons the write.

Tests: one new case (confinement_check_refuses_a_damaged_entry; 113 in all), and four extended:
signal_mid_write_leaves_nothing (signals at the lock's mkdir, straight after the temp's create,
mid-restore, and SIGINT; the handlers restored), stale_temp_files_swept (pid names, a live
run's file, a trailing newline, another user's file, a linked config directory),
lock_held_too_long_abandons (no temp left) and hard_linked_config_refused (a link made after
the read). --self-test: 12 new mutations, 87 in all, each caught by the case named for it. 113
pass under python3 3.14 and /usr/bin/python3 3.9.

The reviewer's signal matrix (14 points x SIGTERM, SIGHUP, SIGINT) re-run on this tree, plus a
point straight after the temp file's create (mkstemp is no longer used, so the matrix's own
mkstemp point is not reached): no point leaves this run's lock or a temp file, prints a value
or a traceback, or makes a config anything but its original or its repaired self. SIGTERM exits
143, SIGHUP 129, SIGINT 130. Two rows are by design: at "lockswap" the lock left is the other
process's, and at "restore-tmp" the config is the probe's own simulated bad read-back, with the
backup kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…made it, so a signal can never take Claude Code's held lock, and a second signal cannot cut its clean-up short

The third review of Task 2 (79aa251), with the coordinator's rulings. The rule now: this run
removes a lock or a file only when it has proof it created it - a record made with the create
in one signal-held step - never on an exception path that cannot prove it.

1. (Medium; it broke "never break Claude Code's lock") ClaudeLock.__enter__'s except removed the
   lock even when this run's mkdir had failed, so it could remove Claude Code's held lock: an
   interrupt raised from os.mkdir did, deterministically, and real signals did 6 times in 300
   on 3.9 with LOCK_POLL=0. signals_held() now blocks SIGTERM, SIGHUP and SIGINT
   (pthread_sigmask) from the mkdir until the lock's identity is recorded; a signal that
   arrives is delivered when the block ends. The blanket rmdir is gone: an exception in
   __enter__ releases only a lock whose recorded identity matches. Cases: an interrupt or a
   SystemExit raised from os.mkdir with a holder's lock present (the lock stays), and a real
   SIGTERM between the mkdir and the record (this run's lock is then removed, not left).
2. (Medium, ADR-005) Five mutants survived: O_EXCL dropped, the temp created 0666, a taken name
   left registered, the parent's pid in the name, EPERM read as dead. A case and a mutation for
   each (temp_files_are_this_runs_alone; stale_temp_files_swept's EPERM world).
3. (Low) A second signal during the clean-up aborted it. On the first stop, apply's handler now
   blocks SIGTERM, SIGHUP and SIGINT (pthread_sigmask) to the end of the process, and ignores
   one already on its way (a flag). SIGINT is now handled by it too. Ignoring alone was not
   enough, as the re-run double-signal matrix showed: Python's own shutdown gives the handlers
   back to SIG_DFL, and a second signal then killed the exit after "stopped" was printed (-15)
   or raised a traceback (-2). With the block, handlers are restored on every exit, as before.
   Cases: a second signal sent during the clean-up, two (HUP, TERM) in flight together, and
   the stop signals still held after a stop.
4. (Info) new_temp and make_backup register a name only after its O_EXCL create succeeds, with
   the create and the record in one signals_held() step: a name another process holds is never
   registered, so never removed, and a signal can no longer leave an empty `.bak-<stamp>`.
   A sixth surviving mutant, the clean-up removing the backup of a config already replaced, is
   now pinned through a "swapped" point just after the replace.

Tests: 115 cases (2 new; signal_mid_write_leaves_nothing and stale_temp_files_swept extended).
Against 79aa251 the new lock case and the backup-record world fail. --self-test: 99 mutations,
each caught by the case named for it. 115 pass under python3 3.14 and /usr/bin/python3 3.9.

The reviewer's probes, re-run on this tree, on python3 3.14 and /usr/bin/python3 3.9:
- Signal matrix (20 points x TERM, HUP, INT): 60 of 60 exit 143/129/130 on each, no
  traceback, no value printed; the only things left are by design (the holder's lock at
  "lockwait" and "lockswap", the repaired config's backup after the replace, the probe's own
  bad read-back with its backup kept).
- Double-signal matrix (20 points x HUP+TERM, TERM+TERM, INT+INT, INT+TERM): 80 of 80 exit
  with the first signal's status on each; none -15 or -2, no traceback.
- Lock probe, LOCK_POLL=0: the holder's lock removed in 0/300 runs for SIGTERM and 0/300 for
  SIGINT, on each (was 6/300 on 3.9).
- Unit probe: T5 (a signal as os.open fails on another's name) leaves that file intact; T7 (an
  interrupt out of os.mkdir) leaves the holder's lock. T6's "-ABCDEFGH removed" is this
  volume folding case: it is the same file as the "-abcdefgh" removed beside it.
- The reviewer's 25 mutants: 20 caught; 4 no longer apply (their text moved), each with an
  equivalent here that is caught; 1 survives, dropping O_NOFOLLOW, which is equivalent under
  O_CREAT|O_EXCL (their T1: every existing name, links included, is refused).
Their driver's hold was cut from 60 s to 5 s: at the four points now inside a signal-held
region (mkdir, temp open, backup open, restore open) a 60 s hold keeps the signal past their
30 s timeout and SIGKILLs the run; 5 s shows the held signal delivered, and handled, as the
region ends. The lock probe was run through a launcher that resets SIGINT to its default: a
background job inherits it ignored, and apply rightly leaves an ignored SIGINT ignored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s that a signal hold keeps the caller's mask, and says what a hang while signals are held costs

The fourth review of Task 2 (f566ac2) approved it with three lows, folded in here:

1. The suite failed deterministically ("SIGINT: the clean-up was never reached") when the
   runner had SIGINT ignored, as `check-all.sh &` from a non-interactive shell does: the
   in-process cases never reset it, and apply rightly leaves an ignored signal ignored.
   apply_stopped now starts SIGINT at default_int_handler and SIGTERM and SIGHUP at SIG_DFL
   (nohup ignores SIGHUP), and restores the runner's own afterwards. Verified with
   `trap '' INT HUP` around the suite: 116 pass on python3 3.14 and /usr/bin/python3 3.9.
2. signals_held restoring with `SIG_UNBLOCK, sigs` instead of `SIG_SETMASK, old` survived the
   suite. New case signals_held_keeps_the_callers_mask: a signal the caller had blocked stays
   blocked across the hold; mutation added.
3. The docstrings of signals_held and exits_on_signals say what holding the signals costs:
   a create, or a post-stop clean-up, that hangs ignores Ctrl-C, SIGTERM and SIGHUP until it
   returns; SIGQUIT and SIGKILL still end it, leaving at most a temp file (swept by the next
   apply), an unused backup (bounded by the prune) and Claude Code's lock (named by the
   to-do).

Tests: 116 (1 new). --self-test: 100 mutations, each caught by the case named for it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…andshake, one at a time, bounded, with no secret in what it prints, and a rerun holds the check until it is measured

csa-mcp-registrations.py gains `verify [--run]` (#179, Plan 2 Task 3).
The subject is the plan's; M5 has since measured each server's start, so
what holds a rerun's check now is D5's answer, not a measurement.

- Without --run it checks only the servers VERIFY_ON_RERUN names, still
  frozenset() (D5's safe default): one info line, and nothing is run, not
  even the audit.
- `verify --run` re-audits. It launches each working standard or elsewhere
  registration that is a direct executable, one at a time, in a fresh empty
  directory and a session of its own, and sends one `initialize`. Then it
  stops the process group: stdin closed, SIGTERM, SIGKILL, reaped, each step
  bounded, with the stop signals held so no signal cuts it short.
- A dead registration, a dead standard binary and a launcher form are
  reported and never launched. Identical launches are made once.

Measurement branches applied
- M3: a launch env per client (launch_env). Claude Code: the installer's
  whole env. Codex: HOME LANG LOGNAME PATH SHELL TERM TMPDIR USER (a lower
  bound) and its env_vars; its two PATH prepends are not reproduced.
  Gemini: the installer's env minus what Gemini CLI 0.67's own rule drops
  (shouldRedactEnvironmentVariable, read from the installed bundle; it
  agrees with M3). Desktop: HOME LOGNAME PATH SHELL USER. Each also gets
  the registered env; none gets CSA_TODO_FILE, CSA_LOG, CSA_DEBUG,
  CSA_NESTED or CSA_REGISTRATIONS_*. ENGINEERING.md labels it an
  approximation, and says which two Desktop names it leaves out, and why.
- M4/M5: the 20 s timeout stands; the figures are in ENGINEERING.md.
- M6: Claude Code sends server/discover first. The check is initialize
  only, and never says "as <client> launches it".
- The A8 ruling: a bare-name Desktop entry stays "not checked". Desktop's
  launch PATH is the installer's, not M3's one-Mac PATH.
- Task 1's review rules: a dead standard binary is "does not start" and is
  never launched; a launcher form is "not checked: launcher form" and is
  never launched; an interpreter-shaping env key means it is not launched.

Departures from the plan's text (the plan is not rewritten mid-run)
- The held line no longer says "until its effect on tokens is measured",
  which M5 made untrue. It says whether a rerun launches the servers is
  not decided yet (#179, D5). P2, honesty.
- Masking covers every launch-env value of 4+ characters, not only the
  registration's: the installer's env can hold a secret too. P1.
- Also not launched, and said so: args using $-expansion, and a
  registration that sets its own cwd (Gemini, Codex). The check cannot
  reproduce either. P2.
- The teardown waits *up to* 2 s at each step, so a server that exits at
  once is not held 4 s. The bound is unchanged: 24 s, plus 2 s only for a
  process that outlives SIGKILL.
- __CF_USER_TEXT_ENCODING, which macOS gives every process anyway, passes
  to every launch, so two launches differing only there are one.
- ENGINEERING.md gets a short subsection now, because Task 3 and the M3/M4
  branches put the env label and the run time there. Task 5 folds it into
  its "Registration audit and repair" section.

Tests: 21 new cases (137 in all), each failing before the change, on
python3 and /usr/bin/python3. 30 new --self-test mutations: the plan's
four, and one for each guard added. All 130 are caught.
./tools/check-all.sh: exit 0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ver's output, name or error text, stops a child a server leaves, holds all its launches to 120 s, and knows a launcher behind another name

The review of bbb6f82 reproduced four ways past its masking, so that
commit's subject claim, "no secret in what it prints", was false. The
four: an arg was never masked (an argparse "unrecognized arguments:
--token <value>" line, and a serverInfo.name holding argv); a multi-line
value got through, because stderr was split before masking; an escaped
value (repr, json.dumps) got through; and the 64 KB stderr tail could cut
a value and print its suffix.

The coordinator's ruling (P1, privacy first): masking is a deny-list and
cannot be made complete, so verify prints none of a server's text.

- verify's lines are now fixed text this file composes (F_*, OK_CHECK,
  W_CHECK, I_JUNK, I_BUDGET, T_NO_ANSWER). Only integers of the server's
  reach them: an exit code or signal number, a JSON-RPC error code in the
  range the spec reserves (any other code is not printed), and a count of
  stdout lines that were not JSON. Its stderr is read only to keep the
  pipe from filling, and dropped. Its serverInfo name and version, and an
  error's message, are never printed.
- The to-do for a server that did not answer names its command, never
  its args or env, to run in a terminal to see its own messages.
- Removed as dead: mask(), shown(), REDACTIONS, MASK_MIN, STDERR_KEPT,
  SHOWN_MAX, NAME_MAX.
- no_server_text_printed: four stubs (one answers, one answers with an
  error, one exits, one stays silent) put every value they are given
  everywhere a server's text can go. That covers their env (multi-line,
  quoted and backslashed, and short), an inherited value, an arg, and an
  unreserved error code. The forms are raw, repr, JSON, an argparse line,
  a stderr flood past 64 KB, stdout lines, a notification, their own name
  and version, an error's message and data, and an unfinished line at
  exit. Every line printed and every ledger line must match FIXED_LINES,
  whose only holes are a CSA name, a client, an integer and the command.
  No 4-character run of any value may appear, with or without a ledger.

Also from the review:
- (5) group_alive's "always False" mutant survived, leaving a live
  grandchild. orphan_child_is_stopped now covers it: a server that exits
  by itself on EOF but leaves a child in its group.
- (6) The total run time was unbounded: per-client envs defeat
  de-duplication, and each Claude Code local-scope entry adds a launch.
  VERIFY_BUDGET = 120 s now holds the launches together. A launch that
  could run past it (launch_max(), 26 s) is not started, and is reported
  "not checked". Covered by time_budget_bounds_the_launches.
- (7) A link named otherwise to a Python console-script launcher (pipx)
  was a "direct executable" and was launched, because LAUNCHERS matched
  the basename only. executable_kind now checks the realpath's basename
  too, so plan, apply and verify all leave it. Covered by
  launcher_behind_another_name_left.
- (8) The setsid grandchild that escapes the group stays documented: in
  end()'s docstring, and now in ENGINEERING.md.
- (10) gemini_drops' docstring said the opposite of what it returns; it
  now says it.

ENGINEERING.md's "What it prints" and "Run time" now say all of this.

The plan's "skip masking" mutation has nothing left to break, so its
place is taken by the leak it stood for: print what the server left on
stdout at its exit (exits_before_answering_masked).

Tests: 4 new cases, 141 in all, passing on python3 and /usr/bin/python3.
Against bbb6f82's script, no_server_text_printed,
exits_before_answering_masked and launcher_behind_another_name_left
fail. The orphan and budget cases are proven by their mutations.
--self-test: 134 mutations, all caught (3 masking ones retired, 7
added). ./tools/check-all.sh: exit 0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…le as well as its Python, and caps the count of lines it skipped at 1000

The two lows from the re-review of c2678ee, which approved Task 3:

- For an interpreter-form registration (`python -m <module>`), the to-do
  said to run the bare Python, which opens a prompt and shows no server
  messages. command_of() now appends the pinned `-m <module>`, taken from
  SERVERS, never from the registration, and still never its other args
  or its env. interpreter_form_todo_names_its_module covers it. Its
  module is a stub: the test's "python" puts a stub package first on its
  path and runs with -S, so a real CSA server installed for this Python
  is never what starts.
- The count of stdout lines skipped as not JSON was unbounded, the
  widest integer channel a server has into a line. Above 1000 it is now
  shown as "more than 1000" (JUNK_SHOWN_MAX). junk_count_capped covers
  it at 1000 and at 1502 lines.
- FIXED_LINES is tightened to match. Each integer hole is now no wider
  than its channel: an exit code of 1-3 digits, a signal of 1-2, an
  error code in -32799..-32000, and a count of 1-1000 or
  "more than 1000". The to-do may add only a SERVERS module.

ENGINEERING.md says both.

Tests: 2 new cases, 143 in all, passing on python3 and /usr/bin/python3.
Both fail against c2678ee's script. --self-test: 136 mutations, all
caught. ./tools/check-all.sh: exit 0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…point before asking, then repairs them after the server setups

Plan 2 Task 4 (macOS), #179. macos-ai-tools.sh, macos-update.sh and macos-plugins.sh
carry byte-identical functions: csa_registrations_dir, _py, _python, _log, _preview and
repair_csa_registrations.
- Each preflight's Internal MCP servers block prints the plan's header and the .py's
  `plan` rows before `each prints what it may do`. In -ai-tools this comes after the
  tool rebuilds.
- The last step of setup_csa_internal_tools runs `apply --approved` on exactly that
  plan file, behind the same gh gate. Then it runs `verify` without --run, which
  launches nothing while D5 holds.
- csa_on_exit removes the run's mktemp directory on every exit path.

Safe defaults kept (D1, D2, D4, D5 unanswered). The .py's constants are unchanged, so
VERIFY_ON_RERUN is empty and Desktop's config is not written while Desktop runs.

Parity (D3, "Ship macOS first", 2026-11-13). No main() step is added (A6), so
check-parity.py passes as before. Nothing is declared PLATFORM_ONLY. The Windows half
is #184's Task 4W. wiring_windows_twin_exists reports it as a SKIP on every run, and
fails if only some of the three .ps1 define the twins. Task 5 records it in TODO.md
and on #184.

Tests: 19 wiring_ cases in tests/test_mcp_registrations.py. 18 fail on bca2547; the
Windows-twin case SKIPs by design. 28 wiring mutations in --self-test are each caught.
Step 5's Plan 1 gap is #199.

Departures from the plan:
- A sixth shared function, csa_registrations_log. It sends the .py's `log` lines to the
  debug log only, through csa_redact, and only when CSA_DEBUG made a log.
- csa_on_exit is shared by five scripts (check-duplication), not three. So
  macos-work-tools.sh and clone-and-claude.sh get the same line, where it does nothing.
  Both versions are bumped.
- `unset CSA_REG_DIR` goes before `trap csa_on_exit EXIT` in all five. csa_on_exit
  removes CSA_REG_DIR with rm -rf, so an inherited value would have been used and then
  removed (P1).
- With no plan file, apply gets a plan with no findings, not a zero-byte file. A
  zero-byte file makes apply say the agreed plan "could not be read", which is untrue
  when no plan was shown (P2).
- A CSA_REGISTRATIONS_PY that is not a readable file is reported as skipped. It is
  never silently replaced by HEAD's copy (P2).
- `uv python find --system "$CSA_PYTHON_PREFERRED"`: --system so that a project's .venv
  in the caller's directory is not chosen (A11's reasoning).
- The repair streams each line as the .py prints it, so a check D5 later allows is not
  a silent wait. A failed step is reported by its exit code.
- curl has --max-time 60, and an empty download counts as a failure.
- The case names carry a wiring_ prefix. The runner has a SKIP outcome.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he held server check names no command the run deletes, a download that is not Python is skipped in one line, and a left finding is said once

The review of f18337c (Plan 2 Task 4).

- M2 (consent). End of input at `Proceed…? [Y/n]` was taken as yes, and a run in a pty
  then went on to re-point a config.
  - All four bash `confirm` copies now read with `|| return 1`.
  - All four PowerShell `Confirm-Step` copies now answer `$null` from Read-Host with
    no, and log it as a closed input.
  - Measured on pwsh 7.6: Read-Host returns $null at end of input, and `$null -eq ''` is
    false, so the .ps1 already answered no there. The change makes that explicit and
    logs it truthfully; it used to log `answered: ''`. Windows PowerShell 5.1 is not
    measured.
  - Tests: test_headless.py checks for every macOS confirm that end of input answers
    no, Enter alone yes, and n no. A control shows the shipping confirm without the
    guard answers yes. tests/ConfirmStep.Tests.ps1 is new: four cases per .ps1, with
    the same control.
  - Before the fix, the bash case failed on all four scripts. The .ps1 case failed on
    its log line only.
- M1 (honesty). The held server check no longer says to run `verify --run`, because the
  run deletes its copy of the .py. It now reads: `server check held: this run launched no
  CSA server; whether a rerun should is not decided yet (#179, D5)`. I_HELD_SOME is
  reworded the same way. The by-hand command goes into Task 5's docs.
- L1. With no ledger, a to-do already printed as a warning is not printed again as an
  info line. New case: left_finding_printed_once_without_ledger.
- L2. The entry scripts parse the download (`ast.parse`, which runs none of it) before
  using it. HTML from a network sign-in page now gives one skip row in the plan and one
  line at the repair, not three tracebacks. New case: wiring_download_not_python_skipped.

Mutations added: 2 for the .py and 2 for the wiring, each caught. The L3 EXIT-trap /
set -u issue is left to the coordinator, as ruled.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ers as the audit does, and skip in one line a file that is not it, or that hangs

The re-review of 8dc8699, item 1. A file that `ast.parse` accepts but that is not the
audit used to run and fail in a noisy way. A file with no `plan` printed "audit failed",
two argparse usage errors and two "exited 2" warnings. A file that does nothing printed
only "re-pointing what the plan showed", and said nowhere that nothing was checked.

csa_registrations_usable now asks the file about its interface, before the preview and
before the repair. Every question runs within 10 s.
- `--version` must print a version in the form every script here declares.
- `plan`, `apply` and `verify` must each answer `--help` with a usage line that names
  that command. The exit code alone is not enough: argparse answers `--help` with 0 even
  after a word it does not know, so a program with no commands passed that test (found
  while testing).

A file that fails any of these gets one skip row in the plan and one line at the repair,
and none of its steps runs.

csa_registrations_bounded is the 10 s watchdog, which the interpreter probe now shares.

The `ast.parse` step is dropped. HTML fails to compile at `--version`, before anything
runs, so a separate parse step was a guard no test could see fail (ADR-005).
wiring_download_not_python_skipped still pins the HTML case.

Tests:
- wiring_not_the_audit_skipped covers four files that are Python but not the audit:
  one that does nothing, another program, the same commands at another version, and one
  that knows plan only. Each is refused by a different check.
- wiring_interface_probe_bounded: a file that hangs is skipped after 10 s.
- wiring_real_py_passes_the_probe: the shipping .py passes the probe, so a change to its
  version form or its commands fails here, rather than quietly skipping the audit on
  every Mac.
- Seven new wiring mutations, each caught; the two parse mutations are retargeted at
  the probe.

The branch is rebased onto main 87d4280 (#196, #197). Only SCRIPT_VERSION lines
conflicted, and they now carry the time of the rebase. check-duplication is clean, and
#197's tests pass on the merged scripts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n in place and holds its server check until D5 is decided, and the Windows halves are on #184

Plan 2, Task 5. The subject is the plan's, with "until measured" changed to
"until D5 is decided": M5 has measured the launch (2026-11-13), and what holds the
check now is the CINO's answer. The .py's own held line was reworded the same way,
under P2 (honesty of what we claim).

- ENGINEERING.md: a new "Registration audit and repair" section under The CSA
  contracts, absorbing Task 3's server-check subsection: what a macOS run does,
  what is read, the reasons verbatim, what apply changes and never touches, D1-D5
  with their constants, Claude Code's lock, the Desktop-running skip, backups (the
  shared name and prune, secrets at the file's mode, xattrs and ACLs dropped), the
  credential rule, run time (bounds; real-machine time not measured yet), how to
  run plan and verify --run by hand from a checkout, and the macOS-only gap. Also
  the scripts list, Layout, the test count (21), and SERVERS as a seventh copy of
  the server list.
- AGENTS.md: the "who registers it" trap says this repo now repairs existing
  registrations on macOS, and never creates one.
- FRICTION.md: 007 argv visible to every account, 008 narrowest scope wins,
  009 a launch check can act on an account (M5).
- TODO.md: the #184 row gains 1W, 4W, G1W, G2W, 6W, the companion and D3's answer;
  new P1 records the macOS-only gap.
- README.md, BACKUP-RESOURCES.md: what a rerun does for a user, the new backups.
- The Windows companion: 4W's Python said Plan 1's Find-CsaPython, which lands in
  windows-ai-tools.ps1 only; now a self-contained resolver in all three. Its
  function list and test name are brought up to the macOS build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ce line, each in the foreground under a 10 s perl alarm, so no exported setting skips the real audit and a Ctrl-C leaves nothing running

The delta review of c5308c3. The ruling was to simplify, and not to parse argparse output.

- The real .py failed the probe when FORCE_COLOR was set on Python 3.14, which colours the
  usage line, or when COLUMNS=40, which wraps it. The audit was then skipped as "a network
  sign-in page". The .py now writes `--interface`
  (`csa-mcp-registrations interface 1: plan apply verify`) and `--version` itself, each
  alone on one line and outside argparse, so no environment changes them. Measured
  unchanged on 3.14 and 3.9 under FORCE_COLOR, COLUMNS=40 and 12, NO_COLOR and TERM=dumb.
  The probe asks only these two questions.
- A Ctrl-C during a hung probe ended the script but left the Python child running,
  because a background job ignores SIGINT. Each probe, and the Python-candidate check,
  now runs in the foreground under
  `perl -e 'alarm shift; exec { $ARGV[0] } @argv or exit 127' 10 …`. The alarm outlives
  the exec, so SIGALRM ends the command, and a Ctrl-C reaches it. The watchdog is gone:
  no background job, no kill, no trap.
- kill -9 reached only the Python, not a child it spawned. That kill is gone too.
  SIGALRM, like a Ctrl-C, still reaches only the process it is sent to, so a child the
  probed file starts is not stopped with it. Neither question starts one, and the
  comment and ENGINEERING.md say so.
- The comment that every preflight run was bounded was wrong. It now says exactly what
  is bounded here, the candidate probes and the two questions, and that plan, apply and
  verify bound their own steps.
- With no perl, both the preview and the repair skip in one line, and no Python is run.

Departure from the ruling's literal one-liner: `exec { $ARGV[0] } @argv or exit 127`, not
`exec @ARGV`. Measured: when the exec fails, the bare form lets perl exit 0, which reads as
a pass. The block form never goes through a shell.

Tests:
- wiring_real_py_passes_the_probe runs the real .py under seven environments, including
  FORCE_COLOR=1, COLUMNS=40, COLUMNS=12, NO_COLOR and TERM=dumb.
- wiring_ctrl_c_stops_a_hung_probe sends SIGINT to the run's process group while the
  probe hangs. The run ends, and no Python survives; on c5308c3 one did.
- wiring_perl_missing_skipped.
- wiring_not_the_audit_skipped covers five files, refused by version, by interface, or by
  interface number.
- wiring_interface_probe_bounded now hangs a file at each question in turn. A first run
  of the suite showed that a file hanging at --version never reaches --interface, so the
  mutation taking --interface outside the bound went uncaught.
- Mutations: two for the .py (each line routed back through argparse, caught only at
  COLUMNS=40 and COLUMNS=12), and seven for the wiring. The four that tested the watchdog
  and the --help parsing are removed or retargeted.

Docs: ENGINEERING.md's preview steps, run-time bounds and by-hand commands, and the
Windows companion's description of the macOS build, now describe this mechanism (Task 5's
ff0d957 had described the --help probe).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…c18d superseded it, and the Windows companion's Task 1W carries everything #184 was told to build and measure

The review of ff0d957 and 548c18d (approve, with doc follow-ups):
- plans/2026-11-12-registration-repair.md: D3 records the CINO's answer, verbatim
  "Ship macOS first (Recommended)" (2026-11-13), and its safe default no longer
  applies; Task 4's 10 s watchdog text is marked superseded by 548c18d (a perl alarm
  in the foreground; --version and --interface); windows_twin_exists is spelled as
  built, wiring_windows_twin_exists.
- plans/2026-11-12-registration-repair-windows.md: D3's answer; Task 1W gains the
  #184 comment's list: M1 on Windows, Confirm-Step under 5.1, M5 on Windows, the
  POSIX-only parts of the .py as built, the Windows CI job; it now says a BOM file
  is "not audited" today; CSA-Plugins#198 is written in full.
- ENGINEERING.md: D5 is pinned by two tests (no_check_rows_while_held too); the
  temp file is created 0600 and set to the config's mode before any byte is written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d registrations with every setting kept, a second changes nothing

Task 6 Step 1 of plans/2026-11-12-registration-repair.md (#179 Plan 2): the
isolated acceptance, recorded in
plans/reviews/2026-11-12-registration-repair-acceptance.md. Step 2, the real
run on the CINO's Mac, waits for his go-ahead after the merge.

- scripts/macos-plugins.sh at 628f000 ran whole, in a pseudo-terminal, with
  "y" typed at its consent prompt. It ran in two scratch worlds from one seed,
  one per stub `ps` answer (Desktop running / not running).
- Each world had its own mktemp HOME, CLAUDE_CONFIG_DIR, CODEX_HOME, TMPDIR,
  XDG_* and getconf cache dir.
- The real codex 0.169.0 ran behind an argv logger. The real installed CSA
  binaries were symlinked as ~/.local/bin, and the gate setups, claude, gh,
  curl, uv, brew and ps were stubs.
- verify --run was run by hand, then the entry script again.
- 204 of 204 assertions pass. All eight seeded rows behave as the plan's
  table expects, with row 4 run both ways.
- The set re-pointed equals the set the plan showed.
- The env and every other field are identical, compared in process. Modes
  are kept, and each written config has one backup at its mode.
- No fake secret is in any screen or argv. codex was asked only
  `mcp list|get --json`, and gemini was never run.
- The second run wrote nothing and made no backup.
- The real Desktop, Codex and Gemini configs, ~/.local/bin and the token
  directories were stat'ed before and after: unchanged.
- Deviations, recorded: only -plugins ran end to end; the gate setups did
  not run (they install); claude was a stub (its plugin steps clone and its
  csa-mcp step writes the seeded config).
- A first harness run's seed gave csa-google-workspace a non-URL allowlist,
  which the server refuses. That is recorded under Harness corrections; no
  code was changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…at proves it, the review history, and where the author is least sure

Written to CloudSecurityAlliance-Internal/CINO-Project-Management-Tools
system/templates/REVIEW-BRIEF.md, for the PR from feat/registration-repair.

- Where everything is, a stage table (evidence, plan, apply, verify, entry
  scripts, acceptance, docs and the gap) in place of a separate review map, and
  the commands with their expected results: 168 cases plus one SKIP on python3
  3.14 and Apple's 3.9, 182 mutations each caught, check-all exit 0 (701 s).
- 30 claims, each with a case or a command and what "true" means; the two with
  no automated check say so.
- The review history per task, with the reviewed (pre-rebase) tree and the
  fixing commit; the CINO's D3 verbatim; D1, D2, D4, D5 at their safe defaults;
  the AI's rulings with their rules; known limits; where the author is least
  confident; what is not verified.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…r's own check, and the token-file, debug-log and bare-name Desktop promises are each held by a test

The final whole-branch review of fc9614d (PR #201).

1. Minor. wiring_ctrl_c_stops_a_hung_probe failed whenever the suite ran with SIGINT
   ignored (a `&` job, nohup). The shell it starts inherited the ignore, which bash
   cannot undo, so the case's Ctrl-C never landed. Rig.start now resets SIGINT in a
   preexec_fn. Verified under `trap '' INT`: the case fails at fc9614d and passes now,
   on python3 and /usr/bin/python3, and the whole suite passes that way on both.
2. Nit. When the audit was skipped before consent, apply reported a dead entry as
   "found after you agreed to the plan". The scripts now mark the plan they hand apply
   `"audited": false`. Such a plan approves nothing, whatever it lists, and apply says
   `found by the repair's own check, because the plan you agreed to could not audit the
   registrations; not changed — run again`. New case: unaudited_plan_reason_is_honest,
   with two mutations, one approving what such a plan lists, one using the old reason.
3. Three new cases, each with a mutation:
   - token_file_never_opened: plan, apply (which re-points a registration carrying a
     token path) and verify --run each run under a Python audit hook. The hook records
     any `open` of four seeded token files; two of them are named by
     CSA_ZENDESK_TOKEN_FILE and CSA_GW_TOKEN, in the registrations' env and in the
     process's. A control shows the hook records an open. Mutation: open a token path a
     registration's env names.
   - bare_name_desktop_never_launched: verify --run, with a stub server of the entry's
     name first on the installer's PATH, launches nothing and says "not checked".
     Mutation: Desktop resolves on the installer's PATH (INHERITS_PATH), and the stub is
     launched.
   - wiring_no_value_reaches_the_screen_or_debug_log: preview and repair with the real
     .py, under CSA_DEBUG, on a fixture HOME whose registrations carry secret values. The
     dead entry is re-pointed and a skipped local entry is logged, yet no value reaches
     the screen or the debug log, and the repaired config keeps them. Mutation: put
     registration values into a log line.
4. The review brief:
   - Claim 8 names the new case.
   - Claim 20 names bare_name_desktop_never_launched in place of "no verify case".
   - The two "no automated check" claims now name their cases and mutations.
   - The open( list adds the CSA_TODO_FILE append (Todos.flush) and /dev/null (show).
   - The review history records this review, and the mutation count is now 188.
   ENGINEERING.md and the .py's docstring say what a plan marked `"audited": false`
   does.

CodeQL's test-fixture alerts are left to the coordinator, as asked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ny case past 120 s by name, and the macOS CI job fails at 20 minutes rather than running to the 6-hour default

The macOS job on PR #201 was cancelled at 15 minutes twice on bfa2aa6, with no log. Nothing
hung. In both attempts no runner was ever assigned: runner_name is empty and the job has
zero steps. The ubuntu and windows jobs got runners at once, and fc9614d's macOS job got
one within a second. GitHub's own annotations on the job say why:

  "The job was not acquired by Runner of type hosted even after multiple attempts"
  "Due to capacity constraints, jobs targeting macOS arm64 runners may experience longer
  queue times."

Reproduced anyway, as asked. The full suite was run in one process under CI-like
conditions: a new session with no controlling terminal (perl POSIX::setsid), stdin
/dev/null, env -i with CI=true and GITHUB_ACTIONS=true, a fresh HOME, and ~/.local/bin
first on PATH. It passed on python3 (Homebrew 3.15 here) in 144 s and on /usr/bin/python3
(3.9.6) in 189 s, near fc9614d's 6 minutes in CI. Each of bfa2aa6's new cases also passed
alone under those conditions, in 0.1 to 2.6 s.

So that the next real hang fails fast, and by name:
- The runner prints each case's name to stderr, flushed, before the case starts.
- A per-case SIGALRM stops any case past 120 s (CSA_TEST_CASE_TIMEOUT overrides it). The
  case fails by name, and the run goes on. The handler raises a BaseException, so no
  `except Exception` can swallow it. Under PEP 475 the raise also ends a blocking wait or
  read. The slowest case takes 20.7 s (wiring_interface_probe_bounded, Apple's 3.9, no
  terminal).
- stdout is line-buffered, so a log that is cut off keeps what was printed.
- `--self-test` breaks the bound on purpose. wiring_python_probe_bounded, which takes about
  10 s, is run under a 2 s bound, and must fail by name within seconds with its name
  already on stderr. It did in 2.1 s, leaving no process.
- Each ok line now shows its time.
- lint.yml: `timeout-minutes: 20` on "venv on macOS (BSD mv, real uv)". Its comment says
  this does not cover a job that never starts.

No script changed, so no SCRIPT_VERSION is bumped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kurtseifried
kurtseifried merged commit 58c76d1 into main Nov 17, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant