@osolmaz/pi-workflows 0.9.1 → 0.11.0

package/dist/extension/index.js

@@ -3,19 +3,23 @@ import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { builtinWorkflowCatalog } from "../builtins/catalog.js";
 import { projectControllerStorePath, SqliteControllerStore } from "../controllers/index.js";
+import { humanDecisionChannelRequest } from "../workflows/decision-presentation.js";
 import { WorkflowEngine } from "../workflows/engine.js";
 import { ClaimLostError, errorMessage, isClaimLostError, TimeoutError, } from "../workflows/errors.js";
+import { HumanDecisionStore, createHumanDecisionAttemptId, validateHumanDecisionResponse, } from "../workflows/human-decision.js";
 import { discoverWorkflows, resolveWorkflowRef } from "../workflows/loader.js";
 import { migrateLegacyWorkflowSources } from "../workflows/migrate-sources.js";
 import { appendProgressHistory, progressRecordsFromTrace } from "../workflows/progress.js";
 import { createRunId, listRunBundles, readLastTraceEvent, readRunBundle, WorkflowRunStore, createDefinitionSnapshot, } from "../workflows/store.js";
 import { PiControllerHost, parseControllerArgs, } from "./controller-host.js";
+import { PiDecisionChannel, TelegramDecisionChannel, audienceChannels, createTelegramChannels, loadDecisionChannelConfig, verifyTelegramTokenFile, writeDecisionChannelProfile, } from "./decision-channels.js";
 import { ConversationStepExecutor } from "./executor.js";
 import { HerdrWorkflowViewer, parseViewerPlacement, PIW_SHORTCUT, PIW_SHORTCUT_HINT, VIEWER_PLACEMENTS, } from "./herdr-viewer.js";
 import { SessionRecorder } from "./recorder.js";
 import { registerWorkflowAgentStepMessageRenderer, WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA, WORKFLOW_AGENT_STEP_MESSAGE_TYPE, } from "./step-message.js";
 import { buildWidgetView } from "./widget.js";
-import { WorkflowToolParameters } from "./workflow-tool.js";
+import { parseWorkflowToolInput, WorkflowToolParameters } from "./workflow-tool.js";
+export { PiDecisionChannel, TelegramDecisionChannel, audienceChannels, createTelegramChannels, decisionConfigDir, loadDecisionChannelConfig, verifyTelegramTokenFile, writeDecisionChannelProfile, } from "./decision-channels.js";
 const RUN_CLAIM_LEASE_MS = 30_000;
 const RUN_CLAIM_RENEW_MS = 10_000;
 const RUN_SYNC_POLL_MS = 3_000;
@@ -42,6 +46,16 @@ class PresentationSupersededError extends Error {
 }
 class PresentationTimeoutError extends Error {
 }
+function humanDecisionRequest(value) {
+    const schema = value !== null && typeof value === "object"
+        ? value.schema
+        : undefined;
+    if (schema !== "pi-workflows.human-decision-request.v1" &&
+        schema !== "pi-workflows.human-decision-request.v2") {
+        return null;
+    }
+    return value;
+}
 /** Parse `/workflow` arguments. Exported for tests. */
 export function parseWorkflowArgs(args) {
     const trimmed = args.trim();
@@ -145,6 +159,16 @@ export default function piWorkflows(pi) {
     // One runner identity per session; it names this session in run claims.
     const runnerId = randomUUID();
     let runQueueStore = null;
+    let decisionChannelConfig = null;
+    let telegramDecisionChannels = new Map();
+    const activePiDecisionChannels = new Map();
+    const settleHumanDecisionChannels = async (decision) => {
+        const piChannel = activePiDecisionChannels.get(decision.decisionId);
+        await Promise.allSettled([
+            ...(piChannel === undefined ? [] : [piChannel.settle(decision)]),
+            ...[...telegramDecisionChannels.values()].map(async (channel) => channel.settle(decision)),
+        ]);
+    };
     const migrationBlockedRuns = new Set();
     const ensureRunQueueStore = (cwd) => {
         runQueueStore ??= new SqliteControllerStore(projectControllerStorePath(cwd));
@@ -154,6 +178,8 @@ export default function piWorkflows(pi) {
     // Run events remain an audit feed and never enter a conversation.
     let syncArmed = false;
     let runSyncTimer = null;
+    let decisionRecoveryTimer = null;
+    let decisionRecoveryActive = false;
     const recordRunEvent = (event) => {
         try {
             runQueueStore?.recordRunEvent({ ...event, runnerId });
@@ -548,8 +574,11 @@ export default function piWorkflows(pi) {
         if (state.status === "waiting" && run.childKey === undefined) {
             lastWaitingRunId = run.runId;
         }
+        const pendingDecision = humanDecisionRequest(state.finalOutput);
         const summary = state.status === "waiting" && state.waitingOn
-            ? `Workflow ${state.workflowName} parked at checkpoint ${state.waitingOn} — answer with /workflow answer <json> (run ${state.runId})`
+            ? pendingDecision === null
+                ? `Workflow ${state.workflowName} parked at checkpoint ${state.waitingOn} — answer with /workflow answer <json> (run ${state.runId})`
+                : `Workflow ${state.workflowName} is waiting for a verified human decision: ${pendingDecision.title} (run ${state.runId})`
             : `Workflow ${state.workflowName} ${state.status} (run ${state.runId})${state.error !== undefined ? `: ${state.error.slice(0, MAX_STATUS_ERROR_CHARS)}` : ""}`;
         notify(ctx, summary, state.status === "completed" ? "info" : "warning");
         try {
@@ -568,6 +597,24 @@ export default function piWorkflows(pi) {
             notify(ctx, `Could not record child workflow completion: ${errorMessage(error)}`, "warning");
         }
         void presentRun(ctx, run, state);
+        if (pendingDecision !== null && state.status === "waiting") {
+            const channels = audienceChannels(decisionChannelConfig, pendingDecision.audience);
+            let available = false;
+            if (ctx.mode === "tui" && channels.includes("pi")) {
+                available = true;
+                queueMicrotask(() => void promptHumanDecision(ctx, pendingDecision));
+            }
+            for (const channelId of channels) {
+                const channel = telegramDecisionChannels.get(channelId);
+                if (channel !== undefined) {
+                    available = true;
+                    queueMicrotask(() => void channel.deliver(humanDecisionChannelRequest(pendingDecision)));
+                }
+            }
+            if (!available) {
+                notify(ctx, `Human decision ${pendingDecision.title} remains waiting because its audience has no available channel.`, "warning");
+            }
+        }
     };
     const startRun = async (ctx, ref, input, options = {}) => {
         if (options.signal?.aborted) {
@@ -784,6 +831,9 @@ export default function piWorkflows(pi) {
                 : engine.continueRun(workflow, options.parentRunId, input, {
                     workflowSource,
                     runId,
+                    ...(options.humanDecision !== undefined
+                        ? { humanDecision: options.humanDecision }
+                        : {}),
                 }))
             .then((result) => finishRun(ctx, run, result))
             .catch(async (error) => {
@@ -1025,7 +1075,35 @@ export default function piWorkflows(pi) {
         const result = await listWorkflowControl(ctx);
         notify(ctx, result.message, result.level);
     };
-    const cancelWorkflowControl = (ctx) => {
+    const cancelHumanDecision = async (request) => {
+        const store = new HumanDecisionStore(new WorkflowRunStore().outputRoot);
+        await store.cancel(request, "cancelled");
+        const cancellation = await store.readCancellation(request.decisionId);
+        if (cancellation !== null)
+            await settleHumanDecisionChannels(cancellation);
+        lastWaitingRunId = null;
+    };
+    const findOwnedWaitingHumanDecision = async (ctx) => {
+        const rows = ensureRunQueueStore(ctx.cwd).listWorkflowRuns();
+        const sessionId = ctx.sessionManager.getSessionId();
+        const owned = new Set(rows
+            .filter((row) => row.originSessionId === null || row.originSessionId === sessionId)
+            .map((row) => row.runId));
+        const continued = new Set(rows.map((row) => row.parentRunId).filter((parent) => parent !== null));
+        const bundles = await listRunBundles(new WorkflowRunStore().outputRoot);
+        for (const bundle of bundles) {
+            if (bundle.state.status !== "waiting" ||
+                !owned.has(bundle.state.runId) ||
+                continued.has(bundle.state.runId)) {
+                continue;
+            }
+            const request = humanDecisionRequest(bundle.state.finalOutput);
+            if (request !== null)
+                return { state: bundle.state, request };
+        }
+        return null;
+    };
+    const cancelWorkflowControl = async (ctx) => {
         if (activeRun) {
             const workflowName = activeRun.workflowName;
             const runId = activeRun.runId;
@@ -1045,6 +1123,16 @@ export default function piWorkflows(pi) {
         }
         if (widgetSource) {
             const { state } = widgetSource;
+            const request = humanDecisionRequest(state.finalOutput);
+            if (state.status === "waiting" && request !== null) {
+                await cancelHumanDecision(request);
+                clearWidgetTimer();
+                clearWidget(ctx);
+                return {
+                    message: `Cancelled the pending human decision for workflow ${state.workflowName}.`,
+                    details: { action: "cancel", workflowName: state.workflowName, runId: state.runId },
+                };
+            }
             clearWidgetTimer();
             clearWidget(ctx);
             const detail = state.status === "waiting" && state.waitingOn
@@ -1055,6 +1143,18 @@ export default function piWorkflows(pi) {
                 details: { action: "clear", workflowName: state.workflowName, runId: state.runId },
             };
         }
+        const recovered = await findOwnedWaitingHumanDecision(ctx);
+        if (recovered !== null) {
+            await cancelHumanDecision(recovered.request);
+            return {
+                message: `Cancelled the pending human decision for workflow ${recovered.state.workflowName}.`,
+                details: {
+                    action: "cancel",
+                    workflowName: recovered.state.workflowName,
+                    runId: recovered.state.runId,
+                },
+            };
+        }
         return {
             message: "No workflow is running.",
             details: { action: "cancel", active: false },
@@ -1156,7 +1256,7 @@ export default function piWorkflows(pi) {
             details: workflowStateSummary(state),
         };
     };
-    const resolveWaitingWorkflow = async (ctx, requestedRunId) => {
+    const resolveWaitingWorkflow = async (ctx, requestedRunId, allowOtherSession = false) => {
         let parentRunId = requestedRunId ?? lastWaitingRunId;
         if (parentRunId === null) {
             const rows = ensureRunQueueStore(ctx.cwd).listWorkflowRuns();
@@ -1175,7 +1275,8 @@ export default function piWorkflows(pi) {
             throw new Error("No workflow is waiting for an answer.");
         }
         const queueRecord = ensureRunQueueStore(ctx.cwd).getWorkflowRun(parentRunId);
-        if (queueRecord?.originSessionId !== null &&
+        if (!allowOtherSession &&
+            queueRecord?.originSessionId !== null &&
             queueRecord?.originSessionId !== undefined &&
             queueRecord.originSessionId !== ctx.sessionManager.getSessionId()) {
             throw new Error(`Workflow run ${parentRunId} belongs to another Pi session.`);
@@ -1196,14 +1297,98 @@ export default function piWorkflows(pi) {
                 : parent.state.workflowSource.path,
         };
     };
-    const answerWorkflowControl = async (ctx, input, requestedRunId) => {
-        const waiting = await resolveWaitingWorkflow(ctx, requestedRunId);
-        const continued = await startRun(ctx, waiting.workflowRef, input, {
+    const answerWorkflowControl = async (ctx, input, requestedRunId, verified) => {
+        const waiting = await resolveWaitingWorkflow(ctx, requestedRunId, verified !== undefined);
+        const parent = await readRunBundle(new WorkflowRunStore().runDirFor(waiting.parentRunId));
+        if (parent === null)
+            throw new Error(`Workflow run ${waiting.parentRunId} is unreadable.`);
+        const request = humanDecisionRequest(parent.state.finalOutput);
+        let accepted;
+        let continuationInput = input;
+        let continuationRunId;
+        if (request !== null) {
+            if (verified !== undefined &&
+                (verified.request.decisionId !== request.decisionId ||
+                    verified.request.requestDigest !== request.requestDigest)) {
+                throw new Error("Verified human answer does not match the waiting decision.");
+            }
+            const response = validateHumanDecisionResponse(request, verified?.response ?? input);
+            const submission = {
+                decisionId: request.decisionId,
+                requestDigest: request.requestDigest,
+                ...response,
+                source: verified?.source ?? {
+                    channel: "pi",
+                    actorId: ctx.sessionManager.getSessionId(),
+                    eventId: createHumanDecisionAttemptId(),
+                },
+                idempotencyKey: verified?.idempotencyKey ?? createHumanDecisionAttemptId(),
+            };
+            const store = new HumanDecisionStore(new WorkflowRunStore().outputRoot);
+            const acceptance = await store.accept(request, submission);
+            if (acceptance.status === "conflict") {
+                throw new Error("That human decision was already answered differently.");
+            }
+            accepted = acceptance.decision;
+            continuationInput = parent.state.input;
+            continuationRunId = `continuation-${request.decisionId.slice("decision-".length)}`;
+        }
+        if (request !== null && accepted !== undefined && verified !== undefined) {
+            const queueRecord = ensureRunQueueStore(ctx.cwd).getWorkflowRun(waiting.parentRunId);
+            const currentSessionId = ctx.sessionManager.getSessionId();
+            if (queueRecord === undefined ||
+                (queueRecord.originSessionId !== null && queueRecord.originSessionId !== currentSessionId)) {
+                await settleHumanDecisionChannels(accepted);
+                return {
+                    message: "Human decision accepted; its owning Pi session will continue the workflow.",
+                    details: {
+                        action: "answer",
+                        parentRunId: waiting.parentRunId,
+                        accepted: true,
+                        continuationPending: true,
+                    },
+                };
+            }
+        }
+        const decisionStore = new HumanDecisionStore(new WorkflowRunStore().outputRoot);
+        if (request !== null && continuationRunId !== undefined && accepted !== undefined) {
+            await decisionStore.recordContinuation(request.decisionId, {
+                schema: "pi-workflows.human-decision-continuation.v1",
+                decisionId: request.decisionId,
+                requestDigest: request.requestDigest,
+                parentRunId: waiting.parentRunId,
+                runId: continuationRunId,
+                createdAt: accepted.acceptedAt,
+            });
+        }
+        if (continuationRunId !== undefined) {
+            const existingContinuation = await readRunBundle(new WorkflowRunStore().runDirFor(continuationRunId));
+            if (existingContinuation !== null) {
+                if (accepted !== undefined)
+                    await settleHumanDecisionChannels(accepted);
+                lastWaitingRunId = null;
+                return {
+                    message: `Human decision already continued as ${continuationRunId}.`,
+                    details: {
+                        action: "answer",
+                        parentRunId: waiting.parentRunId,
+                        runId: continuationRunId,
+                        adopted: true,
+                    },
+                };
+            }
+        }
+        const continued = await startRun(ctx, waiting.workflowRef, continuationInput, {
             parentRunId: waiting.parentRunId,
+            ...(accepted !== undefined ? { humanDecision: accepted } : {}),
+            ...(continuationRunId !== undefined ? { runId: continuationRunId } : {}),
         });
         if (continued === undefined) {
             throw new Error("Could not start the checkpoint continuation.");
         }
+        if (request !== null && accepted !== undefined) {
+            await settleHumanDecisionChannels(accepted);
+        }
         lastWaitingRunId = null;
         return {
             message: `Answered checkpoint ${waiting.parentRunId}; continuation ${continued} started.`,
@@ -1214,6 +1399,148 @@ export default function piWorkflows(pi) {
             },
         };
     };
+    async function promptHumanDecision(ctx, request) {
+        if (activePiDecisionChannels.has(request.decisionId))
+            return;
+        const channel = new PiDecisionChannel({
+            actorId: ctx.sessionManager.getSessionId(),
+            ui: ctx.ui,
+            store: new HumanDecisionStore(new WorkflowRunStore().outputRoot),
+            onAnswer: async (answer) => {
+                const result = await answerWorkflowControl(ctx, answer.response, request.runId, answer);
+                notify(ctx, result.message, result.level);
+            },
+        });
+        activePiDecisionChannels.set(request.decisionId, channel);
+        try {
+            await channel.deliver(humanDecisionChannelRequest(request));
+        }
+        catch (error) {
+            notify(ctx, `Could not answer human decision: ${errorMessage(error)}`, "error");
+        }
+        finally {
+            if (activePiDecisionChannels.get(request.decisionId) === channel) {
+                activePiDecisionChannels.delete(request.decisionId);
+            }
+        }
+    }
+    const stopDecisionChannels = async () => {
+        await Promise.allSettled([
+            ...[...activePiDecisionChannels.values()].map(async (channel) => channel.stop()),
+            ...[...telegramDecisionChannels.values()].map(async (channel) => channel.stop()),
+        ]);
+        activePiDecisionChannels.clear();
+        telegramDecisionChannels.clear();
+        decisionChannelConfig = null;
+    };
+    const reloadDecisionChannels = async (ctx) => {
+        await stopDecisionChannels();
+        const loaded = await loadDecisionChannelConfig();
+        if (loaded === null)
+            return;
+        decisionChannelConfig = loaded.channels;
+        telegramDecisionChannels = createTelegramChannels({
+            config: loaded.channels,
+            credentials: loaded.credentials,
+            configDir: loaded.configDir,
+            store: new HumanDecisionStore(new WorkflowRunStore().outputRoot),
+            onAnswer: async (answer) => {
+                await answerWorkflowControl(ctx, answer.response, answer.request.runId, answer);
+            },
+        });
+        await Promise.all([...telegramDecisionChannels.values()].map(async (channel) => channel.start()));
+    };
+    const recoverHumanDecisions = async (ctx, deliverPending = true) => {
+        const runStore = new WorkflowRunStore();
+        const store = new HumanDecisionStore(runStore.outputRoot);
+        const requests = (await store.listRequests()).sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+        for (const request of requests) {
+            const parent = await readRunBundle(runStore.runDirFor(request.runId));
+            if (parent === null || parent.state.status !== "waiting")
+                continue;
+            const currentRequest = humanDecisionRequest(parent.state.finalOutput);
+            if (currentRequest === null ||
+                currentRequest.decisionId !== request.decisionId ||
+                currentRequest.requestDigest !== request.requestDigest) {
+                continue;
+            }
+            const queueRecord = ensureRunQueueStore(ctx.cwd).getWorkflowRun(request.runId);
+            const ownedBySession = queueRecord !== undefined &&
+                (queueRecord.originSessionId === null ||
+                    queueRecord.originSessionId === ctx.sessionManager.getSessionId());
+            const accepted = await store.readAccepted(request.decisionId);
+            if (accepted === null) {
+                let cancellation = await store.readCancellation(request.decisionId);
+                if (cancellation === null &&
+                    request.expiresAt !== undefined &&
+                    Date.parse(request.expiresAt) <= Date.now()) {
+                    await store.cancel(request, "expired");
+                    cancellation = await store.readCancellation(request.decisionId);
+                }
+                if (cancellation !== null) {
+                    await settleHumanDecisionChannels(cancellation);
+                    continue;
+                }
+                if (!deliverPending || !ownedBySession)
+                    continue;
+                const channels = audienceChannels(decisionChannelConfig, request.audience);
+                for (const channelId of channels) {
+                    const channel = telegramDecisionChannels.get(channelId);
+                    if (channel !== undefined)
+                        await channel.deliver(humanDecisionChannelRequest(request));
+                }
+                if (ctx.mode === "tui" && channels.includes("pi") && lastWaitingRunId === null) {
+                    lastWaitingRunId = request.runId;
+                    queueMicrotask(() => void promptHumanDecision(ctx, request));
+                }
+                continue;
+            }
+            if (!ownedBySession)
+                continue;
+            const runId = `continuation-${request.decisionId.slice("decision-".length)}`;
+            const continuation = (await store.readContinuation(request.decisionId)) ?? {
+                schema: "pi-workflows.human-decision-continuation.v1",
+                decisionId: request.decisionId,
+                requestDigest: request.requestDigest,
+                parentRunId: request.runId,
+                runId,
+                createdAt: accepted.acceptedAt,
+            };
+            await store.recordContinuation(request.decisionId, continuation);
+            const existing = await readRunBundle(runStore.runDirFor(continuation.runId));
+            if (existing === null && activeRun === null) {
+                if (parent.state.workflowSource === undefined)
+                    continue;
+                const workflowRef = parent.state.workflowSource.kind === "builtin"
+                    ? `builtin:${parent.state.workflowSource.id}`
+                    : parent.state.workflowSource.path;
+                await startRun(ctx, workflowRef, parent.state.input, {
+                    parentRunId: request.runId,
+                    humanDecision: accepted,
+                    runId: continuation.runId,
+                    quiet: true,
+                });
+            }
+            await settleHumanDecisionChannels(accepted);
+            if (activeRun !== null)
+                break;
+        }
+    };
+    const startDecisionRecovery = (ctx) => {
+        if (decisionRecoveryTimer !== null)
+            return;
+        decisionRecoveryTimer = setInterval(() => {
+            if (decisionRecoveryActive || sessionClosed)
+                return;
+            decisionRecoveryActive = true;
+            void recoverHumanDecisions(ctx, false)
+                .catch(() => undefined)
+                .finally(() => {
+                decisionRecoveryActive = false;
+            });
+        }, 1_000);
+        decisionRecoveryTimer.unref?.();
+    };
     const startWorkflowControl = async (ctx, ref, input) => {
         if (activeRun !== null) {
             throw new Error(`A workflow is already running: ${activeRun.workflowName}.`);
@@ -1312,7 +1639,7 @@ export default function piWorkflows(pi) {
                 return;
             }
             if (parsed.kind === "cancel") {
-                const result = cancelWorkflowControl(ctx);
+                const result = await cancelWorkflowControl(ctx);
                 notify(ctx, result.message, result.level);
                 return;
             }
@@ -1358,6 +1685,69 @@ export default function piWorkflows(pi) {
             }
         },
     });
+    pi.registerCommand("workflow-channel", {
+        description: "Configure or reload private human decision channels",
+        handler: async (args, ctx) => {
+            const action = args.trim() || "status";
+            try {
+                if (action === "reload") {
+                    await reloadDecisionChannels(ctx);
+                    notify(ctx, "Human decision channels reloaded.");
+                    return;
+                }
+                if (action === "status") {
+                    notify(ctx, decisionChannelConfig === null
+                        ? "Human decisions use the Pi channel only."
+                        : `Human decision channels are configured for ${Object.keys(decisionChannelConfig.audiences).length} audience(s).`);
+                    return;
+                }
+                if (action !== "setup") {
+                    throw new Error("Use /workflow-channel status, setup, or reload.");
+                }
+                if (!ctx.hasUI || ctx.mode !== "tui") {
+                    throw new Error("Channel setup requires interactive Pi TUI mode.");
+                }
+                const tokenFile = await ctx.ui.input("Absolute path to the mode-0600 Telegram token file", "");
+                if (tokenFile === undefined)
+                    return;
+                const audience = await ctx.ui.input("Logical audience", "operator");
+                if (audience === undefined)
+                    return;
+                const profile = await ctx.ui.input("Private Telegram profile name", "default");
+                if (profile === undefined)
+                    return;
+                const credential = await ctx.ui.input("Private credential reference name", "telegram");
+                if (credential === undefined)
+                    return;
+                const users = await ctx.ui.input("Allowed numeric Telegram user IDs, comma separated", "");
+                if (users === undefined)
+                    return;
+                const chats = await ctx.ui.input("Allowed numeric Telegram chat IDs, comma separated", "");
+                if (chats === undefined)
+                    return;
+                await verifyTelegramTokenFile(tokenFile.trim());
+                await writeDecisionChannelProfile({
+                    audience: audience.trim(),
+                    profile: profile.trim(),
+                    credential: credential.trim(),
+                    tokenFile: tokenFile.trim(),
+                    allowedUserIds: users
+                        .split(",")
+                        .map((value) => value.trim())
+                        .filter(Boolean),
+                    allowedChatIds: chats
+                        .split(",")
+                        .map((value) => value.trim())
+                        .filter(Boolean),
+                });
+                await reloadDecisionChannels(ctx);
+                notify(ctx, "The private human decision channel profile was verified and installed.");
+            }
+            catch (error) {
+                notify(ctx, `Human decision channel setup failed: ${errorMessage(error)}`, "error");
+            }
+        },
+    });
     pi.registerCommand("controller", {
         description: "Manage durable controllers: list, get, apply, reconcile, delete, start, or stop",
         getArgumentCompletions: async (prefix) => {
@@ -1431,7 +1821,8 @@ export default function piWorkflows(pi) {
             "Do not start repeated work without the user's request, and keep monitoring observation-only unless the user authorizes mutations.",
         ].join(" "),
         parameters: WorkflowToolParameters,
-        async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+        async execute(toolCallId, rawParams, _signal, _onUpdate, ctx) {
+            const params = parseWorkflowToolInput(rawParams);
             let control;
             switch (params.action) {
                 case "list":
@@ -1450,10 +1841,14 @@ export default function piWorkflows(pi) {
                     control = resumeWorkflowControl(ctx);
                     break;
                 case "cancel":
-                    control = cancelWorkflowControl(ctx);
+                    control = await cancelWorkflowControl(ctx);
                     break;
                 case "answer": {
                     const waiting = await resolveWaitingWorkflow(ctx, params.runId);
+                    const parent = await readRunBundle(new WorkflowRunStore().runDirFor(waiting.parentRunId));
+                    if (parent !== null && humanDecisionRequest(parent.state.finalOutput) !== null) {
+                        throw new Error("This checkpoint requires a verified human answer from Pi UI or a configured decision channel.");
+                    }
                     control = await queueToolLaunch(ctx, waiting.workflowRef, params.input, {
                         parentRunId: waiting.parentRunId,
                     });
@@ -1534,6 +1929,13 @@ export default function piWorkflows(pi) {
         catch (error) {
             notify(ctx, `Could not migrate legacy workflow sources: ${errorMessage(error)}`, "warning");
         }
+        try {
+            await reloadDecisionChannels(ctx);
+        }
+        catch {
+            await stopDecisionChannels();
+            notify(ctx, "Could not start human decision channels because the private channel configuration is invalid or unavailable.", "warning");
+        }
         try {
             syncArmed = true;
             startRunSync(ctx);
@@ -1541,6 +1943,13 @@ export default function piWorkflows(pi) {
         catch {
             // Session sync is best-effort; runs themselves never depend on it.
         }
+        try {
+            await recoverHumanDecisions(ctx);
+            startDecisionRecovery(ctx);
+        }
+        catch (error) {
+            notify(ctx, `Could not recover human decisions: ${errorMessage(error)}`, "warning");
+        }
         try {
             await resumeParkedRun(ctx);
         }
@@ -1673,7 +2082,13 @@ export default function piWorkflows(pi) {
             clearInterval(runSyncTimer);
             runSyncTimer = null;
         }
+        if (decisionRecoveryTimer !== null) {
+            clearInterval(decisionRecoveryTimer);
+            decisionRecoveryTimer = null;
+        }
+        decisionRecoveryActive = false;
         syncArmed = false;
+        await stopDecisionChannels();
         await controllerHost?.close().catch(() => undefined);
         controllerHost = undefined;
         controllerContext = null;