Agent replacement and handoff

Praxis naming: This page documents Praxis, the AIWS workflow engine. Existing engine/* source paths, /engine/... routes, aiws-engine/* protocol identifiers, and existing script names remain unchanged for compatibility.

M7 Slice 6 supports human-approved replacement before dispatch or between fully settled stages in an opt-in bound coding workflow. The replacement receives an immutable handoff, acknowledges it under its authenticated agent identity, and executes through a host-installed adapter. Use current GitHub source on Node.js 24; baseline SDK packages and source downloads do not contain this API.

npm run engine:typecheck
npm run test:engine:m7-replacement
npm run example:engine:replacement

The example uses explicitly simulated human/agent identities and capability evidence. It runs implementation with the original worker, transfers validation to the replacement, and verifies human acceptance, preserved original evidence and cumulative attempts.

Review, acknowledge and continue

The host installs a CodingWorkflowRunner adapter in agentAdapters[agentId] with the reviewed capabilityDigest and execute(request). DynamicWorkflowRepository also requires host authorization, exact human approval verification and an independent verifyReplacement(target, review) capability check. Production hosts must establish these identities and proofs; the example’s tokens are only local simulation.

1. Read the current bound definition and workflow state. Build a candidate with definitionWithAgentReplacement(head.definition, {agentId, capabilityDigest}) and submit it through PROPOSE.
2. Present the exact ACTIVATE_REPLACEMENT review to the human. The command includes the proposal, expected workflow revision, replacement and approval ID. Reviewing does not itself authorize activation.
3. Execute the approved command. The engine preserves the plan, stage, inputs, old evidence and accounting; records the replacement and handoff; cancels superseded queued instances; and requires fresh stage approval.
4. Read registry.replacementHandoff(assignmentId) through the trusted host. The assigned agent submits ACK_REPLACEMENT with the exact assignment and handoff digest. A human session cannot substitute for the agent’s acknowledgment.
5. Renew human stage approval and run the workflow. Dispatch requires both approvals and the exact installed adapter. After restart, use human resume and obtain an acknowledgment for the new coordinator epoch before new dispatch.

The complete runnable sequence is engine/examples/agent-replacement.ts. These are local TypeScript repository/runner APIs; remote CLI/web commands and native SDK parity remain Slice 8 work.

What can be transferred?

State	Behavior
Unstarted next stage, no live claim or attempt	Eligible for reviewed replacement
Previous stage fully settled, next stage unstarted	Eligible; prior evidence and accounting are retained
Active claim, acquired handoff or unresolved attempt	Replacement refused
Paused controls or open accounting hold	Replacement refused
Awaiting final acceptance or succeeded	Replacement refused
Target has not acknowledged	Dispatch blocked; another reviewed replacement is possible
Adapter missing or capability digest differs	Dispatch blocked before stage handoff acquisition

Replacement changes the one coding agent across all graph nodes. Commands, task identities, dependencies, acceptance criteria, resource limits and correction policy stay fixed. The immutable handoff includes the exact source state, previous agent, new definition and queue supersession. Renewed human stage approval creates the next stage handoff from that reviewed transfer.

Hold uncertain work

An exact human-approved HOLD_REPLACEMENT command moves the workflow to HELD and records a durable dispatch hold. It fences new delivery, acknowledgment and live result publication. The engine retains outstanding attempts and exposure: a late or disconnected worker may still have caused external effects.

A hold does not terminate the worker, undo effects, settle attempts or refund resources. Generic resume cannot release it. Slice 7 adds explicit same-stage retry after verified effect reconciliation. Stale results remain rejected; no compatibility grant is implemented. Do not treat entering a hold as successful agent transfer.

Ownership and recovery

Worker identity includes the coordinator epoch and assignment generation. Dispatch material and result pins bind the logical agent, reviewed capability digest and exact handoff. Superseded owners cannot publish under the new assignment. Historical results keep their original ownership; completed work is not relabeled or rerun during transfer.

Activation, acknowledgment and hold receipts are durable and idempotent. Replacement commit tests cover rollback and real process termination before and after commit. Existing saved-result recovery avoids repeating committed effects under the same assignment. New execution after restart requires the current epoch acknowledgment.

Plan/dependency edits and preparation insertion after replacement are currently blocked until a combined capability-review path is defined. Repeated whole-agent replacement is supported. Concurrent heterogeneous agents, remote adapter transport, external process termination and cross-revision reuse of unsettled results remain outside this profile.

The contract is spec/engine-v1/AGENT-REPLACEMENT.md; verification is in docs/M7-AGENT-REPLACEMENT.md. M6 platform and long-duration qualification remains open independently.