One client owns a Mini App at a time #254

Activity

1. Fectivnfy112357

   added

   ready-for-agentFully specified, ready for an AFK agentFully specified, ready for an AFK agent

   miniappWebUI Mini App hosting programme (ADR 0020)WebUI Mini App hosting programme (ADR 0020)

   on Oct 26, 2026
2. Fectivnfy112357

   marked this as blocked on Oct 26, 2026

   • Mini App loopback credential guard and readiness #253
3. Fectivnfy112357

   added a parent issue on Oct 26, 2026

   • WebUI hosting for Mini Apps (ADR 0020) #251
4. Fectivnfy112357

   added 2 commits that reference this issue on Oct 26, 2026

   feat(webui): take Mini App ownership through an exclusively bound end…

   ...

   eb61713

   feat(webui): refuse a Mini App another client owns before spawning it

   ...

   e3cc29e
5. Fectivnfy112357 commented on Oct 26, 2026

   

   Fectivnfy112357

   on Oct 26, 2026

   Author

   More actions

   All four remaining criteria are proven and implemented; the fifth moved to #256 with your agreement
   because the surface that would show it does not exist yet.

   Branch feat/miniapp-ownership-probe, commits 85c94c49 → eb617131 → e3cc29e9, stacked on #262.

   1. A second client does not spawn a Mini App whose ownership record is live

   prepareRuntime takes ownership before the port loop and before any spawn
   (node-runtime.ts, acquireMiniAppOwner). A held endpoint throws
   MiniAppNodeRuntimeError('OWNED_ELSEWHERE', 'Mini App <id> is already running in <client> (pid <pid>)').

   Proven through the scripted-child harness
   (packages/local-runtime-v2/test/unit/miniapp/node-runtime-credential.test.ts):
   refuses a Mini App another client owns, without spawning a process — the second preparation rejects
   with OWNED_ELSEWHERE and the second child receives no init message at all.

   2. A record left behind by a crashed owner is reclaimable

   The proof is an exclusively bound endpoint per Mini App: a socket file on POSIX, a named pipe on
   Windows, named from the plugin id. Binding is the ownership; the OS releases it when the owner dies, so
   "record present, nobody listening" is stale by definition rather than by timestamp.

   The crash path is the interesting one: a dead owner leaves the socket file behind, so a failed bind is
   distinguished from a leftover by connecting. reclaims an endpoint left behind by an owner that died
   creates a real socket, closes the server without unlinking, and the acquisition succeeds.

   ADR 0020's ownership section now records this mechanism, including why this code does not copy the
   OAuth lease server's rm(endpoint) before binding: that would steal a live owner's endpoint.

   3. A Mini App already running outside the record is detected through its derived port

   probeMiniAppPortOwnership answers free | guarded | foreign — the guard's answer, not a bare connect:
   free for a closed port, guarded when the port answers 401 to an anonymous health request, foreign
   when something holds the port and does not answer like the guard, so a stray listener is never mistaken
   for a Mini App. Three cases in loopback-guard.test.ts run against a closed port, the guarded fixture,
   and a plain node:http server in a child process.

   4. Two different Mini Apps may be owned by two different clients at once

   Ownership is per plugin: lets two different Mini Apps be owned at the same time, and the endpoint is
   named from the plugin data directory rather than a global path.

   Moved to #256: reporting the refusal in the listing and the picker

   The ticket body now says so. Reason: the WebUI's Mini App service is not enabled yet
   (wiring.miniAppService), and ADR 0020 requires the cell, the presenter and the view to land as one
   change. A listing presentation built now would be unreachable code. What #256 receives is the readable
   refusal — client and pid — which this branch already produces.

   Gates at e3cc29e9

   $ pnpm run test:capabilities
   Test Files  237 passed (237)
        Tests  5833 passed | 18 skipped (5851)
   $ pnpm typecheck            # passed
   $ pnpm check:source         # 5457 files, passed
   

   Not run: pnpm verify in full; browser and release-package steps are left to CI. No PR was opened for
   this branch — it rides behind #262 and the ownership work continues into #255's consumer.

   Untested boundary

   The desktop client writes no ownership record, so its presence is detected only by its port answering
   like the guard. That is the whole of what criterion 3 can promise, and it is stated in ADR 0020.
6. Fectivnfy112357

   closed this as completedon Oct 26, 2026
7. Fectivnfy112357

   added 3 commits that reference this issue on Oct 26, 2026

   feat(webui): probe a derived Mini App port before spawning

   ...

   28b5eb8

   feat(webui): take Mini App ownership through an exclusively bound end…

   ...

   2a462c4

   feat(webui): refuse a Mini App another client owns before spawning it

   ...

   fb56967