Isolate each Pilcrow instance's mutable state #2

New issue

Closed

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

dikka commented

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

Owner

What to build

Give every configured Pilcrow hub an explicit mutable-state root. Production and development must be able to run at the same time with separate Pilcrow state, HTTP port, producer socket, browser route, and project-terminal identity while continuing to use the same normal Pi settings, models, resources, and session files.

Add a command-line state-directory option and matching PILCROW_STATE_DIR environment variable. The configured state root owns Pilcrow catalogs, workspace records, placements, acknowledgements, drafts, and settings introduced by later tickets. It does not replace Pi's session-directory resolution and must not grow into an instance-name or profile framework.

The current hub already accepts explicit port and producer-socket configuration, while development still defaults to production catalog state. Follow the existing operational configuration style and keep the foreground hub as the only Pilcrow process required in normal use.

Acceptance criteria

A hub started with an explicit state directory reads and writes Pilcrow mutable state only beneath that directory.
PILCROW_STATE_DIR and the command-line option have documented deterministic precedence and reject invalid paths with bounded startup diagnostics.
The development launcher supplies development-specific Pilcrow state, socket, port, route, and terminal identity without partitioning Pi-owned resources.
Two configured hubs can use separate Pilcrow state without overwriting each other's catalogs or terminal authority.
Existing default production behavior remains available when no state-directory override is supplied.
Focused configuration and development-launcher tests pass, followed by vp check.

Blocked by

None (can start immediately).

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 Give every configured Pilcrow hub an explicit mutable-state root. Production and development must be able to run at the same time with separate Pilcrow state, HTTP port, producer socket, browser route, and project-terminal identity while continuing to use the same normal Pi settings, models, resources, and session files. Add a command-line state-directory option and matching PILCROW_STATE_DIR environment variable. The configured state root owns Pilcrow catalogs, workspace records, placements, acknowledgements, drafts, and settings introduced by later tickets. It does not replace Pi's session-directory resolution and must not grow into an instance-name or profile framework. The current hub already accepts explicit port and producer-socket configuration, while development still defaults to production catalog state. Follow the existing operational configuration style and keep the foreground hub as the only Pilcrow process required in normal use. ## Acceptance criteria - [ ] A hub started with an explicit state directory reads and writes Pilcrow mutable state only beneath that directory. - [ ] PILCROW_STATE_DIR and the command-line option have documented deterministic precedence and reject invalid paths with bounded startup diagnostics. - [ ] The development launcher supplies development-specific Pilcrow state, socket, port, route, and terminal identity without partitioning Pi-owned resources. - [ ] Two configured hubs can use separate Pilcrow state without overwriting each other's catalogs or terminal authority. - [ ] Existing default production behavior remains available when no state-directory override is supplied. - [ ] Focused configuration and development-launcher tests pass, followed by vp check. ## Blocked by - None (can start immediately). > **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:37 +00:00

dikka referenced this issue

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

Persist terminal-observed sessions as workspace records #4

dikka added a new dependency

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

#4 Persist terminal-observed sessions as workspace records

dikka commented

2026-08-28 21:11:57 +00:00

Author

Owner

Implemented in jj revision de256050 (feat(hub): add configurable Pilcrow state directory isolation).

What changed:

Added --state-dir and PILCROW_STATE_DIR with deterministic CLI > environment > XDG/home-default precedence, absolute-path/control-character/UTF-8-size validation, and bounded startup diagnostics.
Rooted the saved-project catalog under the configured Pilcrow state directory.
Included the state root in project-terminal identity so separate Pilcrow instances cannot claim the same terminal session.
Gave the development launcher isolated Pilcrow state/socket defaults while preserving shared Pi settings, models, resources, and session files.
Documented production/development behavior and added focused configuration, catalog, terminal, launcher, and hub tests.

Validation:

Focused state/config/catalog/terminal/dev-launcher suites passed.
Full suite passed: 59 files / 395 tests.
Hub TypeScript build passed and runtime hub artifacts were regenerated.
Changed files passed formatting/type validation; git diff --check passed.

No dev server was managed and no Pi-owned data was migrated or rewritten.

Implemented in jj revision `de256050` (`feat(hub): add configurable Pilcrow state directory isolation`). What changed: - Added `--state-dir` and `PILCROW_STATE_DIR` with deterministic CLI > environment > XDG/home-default precedence, absolute-path/control-character/UTF-8-size validation, and bounded startup diagnostics. - Rooted the saved-project catalog under the configured Pilcrow state directory. - Included the state root in project-terminal identity so separate Pilcrow instances cannot claim the same terminal session. - Gave the development launcher isolated Pilcrow state/socket defaults while preserving shared Pi settings, models, resources, and session files. - Documented production/development behavior and added focused configuration, catalog, terminal, launcher, and hub tests. Validation: - Focused state/config/catalog/terminal/dev-launcher suites passed. - Full suite passed: 59 files / 395 tests. - Hub TypeScript build passed and runtime hub artifacts were regenerated. - Changed files passed formatting/type validation; `git diff --check` passed. No dev server was managed and no Pi-owned data was migrated or rewritten.

dikka closed this issue

2026-08-28 21:11:57 +00:00