crewly 1.20.40 → 1.20.47

package/packages/crewly-agent/src/runtime/desktop-task-runtime.test.ts

@@ -0,0 +1,251 @@
+/**
+ * Tests for the desktop task runtime.
+ *
+ * The rule these exist to hold: a subgoal is done when its checkpoint holds,
+ * never when the agent says so. Every other behaviour here — budgets,
+ * surprise handling, confirmation — is in service of a forty-step task not
+ * ending in a confident, false report.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  beginTask, step, chooseRoute, needsConfirmation, awaitConfirmation,
+  resolveConfirmation, summarize, activeSubgoal, DEFAULT_TASK_BUDGET,
+  type Subgoal, type TaskState,
+} from './desktop-task-runtime.js';
+import type { Scene } from './desktop-recovery.js';
+
+/** A plan of two subgoals, each checked against a file. */
+function plan(): Subgoal[] {
+  return [
+    { id: 's1', goal: 'write the note', checkpoint: { kind: 'file-contains', path: '/tmp/a', text: 'ok' }, maxSteps: 3 },
+    { id: 's2', goal: 'rename it', checkpoint: { kind: 'file-exists', path: '/tmp/b' }, maxSteps: 3 },
+  ];
+}
+
+/** An empty screen — nothing surprising on it. */
+const CALM: Scene = { elements: [] };
+
+/** Checkpoint IO that answers from a fake filesystem. */
+function fakeFs(files: Record<string, string>) {
+  return {
+    readFile: async (p: string) => {
+      if (!(p in files)) throw new Error('ENOENT');
+      return files[p]!;
+    },
+    statFile: async (p: string) => {
+      if (!(p in files)) throw new Error('ENOENT');
+      return { size: files[p]!.length };
+    },
+  };
+}
+
+describe('checkpoints decide, not the agent', () => {
+  it('keeps the agent on a subgoal until the world matches, and says what is wrong', async () => {
+    const state = beginTask('write and rename', plan());
+    const files: Record<string, string> = {};
+
+    // The agent has "done" the work, but the file is not there.
+    const first = await step(state, CALM, fakeFs(files));
+    expect(first.kind).toBe('continue');
+    expect((first as { hint?: string }).hint).toContain('/tmp/a');
+    expect(activeSubgoal(state)!.subgoal.id).toBe('s1');
+
+    // Now it really is.
+    files['/tmp/a'] = 'ok';
+    const second = await step(state, CALM, fakeFs(files));
+    expect(second.kind).toBe('advance');
+    expect((second as { next: Subgoal }).next.id).toBe('s2');
+  });
+
+  it('calls an empty file out rather than passing it — that is the unfinished save', async () => {
+    const state = beginTask('save', [
+      { id: 's1', goal: 'save the file', checkpoint: { kind: 'file-exists', path: '/tmp/a' } },
+    ]);
+    const out = await step(state, CALM, fakeFs({ '/tmp/a': '' }));
+    expect(out.kind).toBe('continue');
+    expect((out as { hint?: string }).hint).toMatch(/empty|did not complete/i);
+  });
+
+  it('reports done only when every checkpoint held', async () => {
+    const state = beginTask('write and rename', plan());
+    const files = { '/tmp/a': 'ok', '/tmp/b': 'x' };
+    expect((await step(state, CALM, fakeFs(files))).kind).toBe('advance');
+    expect((await step(state, CALM, fakeFs(files))).kind).toBe('done');
+    expect(summarize(state)).toContain('2/2 verified');
+  });
+
+  it('escalates a subgoal that burns its budget, and does not move on', async () => {
+    const state = beginTask('write', [
+      { id: 's1', goal: 'write the note', checkpoint: { kind: 'file-exists', path: '/tmp/never' }, maxSteps: 2 },
+      { id: 's2', goal: 'later work', checkpoint: { kind: 'file-exists', path: '/tmp/b' } },
+    ]);
+    expect((await step(state, CALM, fakeFs({}))).kind).toBe('continue');
+    const out = await step(state, CALM, fakeFs({}));
+    expect(out.kind).toBe('escalate');
+    // The later subgoal assumed this one worked, so it must not start.
+    expect(state.progress[1]!.state).toBe('pending');
+    expect((out as { detail: string }).detail).toContain('later subgoals assume');
+  });
+});
+
+describe('budgets', () => {
+  it('stops on the step ceiling and says what got done', async () => {
+    const state = beginTask('long task', plan(), { ...DEFAULT_TASK_BUDGET, maxSteps: 1 });
+    await step(state, CALM, fakeFs({}));
+    const out = await step(state, CALM, fakeFs({}));
+    expect(out.kind).toBe('budget-exhausted');
+    expect((out as { remaining: string[] }).remaining).toContain('write the note');
+  });
+
+  it('stops on the clock', async () => {
+    let clock = 1_000;
+    const state = beginTask('slow task', plan(), { ...DEFAULT_TASK_BUDGET, maxDurationMs: 100 }, () => clock);
+    clock += 500;
+    const out = await step(state, CALM, fakeFs({}), () => clock);
+    expect(out.kind).toBe('budget-exhausted');
+    expect((out as { reason: string }).reason).toMatch(/longer than/);
+  });
+});
+
+describe('surprises', () => {
+  const dialog: Scene = {
+    elements: [
+      { role: 'AXSheet', name: 'Save changes?' },
+      { role: 'AXButton', name: 'Save' },
+      { role: 'AXButton', name: "Don't Save" },
+      { role: 'AXButton', name: 'Cancel' },
+    ],
+  };
+
+  it('does not test the checkpoint while a dialog is covering the window', async () => {
+    const state = beginTask('edit', plan());
+    const checkpoint = vi.fn();
+    const out = await step(state, dialog, { statFile: checkpoint as never });
+    expect(out.kind).toBe('continue');
+    // Testing it now would be testing the wrong world.
+    expect(checkpoint).not.toHaveBeenCalled();
+    expect((out as { hint?: string }).hint).toContain("Don't Save");
+  });
+
+  it('gives up on a surprise that keeps coming back instead of looping', async () => {
+    const state = beginTask('edit', plan());
+    let out = await step(state, dialog, {});
+    out = await step(state, dialog, {});
+    out = await step(state, dialog, {});
+    out = await step(state, dialog, {});
+    expect(out.kind).toBe('escalate');
+    expect((out as { detail: string }).detail).toMatch(/three times/);
+  });
+
+  it('never tries to answer a permission prompt on the owner\'s behalf', async () => {
+    const state = beginTask('open', plan());
+    const prompt: Scene = {
+      elements: [
+        { role: 'AXSheet', name: 'Terminal would like to access your Documents' },
+        { role: 'AXButton', name: 'Allow' },
+      ],
+    };
+    const out = await step(state, prompt, {});
+    expect(out.kind).toBe('escalate');
+    expect((out as { detail: string }).detail).toMatch(/their decision|owner/i);
+  });
+
+  it('stops at a login wall rather than typing credentials', async () => {
+    const state = beginTask('open', plan());
+    const out = await step(state, { elements: [{ role: 'AXStaticText', name: 'Sign in to continue' }] }, {});
+    expect(out.kind).toBe('escalate');
+    expect((out as { reason: string }).reason).toBe('login-required');
+  });
+
+  it('notices focus moving to another app and says the refs are stale', async () => {
+    const state = beginTask('work in TextEdit', [
+      { id: 's1', goal: 'type', checkpoint: { kind: 'app-frontmost', app: 'TextEdit' } },
+    ]);
+    const out = await step(state, { app: 'Safari', elements: [] }, {});
+    expect(out.kind).toBe('continue');
+    expect((out as { hint?: string }).hint).toMatch(/stale/);
+  });
+});
+
+describe('routing', () => {
+  it('prefers a skill over the screen when one exists', () => {
+    const out = chooseRoute('send the summary by email', ['gmail-send']);
+    expect(out.route).toBe('skill');
+    expect(out.candidate).toBe('gmail-send');
+  });
+
+  it('falls back to the screen when the skill is not installed', () => {
+    expect(chooseRoute('send the summary by email', []).route).toBe('element');
+  });
+
+  it('uses the browser for a page and pixels for a canvas', () => {
+    expect(chooseRoute('open https://example.com and read it').route).toBe('browser');
+    expect(chooseRoute('draw a line on the canvas').route).toBe('pixel');
+  });
+
+  it('hands credentials to a person', () => {
+    expect(chooseRoute('log in with the password').route).toBe('human');
+  });
+
+  it('defaults to elements, not coordinates', () => {
+    const out = chooseRoute('rename the file in Finder');
+    expect(out.route).toBe('element');
+    expect(out.because).toMatch(/cannot miss/);
+  });
+});
+
+describe('irreversible actions', () => {
+  it('spots the ones that cannot be undone, in either language', () => {
+    for (const action of ['click the Send button', 'delete the folder', 'publish the post', '发送邮件', '删除文件']) {
+      expect(needsConfirmation(action).required, action).toBe(true);
+    }
+  });
+
+  it('does not stop ordinary work', () => {
+    // "sender" contains "send" but is not it — the word boundary is the point.
+    for (const action of ['open the document', 'read the second row', 'check the sender name']) {
+      expect(needsConfirmation(action).required, action).toBe(false);
+    }
+  });
+
+  it('holds the task until the owner answers, doing nothing meanwhile', async () => {
+    const state = beginTask('send it', plan());
+    awaitConfirmation(state, 'click Send on the email');
+    const out = await step(state, CALM, fakeFs({ '/tmp/a': 'ok' }));
+    // Even though the checkpoint would now pass, nothing moves.
+    expect(out.kind).toBe('await-confirmation');
+    expect(activeSubgoal(state)!.subgoal.id).toBe('s1');
+  });
+
+  it('carries on when approved', () => {
+    const state = beginTask('send it', plan());
+    awaitConfirmation(state, 'click Send');
+    const out = resolveConfirmation(state, true);
+    expect(out.kind).toBe('continue');
+    expect(state.awaitingConfirmation).toBeUndefined();
+  });
+
+  it('stops for good when declined, and forbids working around it', () => {
+    const state = beginTask('send it', plan());
+    awaitConfirmation(state, 'click Send');
+    const out = resolveConfirmation(state, false);
+    expect(out.kind).toBe('escalate');
+    expect((out as { detail: string }).detail).toMatch(/do not look for another way/i);
+    expect(state.progress[0]!.state).toBe('skipped');
+  });
+});
+
+describe('summary', () => {
+  it('names a stuck subgoal as stuck rather than rounding up', async () => {
+    const state: TaskState = beginTask('two things', plan());
+    await step(state, CALM, fakeFs({ '/tmp/a': 'ok' }));   // s1 done
+    state.progress[1]!.state = 'stuck';
+    state.progress[1]!.blockedBy = 'the dialog never closed';
+    const text = summarize(state);
+    expect(text).toContain('1/2 verified');
+    expect(text).toContain('✓ write the note');
+    expect(text).toContain('✗ rename it');
+    expect(text).toContain('the dialog never closed');
+  });
+});

package/packages/crewly-agent/src/runtime/desktop-task-runtime.ts

@@ -0,0 +1,423 @@
+/**
+ * The desktop task runtime — subgoals, checkpoints, budgets, escalation.
+ *
+ * Phase 4 of docs/research/computer-use-capability-assessment.md, and the one
+ * the document calls the dividing line for unattended work. Phases 1–3 gave
+ * an agent safe, precise, one-call access to the desktop. None of that stops
+ * a forty-step task from going wrong in the four ways §5.1 lists, because
+ * every one of them is about the *shape* of the attempt rather than any
+ * single action:
+ *
+ *   - taking the GUI route when a skill would have done it  → the router
+ *   - drifting onto a state that changed at step 15         → checkpoints
+ *   - reporting success that never happened                 → checkpoints
+ *   - doing something irreversible unasked                  → confirmation
+ *
+ * A subgoal is not finished when the agent says so. It is finished when its
+ * checkpoint holds, and the runtime is what refuses to move on until it does.
+ *
+ * @module runtime/desktop-task-runtime
+ */
+
+import { evaluateCheckpoint, describeCheckpoint, type Checkpoint, type CheckpointDeps, type CheckpointResult } from './desktop-checkpoint.js';
+import { detectSurprise, shouldRetryAfter, type Scene, type Surprise } from './desktop-recovery.js';
+
+/** One step of the plan. */
+export interface Subgoal {
+  id: string;
+  /** What to achieve, in the agent's own words. */
+  goal: string;
+  /** How the runtime will know it happened. */
+  checkpoint: Checkpoint;
+  /** Steps this subgoal may take before it is declared stuck. */
+  maxSteps?: number;
+}
+
+/** Where a subgoal stands. */
+export type SubgoalState = 'pending' | 'active' | 'done' | 'stuck' | 'skipped';
+
+/** A subgoal plus its progress. */
+export interface SubgoalProgress {
+  subgoal: Subgoal;
+  state: SubgoalState;
+  stepsUsed: number;
+  /** Surprises handled while working on it, by kind. */
+  recoveries: Record<string, number>;
+  /** Why it is stuck, when it is. */
+  blockedBy?: string;
+  lastCheck?: CheckpointResult;
+}
+
+/** Caps for a whole task. */
+export interface TaskBudget {
+  /** Total steps across every subgoal. */
+  maxSteps: number;
+  /** Wall-clock milliseconds. */
+  maxDurationMs: number;
+  /** Steps any one subgoal may take when it does not say. */
+  defaultSubgoalSteps: number;
+}
+
+/** Sensible caps. A desktop task that needs more than this has gone wrong. */
+export const DEFAULT_TASK_BUDGET: TaskBudget = {
+  maxSteps: 120,
+  maxDurationMs: 15 * 60 * 1000,
+  defaultSubgoalSteps: 20,
+};
+
+/** The layers an action can be taken at, cheapest and most reliable first. */
+export type Route = 'skill' | 'browser' | 'element' | 'pixel' | 'human';
+
+/** What the runtime says to do next. */
+export type Directive =
+  /** Keep working on this subgoal. */
+  | { kind: 'continue'; subgoal: Subgoal; stepsLeft: number; hint?: string }
+  /** The checkpoint held; here is the next subgoal. */
+  | { kind: 'advance'; completed: Subgoal; next: Subgoal }
+  /** Everything's checkpoint held. */
+  | { kind: 'done'; summary: string }
+  /** Something needs a person. */
+  | { kind: 'escalate'; reason: string; detail: string }
+  /** An irreversible action is waiting on the owner. */
+  | { kind: 'await-confirmation'; action: string; detail: string }
+  /** The budget ran out. */
+  | { kind: 'budget-exhausted'; reason: string; completed: string[]; remaining: string[] };
+
+/**
+ * Pick the cheapest layer that can do a thing.
+ *
+ * The first failure in §5.1 is an agent opening Mail.app to send an email
+ * Crewly already has a skill for. Thirty clicks that can each go wrong, in
+ * place of one call that cannot. The router exists to make the cheap answer
+ * the obvious one.
+ *
+ * @param goal - The subgoal text
+ * @param available - What this install can do (skill ids, connector names)
+ * @returns The layer to prefer, and why
+ *
+ * @example
+ * chooseRoute('send the summary by email', ['gmail-send'])
+ * // → { route: 'skill', because: 'gmail-send does this without touching the screen' }
+ */
+export function chooseRoute(
+  goal: string,
+  available: string[] = [],
+): { route: Route; because: string; candidate?: string } {
+  const text = goal.toLowerCase();
+
+  // A named skill beats everything. Matching is on the words a person would
+  // use, not on the skill id, because the plan is written in prose.
+  const skillHints: Array<{ words: string[]; skill: string }> = [
+    { words: ['email', 'mail', '邮件'], skill: 'gmail-send' },
+    { words: ['calendar', 'meeting', 'event', '日历'], skill: 'calendar-create' },
+    { words: ['drive', 'upload', '上传'], skill: 'drive-upload' },
+    { words: ['slack', 'channel', '频道'], skill: 'reply-channel' },
+    { words: ['spreadsheet', 'sheet', '表格'], skill: 'sheets-write' },
+    { words: ['doc', 'document', '文档'], skill: 'docs-write' },
+  ];
+  for (const hint of skillHints) {
+    if (!hint.words.some((w) => text.includes(w))) continue;
+    if (available.includes(hint.skill)) {
+      return {
+        route: 'skill',
+        candidate: hint.skill,
+        because: `${hint.skill} does this without touching the screen — no clicks to misfire.`,
+      };
+    }
+  }
+
+  // No trailing \b on the scheme: ':' and '/' are both non-word characters,
+  // so \b between them never matches and every URL fell through to `element`.
+  if (/\b(web ?page|website|browser|url)\b|https?:\/\//.test(text)) {
+    return { route: 'browser', because: 'A page is DOM, so the browser tools are exact where coordinates are not.' };
+  }
+
+  if (/\b(draw|canvas|game|sketch|paint)\b/.test(text)) {
+    return { route: 'pixel', because: 'Nothing here exposes elements, so coordinates are the only option.' };
+  }
+
+  if (/\b(sign in|log ?in|password|2fa|captcha|credential)\b/.test(text)) {
+    return { route: 'human', because: 'Credentials are never entered by an agent.' };
+  }
+
+  return {
+    route: 'element',
+    because: 'Take a snapshot and act on refs — naming an element cannot miss the way a coordinate can.',
+  };
+}
+
+/** Phrases that mean an action cannot be taken back. */
+const IRREVERSIBLE = [
+  'send', 'submit', 'publish', 'post', 'delete', 'remove', 'erase', 'empty trash',
+  'pay', 'purchase', 'buy', 'transfer', 'confirm order', 'deploy', 'merge',
+  '发送', '提交', '发布', '删除', '付款', '购买',
+];
+
+/**
+ * Whether an action needs the owner's word before it happens.
+ *
+ * Deliberately generous: a false positive costs one notification, a false
+ * negative sends an email that cannot be unsent. §5.8 makes the confirmation
+ * asynchronous precisely so that being generous here is cheap — the owner
+ * answers from their phone and the machine is not blocked meanwhile.
+ *
+ * @param action - What the agent is about to do, in words
+ * @returns Whether to ask first, and the phrase that triggered it
+ *
+ * @example
+ * needsConfirmation('click the Send button') // → { required: true, trigger: 'send' }
+ */
+export function needsConfirmation(action: string): { required: boolean; trigger?: string } {
+  const text = action.toLowerCase();
+  for (const phrase of IRREVERSIBLE) {
+    // Word boundaries for Latin phrases; CJK has none, so substring is right.
+    const pattern = /[a-z]/.test(phrase) ? new RegExp(`\\b${phrase}\\b`) : null;
+    if (pattern ? pattern.test(text) : text.includes(phrase)) {
+      return { required: true, trigger: phrase };
+    }
+  }
+  return { required: false };
+}
+
+/** Everything the runtime remembers about one task. */
+export interface TaskState {
+  goal: string;
+  progress: SubgoalProgress[];
+  budget: TaskBudget;
+  startedAt: number;
+  stepsUsed: number;
+  /** Set while an irreversible action waits on the owner. */
+  awaitingConfirmation?: { action: string; since: number };
+}
+
+/**
+ * Start a task.
+ *
+ * @param goal - The whole task, in words
+ * @param subgoals - The plan
+ * @param budget - Caps; defaults are usually right
+ * @param now - Clock, injectable for tests
+ * @returns Fresh state
+ */
+export function beginTask(
+  goal: string,
+  subgoals: Subgoal[],
+  budget: TaskBudget = DEFAULT_TASK_BUDGET,
+  now: () => number = Date.now,
+): TaskState {
+  return {
+    goal,
+    budget,
+    startedAt: now(),
+    stepsUsed: 0,
+    progress: subgoals.map((subgoal, index) => ({
+      subgoal,
+      state: index === 0 ? 'active' : 'pending',
+      stepsUsed: 0,
+      recoveries: {},
+    })),
+  };
+}
+
+/** The subgoal being worked on, if any. */
+export function activeSubgoal(state: TaskState): SubgoalProgress | undefined {
+  return state.progress.find((p) => p.state === 'active');
+}
+
+/**
+ * Advance the task by one step's worth of thinking.
+ *
+ * Called after each action the agent takes. It checks the budget, looks for a
+ * surprise, tests the checkpoint, and says what to do next — which is the
+ * whole point: the decision to move on is the runtime's, not the agent's.
+ *
+ * @param state - Mutated in place with progress
+ * @param scene - What is on screen now, for surprise detection
+ * @param deps - IO for checkpoint evaluation
+ * @param now - Clock
+ * @returns What the agent should do next
+ */
+export async function step(
+  state: TaskState,
+  scene: Scene,
+  deps: CheckpointDeps = {},
+  now: () => number = Date.now,
+): Promise<Directive> {
+  const completed = () => state.progress.filter((p) => p.state === 'done').map((p) => p.subgoal.goal);
+  const remaining = () => state.progress.filter((p) => p.state !== 'done').map((p) => p.subgoal.goal);
+
+  if (state.awaitingConfirmation) {
+    return {
+      kind: 'await-confirmation',
+      action: state.awaitingConfirmation.action,
+      detail: 'Waiting for the owner to approve. Do nothing else until they answer.',
+    };
+  }
+
+  state.stepsUsed += 1;
+  const current = activeSubgoal(state);
+  if (!current) {
+    return { kind: 'done', summary: `All ${state.progress.length} subgoals verified.` };
+  }
+  current.stepsUsed += 1;
+
+  // Budget before anything else: an exhausted task should stop, not spend its
+  // last step discovering a surprise it has no budget to handle.
+  if (state.stepsUsed > state.budget.maxSteps) {
+    return {
+      kind: 'budget-exhausted',
+      reason: `Used ${state.stepsUsed} steps of ${state.budget.maxSteps}.`,
+      completed: completed(),
+      remaining: remaining(),
+    };
+  }
+  if (now() - state.startedAt > state.budget.maxDurationMs) {
+    return {
+      kind: 'budget-exhausted',
+      reason: `Ran for longer than ${Math.round(state.budget.maxDurationMs / 60000)} minutes.`,
+      completed: completed(),
+      remaining: remaining(),
+    };
+  }
+
+  // A surprise means the screen is not what the plan assumed. Checking the
+  // checkpoint now would test the wrong world.
+  const surprise = detectSurprise(scene, sceneAppFor(current));
+  if (surprise) {
+    const kind = surprise.kind;
+    current.recoveries[kind] = (current.recoveries[kind] ?? 0) + 1;
+    const verdict = shouldRetryAfter(kind, current.recoveries[kind] - 1, surprise.selfRecoverable);
+    if (!verdict.retry) {
+      current.state = 'stuck';
+      current.blockedBy = surprise.detail;
+      // The surprise's own instruction is the actionable half ("this is the
+      // owner's decision, tell them what is being asked"); dropping it for
+      // the generic escalation line would lose exactly the useful part.
+      return {
+        kind: 'escalate',
+        reason: surprise.kind,
+        detail: [surprise.detail, surprise.instruction, verdict.escalation].filter(Boolean).join(' '),
+      };
+    }
+    return { kind: 'continue', subgoal: current.subgoal, stepsLeft: stepsLeftFor(current, state), hint: surprise.instruction };
+  }
+
+  // The only thing that completes a subgoal.
+  const check = await evaluateCheckpoint(current.subgoal.checkpoint, deps);
+  current.lastCheck = check;
+
+  if (check.passed) {
+    current.state = 'done';
+    const next = state.progress.find((p) => p.state === 'pending');
+    if (!next) {
+      return { kind: 'done', summary: `All ${state.progress.length} subgoals verified.` };
+    }
+    next.state = 'active';
+    return { kind: 'advance', completed: current.subgoal, next: next.subgoal };
+  }
+
+  const left = stepsLeftFor(current, state);
+  if (left <= 0) {
+    current.state = 'stuck';
+    current.blockedBy = check.reason ?? 'The checkpoint never held.';
+    return {
+      kind: 'escalate',
+      reason: 'subgoal-stuck',
+      detail:
+        `"${current.subgoal.goal}" used its whole budget and ${describeCheckpoint(current.subgoal.checkpoint)} is still false. ` +
+        `${check.reason ?? ''} Report what you tried rather than continuing — the later subgoals assume this one worked.`.trim(),
+    };
+  }
+
+  return {
+    kind: 'continue',
+    subgoal: current.subgoal,
+    stepsLeft: left,
+    // The reason is the useful part: "the file is empty" tells the agent the
+    // save dialog is still open, where "not done" tells it nothing.
+    hint: check.reason,
+  };
+}
+
+/** Steps this subgoal has left. */
+function stepsLeftFor(progress: SubgoalProgress, state: TaskState): number {
+  const cap = progress.subgoal.maxSteps ?? state.budget.defaultSubgoalSteps;
+  return cap - progress.stepsUsed;
+}
+
+/** The app a subgoal implies, for focus-loss detection. */
+function sceneAppFor(progress: SubgoalProgress): string | undefined {
+  const cp = progress.subgoal.checkpoint;
+  if (cp.kind === 'app-frontmost') return cp.app;
+  if ((cp.kind === 'element-present' || cp.kind === 'element-absent') && cp.app) return cp.app;
+  return undefined;
+}
+
+/**
+ * Hold the task while the owner approves something irreversible.
+ *
+ * The machine is not blocked — nothing else is running — but the agent is,
+ * which is the point: the owner answers from wherever they are and the task
+ * picks up where it stopped.
+ *
+ * @param state - Mutated
+ * @param action - What is waiting
+ * @param now - Clock
+ */
+export function awaitConfirmation(state: TaskState, action: string, now: () => number = Date.now): void {
+  state.awaitingConfirmation = { action, since: now() };
+}
+
+/**
+ * Record the owner's answer.
+ *
+ * @param state - Mutated
+ * @param approved - Their decision
+ * @returns What to do next
+ */
+export function resolveConfirmation(state: TaskState, approved: boolean): Directive {
+  const pending = state.awaitingConfirmation;
+  state.awaitingConfirmation = undefined as TaskState['awaitingConfirmation'];
+  if (!pending) {
+    return { kind: 'escalate', reason: 'no-pending-confirmation', detail: 'Nothing was waiting for approval.' };
+  }
+  if (approved) {
+    const current = activeSubgoal(state);
+    return current
+      ? { kind: 'continue', subgoal: current.subgoal, stepsLeft: stepsLeftFor(current, state), hint: `Approved: ${pending.action}. Go ahead.` }
+      : { kind: 'done', summary: 'Approved, and nothing left to do.' };
+  }
+  const current = activeSubgoal(state);
+  if (current) {
+    current.state = 'skipped';
+    current.blockedBy = `The owner declined: ${pending.action}`;
+  }
+  return {
+    kind: 'escalate',
+    reason: 'declined',
+    detail: `The owner declined "${pending.action}". Do not look for another way to do it — stop and report.`,
+  };
+}
+
+/**
+ * A plain-language account of where the task stands.
+ *
+ * This is what gets reported when the task ends, for whatever reason, so it
+ * has to be true rather than encouraging: a stuck subgoal is named as stuck.
+ *
+ * @param state - The task
+ * @returns Lines for the owner
+ */
+export function summarize(state: TaskState): string {
+  const mark: Record<SubgoalState, string> = {
+    done: '✓', stuck: '✗', skipped: '—', active: '→', pending: '·',
+  };
+  const lines = state.progress.map((p) => {
+    const base = `${mark[p.state]} ${p.subgoal.goal}`;
+    if (p.state === 'done') return `${base}  (verified: ${describeCheckpoint(p.subgoal.checkpoint)})`;
+    if (p.blockedBy) return `${base}  — ${p.blockedBy}`;
+    return base;
+  });
+  const done = state.progress.filter((p) => p.state === 'done').length;
+  return [`${done}/${state.progress.length} verified · ${state.stepsUsed} steps`, ...lines].join('\n');
+}