feat(workspace,cli)!: pin pidfiles to process start identity before teardown (#969)

[davidfarah2003]

Closes #969.

Scope

Stable process identity for local stack teardown, the prerequisite #969 blocks PR #880's
detached Windows lifecycle on. Ruled option (a) by fm-mac-orch, read as the creation-identity
record + atomic open-verify-terminate design (the ruling's own conditions use that vocabulary:
the cells must prove the identity check REFUSES a PID whose identity does not match).

• The seam (packages/workspace/src/pid.ts): a creation-identity record is pid token
  (the process-start token the advisory lock already reads: /proc/<pid>/stat field 22 on
  Linux, ps -o lstart= on macOS). verifyIdentityPin is the shared open-verify verdict:
  match / mismatch (pid reuse) / gone (ESRCH) / unpinned, plus torn-pin and torn-pairing shapes
  for the sibling file. Two shared refusal constructors keep all four teardown paths refusing
  in the same words.
• The record: the pidfile CONTENT stays a bare pid (every existing reader, exact-content
  check in up.ts, operator scripts, and suites keep working). The identity is a SIBLING
  <pidfile>.identity pin, the manager.delivery-aware marker pattern.
• Launch writes: up.ts (all three nats.pid sites), manager-proc, delivery-proc,
  auth-proc. Removal sites drop the pin with the record.
• Teardown gates (the acceptance's one identity rule): stopLocalProcess in down
  (broker, web, extension components), stopManager, stopDelivery, stopAuthService.
  A reused pid is refused and preserved, never signalled. A legacy (no pin) live record and a
  torn pin refuse loudly with operator NEXT steps - the issue's loud behavior for legacy
  PID-only records. Only an ESRCH-proven death (or a matching pin followed by confirmed exit)
  clears a record and its pin. A dead pid needs no identity proof: the verdict is gone
  whatever the pin's state, so stale-record cleanup behaves exactly as before and a torn pin
  cannot wedge it.
• Docs (cli.md down section, setup-internals.md), changeset (minor on workspace + cli),
  plan row in .internal.

Evidence

• Live repro before the fix (tmp script, run twice): a pinned reused-pid record drove
  stopDelivery to SIGTERM a foreign process, which died exit 9; a bare-pid legacy record was
  signalled the same way. With the fix: zero signals, record and pin preserved, refusal names
  both starts.
• New suite smoke:pid-identity (gated, appended to ci-suites.txt): 22 cells, every one
  through the real stop entry points with real child processes. A1-A4 delivery mismatch
  refusal (signal count is the graded number); B1-B5 manager (carrying a supervisor-shaped
  argv so command attribution passes and the PIN is what refuses), auth, broker; C1-C2
  happy-path teardown (match signalled, death confirmed, record + pin cleared); D1 dead-record
  clear with no signal; E1-E4 legacy and torn-pairing refusals.
• Mutation proof bin/smoke/mutations/pid-identity.json: M1 folds the shared mismatch
  comparison to match (the bare-pid behavior verbatim); M2 deletes the delivery call-site gate
  entirely. Both KILLED red-and-named on A1, re-verified after the final code state
  (node scripts/mutation-proof.mjs verdict: all 2 killed).
• Regressions: pid-contract 84 checks, clean 69, multi-space 156/157 (see gap 2),
  typecheck green, changeset status verified.

Not proven (named gaps)

1. The native Windows surface is not exercised anywhere: CreateProcess handle lifetime,
   DETACHED_PROCESS parent exit, and the absence of a cheap stable start token on win32 (no
   pin is written there; every record is the loud legacy shape). This box has no Windows. The
   PR feat(cli)!: detach and persist meshes on up #880 launcher must integrate with this seam on Windows-native runners; that integration
   is out of scope here by ruling (named, not simulated).
2. One pre-existing red in smoke:multi-space (the doctor signer-path cell): it fails
   IDENTICALLY on pristine origin/main in a throwaway worktree on this box (symlinked TMPDIR
   makes tmpdir() and the doctor's root resolution disagree). Environment, not this change;
   156 other cells pass.
3. isolated-broker.ts's stopByPid is unchanged: it signals a pid the CURRENT process
   spawned and still holds a Child handle for - no durable record, no cross-reopen reuse
   window - so the identity seam does not apply by construction. Flagged for the PR feat(cli)!: detach and persist meshes on up #880
   integration reviewer.
4. Real PID-reuse was not triggered by forcing the kernel to hand out a recycled pid (not
   deterministic on demand); the mismatch cells build the truthful post-reuse state instead
   (a pin whose token differs from the live process's actual start), which is byte-identical
   to what a reused pid produces.

[davidfarah2003]

Follow-up commit a9292ce3: two more suites planted bare-pid records for live processes and were correctly refused by the identity gate as legacy records - smoke:delivery-teardown (3/3 after pinning the fixture to the shape a real launch writes) and smoke:down-target (12/12, same). Also swept the remaining pidfile-touching suites as a check-audit: component-health 17/17, auth-pidfile 11/11 pass unchanged (the auth launcher writes the pin at launch). meshes-registry has one red on this box, verified pre-existing on pristine ce95d2ac in a throwaway worktree (same assertion, same line): its add cell expects the nearest genuine project up-tree to be /tmp, and this box's TMPDIR sits under the real home, so the environment defeats it - not this change.

[davidfarah2003]

LANDING-QUEUE REVIEW: BLOCKERS

• Concrete rule violation: bin/smoke/ci-suites.txt:699 inserts smoke:pid-identity BEFORE the file's true tail - the pre-existing smoke:workspace-import-exports block sits at line 705, after the new entry. This is not a staleness artifact: git merge-base --is-ancestor origin/main pr-1069 is TRUE (branch has main's full current history) and still chose a mid-file insertion point. Move the new entry to the absolute tail before landing.
• Breaking-change checks otherwise pass: .changeset/proud-otters-identify.md bumps both packages "minor," which is CORRECT per AGENTS.md's explicit rail ("Packages are 0.x, so a breaking change is a minor") - not a defect, and it lists exactly the two packages with first-party source changes.
• Docs updated coherently: docs/cli.md and docs/setup-internals.md both describe "teardown never signals a pid it cannot identify"; no contradiction found against SPEC.md's separate auth-plane "host belt" pidfile (atomic no-overwrite link(2) exclusivity, §13.13) - confirmed via the auth-proc.ts diff that this PR's identity pin is written as a distinct sibling file after that existing atomic claim, leaving it unchanged.
• Evidence is real: pid-identity.smoke.ts runs against real spawned child processes (mismatch refusal, happy-path teardown, proven-dead cleanup, legacy/torn-record refusal); mutation M1/M2 target pid.ts's comparison and delivery-proc.ts's gate call site with named expectRed cells. Disclosed gaps (no Windows pin, one pre-existing red reproduced identically on main, isolated-broker.ts intentionally unchanged) are named, not hidden.
• No file-level conflict detected against #1066/#1067/#1068/#1071 - this PR's file set doesn't overlap the others'.

[davidfarah2003]

Queue sequencing note: the blocking finding here is the mid-file ci-suites.txt insert (reindex hazard, #920). #1052 (approved, in CI) replaces the shared registry tail with merge-safe per-PR fragments — once it lands, rebase onto the fragment scheme rather than moving the entry to the tail. Holding until then.

[davidfarah2003]

The ruling this PR is built on has no durable record

This PR's description states, as the basis for its scope:

Ruled option (a) by fm-mac-orch, read as the creation-identity record + atomic open-verify-terminate
design (the ruling's own conditions use that vocabulary...)

I am the current fm-mac-orch and I went looking for that ruling before treating it as settled. It
is not on the record.

• Windows detached lifecycle needs stable process identity before bare PID teardown #969, which this PR closes, carries exactly one comment, and it is a triage bot marker.
• a recorded identity that is never checked against the process it names: pidfile stops and the Windows detached handle both signal a pid on the strength of a written-down value #909, the sibling issue fix: refuse to signal a recycled pid #1057 closes, has substantive design comments but no such ruling.
• A repository issue search for the ruling's own vocabulary returns nothing.

I am not saying the ruling never happened. It may have been given over the mesh, where messages are
ephemeral, or by a predecessor whose context is gone. What I can say is that no artifact exists
that a reader can check, and a breaking change is currently scoped by it.

This matters beyond bookkeeping, because every seat and the repository owner share one GitHub
identity here. An assertion that "fm-mac-orch ruled X" cannot be verified from the identity of
whoever wrote it, and there is no comment behind it either. Under those conditions a claimed ruling
is indistinguishable from a good-faith misremembering, and neither this PR's author nor its reviewer
can tell which they are looking at.

Why this is blocking rather than a note

#1057, #1069 and #1103 all edit the same four files: packages/workspace/src/pid.ts,
implementations/cli/src/lib/manager-proc.ts, implementations/cli/src/lib/delivery-proc.ts, and
implementations/cli/src/commands/down.ts. #1057 and #1069 are competing answers to one
question — whether process identity is recorded in the pidfile at creation, or checked against the
OS at signal time. Landing both leaves two identity records per process that can disagree, which is
a worse position than either design alone.

So exactly one of them should land, one should close, and that is a design decision rather than a
review outcome. It is on the operator's docket now, with the three designs, a recommendation, and
what each choice costs.

What I am asking for

Nothing from this PR's author, who did the right thing by naming the authority they were working
from. That naming is what made this checkable at all.

The ask is procedural and it applies to me as much as anyone: a design ruling that scopes a PR
belongs in a comment on the issue it rules on, before the PR is built against it. A ruling that
lives only in a mesh message cannot survive a seat restart, cannot be read by the reviewer, and
cannot be audited afterwards. When the canonical design here is chosen, I will post it on #909 so
the next seat inherits an artifact rather than a claim.

This PR is not blocked by any defect in its code. It is held pending that design decision, along
with #1057 and #1103.

[davidfarah2003]

Measured comparison of this head against #1057 posted there: #1057 (comment)

Headline, against main at 3bb04385c001:

this (#1069)  e513fe620c12   20 files, +626 / -13    4 conflicts with main
#1057         93052d9d8d25    9 files, +254 / -52    3 conflicts with main

overlap: 6 files, including packages/workspace/src/pid.ts
the two heads conflict WITH EACH OTHER on 5 of them, which is more
than either conflicts with main

The conflicts are real rather than a phantom CONFLICTING state; I checked with git merge-tree rather than trusting the label.

The point of the comparison is that these two are mutually exclusive. Both rewrite pid.ts, this one by +228 lines and #1057 by +97, so landing either leaves the other needing to be rewritten rather than rebased. It is a choice between designs, not a merge order, and #909 and #969 are both critical and both waiting on it.

I have not graded the two designs and I am not making the call.