lab/pilcrow

Watch

Fork 0

Persist terminal-observed sessions as workspace records #4

New issue

Closed

opened 2026-08-28 19:24:37 +00:00 by dikka · 1 comment

dikka commented

2026-08-28 19:24:37 +00:00

Owner

What to build

Replace the hub registry's process-lifetime-only view with durable Pilcrow workspace session records for independently launched Pi sessions. When a TUI or other independent Pi runtime registers through the extension, Pilcrow creates or refreshes one record with its own opaque workspace identity, exact Pi identity and path when available, project directory, Pi-owned name, observed origin, timestamps, and bounded last-known presentation facts.

Pi remains authoritative for conversation files and names. Origin affects only runtime authority: Pilcrow observes independent processes but cannot stop or signal them. Closing the TUI leaves a stopped record that remains selectable after hub restart. A reconnect with the same exact session refreshes the record rather than creating a duplicate.

Persist the catalog atomically with private local permissions and serialized mutation, following the project's existing catalog safety principles. The browser should route and select by workspace identity rather than overloading the Pi session ID.

Acceptance criteria

A previously unknown connected TUI session creates exactly one durable observed workspace record.
The record survives browser closure, clean TUI exit, and hub restart and is shown honestly as stopped when no runtime owns it.
Reconnection of the same exact Pi session refreshes the existing record without changing its workspace identity.
Pi name changes are reflected; Pilcrow does not add a competing Rename action.
Pilcrow never exposes Stop authority for an independently launched runtime.
Nullable paths are supported for sessions that do not yet have a durable file.
Malformed catalog data and conflicting live ownership produce bounded diagnostics without damaging healthy records.
The real hub/SSE harness proves persistence and browser projection across a hub restart.

Blocked by

#2 — Isolate each Pilcrow instance's mutable state
#3 — Establish the next exact producer interface

Human checkpoint note: Do not request routine per-ticket approval. The implementing agent may make the internal architecture, refactoring, testing, and UI-detail decisions needed to satisfy the acceptance criteria. Pause only if implementation requires a material product or ownership change, a destructive or hard-to-reverse action, excluded security or deployment scope, credentials or spending, or a real-browser design fork with no safe default. Forgejo completion updates may be batched with the rest of the completed frontier. The user performs final hub and Pi restart steps. Agents must not start, restart, replace, or stop the user-run Pilcrow development server.

## What to build Replace the hub registry's process-lifetime-only view with durable Pilcrow workspace session records for independently launched Pi sessions. When a TUI or other independent Pi runtime registers through the extension, Pilcrow creates or refreshes one record with its own opaque workspace identity, exact Pi identity and path when available, project directory, Pi-owned name, observed origin, timestamps, and bounded last-known presentation facts. Pi remains authoritative for conversation files and names. Origin affects only runtime authority: Pilcrow observes independent processes but cannot stop or signal them. Closing the TUI leaves a stopped record that remains selectable after hub restart. A reconnect with the same exact session refreshes the record rather than creating a duplicate. Persist the catalog atomically with private local permissions and serialized mutation, following the project's existing catalog safety principles. The browser should route and select by workspace identity rather than overloading the Pi session ID. ## Acceptance criteria - [ ] A previously unknown connected TUI session creates exactly one durable observed workspace record. - [ ] The record survives browser closure, clean TUI exit, and hub restart and is shown honestly as stopped when no runtime owns it. - [ ] Reconnection of the same exact Pi session refreshes the existing record without changing its workspace identity. - [ ] Pi name changes are reflected; Pilcrow does not add a competing Rename action. - [ ] Pilcrow never exposes Stop authority for an independently launched runtime. - [ ] Nullable paths are supported for sessions that do not yet have a durable file. - [ ] Malformed catalog data and conflicting live ownership produce bounded diagnostics without damaging healthy records. - [ ] The real hub/SSE harness proves persistence and browser projection across a hub restart. ## Blocked by - #2 — Isolate each Pilcrow instance's mutable state - #3 — Establish the next exact producer interface > **Human checkpoint note:** Do not request routine per-ticket approval. The implementing agent may make the internal architecture, refactoring, testing, and UI-detail decisions needed to satisfy the acceptance criteria. Pause only if implementation requires a material product or ownership change, a destructive or hard-to-reverse action, excluded security or deployment scope, credentials or spending, or a real-browser design fork with no safe default. Forgejo completion updates may be batched with the rest of the completed frontier. The user performs final hub and Pi restart steps. Agents must not start, restart, replace, or stop the user-run Pilcrow development server.

dikka added the

ready-for-agent

label

2026-08-28 19:24:38 +00:00

dikka referenced this issue

2026-08-28 19:24:38 +00:00

Manage the complete browser-session lifecycle #5

dikka referenced this issue

2026-08-28 19:24:38 +00:00

Read known sessions as paged active-branch streams #6

dikka referenced this issue

2026-08-28 19:24:40 +00:00

Make placement and Later scheduling durable #8

dikka referenced this issue

2026-08-28 19:24:44 +00:00

Make Changes and the terminal project-owned #15

dikka added a new dependency

2026-08-28 19:24:46 +00:00

#2 Isolate each Pilcrow instance's mutable state

dikka added a new dependency

2026-08-28 19:24:46 +00:00

#3 Establish the next exact producer interface

dikka added a new dependency

2026-08-28 19:24:46 +00:00

#5 Manage the complete browser-session lifecycle

dikka added a new dependency

2026-08-28 19:24:46 +00:00

#6 Read known sessions as paged active-branch streams

dikka added a new dependency

2026-08-28 19:24:46 +00:00

#8 Make placement and Later scheduling durable

dikka added a new dependency

2026-08-28 19:25:10 +00:00

#15 Make Changes and the terminal project-owned

dikka commented

2026-08-28 22:02:12 +00:00

Author

Owner

Implemented in jj revision 45c5c54d (feat(workspace): persist opaque identities for observed Pi sessions).

What changed:

Added a bounded version-1 workspace-sessions.json catalog beneath the configured Pilcrow state directory, with serialized atomic replacement, private file permissions, strict startup parsing, bounded diagnostics, and no migration path.
Independently launched Pi producers create or refresh durable origin: observed records with stable opaque workspace IDs, exact nullable Pi session paths, Pi-owned identity/name, project cwd, timestamps, and bounded last-known presentation facts.
Disconnect and hub restart retain stopped selectable records while clearing transient busy/compacting/turn state; exact reconnect reuses the same workspace ID.
Exact non-null paths are the primary durable identity. Copied Pi JSONL files with the same declared Pi ID remain separate records; nullable-path transitions are accepted only when unambiguous.
Browser, HTTP, Changes, terminal, drafts, placement, notification, submit/render/reload, stop, and dismiss routing now require opaque workspace IDs. Pi IDs are retained only for explicitly named producer/launcher correlation.
Observed sessions never acquire Stop/signal authority. A stopped non-authoritative transient managed record converts safely to observed when an independent runtime later owns the same exact path.
Registry/catalog transitions are generation/owner fenced so delayed persistence, abrupt close, reconnect timers, and backward-moving clocks cannot resurrect dead authority or create invalid durable timestamps.

Audit and regression coverage:

Added copied-path, nullable-transition, ambiguity, duplicate-path, managed↔observed collision, delayed-write/abrupt-close/reconnect, persistence-failure, malformed-startup/no-rewrite, restart-state reset, catalog bound/capacity, exact route rejection, and real hub/SSE identity tests.
A post-implementation audit found identity conflation, mixed route lookup, managed-to-observed persistence loss, and an in-flight disconnect race; all were fixed before closure.
Supervisor validation then exposed a clock-regression race. Lifecycle timestamps are now monotonic per durable entry, with a regression test and 30 consecutive combined race-suite passes.

Validation:

Supervisor focused verification passed: 3 files / 67 tests.
Full suite passed: 61 files / 426 tests.
TypeScript no-emit check, hub build, production browser build, changed-file formatting checks, and git diff --check passed.
Whole-tree vp check remains blocked only by the same two unchanged pre-existing formatting findings in .dev/agents/triage-labels.md and web/review/ReviewWorkspace.tsx.

No Pi JSONL was rewritten, no compatibility migration was added, and no dev server was managed. Deployment still requires the documented user-run hub/browser/Pi restart sequence after the larger protocol rollout.

Implemented in jj revision `45c5c54d` (`feat(workspace): persist opaque identities for observed Pi sessions`). What changed: - Added a bounded version-1 `workspace-sessions.json` catalog beneath the configured Pilcrow state directory, with serialized atomic replacement, private file permissions, strict startup parsing, bounded diagnostics, and no migration path. - Independently launched Pi producers create or refresh durable `origin: observed` records with stable opaque workspace IDs, exact nullable Pi session paths, Pi-owned identity/name, project cwd, timestamps, and bounded last-known presentation facts. - Disconnect and hub restart retain stopped selectable records while clearing transient busy/compacting/turn state; exact reconnect reuses the same workspace ID. - Exact non-null paths are the primary durable identity. Copied Pi JSONL files with the same declared Pi ID remain separate records; nullable-path transitions are accepted only when unambiguous. - Browser, HTTP, Changes, terminal, drafts, placement, notification, submit/render/reload, stop, and dismiss routing now require opaque workspace IDs. Pi IDs are retained only for explicitly named producer/launcher correlation. - Observed sessions never acquire Stop/signal authority. A stopped non-authoritative transient managed record converts safely to observed when an independent runtime later owns the same exact path. - Registry/catalog transitions are generation/owner fenced so delayed persistence, abrupt close, reconnect timers, and backward-moving clocks cannot resurrect dead authority or create invalid durable timestamps. Audit and regression coverage: - Added copied-path, nullable-transition, ambiguity, duplicate-path, managed↔observed collision, delayed-write/abrupt-close/reconnect, persistence-failure, malformed-startup/no-rewrite, restart-state reset, catalog bound/capacity, exact route rejection, and real hub/SSE identity tests. - A post-implementation audit found identity conflation, mixed route lookup, managed-to-observed persistence loss, and an in-flight disconnect race; all were fixed before closure. - Supervisor validation then exposed a clock-regression race. Lifecycle timestamps are now monotonic per durable entry, with a regression test and 30 consecutive combined race-suite passes. Validation: - Supervisor focused verification passed: 3 files / 67 tests. - Full suite passed: 61 files / 426 tests. - TypeScript no-emit check, hub build, production browser build, changed-file formatting checks, and `git diff --check` passed. - Whole-tree `vp check` remains blocked only by the same two unchanged pre-existing formatting findings in `.dev/agents/triage-labels.md` and `web/review/ReviewWorkspace.tsx`. No Pi JSONL was rewritten, no compatibility migration was added, and no dev server was managed. Deployment still requires the documented user-run hub/browser/Pi restart sequence after the larger protocol rollout.

dikka closed this issue

2026-08-28 22:02:12 +00:00