conductor-remote 1.124.0 → 1.125.1

package/dist-node/src/mcp/tools/workspaces.js

@@ -1,6 +1,8 @@
+import { createWorkspaceSchema, hasAgentSettings } from "../../contracts/agent-inputs.js";
 import { routes } from "../../routes.js";
 import { workspaceTitle } from "../../shared.js";
-import { need, rejectUnknown, str } from "../arguments.js";
+import { need, str } from "../arguments.js";
+import { defineTool } from "../define-tool.js";
 import { clip, formatDevServer, unmark } from "../formatters.js";
 import { WRITE_TIMEOUT_MS } from "../protocol.js";
 export function createListWorkspacesTool(call) {
@@ -82,51 +84,27 @@ export function createListReposTool(call) {
         }
     };
 }
+const createWorkspaceInputSchema = createWorkspaceSchema
+    .omit({
+    send: true,
+    sendImmediately: true,
+    attachmentIds: true
+})
+    .extend({
+    repo: createWorkspaceSchema.shape.repo.unwrap().describe('Exact name from list_repos.'),
+    model: createWorkspaceSchema.shape.model.describe('Picker label from list_models with no session_id. The relay applies it before the first prompt, or configures an empty workspace once its chat exists.'),
+    wait_for_send: createWorkspaceSchema.shape.send,
+    send_immediately: createWorkspaceSchema.shape.sendImmediately
+})
+    .strict();
 export function createCreateWorkspaceTool(call) {
-    return {
+    return defineTool({
         name: 'create_workspace',
         description: 'Start an ordinary new Conductor workspace in a repo, optionally with a first prompt and agent settings. The workspace starts from a Conductor deep link, so creation itself needs no Accessibility. The relay applies requested model, effort, plan, and fast settings through Conductor’s UI after it creates the first chat and before it delivers the prompt. This utility cannot start or join a Workflow. Returns as soon as the workspace row exists (~2s), before the worktree is built.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                repo: { type: 'string', description: 'Exact name from list_repos.' },
-                prompt: { type: 'string', description: 'First prompt for the new agent. Omit to open an empty workspace.' },
-                model: {
-                    type: 'string',
-                    description: 'Picker label from list_models with no session_id. The relay applies it before the first prompt, or configures an empty workspace once its chat exists.'
-                },
-                effort: {
-                    type: 'string',
-                    enum: ['none', 'low', 'medium', 'high', 'xhigh', 'max', 'ultracode'],
-                    description: 'Reasoning effort applied before the first prompt.'
-                },
-                plan: { type: 'boolean', description: 'Start the first chat in Conductor’s Plan mode.' },
-                fast: { type: 'boolean', description: 'Set Fast mode before the first prompt.' },
-                wait_for_send: {
-                    type: 'boolean',
-                    description: 'Block until the first prompt is actually delivered (tens of seconds, and longer behind other queued sends). Default false.'
-                },
-                send_immediately: {
-                    type: 'boolean',
-                    description: "Send the first prompt without waiting for the worktree to finish building, which is how Conductor's own New workspace box behaves. Default true. Pass false only when the agent's first move needs what the repo's setup script installs."
-                }
-            },
-            required: ['repo'],
-            additionalProperties: false
-        },
+        inputSchema: createWorkspaceInputSchema,
         run: async (args) => {
-            rejectUnknown(args, ['repo', 'prompt', 'model', 'effort', 'plan', 'fast', 'wait_for_send', 'send_immediately']);
-            const repo = need(args, 'repo');
-            const prompt = str(args.prompt);
-            const model = str(args.model);
-            const effort = str(args.effort);
-            const plan = typeof args.plan === 'boolean' ? args.plan : undefined;
-            const fast = typeof args.fast === 'boolean' ? args.fast : undefined;
-            const explicitAgent = model !== undefined || effort !== undefined || plan !== undefined || fast !== undefined;
-            const configured = explicitAgent;
-            const send = args.wait_for_send === true;
-            // Default on, matching the relay: an omitted flag must never mean "wait".
-            const sendImmediately = args.send_immediately !== false;
+            const { repo, prompt, model, effort, plan, fast, wait_for_send: send, send_immediately: sendImmediately } = args;
+            const configured = hasAgentSettings(args);
             const data = await call(routes.createWorkspace.path(), {
                 method: routes.createWorkspace.method,
                 body: { repo, prompt, model, effort, plan, fast, send, sendImmediately },
@@ -146,7 +124,7 @@ export function createCreateWorkspaceTool(call) {
                 lines.push(data.configured ? 'agent settings applied' : 'agent settings queued');
             return lines.join('\n');
         }
-    };
+    });
 }
 export function createSetWorkspaceStatusTool(call) {
     return {

package/dist-node/src/mcp.js

@@ -1,9 +1,6 @@
-import { readFileSync } from 'node:fs';
-import path from 'node:path';
 import { createInterface } from 'node:readline';
-import { stateDir } from "./config.js";
+import { call, relayBase } from "./mcp/client.js";
 import { handleRpc } from "./mcp/dispatcher.js";
-import { READ_TIMEOUT_MS } from "./mcp/protocol.js";
 import { createTools } from "./mcp/registry.js";
 /**
  * MCP over stdio: `conductor-remote mcp`.
@@ -19,9 +16,8 @@ import { createTools } from "./mcp/registry.js";
  *
  * Hand-rolled rather than built on `@modelcontextprotocol/sdk`, which measures 91
  * packages / 24 MB (express, hono, cors, jose) for a server that speaks neither HTTP
- * nor OAuth. The relay's tarball keeps its zero runtime dependencies, which matters
- * more than usual here: it auto-updates itself while holding a token that drives your
- * Mac.
+ * nor OAuth. The tool wrapper uses the relay's existing Zod dependency for shared
+ * input validation and JSON Schema export, without adding the SDK's HTTP/OAuth stack.
  */
 /**
  * stdout is the wire. A stray `console.log` from anywhere in this process would be
@@ -30,56 +26,6 @@ import { createTools } from "./mcp/registry.js";
  */
 console.log = (...args) => console.error(...args);
 console.info = (...args) => console.error(...args);
-function relayBase() {
-    const port = process.env.RELAY_PORT ?? '8787';
-    // The relay binds loopback (see config.ts); RELAY_HOST only widens who else can
-    // reach it, so 127.0.0.1 is always right for a client on the same Mac.
-    return `http://127.0.0.1:${port}`;
-}
-function relayToken() {
-    if (process.env.RELAY_TOKEN)
-        return process.env.RELAY_TOKEN;
-    try {
-        return readFileSync(path.join(stateDir(), 'token'), 'utf8').trim();
-    }
-    catch {
-        throw new Error(`no relay token at ${path.join(stateDir(), 'token')} — start the relay once (conductor-remote service install), or set RELAY_TOKEN`);
-    }
-}
-async function call(route, opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? READ_TIMEOUT_MS;
-    let res;
-    try {
-        res = await fetch(`${relayBase()}${route}`, {
-            method: opts.method ?? 'GET',
-            signal: AbortSignal.timeout(timeoutMs),
-            headers: {
-                authorization: `Bearer ${relayToken()}`,
-                'content-type': 'application/json',
-                // Marks this caller as an agent: the relay drops it to background priority on
-                // the UI lock, behind anyone using the phone (src/http/router.ts ▸ withUiPriority).
-                'x-relay-client': 'mcp',
-                // The relay retries a failed send inside this budget and never past it, so
-                // stating it here is what stops it outliving us — see src/http/services/delivery.ts ▸ sendBudget.
-                'x-client-timeout-ms': String(timeoutMs)
-            },
-            body: opts.body === undefined ? undefined : JSON.stringify(opts.body)
-        });
-    }
-    catch (err) {
-        if (err instanceof DOMException && err.name === 'TimeoutError')
-            throw new Error(`the relay did not answer within ${Math.round(timeoutMs / 1000)}s`);
-        throw new Error(`cannot reach the relay at ${relayBase()} (${err instanceof Error ? err.message : err}). Is it running? \`conductor-remote service status\``);
-    }
-    const payload = (await res.json().catch(() => ({})));
-    if (!res.ok) {
-        // 503 is the UI lock refusing a deep queue, and it is worth naming as such: it
-        // means "retry shortly", not "this failed".
-        const busy = res.status === 503 ? ' (Conductor’s UI is busy — retry shortly)' : '';
-        throw new Error(`${payload.error || `HTTP ${res.status}`}${busy}`);
-    }
-    return payload;
-}
 const tools = createTools(call);
 function write(message) {
     process.stdout.write(`${JSON.stringify(message)}\n`);

package/dist-node/src/orchestration/persistence/db.js

@@ -1,9 +1,9 @@
 import { consumeWorkflowCapability, getWorkflowCapability, issueWorkflowCapability, revokeWorkflowCapabilities } from "./capabilities.js";
 import { PersistenceConnection } from "./connection.js";
 import { markWorkflowEffectReceiptLost, reconcileAbandonedWorkflowEffect, recordLateWorkflowEffect, replayAmbiguousWorkflowEffect, retryWorkflowEffect } from "./effect-recovery.js";
-import { markWorkflowEffectAmbiguous, markWorkflowEffectCancelled, markWorkflowEffectCommitted, markWorkflowEffectDispatched, markWorkflowEffectFailed, markWorkflowEffectFailedBeforeMayExecute, markWorkflowEffectMayExecute } from "./effect-transitions.js";
+import { markWorkflowConfigurationRejected, markWorkflowEffectAmbiguous, markWorkflowEffectCancelled, markWorkflowEffectCommitted, markWorkflowEffectDispatched, markWorkflowEffectFailed, markWorkflowEffectFailedBeforeMayExecute, markWorkflowEffectMayExecute } from "./effect-transitions.js";
 import { claimPreparedWorkflowEffect, markWorkflowEffectSatisfiedWithoutDispatch, prepareWorkflowEffect } from "./effects.js";
-import { listWorkflowEvents } from "./events.js";
+import { listWorkflowEvents, recordWorkflowObservation } from "./events.js";
 import { getIdempotentMutation, idempotentMutation } from "./idempotency.js";
 import { createWorkflowJobAttempt, recordLateWorkflowChildResult, updateWorkflowJobAttempt } from "./job-attempts.js";
 import { activateWorkflowJob, claimNextWorkflowJob, createWorkflowJob, reconcileAbandonedWorkflowJobClaim, updateWorkflowJob } from "./jobs.js";
@@ -66,6 +66,7 @@ export class OrchestrationDb {
     markWorkflowEffectMayExecute = (...args) => markWorkflowEffectMayExecute(this.connection, ...args);
     markWorkflowEffectCommitted = (...args) => markWorkflowEffectCommitted(this.connection, ...args);
     markWorkflowEffectFailed = (...args) => markWorkflowEffectFailed(this.connection, ...args);
+    markWorkflowConfigurationRejected = (...args) => markWorkflowConfigurationRejected(this.connection, ...args);
     markWorkflowEffectFailedBeforeMayExecute = (...args) => markWorkflowEffectFailedBeforeMayExecute(this.connection, ...args);
     markWorkflowEffectAmbiguous = (...args) => markWorkflowEffectAmbiguous(this.connection, ...args);
     markWorkflowEffectReceiptLost = (...args) => markWorkflowEffectReceiptLost(this.connection, ...args);
@@ -80,6 +81,7 @@ export class OrchestrationDb {
     consumeWorkflowCapability = (...args) => consumeWorkflowCapability(this.connection, ...args);
     revokeWorkflowCapabilities = (...args) => revokeWorkflowCapabilities(this.connection, ...args);
     listWorkflowEvents = (...args) => listWorkflowEvents(this.connection, ...args);
+    recordWorkflowObservation = (...args) => recordWorkflowObservation(this.connection, ...args);
     registerRelayInstance = (...args) => registerRelayInstance(this.connection, ...args);
     heartbeatRelayInstance = (...args) => heartbeatRelayInstance(this.connection, ...args);
     listRelayInstances = (...args) => listRelayInstances(this.connection, ...args);

package/dist-node/src/orchestration/persistence/effect-transitions.js

@@ -95,6 +95,23 @@ export function markWorkflowEffectFailedBeforeMayExecute(context, input) {
         eventType: 'workflow_effect_failed_before_may_execute'
     });
 }
+/** A finished configuration write with a known, mismatching readback is safe to retry. */
+export function markWorkflowConfigurationRejected(context, input) {
+    return context.immediate(() => {
+        const effect = requireEffectByAction(context, input.runId, input.actionId);
+        if (effect.kind !== 'configure_root' && effect.kind !== 'configure_child') {
+            throw new WorkflowTransitionError('only a configuration effect can have a verified rejection');
+        }
+        return transitionEffect(context, {
+            ...input,
+            from: ['dispatched'],
+            to: 'failed',
+            requireMayExecute: true,
+            eventKey: input.eventKey ?? `configuration_rejected:${input.actionId}:${input.attemptNumber}`,
+            eventType: 'workflow_configuration_rejected'
+        });
+    });
+}
 export function markWorkflowEffectAmbiguous(context, input) {
     return transitionEffect(context, {
         ...input,

package/dist-node/src/orchestration/persistence/events.js

@@ -1,5 +1,7 @@
 import { and, asc, eq } from 'drizzle-orm';
 import { decodeEvent } from "./codecs.js";
+import { idempotentMutation } from "./idempotency.js";
+import { requireRun } from "./records.js";
 import { workflowEvents } from "./schema.js";
 import { nonEmpty, optionalJson } from "./values.js";
 export function listWorkflowEvents(context, runId) {
@@ -27,3 +29,11 @@ export function appendEvent(context, runId, eventKey, type, data) {
 export function touchRun(context, runId, at) {
     context.db.prepare('UPDATE workflow_runs SET updated_at = ? WHERE id = ?').run(at, runId);
 }
+/** Audit read-only probes and notification attempts without changing run/phase state. */
+export function recordWorkflowObservation(context, input) {
+    idempotentMutation(context, 'workflow_observation', `${input.runId}:${input.eventKey}`, input, () => {
+        requireRun(context, input.runId);
+        appendEvent(context, input.runId, input.eventKey, input.type, input.data);
+        return { runId: input.runId };
+    });
+}

package/dist-node/src/orchestration/workflow/blocked.js

@@ -0,0 +1,93 @@
+import { scrubWorkflowSecrets, withoutWindowEvidence } from "../../shared.js";
+import { withUiPriority } from "../../writes/ui-lock.js";
+import { errorMessage } from "./helpers.js";
+export function workflowBlockMessage(notice, workspace) {
+    return withoutWindowEvidence(scrubWorkflowSecrets([
+        `Workflow paused in ${workspace} during ${notice.run.blocked?.resumePhase.replaceAll('_', ' ')}: ${notice.action}.`,
+        notice.run.blocked?.message,
+        `On your phone: ${notice.recovery}.`
+    ]
+        .filter(Boolean)
+        .join('\n\n')));
+}
+function blockedAction(context, run) {
+    const actionId = run.blocked?.actionId ?? '';
+    const kind = context.db.getWorkflowEffect(run.id, actionId)?.kind;
+    if (kind)
+        return ({
+            create_workspace: 'create the workspace',
+            configure_root: 'apply the planning settings',
+            send_root: 'send the objective to the planner',
+            open_child: 'open a helper chat',
+            configure_child: 'apply the helper settings',
+            send_task: 'send the helper assignment',
+            return_baton: 'return the helper result',
+            authorize_phase: 'deliver the next phase authorization'
+        }[kind] ?? 'advance the Workflow');
+    if (actionId.startsWith('compatibility:'))
+        return 'check relay compatibility';
+    if (actionId.startsWith('job:'))
+        return 'read the helper result';
+    if (actionId === 'bind-root')
+        return 'identify the planning chat';
+    return 'advance the Workflow';
+}
+/** Notifications are best effort, with a durable claim before each external send. */
+export async function notifyBlockedRun(context, run) {
+    if (run.phase !== 'blocked' || !run.blocked)
+        return;
+    const event = context.db.listWorkflowEvents(run.id).findLast(event => event.type === 'workflow_blocked');
+    if (!event)
+        return;
+    const eventId = event.id;
+    const notice = {
+        run,
+        eventId,
+        action: blockedAction(context, run),
+        recovery: run.blocked.retryClass === 'deterministic'
+            ? 'Retry saved action or Cancel'
+            : run.blocked.retryClass === 'ambiguous'
+                ? 'Review risky replay or Cancel'
+                : 'Cancel this run'
+    };
+    async function attempt(channel, send) {
+        const eventKey = `block-${channel}:${eventId}`;
+        const claimed = context.db.idempotentMutation('workflow_block_notice', `${run.id}:${eventKey}`, { eventId, channel }, () => {
+            context.db.recordWorkflowObservation({
+                runId: run.id,
+                eventKey,
+                type: 'workflow_block_notice_claimed',
+                data: { channel, eventId }
+            });
+            return { runId: run.id };
+        });
+        if (claimed.replayed)
+            return;
+        try {
+            await send();
+        }
+        catch (error) {
+            context.db.recordWorkflowObservation({
+                runId: run.id,
+                eventKey: `${eventKey}:failed`,
+                type: 'workflow_block_notice_failed',
+                data: { channel, message: errorMessage(error) }
+            });
+            console.warn(`[workflow ${run.id}] ${channel} block notice failed: ${errorMessage(error)}`);
+        }
+    }
+    if (context.deps.notifyBlocked)
+        await attempt('push', () => context.deps.notifyBlocked(notice));
+    // A notice would make an unprompted root non-pristine and prevent its retry.
+    const canSendRoot = run.rootSessionId &&
+        !['creating_workspace', 'binding_root', 'pending_root'].includes(run.blocked.resumePhase) &&
+        run.blocked.errorCode !== 'workflow_root_not_pristine' &&
+        run.blocked.errorCode !== 'workflow_not_found';
+    if (!canSendRoot || !context.deps.sendBlockedNotice)
+        return;
+    await attempt('root', async () => {
+        if (context.db.getUiQuarantine().active)
+            return;
+        await withUiPriority('background', () => context.deps.sendBlockedNotice(notice));
+    });
+}

package/dist-node/src/orchestration/workflow/compatibility.js

@@ -0,0 +1,42 @@
+import { randomUUID } from 'node:crypto';
+import { errorMessage } from "./helpers.js";
+import { blockRun } from "./state.js";
+const MAX_COMPATIBILITY_READ_FAILURES = 3;
+function failuresSinceRecovery(context, runId) {
+    let count = 0;
+    for (const event of context.db.listWorkflowEvents(runId)) {
+        if (event.type === 'workflow_compatibility_read_failed')
+            count++;
+        if (event.type === 'workflow_compatibility_read_recovered' || event.type === 'workflow_retry_accepted')
+            count = 0;
+    }
+    return count;
+}
+/** One failed wake spends one persisted attempt. Nothing else runs on that tick. */
+export function compatibilityReadFailed(context, run, error) {
+    const message = errorMessage(error);
+    context.db.recordWorkflowObservation({
+        runId: run.id,
+        eventKey: `compatibility-read:${randomUUID()}`,
+        type: 'workflow_compatibility_read_failed',
+        data: { message }
+    });
+    if (failuresSinceRecovery(context, run.id) >= MAX_COMPATIBILITY_READ_FAILURES) {
+        blockRun(context, run, {
+            actionId: `compatibility:${run.id}`,
+            errorCode: 'workflow_incompatible_relay',
+            message: `The relay process check failed ${MAX_COMPATIBILITY_READ_FAILURES} consecutive times. ${message}`,
+            retryClass: 'deterministic'
+        });
+    }
+}
+/** Clear the streak only after an entire wake succeeds, including checks at the UI gate. */
+export function compatibilityReadRecovered(context, runId) {
+    if (!failuresSinceRecovery(context, runId))
+        return;
+    context.db.recordWorkflowObservation({
+        runId,
+        eventKey: `compatibility-recovered:${randomUUID()}`,
+        type: 'workflow_compatibility_read_recovered'
+    });
+}

package/dist-node/src/orchestration/workflow/effects.js

@@ -3,7 +3,7 @@ import { workflowCapabilityToken } from "../../shared.js";
 import { withUiDispatchHook, withUiPriority } from "../../writes/ui-lock.js";
 import { hashCapabilityToken, WorkflowTransitionError } from "../persistence/db.js";
 import { quarantineAndBlock } from "./effect-recovery.js";
-import { WorkflowCoordinatorError } from "./errors.js";
+import { WorkflowCompatibilityReadError, WorkflowCoordinatorError, WorkflowRoleVerificationError } from "./errors.js";
 import { cleanUnknown, errorCode, errorMessage, preExecutionRetryClass, sameRelay } from "./helpers.js";
 import { isTerminalWorkflowPhase } from "./machine.js";
 import { assertCompatible, blockRun, effectReadCall, requireEffect, requireRun } from "./state.js";
@@ -176,6 +176,51 @@ export async function reconcileClaimedEffect(context, run, effect, job) {
 export async function failEffect(context, run, actionId, attemptNumber, error, job) {
     let effect = requireEffect(context, run.id, actionId);
     const currentRun = requireRun(context, run.id);
+    if (error instanceof WorkflowCompatibilityReadError &&
+        !isTerminalWorkflowPhase(currentRun.phase) &&
+        !effect.mayExecute) {
+        // The read failed before any external command was released. Settle this
+        // attempt, put the exact intent back, and let the wake budget decide when to pause.
+        const failure = {
+            runId: run.id,
+            actionId,
+            owner: context.relay,
+            attemptNumber,
+            errorCode: error.code,
+            errorMessage: error.message
+        };
+        if (effect.state === 'prepared' && sameRelay(effect.owner, context.relay)) {
+            context.db.markWorkflowEffectFailed(failure);
+        }
+        else if (effect.state === 'dispatched') {
+            context.db.markWorkflowEffectFailedBeforeMayExecute(failure);
+        }
+        if (requireEffect(context, run.id, actionId).state === 'failed') {
+            context.db.retryWorkflowEffect(run.id, actionId, `compatibility-retry:${actionId}:${attemptNumber}`);
+        }
+        throw error;
+    }
+    if (error instanceof WorkflowRoleVerificationError &&
+        effect.state === 'dispatched' &&
+        effect.mayExecute &&
+        (effect.kind === 'configure_root' || effect.kind === 'configure_child')) {
+        effect = context.db.markWorkflowConfigurationRejected({
+            runId: run.id,
+            actionId,
+            owner: context.relay,
+            attemptNumber,
+            errorCode: error.code,
+            errorMessage: error.message,
+            evidence: { applied: true, matched: false }
+        });
+        blockRun(context, currentRun, {
+            actionId,
+            errorCode: error.code,
+            message: error.message,
+            retryClass: 'deterministic'
+        });
+        return { effect, changed: true };
+    }
     if (currentRun.phase === 'cancelled' || currentRun.phase === 'completed') {
         if (effect.state === 'dispatched') {
             if (!effect.mayExecute) {

package/dist-node/src/orchestration/workflow/errors.js

@@ -11,3 +11,17 @@ export class WorkflowCoordinatorError extends Error {
         this.retryable = options.retryable ?? false;
     }
 }
+/** Only raised after the role write has finished successfully and a present chat was read back. */
+export class WorkflowRoleVerificationError extends WorkflowCoordinatorError {
+    constructor() {
+        super('workflow_role_verification_failed', 'Conductor no longer matches every frozen role setting; no fallback was selected.', { retryable: true });
+        this.name = 'WorkflowRoleVerificationError';
+    }
+}
+/** The process inventory could not be read. No incompatible relay was observed. */
+export class WorkflowCompatibilityReadError extends WorkflowCoordinatorError {
+    constructor(message) {
+        super('workflow_incompatible_relay', message, { retryable: true });
+        this.name = 'WorkflowCompatibilityReadError';
+    }
+}

package/dist-node/src/orchestration/workflow/helpers.js

@@ -31,6 +31,8 @@ export function sanitizeChildOutcome(outcome) {
         ? {
             kind: 'success',
             baton: scrubWorkflowSecrets(outcome.baton),
+            ...(outcome.text === undefined ? {} : { text: scrubWorkflowSecrets(outcome.text) }),
+            ...(outcome.assistantRowid === undefined ? {} : { assistantRowid: outcome.assistantRowid }),
             ...(outcome.evidence === undefined ? {} : { evidence: cleanUnknown(outcome.evidence) })
         }
         : {

package/dist-node/src/orchestration/workflow/job-results.js

@@ -4,6 +4,7 @@ import { markReceiptLost } from "./effect-recovery.js";
 import { runDurableEffect } from "./effects.js";
 import { assertDeliveryReceipt, effectGrant, guardJobs, isDeliveryReceipt, messageReceipt, privateCorrelationBlock, sanitizeChildOutcome, workflowEffectCorrelationMarker } from "./helpers.js";
 import { phaseAfterDeliveredBaton } from "./machine.js";
+import { workflowReportReturnText } from "./report.js";
 import { blockRun, effectCall, effectReadCall, requireEffect, requireRun } from "./state.js";
 export async function driveJobOutcome(context, run, job) {
     const outcome = await context.deps.readChildOutcome({ run, job });
@@ -109,6 +110,11 @@ export async function driveJobBaton(context, run, job) {
         // durable root message; accepted outbox rows do not satisfy the barrier.
         if (designatedFinal && !grant)
             return false;
+        // Old outcomes and already-prepared returns keep their original bytes. A new
+        // return freezes its public message before any UI attempt or receipt lookup.
+        const returnText = outcome.text === undefined
+            ? outcome.baton
+            : workflowReportReturnText(job, outcome, await context.deps.materializeReport({ run, job, outcome }));
         effect = context.db.prepareWorkflowEffect({
             id: `${run.id}:${actionId}`,
             runId: run.id,
@@ -117,6 +123,7 @@ export async function driveJobBaton(context, run, job) {
             jobId: job.id,
             target: { sessionId: run.rootSessionId },
             inputs: {
+                returnText,
                 ...(grant ? { grant } : {}),
                 correlationMarker: workflowEffectCorrelationMarker(run.id, actionId)
             },
@@ -126,6 +133,7 @@ export async function driveJobBaton(context, run, job) {
         }).effect;
     }
     const grant = effectGrant(effect) ?? undefined;
+    const savedText = effect.inputs?.returnText ?? outcome.baton;
     let current = effect;
     let changed = false;
     if (effect.state !== 'committed') {
@@ -148,7 +156,7 @@ export async function driveJobBaton(context, run, job) {
                     ...effectCall(run, effect, dispatch, job),
                     job,
                     sessionId: run.rootSessionId,
-                    text: [outcome.baton, envelope, privateCorrelationBlock(run.id, effect.actionId)].filter(Boolean).join('\n\n')
+                    text: [savedText, envelope, privateCorrelationBlock(run.id, effect.actionId)].filter(Boolean).join('\n\n')
                 });
             },
             validate: assertDeliveryReceipt

package/dist-node/src/orchestration/workflow/report.js

@@ -0,0 +1,31 @@
+import { scrubWorkflowSecrets } from "../../shared.js";
+import { chatCursor } from "../../transcript/cursor.js";
+/** Completion freezes the source. Returning a report never reads the child's later turns. */
+export function workflowReportBody(run, job, outcome) {
+    if (!job.childSessionId || outcome.text === undefined)
+        throw new Error('Workflow report source is incomplete');
+    return scrubWorkflowSecrets([
+        `# Workflow ${job.role} report`,
+        '',
+        `Workflow: ${run.id}`,
+        `Workflow job: ${job.id} (${job.logicalKey}, attempt ${job.attemptCount})`,
+        `Child chat: ${job.childSessionId}`,
+        ...(outcome.assistantRowid === undefined ? [] : [`Completion cursor: ${chatCursor(outcome.assistantRowid)}`]),
+        '',
+        outcome.text
+    ].join('\n'));
+}
+export function workflowReportReturnText(job, outcome, token) {
+    if (!job.childSessionId)
+        throw new Error('Workflow report has no child chat');
+    const read = {
+        session_id: job.childSessionId,
+        ...(outcome.assistantRowid === undefined ? {} : { near: chatCursor(outcome.assistantRowid), before: 6, after: 0 })
+    };
+    return scrubWorkflowSecrets([
+        outcome.baton,
+        `Workflow ${job.role} task ${job.logicalKey} completed.`,
+        `Report: ${token}`,
+        `For earlier investigation, use read_chat(${JSON.stringify(read)}).`
+    ].join('\n\n'));
+}

package/dist-node/src/orchestration/workflow/wake.js

@@ -1,5 +1,8 @@
 import { WorkflowTransitionError } from "../persistence/db.js";
+import { notifyBlockedRun } from "./blocked.js";
+import { compatibilityReadFailed, compatibilityReadRecovered } from "./compatibility.js";
 import { markReceiptLost, reconcileBlockedEffect } from "./effect-recovery.js";
+import { WorkflowCompatibilityReadError } from "./errors.js";
 import { cleanUnknown, effectSessionId, errorMessage, isDeliveryReceipt, receiptEventSuffix, sanitizeChildOutcome } from "./helpers.js";
 import { driveNextJob } from "./job-dispatch.js";
 import { advanceDeliveredBarrier } from "./job-results.js";
@@ -16,6 +19,8 @@ export function wake(context, runId) {
 }
 export async function wakeInternal(context, runId) {
     heartbeat(context);
+    let compatibilityFailed = false;
+    let compatibilityChecked = false;
     for (let step = 0; step < MAX_WAKE_STEPS; step++) {
         const run = requireRun(context, runId);
         if (run.phase === 'cancelled') {
@@ -25,14 +30,21 @@ export async function wakeInternal(context, runId) {
         if (run.phase === 'completed')
             break;
         if (run.phase === 'blocked') {
+            await notifyBlockedRun(context, run);
             if (await reconcileBlockedEffect(context, run))
                 continue;
             break;
         }
         try {
             await assertCompatible(context);
+            compatibilityChecked = true;
         }
         catch (error) {
+            compatibilityFailed = true;
+            if (error instanceof WorkflowCompatibilityReadError) {
+                compatibilityReadFailed(context, requireRun(context, runId), error);
+                break;
+            }
             blockRun(context, run, {
                 actionId: `compatibility:${run.id}`,
                 errorCode: 'workflow_incompatible_relay',
@@ -46,6 +58,11 @@ export async function wakeInternal(context, runId) {
             changed = await driveOnce(context, run);
         }
         catch (error) {
+            if (error instanceof WorkflowCompatibilityReadError) {
+                compatibilityFailed = true;
+                compatibilityReadFailed(context, requireRun(context, runId), error);
+                break;
+            }
             if (error instanceof WorkflowTransitionError) {
                 const current = requireRun(context, runId);
                 if (current.phase !== run.phase || current.cancellationGeneration !== run.cancellationGeneration)
@@ -56,6 +73,9 @@ export async function wakeInternal(context, runId) {
         if (!changed)
             break;
     }
+    if (compatibilityChecked && !compatibilityFailed)
+        compatibilityReadRecovered(context, runId);
+    await notifyBlockedRun(context, requireRun(context, runId));
     return projection(context, runId);
 }
 export async function observeCancelledRun(context, run) {

package/dist-node/src/prefs.js

@@ -10,6 +10,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { stateDir } from "./config.js";
 import { attachmentName, attachmentToken } from "./files/attachments.js";
+import { isAgentEffort } from "./shared.js";
 const MAX_KEYS = 50_000;
 const MAX_KEY_LENGTH = 256;
 const MAX_MARK_LENGTH = 128;
@@ -33,7 +34,7 @@ function sanitizeAgent(raw) {
     const agent = {};
     if (typeof value.model === 'string' && value.model.length <= MAX_AGENT_LABEL_LENGTH)
         agent.model = value.model;
-    if (typeof value.effort === 'string' && value.effort.length <= MAX_AGENT_LABEL_LENGTH)
+    if (isAgentEffort(value.effort))
         agent.effort = value.effort;
     if (typeof value.plan === 'boolean')
         agent.plan = value.plan;

package/dist-node/src/shared.js

@@ -13,6 +13,11 @@
  * Each of these was a second copy before, and each copy was a way for two screens to
  * disagree about the same workspace.
  */
+/** Stable wire values used by request validation and the phone's effort controls. */
+export const AGENT_EFFORTS = ['none', 'low', 'medium', 'high', 'xhigh', 'max', 'ultracode'];
+export function isAgentEffort(value) {
+    return AGENT_EFFORTS.some(effort => effort === value);
+}
 /**
  * Parse the duration grammar accepted by `conductor-remote nosleep`: `90m`,
  * `2h`, `30s`, or bare seconds. Kept here so the CLI and phone cannot drift.

package/dist-node/src/wire.js

@@ -12,8 +12,8 @@
  * Before this, the phone kept a hand-written mirror of all of it and `mcp-tools.ts`
  * kept a third copy inline. Nothing enforced the copies — a field renamed in
  * `reads.ts` typechecked cleanly on both sides and surfaced as `undefined` on a
- * phone. So the rule is: **a shape that leaves the relay is declared here, and
- * nowhere else.**
+ * phone. Each shape has one owner and is exported here; validated request types
+ * are inferred from the Zod schemas in `src/contracts/agent-inputs.ts`.
  *
  * The web app may only `import type` from `src/` (see `scripts/check-imports.ts`).
  * `verbatimModuleSyntax` erases those imports, so nothing here reaches the bundle —