@osolmaz/pi-workflows 0.13.2 → 0.13.4

package/docs/2026-08-25-workflow-follow-ups.md

@@ -0,0 +1,132 @@
+---
+title: Continue normal work after a workflow finishes
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-25
+---
+
+# Continue normal work after a workflow finishes
+
+A workflow can save several normal user prompts while it runs. Pi Workflows sends them in order only after the workflow is officially terminal and its final response has settled. The completed workflow stays terminal and does not enter its start node again.
+
+Follow-up prompts are separate from workflow settings. JSON Patch changes future workflow behavior. Follow-up actions create later normal user turns.
+
+## Queue and remove prompts
+
+Use the workflow tool once for each prompt:
+
+```json
+{
+  "action": "queue-follow-up",
+  "prompt": "Release the package and verify the published files."
+}
+```
+
+The result contains a stable `followUpId` and order number.
+
+Remove an unsent prompt with:
+
+```json
+{
+  "action": "remove-follow-up",
+  "followUpId": "follow-up-0123456789abcdef0123456789abcdef01234567"
+}
+```
+
+A model can remove only a prompt added by the same session tool source. A controller can remove only its own prompt. A verified human can remove any unsent prompt in the owned run.
+
+Direct commands are also available:
+
+```text
+/workflow queue-follow-up Release the package and verify the published files.
+/workflow remove-follow-up follow-up-0123456789abcdef0123456789abcdef01234567
+```
+
+Controllers use:
+
+```ts
+await ctx.workflows.queueFollowUp({
+  requestKey: "release-after-run",
+  runId,
+  prompt: "Release the package and verify the published files.",
+});
+
+await ctx.workflows.removeFollowUp({
+  requestKey: "remove-release-after-run",
+  runId,
+  followUpId,
+});
+```
+
+The host creates the actor and stable request identity. Prompt data cannot claim human or controller authority.
+
+## Ordering and run states
+
+Prompts keep database acceptance order. Several user messages can therefore add several prompts while one workflow response is in progress.
+
+- Running, paused, parked, and waiting workflows accept new prompts.
+- Pause and park keep prompts queued.
+- A checkpoint continuation takes the queued prompts with it in the same transaction that creates the new run.
+- Successful completion records the terminal run before prompts can become ready.
+- Failed, timed-out, and cancelled workflows cancel every unsent prompt.
+- A terminal workflow rejects new prompts. Repeating an earlier request ID can still return its first result.
+
+A repeated request ID with the same prompt returns the first result. Reusing that ID with different content fails.
+
+## Final response barrier
+
+Each run saves one final-response state:
+
+- `not-needed`: the workflow has no final presentation;
+- `pending`: the terminal run has a final response that has not settled;
+- `settled`: the active session branch contains the presentation message and its completed assistant response;
+- `unavailable`: the extension recorded a definite timeout, failure, or restart gap.
+
+Successful completion changes queued prompts to `pending_presentation` when a final response is required. It changes them directly to `ready` when no final response is required. A settled or unavailable presentation changes pending prompts to ready.
+
+The extension includes the run ID in documented presentation-message details. On restart, it scans the active durable branch for the presentation message and completed assistant response. It saves the observed entry IDs. It does not treat an in-memory event alone as proof.
+
+## Delivery
+
+The follow-up coordinator handles one prompt at a time:
+
+1. Wait for terminal workflow state and a completed final-response barrier.
+2. Wait for the target session to be idle and have no active workflow.
+3. Claim the first ready prompt with a lease.
+4. Scan the active session branch for its stable follow-up ID.
+5. If the message already exists, save its session entry ID without sending it again.
+6. Otherwise, call documented `pi.sendUserMessage` with the prompt and a short nonsecret ID in a Markdown comment.
+7. After Pi saves the normal user message, scan the branch and save its entry ID and send time.
+8. Wait for that user turn and any workflow it starts to finish before taking the next prompt.
+
+`pi.sendUserMessage` returns no message ID. Branch evidence is required after a new send and after restart.
+
+The follow-up message is a normal user message. It can start normal work or a different workflow. It cannot resume or reactivate the completed workflow.
+
+## Failure handling
+
+- A crash before claim leaves the prompt ready.
+- A crash after claim lets another process continue after the lease expires.
+- A crash before message append leaves no branch evidence and permits a retry.
+- A crash after append but before the database update is resolved by finding the follow-up ID in the active branch.
+- A definite send failure releases the claim.
+- An unavailable session leaves the prompt pending.
+- Branching follows the active Pi branch. A message on another branch does not count as delivered on the active branch.
+
+Current documented Pi APIs cannot guarantee exactly-once model execution. Pi Workflows can guarantee only its saved order, claim, active-branch evidence, and local delivery state. Delivery also needs a later live Pi process, database, target session, and provider. This feature adds no external service.
+
+## Saved states
+
+A follow-up is in one of these states:
+
+- `queued`;
+- `pending_presentation`;
+- `ready`;
+- `sent`;
+- `removed`;
+- `cancelled`.
+
+A lease is temporary claim data, not another follow-up state.
+
+`workflow_follow_up_queues` stores presentation state and per-run order. `workflow_follow_ups` stores each prompt, source, state, session entry ID, and times. Prompt text stays in the existing content-addressed value store. Normal status views show IDs, order, source type, and state without printing full prompts.
+
+This is part of the same alpha hard change as workflow settings. It adds no Pi core change, private Pi API, external queue, compatibility reader, dual write, alias, fallback, or second schema.

package/docs/2026-08-25-workflow-settings.md

@@ -0,0 +1,169 @@
+---
+title: Change workflow settings during a run
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-25
+---
+
+# Change workflow settings during a run
+
+A workflow can expose a JSON settings value that authorized actors can change while the workflow runs. A change affects only future node attempts and future settings routes. It does not change the workflow definition, immutable input, completed work, or a running node.
+
+## Declare settings
+
+Use `workflowSettings()` in `defineWorkflow()`:
+
+```ts
+import {
+  allowSettingsPath,
+  defineWorkflow,
+  settingsRoute,
+  workflowSettings,
+} from "@osolmaz/pi-workflows";
+
+const settings = workflowSettings({
+  initial: {
+    instructions: [],
+    merge: false,
+    route: "normal",
+  },
+  parse: parseSettings,
+  paths: [
+    allowSettingsPath("/instructions", {
+      read: ["session", "human"],
+      add: ["session", "human"],
+      remove: ["session", "human"],
+      replace: ["session", "human"],
+    }),
+    allowSettingsPath("/merge", {
+      read: ["session", "human"],
+      replace: ["human"],
+    }),
+    allowSettingsPath("/route", {
+      read: ["session", "human"],
+      replace: ["session", "human"],
+    }),
+  ],
+  validateChange: ({ before, after, actor }) => {
+    if (actor.type === "session" && before.merge === false && after.merge === true) {
+      throw new Error("A model cannot grant merge authority");
+    }
+  },
+});
+
+export default defineWorkflow({
+  name: "example",
+  settings,
+  startAt: "choose",
+  nodes: {
+    choose: settingsRoute({
+      run: ({ settings }) => ({ route: settings.route }),
+    }),
+    normal: compute({ run: ({ settings }) => settings.instructions }),
+    careful: compute({ run: ({ settings }) => settings.instructions }),
+  },
+  edges: [
+    {
+      from: "choose",
+      switch: { on: "$.route", cases: { normal: "normal", careful: "careful" } },
+    },
+  ],
+});
+```
+
+The parser must validate without changing the patched value. `validateChange` can reject a valid JSON shape because of a cross-field or authority rule.
+
+A workflow without `settings` has no editable settings. A change request fails clearly.
+
+## Change settings
+
+The workflow tool accepts RFC 6902 JSON Patch:
+
+```json
+{
+  "action": "change-settings",
+  "scopeId": "run-id:$root:1",
+  "expectedChangeNumber": 3,
+  "patch": [
+    { "op": "replace", "path": "/route", "value": "careful" },
+    { "op": "add", "path": "/instructions/-", "value": "Run the full test suite." }
+  ]
+}
+```
+
+A direct verified user can use:
+
+```text
+/workflow change-settings [{"op":"replace","path":"/merge","value":false}]
+```
+
+Controllers use the same saved change path:
+
+```ts
+await ctx.workflows.changeSettings({
+  requestKey: "disable-merge",
+  runId,
+  scopeId,
+  expectedChangeNumber: 3,
+  patch: [{ op: "replace", path: "/merge", value: false }],
+});
+```
+
+Each request has a stable host-issued ID. Repeating the same ID and content returns the first result. Reusing an ID with different content fails. When one model response emits several workflow tool calls, the extension applies them in source order so a settings change cannot race past a later step submission.
+
+`expectedChangeNumber` protects the complete settings value. A JSON Patch `test` operation can protect one field. When no expected number is supplied, the patch applies to the latest saved value in database acceptance order.
+
+## Path permissions
+
+Paths use RFC 6901 JSON Pointer. They deny access by default. Rules apply to their path and descendants on segment boundaries. The most specific rule wins.
+
+The permissions mean:
+
+- `read`: use a path as the source of `test`, `copy`, or `move`;
+- `add`: add a new object value or array item;
+- `remove`: remove a value;
+- `replace`: replace an existing value.
+
+`copy` checks source read and destination add or replace. `move` checks source read and remove, then destination add or replace.
+
+`read` is not a privacy filter. Workflow code in that scope receives the complete typed settings value.
+
+The host records the actor outside the patch:
+
+- `session` for a model workflow-tool call;
+- `human` for a direct command or verified human decision;
+- `controller` for a controller request;
+- `policy` only for existing saved policy code.
+
+Patch data cannot claim another actor type.
+
+## Runtime rules
+
+Each node attempt gets one deep-copied, frozen settings value, scope ID, change number, and settings hash. A change accepted while that node runs does not alter it. The next attempt or node captures the latest value.
+
+Use `settingsRoute()` when a future route must use the latest settings. It is a pure compute node. The database compares its change number in the same transaction that saves the route result. If the number is stale, the engine reruns only that pure route. It never repeats an agent step, shell command, function action, or other external effect because settings changed.
+
+A settings scope accepts changes when its workflow chain is running, paused, parked, or waiting at a checkpoint. A terminal completed, failed, timed-out, or cancelled run rejects new changes.
+
+## Included workflows and checkpoints
+
+The root workflow has one settings scope when it declares settings. Each included-workflow invocation that declares settings gets its own scope. Its ID uses the root run, mount path, and saved invocation number. Re-entry gets fresh settings.
+
+Parent and child settings do not mix automatically. The child initializer receives its mapped child input.
+
+A checkpoint creates a continuation run. The transaction that creates that run transfers the active settings scopes to it. Scope IDs, change numbers, saved changes, and current values remain unchanged. This keeps one ordered settings history across the logical workflow chain.
+
+## Limits
+
+One patch can contain at most 256 operations and 64 KiB. One JSON Pointer can contain at most 1 KiB. The resulting settings value can contain at most 256 KiB.
+
+The engine rejects malformed operations, unknown fields, invalid indexes, invalid pointer escapes, non-JSON values, unsafe object access, and invalid moves. A rejected patch changes nothing.
+
+Workflow settings must not contain credentials or raw secrets. Use the existing credential stores and authority checks instead.
+
+## Saved state and inspection
+
+Each settings scope uses one `resources` row of type `settings`. Its resource revision is the public change number. `workflow_settings` stores the current value. `workflow_setting_changes` stores every accepted patch, actor, source, old hash, new hash, and time.
+
+Node attempts store the scope ID, change number, and settings hash they used. Workflow status, the TypeScript viewer, and `piw` show bounded settings data without printing private values by default.
+
+This is an alpha hard change. The schema keeps its existing v1 name and changes in place. Incompatible old local state remains untouched and must be backed up or reset. There is no old-state reader, second schema, dual write, alias, fallback, or feature flag.

package/docs/DEFERRED_TURNS.md

@@ -260,6 +260,12 @@ The `launch_failure` notification kind is removed. Queued launch failure creates
 
 Pending `launch_failure` rows from the earlier alpha contract are incompatible. Pi Workflows must stop with a clear controller-store reset instruction. It must not reinterpret, migrate, or silently delete those rows.
 
+## Post-completion follow-ups
+
+Deferred turns repair one stranded workflow turn after interruption. Ordered post-completion prompts are different. They represent user-requested normal work after successful completion, use `workflow_follow_up_queues` and `workflow_follow_ups`, and are delivered by the separate follow-up coordinator. Neither feature reads or changes the other's rows.
+
+See [Continue normal work after a workflow finishes](2026-08-25-workflow-follow-ups.md).
+
 ## Availability limits
 
 Pi Workflows can guarantee only the facts under its control:

package/docs/DESIGN_PHILOSOPHY.md

@@ -32,6 +32,8 @@ Runs should survive interruption and remain safe to resume. Save the run input a
 
 Immutable SQLite events are the record of what happened. Domain rows are current projections written in the same transaction. Viewers derive their answers from those facts instead of creating another source of truth.
 
+Live workflow settings follow the same rule. The workflow owns one typed JSON value and path policy. The engine owns ordered JSON Patch application and fixed node bindings. Lifecycle actions, such as queued post-completion prompts, stay outside the settings value.
+
 Reading shared state never gives mutation authority. Every durable write checks its actor, expected resource revision, and current lease generation when ownership is required. Follow-up work uses deterministic effects and idempotent receipts so partial failure can converge safely.
 
 ## Boundaries

package/docs/SQLITE_STATE.md

@@ -18,6 +18,7 @@ The database stores:
 - human-decision requests, submissions, resolutions, and cancellations
 - controller resources, finalizers, effects, and child workflows
 - notifications and deferred turns
+- workflow settings, accepted JSON Patch changes, and post-completion follow-up prompts
 - nonsecret channel cursors, inbox records, messages, and settlement receipts
 - canonical JSON, text, and large text values
 
@@ -57,7 +58,7 @@ Four record groups provide the common lifecycle rules.
 
 ### Resources
 
-`resources` identifies each mutable aggregate and holds its current revision. Runs, decisions, controller resources, effects, channels, notifications, deferred turns, and session segments have stable resource identities.
+`resources` identifies each mutable aggregate and holds its current revision. Runs, settings scopes, follow-up queues and items, decisions, controller resources, effects, channels, notifications, deferred turns, and session segments have stable resource identities.
 
 Every accepted domain command compares its expected revision and increments it once.
 
@@ -93,18 +94,20 @@ Local effects use deterministic transactions. Run queue settlement effects are c
 
 The shared records do not replace domain schemas. The following `STRICT` tables keep the state explicit:
 
-| Area                | Tables                                                                                                        |
-| ------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Schema and projects | `schema_meta`, `projects`                                                                                     |
-| Content             | `blobs`                                                                                                       |
-| Shared lifecycle    | `resources`, `leases`, `events`                                                                               |
-| Workflows           | `workflow_definitions`, `runs`, `run_steps`, `run_bindings`, `run_queue`, `node_attempts`, `workflow_updates` |
-| Session capture     | `session_segments`, `session_entries`, `session_events`                                                       |
-| Human decisions     | `human_decisions`, `human_decision_resolutions`, `human_decision_submissions`, `continuations`                |
-| Controllers         | `controller_resources`, `controller_finalizers`, `controller_queue`, `controller_workflows`                   |
-| Effects             | `effects`, `effect_attempts`                                                                                  |
-| Pi delivery         | `notifications`, `turn_intents`                                                                               |
-| Channels            | `channels`, `channel_cursors`, `channel_inbox`, `channel_messages`, `channel_message_parts`                   |
+| Area                | Tables                                                                                                                       |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Schema and projects | `schema_meta`, `projects`                                                                                                    |
+| Content             | `blobs`                                                                                                                      |
+| Shared lifecycle    | `resources`, `leases`, `events`                                                                                              |
+| Workflows           | `workflow_definitions`, `runs`, `run_sources`, `run_steps`, `run_bindings`, `run_queue`, `node_attempts`, `workflow_updates` |
+| Live settings       | `workflow_settings`, `workflow_setting_changes`                                                                              |
+| Post-run follow-ups | `workflow_follow_up_queues`, `workflow_follow_ups`                                                                           |
+| Session capture     | `session_segments`, `session_entries`, `attempt_entries`, `session_events`                                                   |
+| Human decisions     | `human_decisions`, `human_decision_resolutions`, `human_decision_submissions`, `continuations`                               |
+| Controllers         | `controller_resources`, `controller_finalizers`, `controller_queue`, `controller_workflows`                                  |
+| Effects             | `effects`, `effect_attempts`                                                                                                 |
+| Pi delivery         | `notifications`, `turn_intents`                                                                                              |
+| Channels            | `channels`, `channel_cursors`, `channel_inbox`, `channel_messages`, `channel_message_parts`                                  |
 
 Foreign keys join projects, runs, attempts, decisions, controllers, effects, and channel records. Partial unique indexes enforce one active node attempt per run, one queued or running reservation per Pi session, one decision winner, and one deterministic effect key. A parked waiting parent does not block its continuation. Reserving that continuation settles the parked parent queue in the same transaction, so a failed reservation leaves the parent recoverable.
 
@@ -112,15 +115,17 @@ Foreign keys join projects, runs, attempts, decisions, controllers, effects, and
 
 `blobs` stores canonical JSON and UTF-8 text as bytes. Its primary key is the 32-byte SHA-256 digest of the bytes.
 
-Insertion verifies the digest, media type, byte length, and exact bytes. Repeated content adopts the existing row. This replaces separate artifact files while keeping large prompts, outputs, errors, session payloads, and rendered channel text deduplicated. A writable open removes blobs that no foreign-key column references.
+Insertion verifies the digest, media type, byte length, and exact bytes. Repeated content adopts the existing row. This replaces separate artifact files while keeping outputs, errors, settled Pi entries, and rendered channel text deduplicated. Opening the database never deletes blobs. The explicit prune command removes unreferenced blobs after it deletes safe old run trees.
 
-Runs do not store a nested `WorkflowRunState` blob. `runs` stores scalar run facts and hashes for independent values. `node_attempts` stores each prompt and output once. `run_steps` stores ordered attempt membership and only stores an output override when a continuation changes a carried checkpoint answer. Readers derive `steps`, `outputs`, and `results` from these rows. Compact trace events do not copy node outputs, run inputs, or final outputs.
+Runs do not store a nested `WorkflowRunState` blob. `runs` stores run-level facts and hashes for independent values. `run_sources` stores source identity without source JSON blobs. `node_attempts` stores structured workflow outputs and small execution receipts. `session_entries` is the only stored copy of each settled Pi entry. `attempt_entries` links an attempt to its prompt, response, first, and last Pi entries. `run_steps` stores ordered attempt membership and only stores an output override when a continuation changes a carried checkpoint answer.
+
+Readers derive `steps`, `outputs`, `results`, carried-step count, current-node fields, waiting state, source objects, and continuation decision receipts from these rows. Compact trace events do not copy prompts, node outputs, run inputs, final outputs, action receipts, or assistant receipts.
 
 ### Assistant-message attempts
 
 An agent definition records `expectedOutput` as either a submitted-output description or `{ "kind": "assistant-message", "maxChars"?: number }`. Omitted `maxChars` means that Pi Workflows adds no character limit.
 
-A completed assistant-message attempt stores the exact text through the normal output blob. Its result record also stores a receipt with the text digest, final Pi session entry ID when available, optional author-supplied limit, and whether recovery adopted an existing response. Session tables keep the prompt-to-response entry range and the normal Pi message events.
+A completed interactive assistant-message attempt uses the settled Pi response entry as its output. It does not store a second output blob. Its small receipt keeps the text digest, final Pi session entry ID, optional author-supplied limit, and whether recovery adopted an existing response. A noninteractive attempt with no captured response entry keeps one normal output blob.
 
 An interrupted assistant-message attempt keeps its attempt ID when the origin Pi session resumes it. The executor adopts a matching completed assistant child from the active Pi branch instead of displaying the response twice. Submitted and non-agent attempts keep their normal fresh-attempt resume behavior.
 
@@ -145,7 +150,7 @@ COMMIT
 
 Any failed check rolls back the complete command.
 
-Session-event batches use `session_events` as their journal. They update the contiguous segment counter in the same transaction and do not create a generic `session.events_appended` event for each flush. The recorder stores lifecycle boundaries and settled events. It discards token deltas and incremental tool progress.
+Session-event batches use `session_events` as their journal. They update the contiguous segment counter in the same transaction and do not create a generic `session.events_appended` event for each flush. The recorder stores order, IDs, roles, status, and timing boundaries. It discards token deltas, completed text, thinking text, tool arguments, tool results, and incremental tool progress. The settled Pi entries keep the replay content.
 
 A TypeScript write permit carries the expected facts between layers. It is not authority by itself. The store verifies durable ownership and revision data again inside the transaction.
 
@@ -176,7 +181,11 @@ The same rule applies to run terminal outcomes, continuation admission, queue se
 
 ## Read contract
 
-Status is a pure projection of domain rows, immutable facts, current leases, and effect receipts.
+Status is a pure projection of domain rows, immutable facts, current leases, and effect results.
+
+A settings scope uses its resource revision as its public change number. Each accepted patch, current value, and node binding is saved in one transaction. A checkpoint continuation keeps the same settings resources and transfers them to the continuation run.
+
+A follow-up queue records acceptance order and final-presentation state. Successful terminalization changes queued items to ready or pending presentation in the same transaction as the terminal run fact. Failure, timeout, and cancellation cancel unsent items. Delivery uses item leases and active Pi branch evidence.
 
 - A terminal run fact overrides stale queue presentation.
 - An accepted decision is accepted even if its continuation effect is still pending.
@@ -213,11 +222,15 @@ Supported commands are:
 pi-workflows state status
 pi-workflows state verify
 pi-workflows state backup /absolute/path/to/state-backup.sqlite
+pi-workflows state prune --before 2026-08-01T00:00:00Z --dry-run
+pi-workflows state prune --before 2026-08-01T00:00:00Z --backup /absolute/path/to/before-prune.sqlite --apply
 ```
 
 `status` reports only safe counts, file size, active leases, and unsettled effects.
 It does not print actor IDs, channel references, payloads, or credentials.
 
+`prune --dry-run` reports complete terminal run trees older than the cutoff and the trees that safety checks block. It does not change the database. `prune --apply` requires a new absolute backup path. It verifies the backup, locks maintenance, rechecks the same selection in an exclusive transaction, and refuses trees with live queues, active leases, unsettled effects, controller references, channel references, or step links from runs outside the tree. It deletes the safe aggregates, removes blobs with no remaining foreign-key reference, checkpoints the WAL, vacuums the file, and runs integrity and foreign-key checks. Pi Workflows never runs prune at startup.
+
 ## Alpha cutover
 
 This is a hard cut. Pi Workflows has no normal reader or writer for older live storage. It does not use dual reads, dual writes, aliases, versioned state roots, or automatic import.

package/docs/WORKFLOW_COMPOSITION.md

@@ -198,6 +198,21 @@ A child cannot read parent state except through mapped input. A parent sees only
 
 Each mount entry starts with empty local outputs and results. Earlier invocation data stays in the trace but cannot satisfy callbacks in a later invocation. The latest named exit replaces the parent-visible mount output.
 
+### Workflow settings
+
+A root workflow and each included-workflow invocation can declare separate settings. Included settings are isolated by default and use the mount path plus saved invocation number as their scope. Re-entry creates fresh settings. A child initializer receives the mapped child input.
+
+A parent can override one invocation's initial child settings explicitly:
+
+```ts
+includeWorkflow(child, {
+  input: ({ outputs }) => ({ task: outputs.plan }),
+  settings: ({ settings }) => ({ ...settings, route: "careful" }),
+});
+```
+
+A checkpoint continuation keeps the same active settings scopes, change numbers, and saved changes. The continuation transaction transfers those scopes and queued follow-ups to the new run before execution resumes.
+
 ### Limits and progress
 
 The root `maxSteps` limits all real node attempts in the run. Each child `maxSteps` limits one invocation. Include entry and exit transitions are recorded but do not count as user-authored node attempts.
@@ -267,7 +282,7 @@ monitor
 
 ## Autoplan, autodoc, and autoimplement
 
-`autoplan` accepts the problem, scope, constraints, an optional previous plan, and new evidence. It records two through four practical candidates plus the ideal, automatically selects the best in-scope solution, and records one rejection reason for every other explicit candidate. It includes `plain-summary` on ready and blocked routes, so the user sees one short normal assistant response before the parent continues. The response calls the choice a plan selected for approval and cannot satisfy the later human decision. Autoplan exits through `ready` or `blocked` and returns the full candidates, selection, detailed plan when ready, plain summary, plan digest, and change status.
+`autoplan` accepts the problem, scope, constraints, an optional previous plan, and new evidence. Its `solutions` step records two through four practical candidates and asks whether each is a Long term elegant and production ready solution. Its `holyGrail` step describes the Holy grail separately. Its `select` step chooses the best in-scope option and records one rejection reason for every other explicit candidate, including the Holy grail. It includes `plain-summary` on ready and blocked routes, so the user sees one short normal assistant response before the parent continues. The response calls the choice a plan selected for approval and cannot satisfy the later human decision. Autoplan exits through `ready` or `blocked` and returns the full candidates, selection, detailed plan when ready, plain summary, plan digest, and change status.
 
 `autodoc` accepts an already selected plan or finds it in the active conversation and referenced canonical documents. It adopts current documentation or updates the canonical specification and implementation plan, runs documentation checks, and returns a documented-plan record. It never selects a solution or implements one.
 

package/docs/WORKFLOW_STEP_MESSAGES.md

@@ -55,6 +55,8 @@ The request carries optional presentation data for the run title and node status
 
 One pure formatter remains responsible for the model prompt used by both executors. Interactive delivery must not shorten, summarize, or rebuild the model prompt from display fields.
 
+Before the step contract, the formatter adds the active settings scope, change number, bounded current value, allowed model paths, and exact `change-settings` action when that scope declares settings. It also shows the `queue-follow-up` and `remove-follow-up` actions. Actor identity is never part of model input. The extension derives it from the documented tool call.
+
 ## Compact display
 
 The collapsed card shows only useful workflow identity and current work. For example:
@@ -104,7 +106,7 @@ The two message types must not share delivery code that can accidentally change
 
 Interactive step deliveries use `sendMessage` instead of `sendUserMessage`. Existing session entries remain readable and are not rewritten.
 
-The custom prompt and visible assistant response are normal documented Pi session messages. pi-workflows adds no Pi session schema, private entry type, or separate persistent store. SQLite stores the full prompt, exact assistant text, conversation range, and additive digest receipt in existing content-addressed records, so this behavior adds no durable format.
+The custom prompt and visible assistant response are normal documented Pi session messages. pi-workflows adds no Pi session schema, private entry type, or separate persistent store. SQLite stores each settled Pi entry once. Small relational links connect the workflow attempt to its prompt, response, first, and last entries. The attempt keeps only the assistant digest receipt. It does not copy the prompt or visible response into another blob.
 
 If the renderer is unavailable, Pi still retains the custom message content. pi-workflows does not add a fallback path that sends a duplicate user message.
 
@@ -123,7 +125,7 @@ Tests verify:
 - interactive and RPC executors give the model the same complete prompt
 - one step message starts one model turn
 - collapsed rendering does not show the full prompt
-- expanded rendering shows the full prompt and exact contract ids
+- expanded rendering shows the full prompt, settings scope and change number, allowed paths, and exact contract ids
 - long and missing display fields render safely
 - reminders and resumed deliveries keep the active attempt id
 - submitted steps still reject stale attempts after timeout or cancellation