@osolmaz/pi-workflows 0.11.1 → 0.12.0

package/docs/2026-08-20-durable-workflow-launch-plan.md

@@ -0,0 +1,445 @@
+---
+title: Make deferred workflow launches durable
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-20
+---
+
+# Make deferred workflow launches durable
+
+The launch queue and activation contract in this plan remain current. [Deferred workflow turns](DEFERRED_TURNS.md) replaces the launch-specific failure-notification mechanism with the general successor-turn intent contract.
+
+## Goal
+
+A successful `workflow start` call must create a real queued workflow before it returns. The model
+must receive the final run ID, and pi-workflows must start that run only after the current agent turn
+settles.
+
+If startup then fails, pi-workflows must save the failure and start one new model turn with an
+actionable error. The model can correct the request and call `workflow start` again. A failed launch
+must release the session reservation so the corrected run can start.
+
+This change stays inside pi-workflows. It uses the existing project-scoped SQLite controller store
+and documented Pi extension APIs. It does not change Pi, add a service, or add another database.
+
+## Current failure
+
+The current tool path stores a pending launch only in `pendingToolLaunch`. It returns:
+
+```text
+Workflow <name> will start after this turn finishes.
+```
+
+After the agent turn settles, the `agent_settled` handler clears `pendingToolLaunch` and calls
+`startRun`. If `startRun` fails, the handler sends only a TUI notification. No run ID was returned,
+`workflow status` has no durable launch to inspect, and the model receives no new turn.
+
+This happened twice while starting `autoimplement`. The tool reported a queued launch, but no run
+became active. The initiating model could not see the startup error and incorrectly reported that
+the workflow had started.
+
+## Decision
+
+Use a durable prepared run and one model-visible failure follow-up.
+
+During the `workflow start` tool call, pi-workflows will:
+
+1. Resolve and validate the workflow and all available start conditions.
+2. Allocate the final run ID.
+3. Save a queued record in the existing SQLite workflow queue.
+4. Reserve the initiating Pi session.
+5. Return the run ID and say that the workflow is queued.
+
+After the current agent turn settles, pi-workflows will:
+
+1. Claim the queued record.
+2. Change it to `starting`.
+3. Build the engine and executor without running a node.
+4. Change the record to `running`.
+5. Release the engine to run the first node.
+
+If startup fails, pi-workflows will:
+
+1. Change the record to `failed`.
+2. Save a bounded safe error.
+3. Release the session reservation.
+4. Create one eligible deferred-turn intent for the owning Pi session.
+5. Resolve that intent with one factual follow-up after settlement.
+
+The new model turn will contain the failed run ID and an actionable error. The model can fix the
+workflow reference, input, source, or local condition and call `workflow start` again. Each retry is
+an explicit model action with a new run ID. pi-workflows does not perform a blind automatic retry.
+
+## Alpha compatibility contract
+
+pi-workflows is in alpha. Change the current storage and tool contracts in place.
+
+- Keep `pi-workflows.controller-store.v1`.
+- Keep existing run-bundle schema identifiers.
+- Do not add a v2 schema.
+- Do not add a compatibility reader, data migration, dual path, alias, feature flag, or fallback to
+  `pendingToolLaunch`.
+- Change the SQLite table definitions and TypeScript types directly.
+- Remove the superseded status values and launch path in the same change.
+
+An existing controller store with the old alpha table layout is incompatible. On open, pi-workflows
+must verify the required table columns and status contract. If the layout is old, it must stop with a
+clear instruction to preserve any needed run evidence and reset the project-scoped controller store.
+It must not silently reinterpret or delete old state.
+
+Run bundles remain separate evidence. Resetting an incompatible controller queue must not delete run
+bundle directories.
+
+## Public behavior
+
+### Start
+
+A successful tool result becomes:
+
+```text
+Workflow autoimplement queued (run autoimplement-...).
+```
+
+The structured result contains:
+
+```json
+{
+  "action": "start",
+  "workflow": "autoimplement",
+  "runId": "autoimplement-...",
+  "queued": true
+}
+```
+
+Queued means that the durable reservation exists. It does not mean that the engine is running.
+
+Every check that can run before acknowledgement must run before the queue record is committed. This
+includes:
+
+- Workflow resolution and definition validation.
+- Declared input validation.
+- Parent checkpoint and source checks for continuations.
+- Controller-store access.
+- Existing active or queued session reservation.
+- Pending final presentation conflicts.
+
+A preflight error returns through the original tool call. The model can correct it in the same turn.
+No queued record remains after a failed preflight.
+
+### Activation
+
+Interactive activation starts only from a safe idle boundary:
+
+- `agent_settled` after the initiating turn.
+- `session_start` recovery when no agent turn is active.
+- The next `agent_settled` event when recovery starts during an active turn.
+
+Repeated lifecycle events must not start the same run twice. Claims use compare-and-set updates, a
+claim token, a bounded lease, and a final fence before the engine starts its first node.
+
+No compute node, shell action, function action, agent node, or presentation starts while the
+initiating agent turn is active.
+
+### Failure and model iteration
+
+A deferred startup failure becomes a terminal queued-run state. The safe follow-up message is:
+
+```text
+Workflow autoimplement failed to start (run autoimplement-...): <safe reason>.
+Inspect the error and call workflow start again only after you correct the cause.
+```
+
+The message does not contain raw workflow input, prompt text, credentials, request headers, or a
+stack trace.
+
+The turn intent has a deterministic ID derived from the session, run, and launch event. Pi Workflows records it in `workflow_turn_intents`. Before a delivery retry, it checks the Pi session branch for the intent ID. This prevents a duplicate after a crash between session append and intent resolution.
+
+A failed launch releases the one-workflow session reservation before it sends the follow-up. The
+model can therefore call `workflow start` during the new turn. If that launch also fails, the same
+process repeats with a new run ID. The regular Pi loop and user control remain the bounds; Pi
+Workflows does not create an internal retry loop.
+
+### Status
+
+`workflow status` with a run ID reads the queued-run record before a run bundle exists. After the
+engine starts, it also reads the normal run bundle.
+
+Status reports these launch states:
+
+```text
+queued
+starting
+running
+failed
+cancelled
+parked
+done
+```
+
+A failed status includes only the bounded safe error. Status without a run ID shows the current
+session reservation or the displayed run.
+
+### Cancellation
+
+`workflow cancel` accepts the queued run ID. Cancellation changes `queued` or `starting` to
+`cancelled` atomically and invalidates the activation fence. A race cannot release the executor after
+cancellation wins.
+
+A cancelled launch releases the session reservation and sends no failure follow-up. A later start
+can create a new run.
+
+## Storage contract
+
+Use the existing `workflow_run_queue` table as the source of truth for launch state.
+
+Change its alpha v1 layout in place to store:
+
+- Final run ID.
+- Workflow name and immutable source identity.
+- Definition digest.
+- Private workflow input while activation needs it.
+- Launch state.
+- Owning Pi session.
+- Claim token and lease expiry.
+- Safe failure code and message.
+- Created, updated, started, and finished times.
+
+Replace the current `claimed`, `parked`, and `done` launch-state contract with:
+
+```text
+queued | starting | running | parked | done | failed | cancelled
+```
+
+Keep `parked` and `done` for current resume and terminal queue behavior. Remove `claimed`; `starting`
+and `running` state its meaning directly.
+
+Clear private queue input when the launch becomes `running`, `failed`, or `cancelled`. The normal run
+bundle owns input after the engine starts.
+
+Keep `workflow_notifications` limited to passive `progress` and `final` reports. A launch failure creates an eligible row in `workflow_turn_intents`; it does not add a run-level notification kind.
+
+The project-scoped controller store remains private local state. Tests must verify restrictive file
+and directory permissions.
+
+## State transitions
+
+Only these launch transitions are valid:
+
+```text
+queued -> starting
+queued -> cancelled
+starting -> running
+starting -> failed
+starting -> cancelled
+starting -> queued       # expired lease with no run bundle
+running -> parked
+running -> done
+running -> failed
+running -> cancelled
+parked -> starting       # explicit resume
+parked -> cancelled
+```
+
+Every transition uses an expected current state and claim token when applicable. A stale handler gets
+no ownership and performs no side effect.
+
+When recovery finds `starting` after a lease expires:
+
+- No run bundle: return to `queued`.
+- Valid running bundle: reconcile to `running` and use existing run recovery.
+- Waiting bundle: reconcile to `parked`.
+- Terminal bundle: reconcile to `done`, `failed`, or `cancelled`.
+- Changed workflow source or unreadable bundle: record `failed` and notify the owning session.
+
+## Error contract
+
+Classify startup failures into a small set of stable codes, such as:
+
+```text
+workflow_not_found
+workflow_invalid
+input_invalid
+source_changed
+store_unavailable
+activation_failed
+cancelled
+```
+
+Persist a plain safe message with a strict byte limit. Keep the original error only in transient
+process memory for local debug logging. Never persist or send the stack, causes, raw input, prompt,
+credential, or unbounded provider text.
+
+A failure must remain useful. The safe message should name the check that failed and the action that
+can correct it without including secret values.
+
+## Implementation plan
+
+### 1. Replace the alpha controller-store layout
+
+Update `src/controllers/sqlite.ts` and its exported queue and notification types.
+
+- Keep `CONTROLLER_STORE_SCHEMA` at `pi-workflows.controller-store.v1`.
+- Change `SCHEMA_SQL` directly.
+- Remove old alpha `ALTER TABLE` compatibility logic for the workflow queue.
+- Add exact-layout validation after table creation.
+- Add the launch states and safe failure fields.
+- Generalize workflow notifications for run-level failure notices.
+- Add a partial unique index for one `queued`, `starting`, or `running` interactive reservation per
+  origin session.
+
+For an incompatible existing table, return a clear alpha reset error. Do not mutate it.
+
+### 2. Add atomic launch operations
+
+Add focused SQLite methods:
+
+- `reservePreparedRun`
+- `claimPreparedRun`
+- `markPreparedRunRunning`
+- `failPreparedRun`
+- `cancelPreparedRun`
+- `parkRunningRun`
+- `finishRunningRun`
+- `findSessionReservation`
+- `listRecoverableRuns`
+- `recoverExpiredStartingRun`
+
+Use `BEGIN IMMEDIATE`, expected states, claim tokens, and lease checks.
+
+### 3. Split preparation from activation
+
+Refactor `src/extension/index.ts`.
+
+Create a small `src/extension/launch-coordinator.ts` if it keeps state transitions and recovery out of
+the extension entry point.
+
+Preparation owns resolution, validation, run ID allocation, immutable source identity, definition
+digest, and reservation. Activation owns claims, engine construction, recorder setup, `activeRun`,
+running state, and executor release.
+
+Controller child workflows remain on their controller scheduler path. Share pure workflow-resolution
+helpers where useful, but do not make controller children wait for an interactive agent boundary.
+
+### 4. Change the start tool
+
+Update `src/extension/workflow-tool.ts` and the extension start handler.
+
+Return the queued run ID only after the SQLite transaction commits. Remove the old “will start”
+result and every success message that says the workflow already started.
+
+### 5. Add the failure follow-up
+
+Create a versioned custom message for launch results. Store only:
+
+- Notification schema.
+- Notification ID.
+- Run ID.
+- Workflow name.
+- `failed` state.
+- Safe error code and message.
+
+Deliver it through public `pi.sendMessage` after settlement with `triggerTurn: true` and
+`deliverAs: "followUp"`.
+
+The notification asks the model to inspect and correct the cause. It does not automatically call
+`workflow start`.
+
+### 6. Update status, cancellation, and recovery
+
+Status must read the queue before a run bundle exists. Cancellation must target queued and starting
+runs by ID. Session startup and agent settlement must ask the launch coordinator for recoverable work
+owned by that session.
+
+Delete `pendingToolLaunch` and all status, cancel, shutdown, and `agent_settled` branches that depend
+on it.
+
+### 7. Keep rendering secondary
+
+Render queued, starting, failed, and cancelled launch state in the TUI from durable storage. A TUI
+notification can announce failure, but it is not the source of truth and is not the only delivery
+surface.
+
+### 8. Update documentation
+
+Update `docs/workflows.md` with the queued start contract, run ID, status, cancellation, failure
+follow-up, and model retry behavior. Update controller-store documentation with the alpha reset rule.
+Do not document a v2 schema or migration path.
+
+## Tests
+
+Add or update these tests:
+
+1. Clean alpha v1 store creation with the new exact layout.
+2. Old alpha v1 layout rejection with a clear reset instruction.
+3. No automatic table migration or silent deletion.
+4. One-session reservation and different-session independence.
+5. Durable run ID before the start tool returns.
+6. Synchronous preflight failure with no queue record.
+7. Zero engine activity before `agent_settled`.
+8. Duplicate `agent_settled` and `session_start` events with one activation.
+9. Lease expiry and recovery at every activation boundary.
+10. Cancellation before claim, during `starting`, and before executor release.
+11. Source change between preparation and activation.
+12. Safe error redaction and byte bounds.
+13. One durable launch-failure turn intent.
+14. Crash before session append, after append, and before intent resolution.
+15. Failed reservation release followed by a corrected model start.
+16. Repeated model correction attempts with one active reservation at a time.
+17. Status for every launch and run state.
+18. Current child workflow, continuation, parking, resume, recorder, widget, and presentation
+    behavior.
+
+Add a real Pi end-to-end test in `test/e2e/workflow.e2e.test.ts` with the existing mock provider:
+
+1. The model calls `workflow start` for a valid file workflow.
+2. The tool returns a durable queued run ID.
+3. The test changes or removes the workflow source before the initiating turn settles.
+4. Activation records `failed`.
+5. Pi sends one follow-up model turn with the safe error.
+6. The model corrects the request and calls `workflow start` again.
+7. The new run starts and reaches its first workflow step.
+8. The first failed run remains inspectable by ID.
+
+The test must use the packaged extension and real Pi lifecycle events. It must not call a real model
+or external service.
+
+## Acceptance criteria
+
+- The start tool never reports success without a committed queued record and final run ID.
+- The model can correct synchronous start errors in the same turn.
+- A deferred startup failure always becomes durable before notification.
+- One launch-failure intent starts one new model turn.
+- The model can correct the cause and start a new run.
+- Failed and cancelled launches release the session reservation.
+- No two runs activate for one reservation.
+- Reload, restart, compaction, and repeated settlement do not lose or duplicate a launch.
+- Status and cancellation work before a run bundle exists.
+- Private input and error details do not leak.
+- No Pi change, new service, new database, v2 schema, compatibility path, or migration exists.
+- The old `pendingToolLaunch` path is gone.
+
+## Verification
+
+Run the canonical repository gates:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+git diff --check
+```
+
+Run pi-reviewer against the base branch and fix all valid P0 and P1 findings before release work.
+
+Package publication and OnurPi adoption are separate tasks. Do not edit an installed `node_modules`
+copy as the implementation source.
+
+## Non-goals
+
+- Do not change Pi or propose a new Pi API.
+- Do not add a service, daemon, remote queue, telemetry endpoint, or second database.
+- Do not preserve old alpha controller-store layouts.
+- Do not add a migration or v2 schema.
+- Do not add blind automatic workflow retries.
+- Do not change built-in workflow behavior except for test fixtures needed to verify startup.
+- Do not publish or adopt a package as part of this documentation change.

package/docs/CONTROLLERS.md

@@ -1,10 +1,10 @@
 # Controller runtime specification
 
-Pi Workflows runs finite TypeScript graphs. A graph starts with an input, follows explicit edges, and ends with a result or checkpoint. This works well for one bounded task.
+pi-workflows runs finite TypeScript graphs. A graph starts with an input, follows explicit edges, and ends with a result or checkpoint. This works well for one bounded task.
 
 Long-running automation has a different job. It must keep comparing a requested state with the current state of another system. Events can arrive more than once, processes can stop between an external request and its local receipt, and the external state can change while work is running.
 
-This specification adds a Kubernetes-style controller runtime to Pi Workflows. The controller runtime sits beside the graph engine. Controllers manage durable resources, while workflows remain finite jobs that a controller can start and observe.
+This specification adds a Kubernetes-style controller runtime to pi-workflows. The controller runtime sits beside the graph engine. Controllers manage durable resources, while workflows remain finite jobs that a controller can start and observe.
 
 The design follows the Kubernetes [controller pattern](https://kubernetes.io/docs/concepts/architecture/controller/), its [`spec` and `status` split](https://kubernetes.io/docs/concepts/overview/working-with-objects/), and the [idempotent reconciliation guidance](https://book.kubebuilder.io/reference/good-practices).