@osolmaz/pi-workflows 0.11.0 → 0.11.2

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

@@ -0,0 +1,449 @@
+---
+title: Make deferred workflow launches durable
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-20
+---
+
+# Make deferred workflow launches durable
+
+## 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. Queue one durable failure notification for the owning Pi session.
+5. Send that notification through `pi.sendMessage` with `triggerTurn: true` and
+   `deliverAs: "followUp"`.
+
+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 failure notification has a deterministic ID derived from the run ID. Pi Workflows records its
+delivery in the existing notification outbox. Before a delivery retry, it checks the native Pi
+session for that notification ID. This prevents a duplicate after a crash between session append and
+outbox acknowledgement.
+
+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.
+
+Extend the existing `workflow_notifications` table in place so a notification can be run-level.
+Add `launch_failure` to its kind contract and allow node and attempt identity to be absent for a
+run-level notification. Reuse its delivery claim, lease, and delivered timestamp.
+
+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 notification.
+14. Crash before session append, after append, and before outbox acknowledgement.
+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 failure notification 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/plans/2026-08-20-autoimplement-blocker-challenge-plan.md

@@ -0,0 +1,138 @@
+---
+title: Confirm blockers before autoimplement stops
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-20
+---
+
+# Confirm blockers before autoimplement stops
+
+Autoimplement must not stop only because one model says that work is blocked. A separate agent must challenge the claim and confirm that the blocker is real before the workflow uses its terminal blocked result.
+
+The canonical workflow behavior is in [Workflow authoring reference](../workflows.md#built-in-planning-and-implementation).
+
+## Outcome
+
+Add one independent `challengeBlocker` agent node to the built-in autoimplement workflow. Use only existing public Pi Workflows primitives. Keep the graph explicit and reuse the existing redesign include and terminal blocked result.
+
+The challenge asks these questions in plain terms:
+
+- Are you really blocked?
+- Is this really a blocker right now?
+- Can you find a safe way to move forward and finish this?
+- Are you getting stuck on something trivial, procedural, reversible, or already authorized?
+
+The challenge inspects the task, approved plan, current result, evidence, scope, authority, previous attempts, and viable alternatives. It distinguishes a true external blocker from normal rollout work, local implementation work, a design adjustment, a missing verification step, or a reversible operational task.
+
+## Output and validation
+
+The challenge returns this bounded structured output:
+
+```json
+{
+  "route": "continue | blocked",
+  "blockingNow": true,
+  "outsideAuthority": true,
+  "canProceed": false,
+  "reason": "concise reason",
+  "nextAction": "",
+  "alternativesChecked": ["checked alternative"],
+  "evidence": ["concrete evidence"]
+}
+```
+
+A terminal blocked result is valid only when all these conditions hold:
+
+- `route` is `blocked`.
+- `blockingNow` is `true`.
+- `outsideAuthority` is `true`.
+- `canProceed` is `false`.
+- `nextAction` is empty.
+- `alternativesChecked` contains checked practical alternatives.
+- `evidence` contains concrete evidence.
+
+A `continue` result must name the next practical action. Contradictory output, such as `route: blocked` with `canProceed: true`, cannot route to the terminal blocked result.
+
+Keep the output concise and bounded.
+
+## Routing
+
+Route `classifyImplementation.blocked` to `challengeBlocker`. A `continue` challenge result routes to the existing redesign include. Redesign can revise and document the plan, then return through implementation, verification, review, comment handling, CI, and delivery. A valid `blocked` result routes to the existing terminal blocked result.
+
+Inspect each later model-produced blocked exit in verification, review, comment handling, CI, delivery, and equivalent current nodes. Route operational or model-judged blockers through the same challenge when it is safe. Use one reusable challenge node and existing edges or includes. Do not copy the prompt into several nodes and do not add an engine-level blocker feature.
+
+Preserve direct terminal stops for these hard boundaries:
+
+- an explicit human stop;
+- cancellation;
+- an exhausted workflow safety or replan limit;
+- a protected authorization gap;
+- an independent blocked result from redesign when another challenge could make an unsafe or unbounded loop.
+
+Limit blocker challenges to three attempts in one run. Include all earlier challenge outputs in each later challenge prompt. If a fourth challenge would be needed, stop with the normal safety-limit reason. Do not repeat an unsupported blocker assertion.
+
+Include the latest challenge output in the workflow's latest-issue or context helper. A later redesign must receive the rejected blocker, its evidence, and its required next action.
+
+## Required behavior
+
+A supported cutover does not become blocked only because an artifact has an ownership or packaging mismatch. In the Bob artifact incident, authorized deployment and rollback make the safe rollout work part of the task. The challenge must return `continue`, name the next rollout action, and route to redesign.
+
+A missing external authorization for a prohibited remote mutation can remain blocked when no non-mutating path completes the task.
+
+A local test failure, stale package, packaging mismatch, rollback preparation, or deployment procedure is not, by itself, outside the granted authority.
+
+## Tests
+
+Add focused tests in `test/builtin-autoimplement.test.ts` or the best current autoimplement test file. Prove all these cases:
+
+1. A false blocker routes to redesign and continued work.
+2. A confirmed blocker reaches the terminal blocked result.
+3. Contradictory blocked output is rejected or cannot route to the terminal blocked result.
+4. The Bob artifact-ownership mismatch returns `continue` when rollout is authorized.
+5. An explicit human stop bypasses the challenge.
+6. A protected authorization gap remains a hard stop.
+7. An independent `redesign.blocked` path does not create a loop.
+8. Earlier challenge context is present and the three-attempt bound works.
+9. All relevant late-stage model-generated blocker routes use the challenge.
+10. Normal success paths remain unchanged.
+
+Keep compute nodes pure. Put the independent reasoning in the challenge agent node.
+
+## Documentation
+
+Update `docs/workflows.md` with the blocker-confirmation rule, hard-stop exceptions, and bounded routing. Keep the public behavior concise. Do not add internal details that users do not need.
+
+## Verification
+
+Run focused tests during development. Before completion, run these exact checks:
+
+```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
+```
+
+Verify discovery and behavior through the installed package path or the repository's supported real-Pi end-to-end path. A fresh Pi process is required because built-in discovery is process-local.
+
+Review the final diff for missing blocker routes, accidental unbounded loops, and false terminal blockers. Fix each valid finding.
+
+## Boundaries
+
+- Preserve current run-bundle schemas unless a schema change is required. Do not add a persistence layer.
+- Use existing public Pi Workflows primitives only. Do not change Pi core.
+- Keep explicit human and protected authorization boundaries intact.
+- Use a hard cutover. Do not retain a legacy blocker route.
+- Preserve unrelated work and do not modify other repositories.
+- Make only the smallest source-based adjustment needed to preserve the approved behavior.
+- Do not stop for a trivial, reversible, or already authorized issue.
+- Commit coherent changes with a Conventional Commit message and push after all checks pass.
+- Do not publish a package, create a release, or merge anything.
+
+## Contract impact
+
+- **Session state:** normal workflow messages and tool results only.
+- **Other persistent data:** none beyond the existing run bundle records for normal node outputs.
+- **Pi internals:** none.
+- **Public Pi API:** existing documented extension APIs only.
+- **Public Pi Workflows API:** existing agent, compute, edge, and included-workflow primitives only.

package/docs/plans/2026-08-20-herdr-plugin-sync-plan.md

@@ -0,0 +1,104 @@
+---
+title: Keep the Herdr plugin linked after package updates
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-20
+---
+
+# Keep the Herdr plugin linked after package updates
+
+Pi Workflows ships its Herdr plugin inside the npm package. Herdr records the package's absolute path. npm can move an installed package between nested and hoisted `node_modules` directories during an update, which leaves Herdr linked to a path that no longer exists.
+
+Pi Workflows will own one explicit command that finds its own package and repairs this link. OnurPi will call that command after it installs an exact reviewed Pi Workflows release. OnurPi will not contain Herdr paths, manifests, or link-repair rules.
+
+## Outcome
+
+The canonical command is:
+
+```bash
+pi-workflows herdr sync --json
+```
+
+`pi-workflows herdr setup` remains an alias for compatibility.
+
+The command validates the bundled package before it changes Herdr. It then creates a missing link, enables a disabled link, leaves a correct link unchanged, or replaces a link to another package path or version. A successful result requires a new Herdr query that shows the expected plugin ID, package version, package root, manifest path, enabled state, and no warning.
+
+## Scope
+
+### Pi Workflows
+
+- Resolve the installed package root from the running CLI.
+- Validate `package.json`, `herdr-plugin.toml`, and the bundled viewer before changing Herdr.
+- Reconcile the current registration through Herdr's public CLI.
+- Return a versioned JSON result with one of `linked`, `relinked`, `enabled`, `unchanged`, or `unavailable`.
+- Return `unavailable` only when the Herdr executable is absent.
+- Treat malformed package data, malformed Herdr output, command failures, identity conflicts, and failed verification as errors.
+- Keep output bounded and use argument arrays instead of shell commands.
+- Test source and packed-package layouts, including paths that contain spaces.
+
+### OnurPi
+
+- Keep the Pi Workflows dependency pinned to an exact reviewed release.
+- Invoke the local `pi-workflows herdr sync --json` command from an explicit TypeScript sync script after dependency installation.
+- Accept the versioned result and keep Herdr-specific behavior in Pi Workflows.
+- Keep package installation free of `postinstall` side effects.
+
+## Non-goals
+
+- Do not create another Herdr plugin package or release.
+- Do not duplicate the manifest or viewer in OnurPi.
+- Do not add hard-coded `node_modules` paths.
+- Do not edit Herdr state files directly.
+- Do not change Herdr core or Pi core.
+- Do not hot-reload running Pi processes. A running process still needs `/reload` or restart after a package update.
+- Do not add a service, watcher, or implicit package-install mutation.
+
+## Command contract
+
+The JSON result uses schema `pi-workflows.herdr-sync.v1` and contains:
+
+- the result status;
+- whether Herdr state changed;
+- the plugin ID;
+- the expected and effective versions when available;
+- the effective enabled state when available;
+- a plain summary; and
+- an advisory that running Pi processes must reload after a package update.
+
+A missing Herdr executable returns `unavailable` with exit code zero because Herdr is an optional integration. Every other failure returns a nonzero exit code and does not claim success.
+
+The command preflights the new package before unlinking an old registration. Herdr currently exposes separate unlink and link commands, so replacement cannot be atomic. If replacement fails, Pi Workflows makes one restore attempt only when the previous package root still passes the same validation. It then reports the state found by a fresh Herdr query.
+
+Concurrent sync commands converge on the same target. After a failed or ambiguous mutation, the command queries Herdr and adopts the result only when another process already reached the exact expected state. It does not repeat the same mutation blindly.
+
+## Compatibility
+
+Existing `herdr setup` callers use the same implementation. Other Pi Workflows CLI commands do not change. The npm package remains the only source of the plugin manifest and viewer.
+
+OnurPi adds only invocation timing and result handling. It does not parse the Herdr manifest or issue link commands.
+
+## Verification
+
+### Pi Workflows
+
+- Test first link, unchanged link, disabled link, moved package path, stale path, and version update.
+- Test missing Herdr, malformed manifests, malformed plugin records, command failures, post-action mismatches, and bounded restore behavior.
+- Test concurrent adoption and paths with spaces.
+- Run the CLI from `npm pack` contents in nested and hoisted layouts.
+- Run `npm run check`, `npm run test:e2e`, Slophammer, SimpleDoc, and diff checks.
+
+### OnurPi
+
+- Test every structured result and invalid command output with a fake executable.
+- Verify the wrapper contains no plugin ID, manifest copy, Herdr mutation command, or package path.
+- Verify root and wrapper dependency pins remain equal.
+- Run `npm run check`, `npm run slophammer`, SimpleDoc, and diff checks.
+
+### Adoption
+
+After a separately approved Pi Workflows release, update OnurPi to that exact version and run:
+
+```bash
+npm run workflows:sync
+```
+
+Then verify the Herdr plugin list, open `piw`, and start or reload Pi to confirm resource discovery. Repeating the sync must return `unchanged`.