@atolis-hq/wake 0.2.84 → 0.2.85

package/dist/src/adapters/claude/claude-runner.js

@@ -116,11 +116,11 @@ const CLAUDE_CLI_NAME = 'Claude';
 // second attempt at the task, so it never needs more than one turn.
 const ENVELOPE_REPAIR_MAX_TURNS = 1;
 const ENVELOPE_REPAIR_TIMEOUT_MS = 60_000;
-function buildEnvelopeRepairPrompt(skipApproval) {
+function buildEnvelopeRepairPrompt(reviewShaped) {
     return [
         'Your previous reply did not end with the required `wake-result` envelope, so it could not be parsed.',
         'Reply with ONLY a fenced `wake-result` JSON block containing a `status` field, then repeat that status word on its own line after the closing fence.',
-        `The status must be exactly one of: ${sentinelListForApproval(skipApproval)}, reflecting the outcome of your previous turn.`,
+        `The status must be exactly one of: ${sentinelListForApproval(reviewShaped)}, reflecting the outcome of your previous turn.`,
         'Do not repeat, summarize, or redo any of your previous work — this reply is parsed automatically and anything besides the envelope is discarded.',
     ].join('\n');
 }
@@ -160,7 +160,7 @@ function mergeTokenUsage(base, extra) {
 async function attemptEnvelopeRepair(input) {
     const args = buildClaudePrintArgs({
         model: input.model,
-        prompt: buildEnvelopeRepairPrompt(input.skipApproval),
+        prompt: buildEnvelopeRepairPrompt(input.reviewShaped),
         sessionName: input.sessionName,
         resumeSessionId: input.sessionId,
         maxTurns: ENVELOPE_REPAIR_MAX_TURNS,
@@ -421,7 +421,7 @@ export function createClaudeRunner(options) {
                 model,
                 sessionName,
                 sessionId: parsed.session_id,
-                skipApproval: stagePrompt.skipApproval,
+                reviewShaped: stagePrompt.reviewShaped,
                 timeoutMs: Math.min(options.settings.timeoutMs, ENVELOPE_REPAIR_TIMEOUT_MS),
             });
             if (repair !== undefined && parseRunnerResult(repair.text).envelope !== 'missing') {

package/dist/src/adapters/http/ui-data.js

@@ -37,6 +37,10 @@ function deriveCondition(item, lastRun, config) {
     if (lastRun?.status === 'blocked' ||
         lastRun?.status === 'awaiting-approval' ||
         lastRun?.sentinel === 'BLOCKED' ||
+        // A run record can never be written with this sentinel value again
+        // (ADR 0002), but a pre-existing run record on disk still can be —
+        // legacyTolerantRunnerSentinelSchema keeps it readable, so this branch
+        // stays to classify it correctly rather than falling through to 'ready'.
         lastRun?.sentinel === 'AWAITING_APPROVAL') {
         return { condition: 'needs-human', reason: `sentinel ${lastRun?.sentinel ?? stage}` };
     }

package/dist/src/adapters/runner/stage-prompt.js

@@ -82,19 +82,24 @@ function parseFrontmatterMaxTurns(input) {
     }
     return parsed;
 }
-export function sentinelListForApproval(skipApproval) {
-    return skipApproval ? 'DONE, BLOCKED, FAILED' : 'AWAITING_APPROVAL, BLOCKED, FAILED';
+// The agent never chooses whether its stage is approval-gated — that's pure
+// policy (ADR 0002), derived from skipApproval and applied by Wake to a
+// DONE reply regardless of what the agent writes. `reviewShaped` is the only
+// axis that changes the agent-facing vocabulary: stages whose role is to
+// render a verdict on some target artifact (pr-review, plan-review) also
+// need REJECTED to report "evaluated, verdict is negative, known corrective
+// next step" — distinct from BLOCKED ("I can't decide at all").
+export function sentinelListForApproval(reviewShaped) {
+    return reviewShaped ? 'DONE, REJECTED, BLOCKED, FAILED' : 'DONE, BLOCKED, FAILED';
 }
-function sentinelInstructionsForApproval(skipApproval) {
-    if (skipApproval) {
-        return [
-            '- DONE: the stage objective is complete.',
-            '- BLOCKED: you need clarification from a human or cannot proceed safely.',
-            '- FAILED: something prevented you from completing this stage at all.',
-        ].join('\n');
-    }
+function sentinelInstructionsForApproval(reviewShaped) {
     return [
-        '- AWAITING_APPROVAL: the stage objective is complete but requires human sign-off before Wake proceeds. Wake will notify the human automatically — do not post a GitHub comment yourself.',
+        '- DONE: the stage objective is complete.',
+        ...(reviewShaped
+            ? [
+                '- REJECTED: you evaluated the target and it does not meet the bar — explain what needs to change. Wake routes this back to a corrective stage automatically; you do not need to ask a human what to do next.',
+            ]
+            : []),
         '- BLOCKED: you need clarification from a human or cannot proceed safely.',
         '- FAILED: something prevented you from completing this stage at all.',
     ].join('\n');
@@ -124,7 +129,7 @@ function buildHarnessPrompt(input) {
     if (input.preExistingUncommittedChanges) {
         lines.push('', 'Pre-existing uncommitted changes notice:', 'This workspace already has uncommitted changes, left over from a previous interrupted attempt at this same issue (e.g. a crash or usage-limit cutoff). They are your own prior partial work, not an unknown or unsafe state - review them with `git status`/`git diff` and continue, amend, or discard as appropriate, then commit when ready.');
     }
-    lines.push('', 'Result envelope ABI:', 'Respond concisely. End your response with a fenced `wake-result` JSON block, then on its own line after the closing fence repeat the status word for degraded-mode fallback.', `The JSON \`status\` and final line must be exactly one of: ${sentinelListForApproval(input.skipApproval)}.`, sentinelInstructionsForApproval(input.skipApproval), 'The JSON object must contain only the `status` field. Do not add other fields.', 'This envelope is mandatory, not optional formatting: an automated parser reads only your final lines, and a reply that omits it is discarded and treated as BLOCKED regardless of the work you actually completed.');
+    lines.push('', 'Result envelope ABI:', 'Respond concisely. End your response with a fenced `wake-result` JSON block, then on its own line after the closing fence repeat the status word for degraded-mode fallback.', `The JSON \`status\` and final line must be exactly one of: ${sentinelListForApproval(input.reviewShaped)}.`, sentinelInstructionsForApproval(input.reviewShaped), 'The JSON object must contain only the `status` field. Do not add other fields.', 'This envelope is mandatory, not optional formatting: an automated parser reads only your final lines, and a reply that omits it is discarded and treated as BLOCKED regardless of the work you actually completed.');
     if (input.prTrackingEnabled) {
         lines.push('', 'Artifact reporting:', 'If you created a pull request during this stage, report it before the result envelope by adding a fenced `wake-artifacts` JSON block:', '```wake-artifacts', '{ "artifacts": [{ "kind": "pr", "url": "<the PR URL>" }] }', '```', 'Only report a PR you actually created in this run. Omit the block entirely if you created no PR.');
     }
@@ -196,6 +201,7 @@ export async function buildStagePrompt(input) {
         Object.assign(context, input.contextOverrides);
     }
     const skipApproval = template.frontmatter.skipApproval === 'true';
+    const reviewShaped = template.frontmatter.sentinelVocabulary === 'review';
     const allowAutoApproval = !skipApproval && template.frontmatter.allowAutoApproval === 'true';
     const permissionMode = template.frontmatter.permissionMode;
     const commentsToAddress = newCommentsSinceLastRun(input.projection);
@@ -239,7 +245,7 @@ export async function buildStagePrompt(input) {
     return {
         prompt: `${renderedTemplate}\n\n${untrustedDataBlock}\n\n${envelopeReminder}`,
         harnessPrompt: buildHarnessPrompt({
-            skipApproval,
+            reviewShaped,
             prTrackingEnabled: input.config?.sources.github.enabled === true &&
                 input.config?.sources.github.pullRequests.enabled === true,
             ...(input.mergeConflictDetected === true ? { mergeConflictDetected: true } : {}),
@@ -255,6 +261,7 @@ export async function buildStagePrompt(input) {
             value: template.frontmatter.maxTurns,
         }),
         skipApproval,
+        reviewShaped,
         allowAutoApproval,
         ...(permissionMode === undefined ? {} : { permissionMode }),
     };

package/dist/src/core/event-builders.js

@@ -79,10 +79,10 @@ export function createPublishIntentEvent(input) {
         ingestedAt: input.occurredAt,
         trigger: 'context-only',
         payload: {
-            kind: input.sentinel === 'BLOCKED'
-                ? 'question'
-                : input.sentinel === 'AWAITING_APPROVAL'
-                    ? 'approval-request'
+            kind: input.sentinel === 'DONE' && input.approvalGated === true
+                ? 'approval-request'
+                : input.sentinel === 'BLOCKED'
+                    ? 'question'
                     : input.sentinel === 'FAILED'
                         ? 'failure'
                         : 'status-update',

package/dist/src/core/policy-engine.js

@@ -1,11 +1,19 @@
-import { awaitingApprovalRunnerSentinel, failedRunnerSentinel } from '../domain/stages.js';
+import { failedRunnerSentinel } from '../domain/stages.js';
 import { resolveCustomCommand } from '../domain/custom-commands.js';
 import { builtInDefaultWorkflowDefinition, chooseAction as chooseWorkflowAction, isKnownWorkflowStage, selectWorkflowForEvent, workflowForProjection, } from '../domain/workflows.js';
 import { alwaysManualIgnoredLabels } from '../domain/manual-labels.js';
 import { autoApprovalLabel } from './approval-intents.js';
 function isAwaitingApproval(issue) {
     const context = issue.context;
-    return context.lastRunSentinel === awaitingApprovalRunnerSentinel;
+    // pendingApprovalAction persists through a changes-requested review round
+    // within the same gated cycle (that fold path never touches it), so it's
+    // the faithful "is this item currently gated on human sign-off" signal —
+    // context.status alone flips between 'awaiting-approval' and
+    // 'changes-requested' within the same gated cycle and can't be used here.
+    // The lastRunSentinel fallback tolerates a projection folded before
+    // pendingApprovalAction was reliably set on every gated DONE.
+    return (typeof context.pendingApprovalAction === 'string' ||
+        context.lastRunSentinel === 'AWAITING_APPROVAL');
 }
 function belowFailureRetryLimit(issue, config) {
     if (config === undefined) {
@@ -137,6 +145,9 @@ export function createPolicyEngine() {
                 }
                 return false;
             }
+            if (lastRunSentinel === 'REJECTED') {
+                return false;
+            }
             if (lastRunSentinel === 'BLOCKED') {
                 return false;
             }

package/dist/src/core/projection-updater.js

@@ -1,6 +1,6 @@
 import { CORRELATION_PRIMARY_CONFLICT_EVENT, CORRELATION_REGISTERED_EVENT, CORRELATION_RETRACTED_EVENT, RETRY_REQUESTED_EVENT, RUN_REQUESTED_EVENT, RUN_CLAIMED_EVENT, RUN_COMPLETED_EVENT, WORKFLOW_SELECTED_EVENT, WORK_ITEM_DELETED_EVENT, WORK_ITEM_FROZEN_EVENT, WORK_ITEM_UNFROZEN_EVENT, WORKSPACE_CLEANED_EVENT, } from '../domain/event-types.js';
 import { UNRESOLVED_WORK_ITEM_KEY, parseIssueStateRecord } from '../domain/schema.js';
-import { doneRunnerSentinel, stageFromLabels } from '../domain/stages.js';
+import { doneRunnerSentinel, rejectedRunnerSentinel, stageFromLabels } from '../domain/stages.js';
 import { FROZEN_WORK_ITEM_LABEL } from '../domain/work-item-lifecycle.js';
 import { workItemStatusForRunOutcome } from '../domain/work-item-status.js';
 import { builtInDefaultWorkflowDefinition, defaultWorkflowName, selectWorkflowForEvent, workflowStageVocabulary, } from '../domain/workflows.js';
@@ -202,6 +202,15 @@ async function applyEvent(current, event, ctx, config) {
     }
     if (event.sourceEventType === RUN_COMPLETED_EVENT) {
         const payload = event.payload;
+        // A historical event stream may still carry the retired AWAITING_APPROVAL
+        // sentinel (pre-ADR-0002). Normalize it here, once, so every branch below
+        // and the strict runnerSentinelSchema validation on new writes to
+        // context.lastRunSentinel only ever see the current four-value
+        // vocabulary — replaying an old event stream must still land on the same
+        // practical state (approval-gated) as it did before this change.
+        const isLegacyAwaitingApproval = payload.sentinel === 'AWAITING_APPROVAL';
+        const sentinel = isLegacyAwaitingApproval ? doneRunnerSentinel : payload.sentinel;
+        const approvalGated = payload.approvalGated === true || isLegacyAwaitingApproval;
         // A rejecting plan-review/pr-review watcher sub-run (§5, trigger 1) or a
         // human /changes reply (§5, trigger 2) folds onto the parent's context
         // without touching wake.stage/lastRunId/session — same isolation
@@ -253,9 +262,9 @@ async function applyEvent(current, event, ctx, config) {
         // the in-progress session after a human replies.
         const isForwardProgression = payload.nextStage !== undefined && payload.nextStage !== current.wake.stage;
         const stageChanged = payload.nextStage !== undefined && payload.nextStage !== current.wake.stage;
-        const isFailed = payload.sentinel === 'FAILED';
+        const isFailed = sentinel === 'FAILED';
         const isCompletedCustomCommand = payload.action !== undefined &&
-            payload.sentinel === doneRunnerSentinel &&
+            sentinel === doneRunnerSentinel &&
             config !== undefined &&
             isCustomCommandAction(payload.action, config);
         const shouldClearSession = isForwardProgression || isFailed;
@@ -268,29 +277,28 @@ async function applyEvent(current, event, ctx, config) {
             lastFailureClass: payload.failureClass,
             failureCount: payload.failureClass !== undefined
                 ? currentFailureCount + 1
-                : payload.sentinel === doneRunnerSentinel || payload.sentinel === 'AWAITING_APPROVAL'
+                : sentinel === doneRunnerSentinel || sentinel === rejectedRunnerSentinel
                     ? 0
                     : currentFailureCount,
             ...(payload.handledCommentId === undefined
                 ? {}
                 : { lastHandledCommentId: payload.handledCommentId }),
-            ...(payload.sentinel === undefined || isCompletedCustomCommand
-                ? {}
-                : { lastRunSentinel: payload.sentinel }),
+            ...(sentinel === undefined || isCompletedCustomCommand ? {} : { lastRunSentinel: sentinel }),
             ...(payload.action === undefined || isCompletedCustomCommand
                 ? {}
                 : { lastRunAction: payload.action }),
-            ...(payload.sentinel === doneRunnerSentinel &&
+            ...(sentinel === doneRunnerSentinel &&
                 payload.action !== undefined &&
                 !isCompletedCustomCommand
                 ? { lastCompletedAction: payload.action }
                 : {}),
             // Remembered so the approval path knows which action to resume or
-            // skip when a human posts /approved.
-            ...(payload.sentinel === 'AWAITING_APPROVAL' && payload.action !== undefined
+            // skip when a human posts /approved. Set only for an approval-gated
+            // DONE — REJECTED/BLOCKED/FAILED never gate on human sign-off this way.
+            ...(sentinel === doneRunnerSentinel && approvalGated && payload.action !== undefined
                 ? { pendingApprovalAction: payload.action }
                 : {}),
-            ...(payload.sentinel === 'AWAITING_APPROVAL'
+            ...(sentinel === doneRunnerSentinel && approvalGated
                 ? { pendingApprovalAllowAutoApproval: payload.allowAutoApproval === true }
                 : {}),
             ...(payload.executionOutcome !== undefined
@@ -310,27 +318,28 @@ async function applyEvent(current, event, ctx, config) {
                 ? { lastExternalSideEffects: payload.externalSideEffects }
                 : {}),
             ...(payload.retrySafety !== undefined ? { lastRetrySafety: payload.retrySafety } : {}),
-            ...(payload.sentinel === undefined || isCompletedCustomCommand
+            ...(sentinel === undefined || isCompletedCustomCommand
                 ? {}
                 : {
                     status: workItemStatusForRunOutcome({
-                        sentinel: payload.sentinel,
+                        sentinel: sentinel,
                         stage: payload.nextStage ?? current.wake.stage,
+                        approvalGated,
                     }),
                 }),
-            // A fresh DONE/AWAITING_APPROVAL cycle resolves whatever changes were
+            // A fresh DONE cycle (gated or not) resolves whatever changes were
             // previously requested — reset the loop counter and stored feedback.
-            ...(payload.sentinel === doneRunnerSentinel || payload.sentinel === 'AWAITING_APPROVAL'
+            ...(sentinel === doneRunnerSentinel
                 ? { changesRequestedCount: 0, changesRequestedFeedback: undefined }
                 : {}),
         };
-        if (payload.sentinel === 'BLOCKED' || payload.sentinel === 'FAILED') {
+        if (sentinel === 'BLOCKED' || sentinel === 'FAILED') {
             nextContext.blockedFromStage = current.wake.stage;
         }
-        else if (payload.sentinel !== undefined) {
+        else if (sentinel !== undefined) {
             delete nextContext.blockedFromStage;
         }
-        if (payload.sentinel !== 'AWAITING_APPROVAL' && !isCompletedCustomCommand) {
+        if (!(sentinel === doneRunnerSentinel && approvalGated) && !isCompletedCustomCommand) {
             delete nextContext.pendingApprovalAction;
             delete nextContext.pendingApprovalAllowAutoApproval;
         }

package/dist/src/core/tick-runner.js

@@ -8,7 +8,6 @@ import { acquireFileLock } from '../lib/lock.js';
 import { CORRELATION_REGISTERED_EVENT, CORRELATION_PRIMARY_CONFLICT_EVENT, PR_AUTO_MERGE_ENABLED_EVENT, PR_REVIEW_APPROVED_EVENT, PUBLISH_INTENT_REQUESTED_EVENT, RUN_CLAIMED_EVENT, RUN_COMPLETED_EVENT, } from '../domain/event-types.js';
 import { parseRunnerArtifacts, parseRunnerResult } from '../domain/schema.js';
 import { maxConfiguredRunnerTimeoutMs, resolveRunnerRouting } from '../domain/runner-routing.js';
-import { awaitingApprovalRunnerSentinel } from '../domain/stages.js';
 import { FROZEN_WORK_ITEM_LABEL, isWorkItemDeleted, isWorkItemRunnable, } from '../domain/work-item-lifecycle.js';
 import { isMeaningfulRuntimeEvent } from '../domain/runtime-events.js';
 import { chooseAction as chooseWorkflowAction, entryStage as workflowEntryStage, isKnownWorkflowStage, workflowChangedBlockReason, workflowForProjection, workflowNameForProjection, } from '../domain/workflows.js';
@@ -204,7 +203,15 @@ export function createTickRunner(deps) {
     });
     const ownerInstanceId = `instance-${process.pid}-${Date.now()}`;
     function isAwaitingApproval(projection) {
-        return projection.context.lastRunSentinel === awaitingApprovalRunnerSentinel;
+        // pendingApprovalAction persists through a changes-requested review round
+        // within the same gated cycle (that fold path never touches it), so it's
+        // the faithful "is this item currently gated on human sign-off" signal —
+        // context.status alone flips between 'awaiting-approval' and
+        // 'changes-requested' within the same gated cycle and can't be used here.
+        // The lastRunSentinel fallback tolerates a projection folded before
+        // pendingApprovalAction was reliably set on every gated DONE.
+        return (typeof projection.context.pendingApprovalAction === 'string' ||
+            projection.context.lastRunSentinel === 'AWAITING_APPROVAL');
     }
     // Always reads the current projection at write time (never a threaded
     // local like a stale `workflowName`/`claimedStage`), so a mid-run
@@ -890,8 +897,10 @@ export function createTickRunner(deps) {
     }
     function watcherStatus(projection) {
         const sentinel = projection.context.lastRunSentinel;
-        if (sentinel === 'AWAITING_APPROVAL')
+        if (isAwaitingApproval(projection))
             return 'awaiting-approval';
+        if (sentinel === 'REJECTED')
+            return 'rejected';
         if (sentinel === 'BLOCKED')
             return 'blocked';
         if (sentinel === 'FAILED')
@@ -1755,19 +1764,21 @@ export function createTickRunner(deps) {
                 clearInterval(leaseRenewalTimer);
                 leaseRenewalTimer = undefined;
                 const parsedRunnerResult = parseRunnerResult(runnerResult.result);
-                const rawSentinel = parsedRunnerResult.status;
-                // Coerce DONE → AWAITING_APPROVAL when the stage requires human sign-off.
-                // An agent that writes DONE but was told not to skip approval has violated
-                // the protocol; treat it as AWAITING_APPROVAL so the gate is enforced.
+                const sentinel = parsedRunnerResult.status;
+                // The approval gate is pure policy, never the agent's word choice —
+                // a DONE on a stage configured with skipApproval: false is gated
+                // regardless of what the agent wrote (ADR 0002).
                 const skipApproval = runnerResult.metadata?.skipApproval;
-                const sentinel = rawSentinel === 'DONE' && skipApproval === false ? 'AWAITING_APPROVAL' : rawSentinel;
+                const approvalGated = sentinel === 'DONE' && skipApproval === false;
                 // A canceled run must not advance the stage regardless of what the
                 // runner echoed back — the snapshot it acted on was superseded.
                 const nextStage = cancellationReason !== null
                     ? null
-                    : isLateralReadOnlyAction(action, deps.config) && sentinel === 'DONE'
+                    : approvalGated
                         ? null
-                        : lifecycle.nextStageFromSentinel(claimedStage, sentinel, workflow);
+                        : isLateralReadOnlyAction(action, deps.config) && sentinel === 'DONE'
+                            ? null
+                            : lifecycle.nextStageFromSentinel(claimedStage, sentinel, workflow);
                 const finishedAt = deps.clock.now().toISOString();
                 let workspaceBookkeeping;
                 if (workspacePath !== undefined) {
@@ -1810,7 +1821,6 @@ export function createTickRunner(deps) {
                             sourceRevision,
                             watcherTrigger: watcherTriggerForRun,
                             verifiedTargetResourceUri: prReviewTargetResourceUri,
-                            rawSentinel,
                         },
                         outcome: {
                             sentinel,
@@ -1818,7 +1828,7 @@ export function createTickRunner(deps) {
                                 ? 'uncertain'
                                 : sentinel === 'DONE'
                                     ? 'approved'
-                                    : sentinel === 'FAILED'
+                                    : sentinel === 'REJECTED'
                                         ? 'changes-requested'
                                         : 'uncertain',
                             reasoning: parsedRunnerResult.body,
@@ -1895,11 +1905,13 @@ export function createTickRunner(deps) {
                 const workflowOutcome = cancellationReason !== null
                     ? undefined
                     : sentinel === 'DONE'
-                        ? 'DONE'
-                        : sentinel === 'BLOCKED'
-                            ? 'BLOCKED'
-                            : sentinel === 'AWAITING_APPROVAL'
-                                ? 'AWAITING_APPROVAL'
+                        ? approvalGated
+                            ? 'AWAITING_APPROVAL'
+                            : 'DONE'
+                        : sentinel === 'REJECTED'
+                            ? 'CHANGES_REQUESTED'
+                            : sentinel === 'BLOCKED'
+                                ? 'BLOCKED'
                                 : undefined;
                 await transitionRunLifecycle('FINALISING');
                 const finalisingRecord = (await deps.stateStore.readRunRecord(runId));
@@ -1917,11 +1929,13 @@ export function createTickRunner(deps) {
                     ...finalisingRecord,
                     lifecycle: 'TERMINAL',
                     status: sentinel === 'DONE'
-                        ? 'completed'
-                        : sentinel === 'BLOCKED'
-                            ? 'blocked'
-                            : sentinel === 'AWAITING_APPROVAL'
-                                ? 'awaiting-approval'
+                        ? approvalGated
+                            ? 'awaiting-approval'
+                            : 'completed'
+                        : sentinel === 'REJECTED'
+                            ? 'rejected'
+                            : sentinel === 'BLOCKED'
+                                ? 'blocked'
                                 : 'failed',
                     finishedAt,
                     sessionId: runnerResult.session_id,
@@ -1947,7 +1961,7 @@ export function createTickRunner(deps) {
                     ? deps.config.workflows[watcherDispatch.parentWorkflowName]?.stages[watcherDispatch.parentStage]?.watch?.[watcherDispatch.watcherIndex]?.onSuccess
                     : undefined;
                 const isReviewRejection = watcherRun &&
-                    (sentinel === 'FAILED' || sentinel === 'BLOCKED') &&
+                    sentinel === 'REJECTED' &&
                     (prReviewTargetResourceUri !== null || watcherSuccessPolicy?.approve === true);
                 const runCompletedEvent = createEventEnvelope({
                     eventId: `${runId}-completed`,
@@ -1967,8 +1981,8 @@ export function createTickRunner(deps) {
                     payload: {
                         action,
                         sentinel,
+                        approvalGated,
                         allowAutoApproval: runnerResult.metadata?.allowAutoApproval === true,
-                        ...(rawSentinel !== sentinel ? { rawSentinel } : {}),
                         ...(nextStage !== null ? { nextStage } : {}),
                         runId,
                         sessionId: runnerResult.session_id,
@@ -2018,6 +2032,7 @@ export function createTickRunner(deps) {
                     runnerResult,
                     parsedRunnerResult,
                     sentinel,
+                    approvalGated,
                     occurredAt: finishedAt,
                     startedAt: nowIso,
                     ...(workspacePath === undefined ? {} : { workspacePath }),
@@ -2030,7 +2045,7 @@ export function createTickRunner(deps) {
                     // registration regardless of the target workflow/action name.
                     const pendingApprovalAction = candidate.context.pendingApprovalAction;
                     if (prReviewTargetResourceUri !== null &&
-                        (sentinel === 'DONE' || sentinel === 'FAILED')) {
+                        (sentinel === 'DONE' || sentinel === 'REJECTED')) {
                         await deliverOutboundEvent({
                             ...publishIntent,
                             sourceRefs: {
@@ -2049,10 +2064,14 @@ export function createTickRunner(deps) {
                     }
                     else if (watcherDispatch !== null &&
                         watcherSuccessPolicy?.approve === true &&
-                        (sentinel === 'DONE' || sentinel === 'FAILED' || sentinel === 'BLOCKED')) {
+                        (sentinel === 'DONE' ||
+                            sentinel === 'REJECTED' ||
+                            sentinel === 'FAILED' ||
+                            sentinel === 'BLOCKED')) {
                         // No PR surface to carry the verdict comment: the child's sentinel
                         // is its verdict. Publish the review body for every verdict so the
-                        // human sees why; only DONE resolves the parent's pending gate.
+                        // human sees why; only an ungated DONE resolves the parent's
+                        // pending gate (checked below via isAwaitingApproval).
                         await deliverOutboundEvent(publishIntent);
                         const approvalId = `${runId}-parent-approval`;
                         const parentWorkflow = deps.config.workflows[watcherDispatch.parentWorkflowName];

package/dist/src/domain/schema.js

@@ -19,6 +19,14 @@ export const wakeArtifactsEnvelopeSchema = z.object({
     artifacts: z.array(reportedArtifactSchema).default([]),
 });
 export const runnerSentinelSchema = z.enum(runnerSentinelValues);
+// A projection persisted before ADR 0002 can still have context.lastRunSentinel
+// = "AWAITING_APPROVAL" on disk. That field is read (not just replayed) on
+// every ordinary parseIssueStateRecord call, not only during an explicit
+// event-log rebuild, so the strict current-vocabulary schema above would
+// reject an untouched legacy projection outright. This schema stays
+// permissive to that one retired value so existing on-disk state keeps
+// loading until it's naturally refreshed by a new run.
+const legacyTolerantRunnerSentinelSchema = z.enum([...runnerSentinelValues, 'AWAITING_APPROVAL']);
 export const executionOutcomeValues = [
     'COMPLETED',
     'STARTUP_FAILED',
@@ -311,9 +319,9 @@ export const issueContextSchema = z.object({
     blockedFromStage: z.string().optional(),
     lastFailureClass: z.enum(['task', 'quota', 'infra']).optional(),
     lastHandledCommentId: z.string().optional(),
-    lastRunSentinel: runnerSentinelSchema.optional(),
-    // Set while AWAITING_APPROVAL so the approval path knows which action to
-    // resume (or skip) once a human responds.
+    lastRunSentinel: legacyTolerantRunnerSentinelSchema.optional(),
+    // Set while approval-gated (context.status === 'awaiting-approval') so the
+    // approval path knows which action to resume (or skip) once a human responds.
     pendingApprovalAction: z.string().optional(),
     pendingApprovalAllowAutoApproval: z.boolean().optional(),
     // Workflow pinned at mint time (WORKFLOW_SELECTED_EVENT); re-read at every
@@ -427,6 +435,7 @@ export const runRecordSchema = z.preprocess((input) => {
         'running',
         'completed',
         'awaiting-approval',
+        'rejected',
         'blocked',
         'failed',
         'superseded',
@@ -434,7 +443,7 @@ export const runRecordSchema = z.preprocess((input) => {
     startedAt: isoTimestampSchema,
     finishedAt: isoTimestampSchema.optional(),
     sessionId: z.string().optional(),
-    sentinel: runnerSentinelSchema.optional(),
+    sentinel: legacyTolerantRunnerSentinelSchema.optional(),
     executionOutcome: executionOutcomeSchema.optional(),
     workflowOutcome: workflowOutcomeSchema.optional(),
     failurePhase: failurePhaseSchema.optional(),
@@ -1097,8 +1106,8 @@ export function parseClaudePrintResult(input) {
 function synthesizeBodyFromEnvelope(envelope) {
     const labels = {
         DONE: 'Run completed.',
+        REJECTED: 'Run rejected — needs changes.',
         BLOCKED: 'Run blocked — needs input.',
-        AWAITING_APPROVAL: 'Ready for approval.',
         FAILED: 'Run failed.',
     };
     return labels[envelope.status] ?? 'Run finished.';
@@ -1116,8 +1125,7 @@ export function parseRunnerResult(result) {
             // Claude sometimes places the sentinel keyword inside the fence rather than after
             // the closing fence. Strip a trailing sentinel line so JSON.parse sees only the JSON.
             // The capture group includes the newline before the closing fence, so allow \n? after.
-            const jsonContent = rawContent.replace(/\n(?:DONE|BLOCKED|FAILED|AWAITING_APPROVAL)[ \t]*\n?$/, '') ||
-                rawContent;
+            const jsonContent = rawContent.replace(/\n(?:DONE|REJECTED|BLOCKED|FAILED)[ \t]*\n?$/, '') || rawContent;
             const parsed = wakeResultEnvelopeSchema.safeParse(JSON.parse(jsonContent));
             if (parsed.success) {
                 const proseBody = result.slice(0, lastMatch.index).trim();

package/dist/src/domain/stages.js

@@ -1,13 +1,13 @@
 export const stageValues = ['queue', 'done'];
 export const doneRunnerSentinel = 'DONE';
+export const rejectedRunnerSentinel = 'REJECTED';
 export const blockedRunnerSentinel = 'BLOCKED';
 export const failedRunnerSentinel = 'FAILED';
-export const awaitingApprovalRunnerSentinel = 'AWAITING_APPROVAL';
 export const runnerSentinelValues = [
     doneRunnerSentinel,
+    rejectedRunnerSentinel,
     blockedRunnerSentinel,
     failedRunnerSentinel,
-    awaitingApprovalRunnerSentinel,
 ];
 export const terminalStageValues = ['done'];
 export function isTerminalStage(stage) {

package/dist/src/domain/work-item-status.js

@@ -17,9 +17,12 @@ export const workItemStatusSchema = z.enum(workItemStatusValues);
 // tick-runner.ts's statusLabelForOutcome/statusLabelForStage. Folded onto
 // context.status alongside (not replacing) context.lastRunSentinel.
 export function workItemStatusForRunOutcome(input) {
-    if (input.sentinel === 'AWAITING_APPROVAL') {
+    if (input.sentinel === 'DONE' && input.approvalGated === true) {
         return 'awaiting-approval';
     }
+    if (input.sentinel === 'REJECTED') {
+        return 'changes-requested';
+    }
     if (input.sentinel === 'BLOCKED') {
         return 'blocked';
     }

package/dist/src/domain/workflows.js

@@ -151,7 +151,7 @@ export function chooseAction(projection, workflow) {
     };
 }
 export function nextStage(stage, sentinel, workflow) {
-    if (sentinel === 'BLOCKED' || sentinel === 'FAILED' || sentinel === 'AWAITING_APPROVAL') {
+    if (sentinel === 'BLOCKED' || sentinel === 'FAILED' || sentinel === 'REJECTED') {
         return null;
     }
     const runnableStage = stage === universalQueueStage ? stageAfterQueue(workflow) : stage;

package/dist/src/version.js

@@ -124,4 +124,4 @@ export function resolveWakeVersion(options = {}) {
     }
     return '0.1.0-dev';
 }
-export const wakeVersion = "g78f9f6b";
+export const wakeVersion = "g47d31f8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolis-hq/wake",
-  "version": "0.2.84",
+  "version": "0.2.85",
   "description": "Local autonomous agent control plane for software development",
   "license": "Apache-2.0",
   "repository": {

package/prompts/plan-review.md

@@ -3,6 +3,7 @@ permissionMode: default
 allowedTools: Read, Glob, Grep, Bash(git fetch), Bash(git status), Bash(gh issue view *), Bash(gh api repos/*/issues/*), WebSearch, WebFetch
 maxTurns: 30
 skipApproval: true
+sentinelVocabulary: review
 ---
 You are Wake, in the PLAN-REVIEW workflow for work item {{workItemKey}}.
 {{toolCapabilityNote}}
@@ -30,8 +31,9 @@ Write your assessment as your response body — it is posted to the issue for th
 
 Verdict mapping:
 - Use `DONE` only when you are confident the plan should be approved; Wake resolves the pending approval and advances the stage.
-- Use `FAILED` when the plan needs changes; explain the required changes clearly.
+- Use `REJECTED` when the plan needs changes; explain the required changes clearly. Wake routes this back to a corrective stage automatically — you do not need to ask what happens next.
 - Use `BLOCKED` when the decision needs human judgment.
+- Use `FAILED` only when something prevented you from completing the review itself (e.g. you couldn't retrieve the plan text or the issue) — not when the plan's contents are the problem.
 
 Do not state your verdict in prose alone (e.g. "Verdict: DONE") — Wake does
 not parse prose. End your response with the Wake result envelope, exactly:
@@ -41,8 +43,8 @@ not parse prose. End your response with the Wake result envelope, exactly:
 ```
 DONE
 
-(substituting `FAILED` or `BLOCKED` for both the JSON value and the trailing
-line, matching your actual verdict). A response without this exact block is
-treated as `BLOCKED`, even if your prose says otherwise.
+(substituting `REJECTED`, `BLOCKED`, or `FAILED` for both the JSON value and
+the trailing line, matching your actual verdict). A response without this
+exact block is treated as `BLOCKED`, even if your prose says otherwise.
 
 {{feedbackCommandNote}}

package/prompts/pr-review.md

@@ -3,6 +3,7 @@ permissionMode: default
 allowedTools: Bash(gh pr view *), Bash(gh pr diff *), Bash(gh pr checks *), Bash(gh pr list *), Bash(gh run view *), Bash(gh api repos/*/pulls*), Bash(gh api repos/*/commits/*), Bash(gh issue view *), Bash(git status), Bash(git log *), Bash(git diff *), Read, Glob, Grep
 maxTurns: 50
 skipApproval: true
+sentinelVocabulary: review
 ---
 You are Wake, in the PR-REVIEW workflow for work item {{workItemKey}}.
 
@@ -28,8 +29,9 @@ Review judgment:
 
 Verdict mapping:
 - Use `DONE` only when you are confident the PR is safe to merge.
-- Use `FAILED` when the PR needs changes; explain the required changes clearly.
-- Use `BLOCKED` when you cannot determine a safe verdict.
+- Use `REJECTED` when the PR needs changes; explain the required changes clearly. Wake routes this back to the author automatically — you do not need to ask what happens next.
+- Use `BLOCKED` when you cannot determine a safe verdict (e.g. you can't find exactly one plausible PR for this work item).
+- Use `FAILED` only when something prevented you from completing the review itself (e.g. no GitHub access, the diff couldn't be retrieved) — not when the PR's contents are the problem.
 
 Safety rules:
 - Do not merge, approve via GitHub review, enable auto-merge, edit labels, push commits, or perform any administrative GitHub mutation.