@osolmaz/pi-workflows 0.16.2 → 0.16.4

package/docs/WORKFLOW_STEP_MESSAGES.md

@@ -6,7 +6,7 @@ Status: this is the implemented workflow-message contract. [Unify workflow messa
 
 Pi Workflows must add several kinds of content to an origin Pi conversation. These include interactive step prompts, protected human decisions, passive notifications, terminal results, and follow-up prompts. Initial, reminder, and resumed prompts are one step-message kind with different display reasons.
 
-The host saves all of them as workflow messages. One extension component sends them through documented Pi APIs. Feature records continue to own workflow results, answers, settings, and timeouts.
+The server saves all of them as workflow messages. One extension component sends them through documented Pi APIs. Feature records continue to own workflow results, answers, settings, and timeouts.
 
 The model receives complete instructions when a workflow message starts a turn. The user sees a compact card for structured workflow content and can expand it.
 
@@ -24,7 +24,7 @@ The message kinds are:
 | `terminal`     | Custom message that starts a model turn         | Final result and safe recovery choice            |
 | `followUp`     | Custom message that starts normal work          | Work saved for after successful completion       |
 
-The host stores one `WorkflowMessage` record before Pi can send it:
+The server stores one `WorkflowMessage` record before Pi can send it:
 
 ```ts
 type WorkflowMessage = {
@@ -45,9 +45,9 @@ type WorkflowMessage = {
 
 The exact Pi content and custom display details remain in the content-addressed value store. `contentDigest` binds the record to those bytes. `sourceId` links the message to the feature record that created it.
 
-`kind` determines the custom renderer, whether a model turn starts, and the host eligibility rule. The host does not store duplicate flags or message-to-message pointers for those facts.
+`kind` determines the custom renderer, whether a model turn starts, and the server eligibility rule. The server does not store duplicate flags or message-to-message pointers for those facts.
 
-`order` is the acceptance order for one origin session. The host marks one pending item as next in the origin-session view. An earlier ineligible or cancelled item does not block unrelated eligible work.
+`order` is the acceptance order for one origin session. The server marks one pending item as next in the origin-session view. An earlier ineligible or cancelled item does not block unrelated eligible work.
 
 A source lifecycle transaction can change `pending` to `cancelled`. Active-branch evidence changes `pending` or `cancelled` to `sent`; evidence wins because Pi already contains the entry. `sent` is terminal. A pending message can be new or uncertain after a process stopped, so the coordinator always checks the active branch before sending it.
 
@@ -118,26 +118,26 @@ Notifications keep the custom type `pi-workflows-notification` and use `triggerT
 
 ## One sender
 
-The extension has one `WorkflowMessageCoordinator` for all message kinds. The host keeps one active coordinator connection and process-local epoch for each origin session. A replacement connection fences the old one, so two Pi processes cannot send for the same session.
+The extension has one `WorkflowMessageCoordinator` for all message kinds. The server keeps one active coordinator connection and process-local epoch for each origin session. A replacement connection fences the old one, so two Pi processes cannot send for the same session.
 
 The coordinator follows this sequence:
 
-1. After every host connection, wait for the complete origin-session view and report the active branch before any send or turn report.
-2. Wait until the host view names the next eligible pending message, Pi is idle, and Pi has no queued user input.
+1. After every server connection, wait for the complete origin-session view and report the active branch before any send or turn report.
+2. Wait until the server view names the next eligible pending message, Pi is idle, and Pi has no queued user input.
 3. Save the message ID in the coordinator's queued map.
 4. Search the active Pi branch for the same hidden message ID and report a matching entry.
 5. Recheck synchronously that Pi is idle, has no pending input, the message is absent, and this connection still owns the active session epoch.
 6. Call `pi.sendMessage()` with no `await` between that final check and call.
 7. Wait until the new Pi entry is visible.
-8. Report the active branch so the host saves its Pi entry ID and marks the message `sent`.
+8. Report the active branch so the server saves its Pi entry ID and marks the message `sent`.
 
 The coordinator sends only one workflow message at a time. A poll can find work, but it cannot send an ID already in its queued map.
 
-Pi can emit `agent_start` before the host saves the new Pi entry ID. The coordinator keeps that start and any matching end in its in-memory session map. It first marks the workflow message `sent`, then reports the saved turn events in order. It does not drop a turn event while host confirmation is in progress.
+Pi can emit `agent_start` before the server saves the new Pi entry ID. The coordinator keeps that start and any matching end in its in-memory session map. It first marks the workflow message `sent`, then reports the saved turn events in order. It does not drop a turn event while server confirmation is in progress.
 
 A visible active-branch entry with the hidden ID is `sent`, even if the source lifecycle cancelled the message before the evidence arrived. Active-branch absence is usable only when the branch has no matching ID, Pi is idle, and Pi has no pending messages in the same observation. If Pi or the extension disappears after the send call, the message stays `pending`; reconnect reports the branch before another send. These rules do not prove cross-branch absence or exactly-once model execution.
 
-After Pi, the extension, or the host restarts, branch reporting runs before any new send. It re-creates a message of the source's own kind only when the active branch has no entry for that source. A pending interaction gets one `step` with reason `resumed`; a pending decision gets one `decision`. Old incompatible workflow state is not reinterpreted.
+After Pi, the extension, or the server restarts, branch reporting runs before any new send. It re-creates a message of the source's own kind only when the active branch has no entry for that source. A pending interaction gets one `step` with reason `resumed`; a pending decision gets one `decision`. Old incompatible workflow state is not reinterpreted.
 
 ## Model-turn status
 
@@ -149,13 +149,13 @@ After Pi, the extension, or the host restarts, branch reporting runs before any
 
 A start against a closed message is rejected. Follow-up turns are reported for ordering but do not show the completed workflow as `running`.
 
-The extension creates one workflow turn ID at `agent_start` and keeps it through the matching `agent_end` and host reconnect. It buffers starts and ends until the session view and message receipt are ready.
+The extension creates one workflow turn ID at `agent_start` and keeps it through the matching `agent_end` and server reconnect. It buffers starts and ends until the session view and message receipt are ready.
 
-At `agent_end`, it derives `completed`, `aborted`, or `error` from the documented assistant messages. It reads response-entry evidence from `ctx.sessionManager.getBranch()`; the entry ID can be null. The host saves one immutable end result. A repeated report adopts it, and a stale turn ID cannot clear newer activity. A supervised worker can continue after accepted tool output while that Pi turn is still open. This normal continuation leaves the session capture recording until `agent_end`; it does not mark the capture as interrupted.
+At `agent_end`, it derives `completed`, `aborted`, or `error` from the documented assistant messages. It reads response-entry evidence from `ctx.sessionManager.getBranch()`; the entry ID can be null. The server saves one immutable end result. A repeated report adopts it, and a stale turn ID cannot clear newer activity. A supervised runner can continue after accepted tool output while that Pi turn is still open. This normal continuation leaves the session capture recording until `agent_end`; it does not mark the capture as interrupted.
 
-The host applies the end and its workflow consequence in one transaction. An aborted turn sets the run pause and cancels the request's pending step messages; the interaction derives its paused state from the run. Resuming that submitted-output step atomically clears the pause, increments the interaction revision, and creates one new step message with reason `resumed`. That message starts a fresh Pi model turn. A protected decision does not start a model turn, so its revision and decision message do not change when its run resumes. A completed, recoverably failed, or proved-lost turn increments `unproductiveTurnEnds` only when the submitted-output step is pending, not paused, and has no accepted or validating submission. Values one and two create one step message with reason `reminder`; a value above two fails the attempt. A partial unique index enforces at most one pending step message for the request, regardless of reason. Acceptance, pause, cancel, timeout, and branch re-presentation cancel all pending step messages. A cancelled message did not start a turn and does not increment the counter.
+The server applies the end and its workflow consequence in one transaction. An aborted turn sets the run pause and cancels the request's pending step messages; the interaction derives its paused state from the run. Resuming that submitted-output step atomically clears the pause, increments the interaction revision, and creates one new step message with reason `resumed`. That message starts a fresh Pi model turn. A protected decision does not start a model turn, so its revision and decision message do not change when its run resumes. A completed, recoverably failed, or proved-lost turn increments `unproductiveTurnEnds` only when the submitted-output step is pending, not paused, and has no accepted or validating submission. Values one and two create one step message with reason `reminder`; a value above two fails the attempt. A partial unique index enforces at most one pending step message for the request, regardless of reason. Acceptance, pause, cancel, timeout, and branch re-presentation cancel all pending step messages. A cancelled message did not start a turn and does not increment the counter.
 
-There is no activity heartbeat, refresh lease, or sequence counter. The host shows `running` from the matching start until the matching end. Host startup never marks a Pi turn lost. On `session_start`, only an idle-session branch report can close an open sent message with synthetic stop reason `lost`. Polling and time alone cannot create a reminder.
+There is no activity heartbeat, refresh lease, or sequence counter. The server shows `running` from the matching start until the matching end. Server startup never marks a Pi turn lost. On `session_start`, only an idle-session branch report can close an open sent message with synthetic stop reason `lost`. Polling and time alone cannot create a reminder.
 
 ## Feature ownership
 
@@ -190,9 +190,9 @@ A terminal or follow-up message does not reopen the completed workflow. A slash-
 
 ## Session recording
 
-The extension records workflow-related Pi events through a batched host client operation. It uses documented Pi events and does not read or edit Pi session files.
+The extension records workflow-related Pi events through a batched server client operation. It uses documented Pi events and does not read or edit Pi session files.
 
-The host deduplicates settled entries by Pi entry ID. It links attempts to their prompt, response, first, and last entries. A recording failure does not fail workflow execution.
+The server deduplicates settled entries by Pi entry ID. It links attempts to their prompt, response, first, and last entries. A recording failure does not fail workflow execution.
 
 ## Public API boundary
 
@@ -214,14 +214,14 @@ Tests must prove:
 - messages remain in saved order without message-pointer deadlocks;
 - an early `agent_start` and `agent_end` wait for the message receipt and session view, then apply in order;
 - every matching model turn shows `running` for its full duration;
-- normal worker continuation leaves the active session capture open until the matching turn ends;
+- normal runner continuation leaves the active session capture open until the matching turn ends;
 - stale turn-end reports and starts against closed messages are rejected;
 - a manual turn cancels pending step messages that it supersedes;
 - a turn cannot bind to an interaction whose run is paused;
 - aborted turns pause without incrementing the unproductive-turn counter;
 - resuming an aborted step creates one new resumed message and one fresh model turn;
 - resuming a protected decision keeps its answer revision and does not create a duplicate decision message;
-- host restart does not close a live Pi turn, while an idle-session branch report can close an unended turn as lost;
+- server restart does not close a live Pi turn, while an idle-session branch report can close an unended turn as lost;
 - two reminder-reason steps are sent at most once and the next unproductive turn fails;
 - initial, reminder, and resumed prompts use the same step kind and differ only by reason;
 - terminal and follow-up messages each start only at their durable boundary;

package/docs/WORKFLOW_UPDATES.md

@@ -11,10 +11,10 @@ const processRows = action({
   run: async (context) => {
     await context.publishUpdate({
       type: "progress",
-      key: "worker-a",
+      key: "runner-a",
       data: {
         schema: "pi-workflows.progress.v1",
-        label: "Worker A",
+        label: "Runner A",
         status: "running",
         phase: "processing",
         completed: 420,
@@ -37,10 +37,10 @@ An agent publishes the same update through the existing `workflow` tool:
   "attempt": "017f5d57-83f1-4d2d-88e6-3dbf878fed17",
   "update": {
     "type": "progress",
-    "key": "worker-a",
+    "key": "runner-a",
     "data": {
       "schema": "pi-workflows.progress.v1",
-      "label": "Worker A",
+      "label": "Runner A",
       "status": "running",
       "completed": 420,
       "total": 1000,
@@ -226,7 +226,7 @@ Shell actions may define a line parser:
 
 ```ts
 shell({
-  exec: () => ({ command: "worker", args: ["--progress=ndjson"] }),
+  exec: () => ({ command: "runner", args: ["--progress=ndjson"] }),
   updates: {
     streams: ["stdout"],
     parseLine: ({ stream, text }, context) => {
@@ -234,7 +234,7 @@ shell({
       if (value.kind !== "progress") return undefined;
       return {
         type: "progress",
-        key: value.worker,
+        key: value.runner,
         data: value.data,
       };
     },
@@ -248,11 +248,11 @@ The runtime keeps normal stdout and stderr capture. It applies backpressure whil
 
 The parser is workflow-author code. Update data never selects or changes the command, arguments, working directory, environment, or privileges.
 
-## Controllers and hosts
+## Controllers and servers
 
-The engine exposes the same publication operation through its runner interface. A controller or standalone host may publish only for a workflow run and attempt whose claim it owns.
+The engine exposes the same publication operation through its runner interface. A resource manager or standalone server may publish only for a workflow run and attempt whose claim it owns.
 
-Controller resource events remain controller events. They become workflow updates only when a controller deliberately publishes them to a linked workflow run.
+Managed resource events remain resource manager events. They become workflow updates only when a resource manager deliberately publishes them to a linked workflow run.
 
 ## Persistence
 
@@ -271,7 +271,7 @@ Each accepted update transaction inserts one `workflow_updates` row and one
   "payload": {
     "updateId": "upd_01K2GZVY3A4D7X8J9M0N",
     "type": "progress",
-    "key": "worker-a",
+    "key": "runner-a",
     "data": {
       "schema": "pi-workflows.progress.v1",
       "status": "running",
@@ -306,11 +306,11 @@ Default safety limits per run are:
 
 The rate limiter uses a token bucket. A rejected update is not queued silently. Agent callers receive a tool error; code publishers receive a rejected promise.
 
-The standalone host and Pi extension apply the same limits.
+The standalone server and Pi extension apply the same limits.
 
 ## Progress update type
 
-`progress` is the standard optional profile for measurable work. Each key represents one process, worker, phase owner, or explicit overall total.
+`progress` is the standard optional profile for measurable work. Each key represents one process, runner, phase owner, or explicit overall total.
 
 Minimal progress data:
 
@@ -326,7 +326,7 @@ Measured progress:
 ```json
 {
   "schema": "pi-workflows.progress.v1",
-  "label": "Worker A",
+  "label": "Runner A",
   "status": "running",
   "phase": "processing",
   "completed": 420,
@@ -363,7 +363,7 @@ Unknown fields in `pi-workflows.progress.v1` are validation errors.
 
 ## Progress estimation
 
-The workflows layer exports pure validation and estimation helpers. Reduction and formatting use the same module. The helpers import no Pi, extension, controller, or viewer code.
+The workflows layer exports pure validation and estimation helpers. Reduction and formatting use the same module. The helpers import no Pi, extension, resource manager, or viewer code.
 
 The estimator groups records by run and key. A new estimation epoch starts when:
 
@@ -402,7 +402,7 @@ The compact widget:
 A typical line is:
 
 ```text
-Worker A  420/1,000 rows  ETA 18–20m
+Runner A  420/1,000 rows  ETA 18–20m
 ```
 
 A footer line may show:
@@ -445,4 +445,4 @@ Updates are data. They do not grant permission to execute a command, retry work,
 
 SQLite runs are private and may contain update data from external systems. The database permission and export warnings in [SQLite state](SQLITE_STATE.md) apply.
 
-This feature does not add remote transports, a metrics database, global aggregation, automatic polling, or a new Pi core API. Workflow authors remain responsible for the trust and cost of their agent, action, shell, and controller code.
+This feature does not add remote transports, a metrics database, global aggregation, automatic polling, or a new Pi core API. Workflow authors remain responsible for the trust and cost of their agent, action, shell, and resource manager code.

package/docs/development.md

@@ -10,22 +10,22 @@ The viewer follows the [incremental and virtualized viewer plan](plans/2026-08-2
 ```
 src/workflows/   finite graph engine: definitions, execution, SQLite stores, loader
 src/builtins/    default workflows shipped at lowest discovery precedence
-src/controllers/ durable resources, queue, reconciliation, effects, child runs
-src/host/        global host, local protocols, resolvers, and worker supervision
+src/resource-managers/ durable resources, queue, reconciliation, effects, child runs
+src/server/      global server, local protocols, resolvers, and runner supervision
 src/extension/   thin Pi client: commands, workflow tool, and origin-session bridge
-src/viewer/      standalone read-only views over runs and controller resources
+src/viewer/      standalone read-only views over runs and managed resources
 tui/             Rust piw viewer, bounded SQLite projection, and replay server
 ```
 
 The dependency direction is enforced by `slophammer.yml`. `src/workflows`
 imports nothing outside itself and never imports Pi. Durable updates,
 progress validation, estimation, and text formatting stay in this layer so the
-engine, extension, hosts, and viewers share one contract. `src/builtins` contains
+engine, extension, servers, and viewers share one contract. `src/builtins` contains
 package-owned definitions and imports only the public workflow engine.
-`src/controllers` may import the public workflow engine for child-run
-scheduling. `src/host` may import controller stores and workflow stores, but the
-host event loop never loads workflow or controller definitions. Resolver and
-worker child entry points load those definitions. The extension uses static
+`src/resource-managers` may import the public workflow engine for child-run
+scheduling. `src/server` may import resource manager stores and workflow stores,
+but the server event loop never loads workflow or resource manager definitions.
+Resolver and runner child entry points load those definitions. The extension uses static
 built-in metadata and never imports the workflow engine. The extension and
 viewer never import each other. The viewer reads SQLite state in read-only mode,
 so it works from any process.
@@ -64,12 +64,13 @@ line, misplaces an arrow, or lets a label damage an edge, those tests fail
 with the offending drawing in the assertion message.
 
 Inside the engine, the model-facing seam is the `AgentStepExecutor` interface.
-The production run worker uses an interaction executor for origin-session work
-and `RpcStepExecutor` for headless controller work. The worker receives a
-`HostBackedWorkflowStore`; it cannot open a writable production store.
+The production workflow runner uses an interaction executor for origin-session
+work and `RpcStepExecutor` for headless resource manager work. The runner
+receives a `ServerBackedWorkflowStore`; it cannot open a writable production
+store.
 
 The Pi extension uses documented session lifecycle, message, tool, and session
-manager APIs. It writes no Pi session file. It saves host mutations through the
+manager APIs. It writes no Pi session file. It saves server mutations through the
 local protocol and uses the public session branch only to adopt the exact
 visible entry for a durable interaction request. Tests can still use scripted
 executors through the Pi-agnostic engine API.
@@ -135,9 +136,9 @@ the real pi CLI from `devDependencies` in RPC mode with:
 - `HOME` pointed at a temporary home containing the canonical workflow database,
 - the extension loaded from source with `-e src/extension/index.ts`.
 
-It drives `/workflow` over the RPC protocol and checks the global host,
+It drives `/workflow` over the RPC protocol and checks the global server,
 durable interaction request, origin-session presentation, accepted submission,
-worker recovery, final SQLite state, and viewer output. It also restarts the
+runner recovery, final SQLite state, and viewer output. It also restarts the
 real Pi process while one request is pending and proves that the same request is
 not inserted twice. Nothing outside the temp directories is touched, and no
 real model is called.

package/docs/live-replay-protocol.md

@@ -4,7 +4,7 @@ Pi Workflows uses one live client protocol for the Pi extension, the TypeScript
 
 The protocol ID is `pi-workflows.client.v1`. Its schema is [`protocol/client.v1.schema.json`](../protocol/client.v1.schema.json). TypeScript and Rust use the same valid and invalid fixture corpus.
 
-The host is the only process that reads or writes the active SQLite database. A client protocol or package-version mismatch does not mean that SQLite state is incompatible. The client stops and asks for matching `pi-workflows` and `piw` packages.
+The server is the only process that reads or writes the active SQLite database. A client protocol or package-version mismatch does not mean that SQLite state is incompatible. The client stops and asks for matching `pi-workflows` and `piw` packages.
 
 ## Transports
 
@@ -14,11 +14,11 @@ The local transport is a user-only Unix socket on Unix systems:
 ~/.pi/agent/workflows/host/host.sock
 ```
 
-On Windows, the same client uses the package-derived `\\.\pipe\pi-workflows-<state-directory-hash>` named pipe. Local `piw`, `piw serve`, and the TypeScript client derive the same endpoint from the workflow state directory. A foreground TypeScript cold start keeps its retry wait referenced until the detached host becomes ready or the start deadline expires. Only background reconnect timers are unreferenced.
+On Windows, the same client uses the package-derived `\\.\pipe\pi-workflows-<state-directory-hash>` named pipe. Local `piw`, `piw serve`, and the TypeScript client derive the same endpoint from the workflow state directory. A foreground TypeScript cold start keeps its retry wait referenced until the detached server becomes ready or the start deadline expires. Only background reconnect timers are unreferenced.
 
 Each message is one canonical JSON object followed by a newline. TypeScript and Rust use the same ECMAScript number formatting and UTF-16 object-key order, including for arbitrary workflow JSON. A message can be at most 1 MiB. Unknown envelope fields, non-canonical JSON, and invalid framing close only the offending connection. If socket backpressure delays a client write, connection close, socket error, or request cancellation ends the wait instead of leaving the request pending.
 
-`piw serve` provides the remote transport at `/ws`. It binds to loopback only. Each WebSocket connection has one matching host-socket connection, and their lifecycles are coupled. The relay forwards one canonical JSON object per text frame. It does not read SQLite, translate views, multiplex clients, or retain state.
+`piw serve` provides the remote transport at `/ws`. It binds to loopback only. Each WebSocket connection has one matching server-socket connection, and their lifecycles are coupled. The relay forwards one canonical JSON object per text frame. It does not read SQLite, translate views, multiplex clients, or retain state.
 
 Remote clients use an SSH tunnel to reach the loopback relay.
 
@@ -31,7 +31,7 @@ The protocol has four message types:
 - `response` settles one request with an outcome, optional revision, receipt, or safe error.
 - `event` carries a revisioned run list, run snapshot, run patch, run page, session snapshot, or unavailable condition.
 
-The host sends `hello` first:
+The server sends `hello` first:
 
 ```json
 {
@@ -48,7 +48,7 @@ A request uses a stable request ID and idempotency key:
 {
   "clientId": "client-1",
   "idempotencyKey": "status-1",
-  "operation": "host.status",
+  "operation": "server.status",
   "payload": {},
   "requestId": "request-1",
   "schema": "pi-workflows.client.v1",
@@ -60,7 +60,7 @@ The closed outcomes are `accepted`, `adopted`, `rejected`, `conflict`, `notFound
 
 ## Run and session views
 
-The host produces `pi-workflows.run-view.v1` from one consistent database read. The view contains the bounded workflow state, graph, trace, session projection, page cursors, presentation revision, and one `display` object. A terminal display includes the stored failure reason, not only its machine error code. A reason above the shared 16 KiB inline-content threshold uses a small `reason` notice and a digest-bound `reasonContent` reference. This keeps the run list below the 1 MiB frame limit and keeps the complete diagnostic available.
+The server produces `pi-workflows.run-view.v1` from one consistent database read. The view contains the bounded workflow state, graph, trace, session projection, page cursors, presentation revision, and one `display` object. A terminal display includes the stored failure reason, not only its machine error code. A reason above the shared 16 KiB inline-content threshold uses a small `reason` notice and a digest-bound `reasonContent` reference. This keeps the run list below the 1 MiB frame limit and keeps the complete diagnostic available.
 
 The closed display statuses are:
 
@@ -74,44 +74,44 @@ The closed display statuses are:
 - `cancelled`
 - `ambiguous`
 
-Only the host computes this status. A parked queue is not a pause. `paused` requires the durable pause flag. An exact live worker or origin-session turn is `running`. An effect being applied by that live worker is still `running`; only a durable `ambiguous` effect that needs operator action is `ambiguous`. `unavailable` is a client connection condition, not a run status.
+Only the server computes this status. A parked queue is not a pause. `paused` requires the durable pause flag. An exact live runner or origin-session turn is `running`. An effect being applied by that live runner is still `running`; only a durable `ambiguous` effect that needs operator action is `ambiguous`. `unavailable` is a client connection condition, not a run status.
 
-The run list uses the same display object. The host sends it as revision-bound `pi-workflows.run-list-page.v1` pages. Each page reads only lightweight run status and source facts. It does not load input, launch options, steps, trace, or session history. TypeScript and Rust clients collect all pages for one revision before they replace the visible list. If the revision changes, they discard the partial list and start from the next subscription event.
+The run list uses the same display object. The server sends it as revision-bound `pi-workflows.run-list-page.v1` pages. Each page reads only lightweight run status and source facts. It does not load input, launch options, steps, trace, or session history. TypeScript and Rust clients collect all pages for one revision before they replace the visible list. If the revision changes, they discard the partial list and start from the next subscription event.
 
 An origin-session subscription returns `pi-workflows.session-view.v1`. It contains the active run view first. When no run is active, it keeps the most recent terminal run while its terminal workflow message is pending or its first model turn is open, and then for 60 seconds after that turn ends. The same response contains an ordered byte-bounded window of all nonterminal workflow messages and open sent messages needed for recovery, their complete count, and the next eligible pending message only for the active coordinator epoch.
 
-The Pi extension assembles the complete run revision and workflow-message content before it updates the widget or coordinator. After every host connection, it reports the active branch before it sends a workflow message or reports a model turn. The report can name only message IDs from the complete session-view window. The extension always uses the exact run ID from that view. It does not select the latest run separately. An idle session does not create empty commands.
+The Pi extension assembles the complete run revision and workflow-message content before it updates the widget or coordinator. After every server connection, it reports the active branch before it sends a workflow message or reports a model turn. The report can name only message IDs from the complete session-view window. The extension always uses the exact run ID from that view. It does not select the latest run separately. An idle session does not create empty commands.
 
 A snapshot page contains at most 256 items and also has a byte budget. `view.page` returns another byte-bounded window that contains the requested cursor. Page responses use `pi-workflows.run-page.v1` and echo the requested cursor and run-view revision. A client applies a page only when both still match its current request and snapshot. A step-centered trace request selects the exact stored attempt first and uses its node only when that attempt has no trace event. Large workflow topology has bounded node, edge, graph-step, and transition projections plus durable content references for the complete original definition and complete graph history. TypeScript clients assemble every run-history page for that revision and hydrate the complete definition and all referenced content before they emit a complete non-interactive view or update the Pi widget. TypeScript and Rust use the same verified content loader for complete graph steps and transitions. Rust also requests, verifies, and decodes the complete referenced definition before it builds the graph layout. A session-event page also carries the replay checkpoint for the exact sequence before its first item, so reducing the page does not lose earlier active messages or tool calls. The checkpoint can itself be a durable content reference. TypeScript hydrates it with the run view, and Rust requests and resolves it before replay.
 
-The host counts histories first and reads only the selected SQLite ranges. An unchanged subscription uses a lightweight revision check and reuses its prior view. It does not rebuild complete histories every 250 milliseconds.
+The server counts histories first and reads only the selected SQLite ranges. An unchanged subscription uses a lightweight revision check and reuses its prior view. It does not rebuild complete histories every 250 milliseconds.
 
-Large prompt, output, event, settings, follow-up, and update values use a content reference instead of making a protocol frame exceed 1 MiB. `view.content` returns the referenced UTF-8 content in verified chunks. The reference includes its media type, byte count, SHA-256 digest, and an opaque marker for host-created references. The host saves generated view content directly under its exact run ID, content digest, and media type before it advertises the reference. It does not share media metadata with general state blobs. A request for another run or media representation is unavailable. Memory-cache eviction therefore cannot make an advertised aggregate unavailable. Run pruning removes the durable content. Clients reassemble all chunks and verify the bytes against both the content response and the advertised reference before display. Opaque content is restored as user data without interpreting nested objects as host references. Other cursors and content references keep the complete logical history and result available.
+Large prompt, output, event, settings, follow-up, and update values use a content reference instead of making a protocol frame exceed 1 MiB. `view.content` returns the referenced UTF-8 content in verified chunks. The reference includes its media type, byte count, SHA-256 digest, and an opaque marker for server-created references. The server saves generated view content directly under its exact run ID, content digest, and media type before it advertises the reference. It does not share media metadata with general state blobs. A request for another run or media representation is unavailable. Memory-cache eviction therefore cannot make an advertised aggregate unavailable. Run pruning removes the durable content. Clients reassemble all chunks and verify the bytes against both the content response and the advertised reference before display. Opaque content is restored as user data without interpreting nested objects as server references. Other cursors and content references keep the complete logical history and result available.
 
 ## Subscriptions and reconnection
 
-A client keeps one persistent connection and records its desired run-list, run, and origin-session subscriptions. A request to watch a run that does not exist returns `notFound` and does not install a subscription. TypeScript and Rust clients show that response instead of waiting for a snapshot. Explicit `piw <runId>` mode keeps that run selected even when the run list contains a newer run. After reconnection, the client sends accepted subscriptions again with its run revision. The host sends a bounded snapshot when the client needs one. The protocol also supports retained revision patches. Unsubscribing sends the subscription ID to the host for every subscription kind, so no unused snapshot work remains on a live connection.
+A client keeps one persistent connection and records its desired run-list, run, and origin-session subscriptions. A request to watch a run that does not exist returns `notFound` and does not install a subscription. TypeScript and Rust clients show that response instead of waiting for a snapshot. Explicit `piw <runId>` mode keeps that run selected even when the run list contains a newer run. After reconnection, the client sends accepted subscriptions again with its run revision. The server sends a bounded snapshot when the client needs one. The protocol also supports retained revision patches. Unsubscribing sends the subscription ID to the server for every subscription kind, so no unused snapshot work remains on a live connection.
 
-A slow or disconnected client cannot stop the host, another client, claim renewal, or workflow execution. The host waits for socket drain before it publishes another snapshot to that connection. Polling coalesces while the connection is blocked, so the socket buffer cannot grow by one snapshot on every poll. When a connection closes, the host removes its subscriptions and active coordinator epoch. It does not infer that an open model turn ended.
+A slow or disconnected client cannot stop the server, another client, claim renewal, or workflow execution. The server waits for socket drain before it publishes another snapshot to that connection. Polling coalesces while the connection is blocked, so the socket buffer cannot grow by one snapshot on every poll. When a connection closes, the server removes its subscriptions and active coordinator epoch. It does not infer that an open model turn ended.
 
 ## Origin-session activity
 
-The Pi extension uses `workflowTurn.report` to record `started` and `ended` for the exact workflow message, workflow turn, run, and origin session. There is no refresh, activity lease, heartbeat, or sequence counter. A started turn keeps the host-produced display status `running` until the matching end is accepted. A stale end cannot clear a newer turn.
+The Pi extension uses `workflowTurn.report` to record `started` and `ended` for the exact workflow message, workflow turn, run, and origin session. There is no refresh, activity lease, heartbeat, or sequence counter. A started turn keeps the server-produced display status `running` until the matching end is accepted. A stale end cannot clear a newer turn.
 
-The host accepts a start only for an open sent workflow message in that origin session. A step message is open while its interaction remains pending and its run is not paused. A terminal or follow-up message is open until its first turn ends. Decisions and notifications never open model turns. Turn binding does not inspect branch membership because documented `agent_start` has no message payload; branch reporting owns entry adoption and branch-specific re-presentation.
+The server accepts a start only for an open sent workflow message in that origin session. A step message is open while its interaction remains pending and its run is not paused. A terminal or follow-up message is open until its first turn ends. Decisions and notifications never open model turns. Turn binding does not inspect branch membership because documented `agent_start` has no message payload; branch reporting owns entry adoption and branch-specific re-presentation.
 
-If the workflow message or session view is still loading, the extension buffers the matching start and end and reports them in order after the message is confirmed `sent`. Activity changes display only. It does not grant workflow authority, renew a run claim, or settle an interaction. Host startup does not close an open Pi turn. Only a later idle-session active-branch report can close a proved-lost turn.
+If the workflow message or session view is still loading, the extension buffers the matching start and end and reports them in order after the message is confirmed `sent`. Activity changes display only. It does not grant workflow authority, renew a run claim, or settle an interaction. Server startup does not close an open Pi turn. Only a later idle-session active-branch report can close a proved-lost turn.
 
 ## Commands and uncertain results
 
-Durable commands use stable idempotency keys. The Pi extension routes each state-changing command through the durable client request path. If the connection closes after the host commits but before the response arrives, the client reconnects with a new request ID and adopts the stored result. A retry with the same durable identity and payload adopts the stored receipt. Reusing that identity with another payload is a conflict. The request ID identifies one transport attempt and is not part of the durable request fingerprint. A retry after a local abort uses a new request ID and keeps the durable idempotency and submission IDs, so a late response from the aborted attempt cannot settle the retry.
+Durable commands use stable idempotency keys. The Pi extension routes each state-changing command through the durable client request path. If the connection closes after the server commits but before the response arrives, the client reconnects with a new request ID and adopts the stored result. A retry with the same durable identity and payload adopts the stored receipt. Reusing that identity with another payload is a conflict. The request ID identifies one transport attempt and is not part of the durable request fingerprint. A retry after a local abort uses a new request ID and keeps the durable idempotency and submission IDs, so a late response from the aborted attempt cannot settle the retry.
 
-An `interaction.submit` response stays open while the supervised workflow child validates the value. The response settles only after the durable result is accepted, adopted, or rejected. A tool abort stops waiting immediately but does not undo an accepted host command. A later retry adopts the durable outcome. The host waits on the stored submission ID returned by adoption, not a different ID from the retry attempt. Clients do not poll SQLite.
+An `interaction.submit` response stays open while the supervised workflow child validates the value. The response settles only after the durable result is accepted, adopted, or rejected. A tool abort stops waiting immediately but does not undo an accepted server command. A later retry adopts the durable outcome. The server waits on the stored submission ID returned by adoption, not a different ID from the retry attempt. Clients do not poll SQLite.
 
 The protocol does not claim exactly-once behavior for an external system that cannot prove it. An uncertain non-idempotent effect becomes ambiguous and requires explicit recovery.
 
 ## Maintenance
 
-Active `state.status`, `state.verify`, `state.backup`, and `state.prune` requests run in the host against its existing database connection. The CLI uses one stable client identity and creates a fresh idempotency key for each backup or applied prune invocation. If that invocation loses its connection, the client reconnects once with a new request ID and the same invocation key, so the host adopts the exact in-flight or stored result. A later user invocation gets a new key and does not reuse a stale success or rejection. The host keeps an in-flight maintenance command alive after a client disconnect, stores its accepted or rejected receipt before it responds, and adopts the exact retry instead of running the operation again. Host shutdown waits for in-flight maintenance receipts. `state.status` returns the database file size and safe counts for resources, runs, controllers, decisions, settings scopes, pending interactions, pending follow-ups, active leases, and unsettled effects.
+Active `state.status`, `state.verify`, `state.backup`, and `state.prune` requests run in the server against its existing database connection. The CLI uses one stable client identity and creates a fresh idempotency key for each backup or applied prune invocation. If that invocation loses its connection, the client reconnects once with a new request ID and the same invocation key, so the server adopts the exact in-flight or stored result. A later user invocation gets a new key and does not reuse a stale success or rejection. The server keeps an in-flight maintenance command alive after a client disconnect, stores its accepted or rejected receipt before it responds, and adopts the exact retry instead of running the operation again. Server shutdown waits for in-flight maintenance receipts. `state.status` returns the database file size and safe counts for resources, runs, managed resources, decisions, settings scopes, pending interactions, pending follow-ups, active leases, and unsettled effects.
 
-Only `pi-workflows state verify <inactive-backup>` opens SQLite outside the host. It uses a query-only TypeScript connection and rejects the active database, including another path to the same file.
+Only `pi-workflows state verify <inactive-backup>` opens SQLite outside the server. It uses a query-only TypeScript connection and rejects the active database, including another path to the same file.

package/docs/plans/2026-08-04-controller-runtime-plan.md

@@ -1,26 +1,26 @@
 ---
-title: Add a durable controller runtime
+title: Add a durable resource manager runtime
 author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
 date: 2026-08-04
 updated: 2026-08-04
 status: implemented
 ---
 
-# Controller runtime plan
+# ResourceManager runtime plan
 
-pi-workflows needs a controller mode for automation that spans repeated events, external state changes, and process restarts. The design in [CONTROLLERS.md](../CONTROLLERS.md) follows the Kubernetes controller pattern. Durable resources hold desired and observed state, events enqueue resource keys, and each reconciliation reads current facts before acting.
+pi-workflows needs a controller mode for automation that spans repeated events, external state changes, and process restarts. The design in [RESOURCE_MANAGERS.md](../RESOURCE_MANAGERS.md) follows the Kubernetes controller pattern. Durable resources hold desired and observed state, events enqueue resource keys, and each reconciliation reads current facts before acting.
 
 The implementation keeps the graph engine focused on finite jobs. Controllers start and observe workflows through a child-run interface. Workflow graphs keep their finite execution model.
 
 ## Shipped design
 
-The implementation follows [CONTROLLERS.md](../CONTROLLERS.md) with these resolved choices:
+The implementation follows [RESOURCE_MANAGERS.md](../RESOURCE_MANAGERS.md) with these resolved choices:
 
 - The local store uses `better-sqlite3` because the Node 22 SQLite module still emits an experimental warning.
-- Controllers are discovered from `.pi/controllers/` and `~/.pi/agent/controllers/`.
-- The existing `pi-workflows` executable provides read-only `controllers` and `controller` commands. Headless workers use the public `ControllerManager` API.
+- Controllers are discovered from `.pi/resource-managers/` and `~/.pi/agent/resource-managers/`.
+- The existing `pi-workflows` executable provides read-only `controllers` and `controller` commands. Headless workers use the public `ResourceManagerRuntime` API.
 - The TypeScript CLI lists and inspects resources. The Rust viewer understands interrupted workflow runs. Resource views stay in the CLI for this release.
-- Per-controller concurrency limits are manager configuration, while controller definitions contain reconciliation behavior and timeout only.
+- Per-controller concurrency limits are manager configuration, while resource manager definitions contain reconciliation behavior and timeout only.
 
 The persisted model was reviewed with Schemator before implementation. The review removed generic timestamps from public resources, kept provider details opaque, moved concurrency policy to the manager, and tightened event payloads to recursive JSON values. The run failed aggregate validation on two proposed structural moves, so those moves received a manual review instead of automatic application.
 
@@ -28,7 +28,7 @@ The persisted model was reviewed with Schemator before implementation. The revie
 
 The first release must provide:
 
-- Typed controller definitions and durable resources with `spec`, `status`, generations and conditions, plus compare-and-swap versions.
+- Typed resource manager definitions and durable resources with `spec`, `status`, generations and conditions, plus compare-and-swap versions.
 - A durable keyed queue with deduplication, delayed wakeups, bounded concurrency, retry backoff, and expiring claims.
 - Level-based reconciliation that receives a resource instead of an event payload.
 - Effect records that recover safely when a process stops around an external mutation.
@@ -43,41 +43,41 @@ The default controller store will use SQLite and local filesystem permissions th
 
 The first release will support several workers in one process. Queue claims will survive process failure, but cross-host leader election will wait for a real remote deployment.
 
-Existing workflow definitions and run bundles remain valid. Controller resources use a separate schema and store. Child workflow attempts use the current run-bundle format; their parent links live in the controller store.
+Existing workflow definitions and run bundles remain valid. ResourceManager resources use a separate schema and store. Child workflow attempts use the current run-bundle format; their parent links live in the controller store.
 
 ## Open questions
 
 Implementation should resolve these points before the public API is frozen:
 
 - Confirm that the built-in Node SQLite API meets package portability and transaction requirements on every supported Node 22 release. Choose one documented dependency if it does not.
-- Decide whether controller discovery belongs in `.pi/controllers/` and `~/.pi/agent/controllers/`, or whether controllers should be registered only from installed packages.
+- Decide whether controller discovery belongs in `.pi/resource-managers/` and `~/.pi/agent/resource-managers/`, or whether controllers should be registered only from installed packages.
 - Decide whether the existing `pi-workflows` executable should gain controller subcommands or whether the package should expose another binary.
 - Set queue claim and retry defaults from local fault tests. Use the same evidence for retention and payload limits.
 - Define the smallest viewer change that makes blocked and indeterminate resources easy to find.
 
 ## Source layout
 
-Add a `src/controllers/` layer with no dependency on Pi:
+Add a `src/resource-managers/` layer with no dependency on Pi:
 
 ```text
 src/workflows/                 finite graph execution
-src/controllers/types.ts      resources, conditions, results, definitions
-src/controllers/store.ts      store and queue interfaces
-src/controllers/sqlite.ts     local durable implementation
-src/controllers/manager.ts    claims, workers, retries, cancellation
-src/controllers/effects.ts    effect lifecycle and recovery
-src/controllers/workflows.ts  child workflow scheduler adapter
+src/resource-managers/types.ts      resources, conditions, results, definitions
+src/resource-managers/store.ts      store and queue interfaces
+src/resource-managers/sqlite.ts     local durable implementation
+src/resource-managers/manager.ts    claims, workers, retries, cancellation
+src/resource-managers/effects.ts    effect lifecycle and recovery
+src/resource-managers/workflows.ts  child workflow scheduler adapter
 src/extension/                 Pi commands and lifecycle hooks, plus UI
 src/viewer/                    read-only local views
 ```
 
-`src/workflows` must never import `src/controllers`. The controller layer may depend on exported workflow contracts through `controllers/workflows.ts`. The extension and viewer may use both layers and remain independent from each other. Update `slophammer.yml` before adding cross-layer imports.
+`src/workflows` must never import `src/resource-managers`. The controller layer may depend on exported workflow contracts through `resource-managers/workflows.ts`. The extension and viewer may use both layers and remain independent from each other. Update `slophammer.yml` before adding cross-layer imports.
 
 ## Work stages
 
 ### Resource contract
 
-Define the TypeScript API, persisted schemas, condition helpers, generation rules, and compare-and-swap behavior. Review the persisted model with Schemator before implementation. Document the final decisions in [CONTROLLERS.md](../CONTROLLERS.md).
+Define the TypeScript API, persisted schemas, condition helpers, generation rules, and compare-and-swap behavior. Review the persisted model with Schemator before implementation. Document the final decisions in [RESOURCE_MANAGERS.md](../RESOURCE_MANAGERS.md).
 
 Add tests for spec updates, status-only writes, stale versions, condition transition times, deletion requests, and finalizer removal. A spec update must increase `generation`; a status update must preserve it.
 
@@ -89,11 +89,11 @@ Implement one queue row per controller and resource key. Enqueue must deduplicat
 
 Run concurrent worker tests that force compare-and-swap conflicts and claim expiry. All tests must use temporary directories.
 
-### Controller manager
+### ResourceManager manager
 
-Implement `defineController`, `ControllerManager`, and the settled, immediate requeue, and delayed requeue results. Reconciliation requests carry a key; the manager reads the resource immediately before calling user code.
+Implement `defineResourceManager`, `ResourceManagerRuntime`, and the settled, immediate requeue, and delayed requeue results. Reconciliation requests carry a key; the manager reads the resource immediately before calling user code.
 
-Enforce one active reconciliation per key. Apply returned status against the version that was read. A conflict discards the stale status and queues another pass. Add global and per-controller worker limits.
+Enforce one active reconciliation per key. Apply returned status against the version that was read. A conflict discards the stale status and queues another pass. Add global and per-resource runner limits.
 
 Emit structured lifecycle records with stable reconcile IDs and bounded error messages. Cancellation must stop new claims and give active reconcilers a fixed shutdown period.
 
@@ -115,7 +115,7 @@ Test duplicate child requests, changed fingerprints, completion races, parent ge
 
 ### Extension and viewer
 
-Add controller discovery and a `/controller` command for listing resources, inspecting conditions, requesting reconciliation, and cancelling active local work. Use only documented Pi extension APIs.
+Add controller discovery and a `/resource-manager` command for listing resources, inspecting conditions, requesting reconciliation, and cancelling active local work. Use only documented Pi extension APIs.
 
 Start local sources from `session_start` and close them idempotently during `session_shutdown`. Pi exit must leave durable resources and queue rows ready for another host. No background service is installed.
 
@@ -156,7 +156,7 @@ npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
 npx -y @simpledoc/simpledoc check
 ```
 
-Exercise the Pi extension from source with `pi -e src/extension/index.ts`. Start a controller resource, stop Pi while work is pending, reopen the same store, and confirm that reconciliation continues from current state. Repeat the effect crash matrix with the fake provider and preserve the test output as CI evidence.
+Exercise the Pi extension from source with `pi -e src/extension/index.ts`. Start a managed resource, stop Pi while work is pending, reopen the same store, and confirm that reconciliation continues from current state. Repeat the effect crash matrix with the fake provider and preserve the test output as CI evidence.
 
 ## Non-goals
 
@@ -164,6 +164,6 @@ The first implementation will not provide Kubernetes API compatibility, a distri
 
 ## Documentation updates
 
-Update [CONTROLLERS.md](../CONTROLLERS.md) whenever the public resource, queue, reconciliation, or effect contracts change. Add the shipped authoring surface to [workflows.md](../workflows.md), the source boundaries to [development.md](../development.md), and user-facing installation and commands to the root README after implementation.
+Update [RESOURCE_MANAGERS.md](../RESOURCE_MANAGERS.md) whenever the public resource, queue, reconciliation, or effect contracts change. Add the shipped authoring surface to [workflows.md](../workflows.md), the source boundaries to [development.md](../development.md), and user-facing installation and commands to the root README after implementation.
 
 Record any meaningful departure from this plan in this document before the implementation is considered complete.