fix(workspaces): make managed runtimes reliable across restarts (#11740)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Execution workspaces need isolated databases, ports, and runtime
services
> - Concurrent workspaces could reuse ports or lose service ownership
after a restart
> - A markerless worktree also needed seed recovery, but normal
markerless instances still needed to boot
> - This pull request makes seed, port, and service ownership state
explicit and recoverable
> - It also checks live process and listener identity before it reclaims
shared resources
> - The benefit is reliable workspace startup, restart, adoption, and
concurrent provisioning

## Linked Issues or Issue Description

**What happened?**

Managed workspaces could lose runtime service ownership after a
control-plane restart. Concurrent worktrees could also reuse a port when
their parent paths differed. A seed recovery change made every
markerless instance resolve a worktree seed source, so normal instances
without a source could not start.

**Expected behavior**

Paperclip must preserve healthy managed services across restarts. It
must reserve unique ports across worktree parents. It must provision a
registered markerless worktree, but it must skip seed work for a normal
markerless instance.

**Steps to reproduce**

1. Start two managed worktrees under different parent paths at the same
time.
2. Restart the control plane while a managed service stays alive.
3. Start Paperclip with a config that has no seed markers and no
registered worktree source.
4. Observe duplicate port selection, lost service adoption, or a
seed-source startup error.

**Paperclip version or commit**

Current `master` plus the workspace runtime reliability changes in this
pull request.

**Deployment mode**

Local development with managed execution workspaces and embedded
Postgres.

## What Changed

- Added a shared port registry with lease heartbeats, process identity
checks, and live listener probes.
- Reserved worktree ports across custom parent paths and repaired
duplicate legacy assignments.
- Preserved and adopted healthy managed services across control-plane
restarts.
- Reconciled guest bind modes and verified listener ownership before
termination or reuse.
- Provisioned registered markerless worktree databases and kept normal
markerless instance startup as a no-op.
- Added CLI, shared, server, and shell regression tests for seed, port,
listener, restart, and adoption behavior.
- Updated the worktree development documentation.

## Verification

- `pnpm exec vitest run cli/src/__tests__/worktree.test.ts
--reporter=verbose` — 63 tests passed.
- `pnpm exec vitest run
packages/shared/src/worktree-port-registry.test.ts --reporter=verbose` —
5 tests passed.
- Focused runtime Vitest set — 199 tests passed across 37 suites.
- `node --test scripts/__tests__/provision-worktree-self-heal.test.mjs`
— 10 tests passed.
- `git diff --check` passed.

## Risks

- Port reservation now depends on lease and process identity data. The
fallback listener probe prevents early reclamation when process metadata
is incomplete.
- Runtime adoption is stricter about bind and owner identity. The tests
cover healthy adoption, stale records, PID reuse, and unrelated
listeners.
- Markerless seed detection now separates registered worktrees from
normal instances. The tests cover both paths.
- There are no database schema migrations.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex with the `gpt-5` model family. The serving snapshot and
context-window size are not exposed. The agent used reasoning,
repository tools, code execution, and test execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Dev Agent <dev@paperclip.ing>

packages/shared/src/runtime-exposure/loopback-bind.test.ts

@@ -13,16 +13,16 @@ describe("forceLoopbackBindInCommand", () => {
     // PAP-17256 reproduction: this is verbatim what `workspace_runtime_services`
     // recorded for every lane the broker denied.
     expect(forceLoopbackBindInCommand("pnpm dev --bind lan")).toBe(
-      "pnpm dev --bind custom --bind-host 127.0.0.1",
+      "pnpm dev --bind loopback",
     );
   });
 
   it("replaces an existing loopback-adjacent bind rather than duplicating it", () => {
     expect(forceLoopbackBindInCommand("pnpm dev --bind tailnet")).toBe(
-      "pnpm dev --bind custom --bind-host 127.0.0.1",
+      "pnpm dev --bind loopback",
     );
     expect(forceLoopbackBindInCommand("pnpm dev --bind custom --bind-host 10.0.0.4")).toBe(
-      "pnpm dev --bind custom --bind-host 127.0.0.1",
+      "pnpm dev --bind loopback",
     );
   });
 
@@ -33,7 +33,7 @@ describe("forceLoopbackBindInCommand", () => {
 
   it("handles the =-separated spelling", () => {
     expect(forceLoopbackBindInCommand("pnpm dev --bind=lan --bind-host=0.0.0.0")).toBe(
-      "pnpm dev --bind custom --bind-host 127.0.0.1",
+      "pnpm dev --bind loopback",
     );
   });
 
@@ -41,7 +41,7 @@ describe("forceLoopbackBindInCommand", () => {
     // A bare `pnpm dev` lets an old guest runner infer its bind from HOST, so the
     // flags must be added rather than assumed.
     expect(forceLoopbackBindInCommand("pnpm dev")).toBe(
-      "pnpm dev --bind custom --bind-host 127.0.0.1",
+      "pnpm dev --bind loopback",
     );
   });
 
@@ -49,19 +49,19 @@ describe("forceLoopbackBindInCommand", () => {
     // `isPaperclipDevRuntimeService` matches `--tailscale-auth` as a substring;
     // an explicit `--bind` already beats the alias in every dev-runner version.
     expect(forceLoopbackBindInCommand("pnpm dev:once --tailscale-auth")).toBe(
-      "pnpm dev:once --tailscale-auth --bind custom --bind-host 127.0.0.1",
+      "pnpm dev:once --tailscale-auth --bind loopback",
     );
   });
 
   it("never strips a value that is actually the next flag", () => {
     expect(forceLoopbackBindInCommand("pnpm dev --bind --verbose")).toBe(
-      "pnpm dev --bind --verbose --bind custom --bind-host 127.0.0.1",
+      "pnpm dev --bind --verbose --bind loopback",
     );
   });
 
   it("does not touch a --bind occurrence that is not a flag boundary", () => {
     expect(forceLoopbackBindInCommand("pnpm dev --no--bind lan")).toBe(
-      "pnpm dev --no--bind lan --bind custom --bind-host 127.0.0.1",
+      "pnpm dev --no--bind lan --bind loopback",
     );
   });
 
@@ -74,8 +74,9 @@ describe("forceLoopbackBindInCommand", () => {
     expect(forceLoopbackBindInCommand(fixture)).toBe(fixture);
   });
 
-  it("uses the loopback host constant", () => {
-    expect(forceLoopbackBindInCommand("pnpm dev")).toContain(RUNTIME_EXPOSURE_BIND_HOST);
+  it("uses the loopback preset without turning it into a custom bind", () => {
+    expect(forceLoopbackBindInCommand("pnpm dev")).toBe("pnpm dev --bind loopback");
+    expect(RUNTIME_EXPOSURE_BIND_HOST).toBe("127.0.0.1");
   });
 });