@anhlp/alp-runtime 0.0.0-beta.2 → 0.0.1-beta.3

package/src/runtime.ts

@@ -56,6 +56,8 @@ const USER_REPLY_MS = 60_000;
 
 /** What a waiting session hears when the user wrote to it. */
 const USER_WROTE = 'The user just wrote to you; their message follows. Answer them first in a short message they can read (tool calls alone show them nothing), and steer an assignment with alp_send when their words change its brief. Your assignments keep running: then alp_wait again, or end your turn and ALP wakes you with their results.';
+/** A wait cut short by the end of its turn: what it waited for goes on. */
+const TURN_ENDED = 'Turn ended before the result arrived. Running assignments keep running; ALP wakes you with their results as mail.';
 /** What a waiting session hears with a check-in, or mail from its requester or the user. */
 const CHECKED_IN = 'Not a result: the assignment keeps running. Act on this mail first (a steer from your requester or the user\'s words may change what your assignments should do: pass that on with alp_send), then alp_wait again or end your turn.';
 /** A session's native process is restarted at most RESTART_LIMIT times within RESTART_WINDOW_MS unless it makes progress meanwhile. */
@@ -206,11 +208,12 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       ...(session.parent ? { parentId: session.parent } : {}),
       ...(session.toolCallId ? { toolCallId: session.toolCallId } : {}),
       ...(session.active ? { activeTurnId: session.active } : {}),
-      ...(session.parked ? { parked: session.parked.reason } : {}),
+      // turn.ended listeners persist the intent before terminal() finishes parking it.
+      ...((session.parked?.reason ?? session.parkReason) ? { parked: session.parked?.reason ?? session.parkReason } : {}),
       ...(session.instructionsSha ? { instructionsSha: session.instructionsSha } : {}),
       ...(takesImages(session) ? { promptImages: true } : {}),
       ...(session.usage ? { usage: session.usage } : {}),
-      busy: !!(session.active || session.pending || session.children.size || session.assignments.size || hasActiveMail(session) || reviewing(session)),
+      busy: !!(session.active || session.pending || session.parked || session.parkReason || session.children.size || session.assignments.size || hasActiveMail(session) || reviewing(session)),
     };
   }
 
@@ -238,7 +241,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       clearTimeout(waiter.timer);
       waiter.resolve(null);
     }
-    cancelQuestions(sessionId);
+    cancelQuestions(sessionId, true);
     if (session.parent) sessions.get(session.parent)?.assignments.get(sessionId)?.ask?.resolve(toolResult(false, { error: 'Turn ended' }));
 
     // Mail is acknowledged only by a turn that completed; otherwise it is delivered again.
@@ -465,7 +468,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
 
       // A usage limit pauses its runtime; an assignment it stopped is parked to continue later.
       if (state === 'failed' && LIMIT_ERRORS.includes(params.turn.error?.codexErrorInfo)) {
-        if (session.parent && session.role !== 'supervisor') session.parkReason = `the ${label(session.runtimeKind)} usage limit was reached`;
+        if (session.role !== 'supervisor') session.parkReason = `the ${label(session.runtimeKind)} usage limit was reached`;
         void limitReached(session, params.turn.error);
       }
 
@@ -484,6 +487,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
 
     session.closed = true;
     cancelQuestions(sessionId);
+    approvalLedger.delete(sessionId);
     releaseClaims(sessionId, session.mapping.agent.projectRoot);
 
     await Promise.all(
@@ -624,7 +628,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
   const boards = new Map<string, Promise<Pin[]>>();
   /** The same boards once loaded, for synchronous status. */
   const loadedBoards = new Map<string, Pin[]>();
-  const userQuestions = new Map<string, { question: UserQuestion; settle: (outcome: 'answered' | 'dismissed' | 'timeout' | 'canceled', answer?: string, reason?: string, result?: unknown) => void }>();
+  const userQuestions = new Map<string, { question: UserQuestion; persistent?: boolean; /** From alp_ask: the user's words in the chat end it (#116). */ asked?: boolean; settle: (outcome: 'answered' | 'dismissed' | 'timeout' | 'canceled', answer?: string, reason?: string, result?: unknown) => void }>();
   let mailSequence = 0;
   let watchdog: NodeJS.Timeout | undefined;
 
@@ -793,6 +797,8 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       : entry.event === 'task' ? `${entry.agent} ${TASK_PAST[entry.action] ?? entry.action} task ${entry.id} "${clip(entry.title, 120)}"${entry.status ? ` (now ${entry.status})` : ''}${entry.detail ? `: ${clip(entry.detail)}` : ''}`
       : entry.event === 'epic.landed' ? `${entry.agent} closed ${entry.id} "${clip(entry.title, 120)}": ${entry.tasks} tasks, ${entry.reworked} reworked, ${entry.unverified?.length ?? 0} closed unverified`
       : entry.event === 'recall' ? `${entry.agent} recalled ${entry.recalled} assignment ${entry.assignmentId}: ${clip(entry.question)}`
+      : entry.event === 'skill.approval' && !entry.saved ? `skill approval ${entry.approvalId} for ${entry.name}: not saved (${entry.error ?? entry.outcome})`
+      : entry.event === 'issue.approval' ? `issue approval ${entry.approvalId} in ${entry.repo}: ${entry.posted ? entry.url : entry.error ?? entry.outcome}`
       : entry.event === 'issue' ? `${entry.action === 'create' ? `opened issue "${clip(entry.title, 200)}"` : `commented on issue #${entry.issue}`} in ${entry.repo} with the user's approval: ${entry.url}`
       : entry.event?.startsWith('worktree.') ? `${entry.event.slice('worktree.'.length)} worktree of ${entry.assignmentId} (${entry.branch})${entry.status ? `: ${entry.status}` : ''}`
       : undefined;
@@ -1253,20 +1259,36 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
   }
 
   function continueParked(sessionId: string, session: Session) {
-    const { reason, prompt } = session.parked!;
-    session.parked = undefined;
-    session.wakeHeld = false;
-    session.lastActivity = Date.now();
-    emit(sessionId, { type: 'session.updated', session: snapshot(sessionId, session) });
-    const parent = session.parent ? sessions.get(session.parent) : undefined;
-    const assignment = parent?.assignments.get(sessionId);
-    runLog(rootOf(sessionId), { event: 'assignment.resumed', assignmentId: sessionId, agent: session.mapping.agent.name });
-    if (assignment) emit(session.parent!, { type: 'assignment', assignment: assignmentSnapshot(assignment, 'running') });
-    void startPrompt(sessionId, {
-      clientMessageId: `alp-resume-${randomUUID()}`,
-      delivery: 'auto',
-      content: [{ type: 'text', text: prompt ?? `ALP resumed this assignment; it had stopped because ${reason}. Continue where you left off: your earlier work in this session and its files are intact. Finish with alp_handoff as before.` }],
-    }, session.parent ? 'assignment' : 'wake').catch(error => session.settle?.('failed', error));
+    void enqueue(async () => {
+      if (session.closed || session.active || session.pending || !session.parked || pauseOf(session.runtimeKind)) return;
+      const parked = session.parked;
+      const { reason, prompt } = parked;
+      session.parked = undefined;
+      session.wakeHeld = false;
+      session.lastActivity = Date.now();
+      const parent = session.parent ? sessions.get(session.parent) : undefined;
+      const assignment = parent?.assignments.get(sessionId);
+      runLog(rootOf(sessionId), { event: 'assignment.resumed', assignmentId: sessionId, agent: session.mapping.agent.name });
+      if (assignment) emit(session.parent!, { type: 'assignment', assignment: assignmentSnapshot(assignment, 'running') });
+      try {
+        await startPrompt(sessionId, {
+          clientMessageId: `alp-resume-${randomUUID()}`,
+          delivery: 'auto',
+          content: [{ type: 'text', text: prompt ?? (session.parent
+            ? `ALP resumed this assignment; it had stopped because ${reason}. Continue where you left off: your earlier work in this session and its files are intact. Finish with alp_handoff as before.`
+            : `ALP resumed this session; it had stopped because ${reason}. Continue the user's request where you left off: your earlier work in this thread and its files are intact.`) }],
+        }, session.parent ? 'assignment' : 'wake');
+        session.resumedTurn = session.active;
+        emit(sessionId, { type: 'session.updated', session: snapshot(sessionId, session) });
+      } catch (error) {
+        if (!session.closed && !session.active) {
+          session.parked = parked;
+          emit(sessionId, { type: 'session.updated', session: snapshot(sessionId, session) });
+          if (assignment) emit(session.parent!, { type: 'assignment', assignment: assignmentSnapshot(assignment, 'parked') });
+        }
+        notice('warning', `Could not resume ${session.mapping.agent.name}: ${errorData(error).message}`);
+      }
+    });
   }
 
   /** When a limit resets, from what the runtime last reported: the latest reset of a window that is used up. */
@@ -1287,8 +1309,10 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
   /** A turn failed on a usage limit: pause that runtime for delegation and wakes, and tell the user. */
   async function limitReached(session: Session, error: any) {
     const kind = session.runtimeKind;
-    if (paused.runtimes[kind]?.by === 'alpd') return;
+    if (pauseOf(kind)) return;
     const resetsAt = await limitReset(session, error);
+    // A user's pause made while the provider lookup awaited remains theirs to lift.
+    if (closed || session.closed || pauseOf(kind)) return;
     const pause: Pause = { since: new Date().toISOString(), by: 'alpd', reason: `${label(kind)} usage limit reached`, ...(resetsAt ? { resetsAt } : {}) };
     pauseRuntime(kind, pause);
     const other = RUNTIMES.find(candidate => candidate !== kind && !pauseOf(candidate));
@@ -1478,10 +1502,10 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
    * Asks the user to approve a proposal and waits for the answer. Only an approving
    * answer approves; a dismissal, a timeout or another answer does not.
    */
-  async function confirm(sessionId: string, session: Session, body: string): Promise<{ approved: boolean; feedback?: string; outcome?: string }> {
+  async function confirm(sessionId: string, session: Session, body: string, approval?: { id: string }): Promise<{ approved: boolean; feedback?: string; outcome?: string }> {
     if ([...userQuestions.values()].some(pending => pending.question.sessionId === sessionId)) return { approved: false, outcome: 'busy', feedback: 'A question is already waiting for the user' };
     const say = wordsFor(session);
-    const result = await askUser(sessionId, session, undefined, body, [say.approve, say.reject]) as { contentItems: Array<{ text: string }> };
+    const result = await askUser(sessionId, session, undefined, body, [say.approve, say.reject], approval) as { contentItems: Array<{ text: string }> };
     let value: any;
     try { value = JSON.parse(result.contentItems[0].text); } catch { value = {}; }
     if (value.status !== 'answered') return { approved: false, outcome: value.status ?? 'canceled', ...(value.reason ? { feedback: value.reason } : {}) };
@@ -1489,18 +1513,25 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     return APPROVALS.includes(answer.toLowerCase()) ? { approved: true } : { approved: false, outcome: 'answered', feedback: answer };
   }
 
-  const declined = (decision: { feedback?: string; outcome?: string }) => toolResult(true, {
-    approved: false,
-    outcome: decision.outcome,
-    ...(decision.feedback ? { feedback: decision.feedback } : {}),
-    next: 'Nothing was saved or posted. Revise from the feedback and propose again, or drop it.',
-  });
-
   const text = (value: unknown, limit: number) => typeof value === 'string' && !!value.trim() && value.length <= limit;
 
+  // Approvals of alp_issue and alp_skill (#114, #116): the tool returns a pending id at once and the
+  // decision comes as result mail. Draft identities stay until session close, so a replayed tool
+  // call or turn never applies an approved draft twice. Interrupting a session cancels its approvals.
+  const approvalCancellation = new WeakMap<Session, number>();
+  const approvalLedger = new Map<string, Map<string, { approvalId: string; draftKey: string; result?: Record<string, unknown> }>>();
+  const approvalsOf = (sessionId: string) => {
+    let approvals = approvalLedger.get(sessionId);
+    if (!approvals) approvalLedger.set(sessionId, approvals = new Map());
+    return approvals;
+  };
+  const approvalCanceled = (session: Session, cancellation: number) => closed || session.closed || cancellation !== (approvalCancellation.get(session) ?? 0);
+
   async function skillTool(sessionId: string, session: Session, args: unknown) {
+    const cancellation = approvalCancellation.get(session) ?? 0;
+    args = structuredClone(args);
     if (
-      !plainObject(args, ['name', 'description', 'body', 'roles', 'lessons', 'replace']) ||
+      !plainObject(args, ['name', 'description', 'body', 'roles', 'lessons', 'replace', 'requestId']) ||
       typeof args.name !== 'string' || !/^[a-z0-9][a-z0-9-]{1,62}$/.test(args.name) ||
       !text(args.description, 300) || !text(args.body, SKILL_BODY_CHARS) ||
       !Array.isArray(args.roles) || !args.roles.length || args.roles.length > 10 || !args.roles.every((role: unknown) => typeof role === 'string' && /^[\w.-]+$/.test(role) && role !== '.' && role !== '..') ||
@@ -1509,14 +1540,25 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     ) {
       return toolResult(false, { error: `A skill needs a name (lowercase letters, digits, hyphens), a one-line description, a body of at most ${SKILL_BODY_CHARS} characters, and the roles that get it` });
     }
-    if (!options.libraryDir) return toolResult(false, { error: 'This host keeps no user skill library' });
-    const known = new Set([...STARTER_ROLES, ...await discoverAgents(session.mapping.agent.projectRoot, { library: options.libraryDir, templates: options.templates })]);
+    if (args.requestId !== undefined && !text(args.requestId, 100)) return toolResult(false, { error: 'requestId must be a nonempty string of at most 100 characters' });
+    const library = options.libraryDir;
+    if (!library) return toolResult(false, { error: 'This host keeps no user skill library' });
+    const known = new Set([...STARTER_ROLES, ...await discoverAgents(session.mapping.agent.projectRoot, { library, templates: options.templates })]);
     const unknown = args.roles.filter((role: string) => !known.has(role));
     if (unknown.length) return toolResult(false, { error: `Unknown roles: ${unknown.join(', ')}. Roles are ${[...known].join(', ')}` });
-    const file = path.join(options.libraryDir, 'skills', args.name, 'SKILL.md');
+    const file = path.join(library, 'skills', args.name, 'SKILL.md');
+    const content = `---\nname: ${args.name}\ndescription: ${JSON.stringify(args.description.replace(/\s+/g, ' ').trim())}\n---\n\n${args.body.trim()}\n`;
+    const lessons: string[] = (args.lessons ?? []).map((lesson: string) => lesson.replace(/\s+/g, ' ').trim());
+    // A replay of a proposed draft returns its approval, before anything it changed is checked again.
+    const draftKey = JSON.stringify(['skill', content, args.roles, lessons, !!args.replace]);
+    const key = `skill:${args.requestId ?? draftKey}`;
+    const approvals = approvalsOf(sessionId);
+    const previous = approvals.get(key);
+    if (previous && previous.draftKey !== draftKey) return toolResult(false, { error: 'requestId was already used for a different draft' });
+    if (previous) return toolResult(true, previous.result ?? { status: 'pending_approval', approvalId: previous.approvalId, file });
     const existing = await readFile(file, 'utf8').catch(() => undefined);
     if (existing !== undefined && !args.replace) return toolResult(false, { error: `The library already has a skill named ${args.name} (${file}); read it, then pass replace: true to propose a new version, or choose another name` });
-    const rolesFile = path.join(options.libraryDir, 'role-skills.json');
+    const rolesFile = path.join(library, 'role-skills.json');
     const readRoles = async () => {
       const raw = await readFile(rolesFile, 'utf8').catch(() => '{}');
       const roles = JSON.parse(raw);
@@ -1524,49 +1566,74 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       return roles as Record<string, unknown>;
     };
     try { await readRoles(); } catch (error) { return toolResult(false, { error: errorData(error).message }); }
-    const content = `---\nname: ${args.name}\ndescription: ${JSON.stringify(args.description.replace(/\s+/g, ' ').trim())}\n---\n\n${args.body.trim()}\n`;
-    const lessons: string[] = (args.lessons ?? []).map((lesson: string) => lesson.replace(/\s+/g, ' ').trim());
+    if (approvalCanceled(session, cancellation)) return toolResult(false, { error: 'Skill proposal canceled or session closed; no approval was created' });
+    if ([...userQuestions.values()].some(pending => pending.question.sessionId === sessionId)) return toolResult(false, { error: 'A question is already waiting for the user; finish it before proposing a skill' });
+    const approvalId = `q-${randomUUID()}`;
+    const record: { approvalId: string; draftKey: string; result?: Record<string, unknown> } = { approvalId, draftKey };
+    approvals.set(key, record);
     const say = wordsFor(session);
-    const decision = await confirm(sessionId, session,
+    // The user sees the whole skill, as it will be saved.
+    const decision = confirm(sessionId, session,
       say.skill(session.mapping.agent.name, existing !== undefined, file, args.roles.join(', '), lessons) +
-      `\n${say.answerLine(session.mapping.agent.name)}\n\n${content}`);
-    if (!decision.approved) return declined(decision);
-    try {
-      await mkdir(path.dirname(file), { recursive: true });
-      await writeFile(file, content);
-      const roles = await readRoles();
-      for (const role of args.roles) {
-        const list = Array.isArray(roles[role]) ? roles[role] as string[] : [];
-        if (!list.includes(args.name)) list.push(args.name);
-        roles[role] = list;
-      }
-      await writeFile(rolesFile, JSON.stringify(roles, null, 2) + '\n');
-    } catch (error) {
-      return toolResult(false, { error: errorData(error).message });
-    }
-    // The lessons the skill replaces leave both files; a lesson matches only by its exact text.
-    const removed = new Set<string>();
-    for (const lessonFile of lessonFiles(session.mapping)) {
-      const current = await readFile(lessonFile, 'utf8').catch(() => undefined);
-      if (current === undefined) continue;
-      const kept = current.split('\n').filter(line => {
-        const match = /^- \d{4}-\d\d-\d\d: (.*)$/.exec(line);
-        if (!match || !lessons.includes(match[1].trim())) return true;
-        removed.add(match[1].trim());
-        return false;
-      });
-      if (kept.length !== current.split('\n').length) await writeFile(lessonFile, kept.join('\n')).catch(() => {});
-    }
-    runLog(rootOf(sessionId), { event: 'skill', agent: session.mapping.agent.name, name: args.name, roles: args.roles, replaced: existing !== undefined, lessons: [...removed] });
-    return toolResult(true, {
-      approved: true, saved: file, roles: args.roles, lessonsRemoved: [...removed],
-      ...(lessons.length > removed.size ? { lessonsNotFound: lessons.filter(lesson => !removed.has(lesson)) } : {}),
-      next: 'New sessions of those roles list the skill; read the file now if you need it in this one.',
-    });
+      `\n${say.answerLine(session.mapping.agent.name)}\n\n${content}`, { id: approvalId });
+    const save = async (): Promise<Record<string, unknown>> => {
+      // A skill of this name saved meanwhile is not overwritten by a proposal that was not a replacement.
+      if (existing === undefined && !args.replace && await readFile(file, 'utf8').then(() => true, () => false)) {
+        return { approved: true, saved: false, error: `A skill named ${args.name} was saved meanwhile (${file}); nothing was overwritten`, next: 'Read it, then propose again with replace: true if yours should replace it.' };
+      }
+      try {
+        await mkdir(path.dirname(file), { recursive: true });
+        await writeFile(file, content);
+        const roles = await readRoles();
+        for (const role of args.roles) {
+          const list = Array.isArray(roles[role]) ? roles[role] as string[] : [];
+          if (!list.includes(args.name)) list.push(args.name);
+          roles[role] = list;
+        }
+        await writeFile(rolesFile, JSON.stringify(roles, null, 2) + '\n');
+      } catch (error) {
+        return { approved: true, saved: false, error: errorData(error).message, next: 'Tell the user; nothing is retried automatically.' };
+      }
+      // The lessons the skill replaces leave both files; a lesson matches only by its exact text.
+      const removed = new Set<string>();
+      for (const lessonFile of lessonFiles(session.mapping)) {
+        const current = await readFile(lessonFile, 'utf8').catch(() => undefined);
+        if (current === undefined) continue;
+        const kept = current.split('\n').filter(line => {
+          const match = /^- \d{4}-\d\d-\d\d: (.*)$/.exec(line);
+          if (!match || !lessons.includes(match[1].trim())) return true;
+          removed.add(match[1].trim());
+          return false;
+        });
+        if (kept.length !== current.split('\n').length) await writeFile(lessonFile, kept.join('\n')).catch(() => {});
+      }
+      runLog(rootOf(sessionId), { event: 'skill', agent: session.mapping.agent.name, name: args.name, roles: args.roles, replaced: existing !== undefined, lessons: [...removed] });
+      return {
+        approved: true, saved: file, roles: args.roles, lessonsRemoved: [...removed],
+        ...(lessons.length > removed.size ? { lessonsNotFound: lessons.filter(lesson => !removed.has(lesson)) } : {}),
+        next: 'New sessions of those roles list the skill; read the file now if you need it in this one.',
+      };
+    };
+    void (async () => {
+      const answer = await decision;
+      const canceled = approvalCanceled(session, cancellation);
+      const result = !answer.approved || canceled
+        ? { approved: false, saved: false, outcome: canceled ? 'canceled' : answer.outcome, ...(answer.feedback ? { feedback: answer.feedback } : {}), next: 'Nothing was saved. Revise from the feedback and propose again with a fresh requestId, or drop it.' }
+        : await save();
+      record.result = { status: 'resolved', approvalId, name: args.name, ...result };
+      runLog(rootOf(sessionId), { event: 'skill.approval', agent: session.mapping.agent.name, ...record.result });
+      if (!closed && !session.closed && sessions.get(sessionId) === session) {
+        // Result mail renews the bounded wake allowance and reaches this main only.
+        post(sessionId, { kind: 'result', from: 'ALP', assignment: approvalId, body: `Skill approval result: ${JSON.stringify(record.result)}` });
+      }
+    })();
+    return toolResult(true, { status: 'pending_approval', approvalId, file, next: 'Continue other work or end your turn. ALP sends the user\'s decision, and whether the skill was saved, by mail; do not resubmit this draft.' });
   }
 
   async function issueTool(sessionId: string, session: Session, args: unknown) {
-    if (!plainObject(args, ['action', 'target', 'query', 'title', 'body', 'issue', 'labels']) || !['search', 'create', 'comment'].includes(args.action) || !['project', 'alp'].includes(args.target)) {
+    const cancellation = approvalCancellation.get(session) ?? 0;
+    args = structuredClone(args);
+    if (!plainObject(args, ['action', 'target', 'query', 'title', 'body', 'issue', 'labels', 'requestId']) || !['search', 'create', 'comment'].includes(args.action) || !['project', 'alp'].includes(args.target)) {
       return toolResult(false, { error: 'An issue call needs action (search, create or comment) and target (project or alp)' });
     }
     const project = session.mapping.agent.projectRoot;
@@ -1589,6 +1656,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     if (args.labels !== undefined && (args.action !== 'create' || !Array.isArray(args.labels) || args.labels.length > 10 || !args.labels.every((label: unknown) => text(label, 50)))) {
       return toolResult(false, { error: 'labels are up to 10 existing label names, for create' });
     }
+    if (args.requestId !== undefined && !text(args.requestId, 100)) return toolResult(false, { error: 'requestId must be a nonempty string of at most 100 characters' });
     // Resolve labels before approval, so a draft with an unknown label never
     // consumes the user's approval and then fails during issue creation.
     if (args.action === 'create' && args.labels?.length) {
@@ -1601,24 +1669,48 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
         return toolResult(false, { repo, error: `Could not validate issue labels: ${errorData(error).message}` });
       }
     }
+    if (approvalCanceled(session, cancellation)) return toolResult(false, { error: 'Issue proposal canceled or session closed; no approval was created' });
+    const draftKey = JSON.stringify([repo, args.action, args.title ?? null, args.issue ?? null, args.body, [...(args.labels ?? [])].sort()]);
+    const key = `issue:${args.requestId ?? draftKey}`;
+    const approvals = approvalsOf(sessionId);
+    const previous = approvals.get(key);
+    if (previous && previous.draftKey !== draftKey) return toolResult(false, { error: 'requestId was already used for a different draft' });
+    if (previous) return toolResult(true, previous.result ?? { status: 'pending_approval', approvalId: previous.approvalId, repo });
+    if ([...userQuestions.values()].some(pending => pending.question.sessionId === sessionId)) return toolResult(false, { error: 'A question is already waiting for the user; finish it before proposing another issue draft' });
+    const approvalId = `q-${randomUUID()}`;
+    const record: { approvalId: string; draftKey: string; result?: Record<string, unknown> } = { approvalId, draftKey };
+    approvals.set(key, record);
     const where = `${repo}${args.target === 'alp' ? ' (ALP itself)' : ''}`;
     const say = wordsFor(session);
-    const decision = await confirm(sessionId, session,
+    const decision = confirm(sessionId, session,
       say.issue(session.mapping.agent.name, args.action === 'create', args.issue, where) + '\n' +
       `${say.answerLine(session.mapping.agent.name)}\n\n` +
-      (args.action === 'create' ? `${say.issueTitle}: ${args.title}\n${args.labels?.length ? `${say.issueLabels}: ${args.labels.join(', ')}\n` : ''}\n` : '') + args.body);
-    if (!decision.approved) return declined(decision);
-    const body = args.body.trim() + ISSUE_FOOTER;
-    try {
-      const output = args.action === 'create'
-        ? await github(['issue', 'create', '-R', repo, '--title', args.title, '--body-file', '-', ...(args.labels ?? []).flatMap((label: string) => ['--label', label])], { cwd: project, input: body })
-        : await github(['issue', 'comment', String(args.issue), '-R', repo, '--body-file', '-'], { cwd: project, input: body });
-      const url = output.trim().split('\n').at(-1) ?? '';
-      runLog(rootOf(sessionId), { event: 'issue', action: args.action, repo, ...(args.title ? { title: args.title } : {}), ...(args.issue ? { issue: args.issue } : {}), url });
-      return toolResult(true, { approved: true, posted: true, repo, url });
-    } catch (error) {
-      return toolResult(false, { approved: true, posted: false, repo, error: errorData(error).message, next: 'Tell the user; the GitHub CLI may need `gh auth login`.' });
-    }
+      (args.action === 'create' ? `${say.issueTitle}: ${args.title}\n${args.labels?.length ? `${say.issueLabels}: ${args.labels.join(', ')}\n` : ''}\n` : '') + args.body.trim() + ISSUE_FOOTER, { id: approvalId });
+    void (async () => {
+      const answer = await decision;
+      let result: Record<string, unknown>;
+      const canceled = approvalCanceled(session, cancellation);
+      if (!answer.approved || canceled) {
+        result = { approved: false, posted: false, outcome: canceled ? 'canceled' : answer.outcome, ...(answer.feedback ? { feedback: answer.feedback } : {}) };
+      } else {
+        try {
+          const body = args.body.trim() + ISSUE_FOOTER;
+          const output = args.action === 'create'
+            ? await github(['issue', 'create', '-R', repo, '--title', args.title, '--body-file', '-', ...(args.labels ?? []).flatMap((label: string) => ['--label', label])], { cwd: project, input: body })
+            : await github(['issue', 'comment', String(args.issue), '-R', repo, '--body-file', '-'], { cwd: project, input: body });
+          result = { approved: true, posted: true, url: output.trim().split('\n').at(-1) ?? '' };
+        } catch (error) {
+          result = { approved: true, posted: false, error: errorData(error).message, next: 'Tell the user; do not retry this draft automatically: GitHub may have accepted it before reporting an error.' };
+        }
+      }
+      record.result = { status: 'resolved', approvalId, repo, ...result };
+      runLog(rootOf(sessionId), { event: 'issue.approval', action: args.action, ...(args.title ? { title: args.title } : {}), ...(args.issue ? { issue: args.issue } : {}), ...record.result });
+      if (!closed && !session.closed && sessions.get(sessionId) === session) {
+        // Result mail renews the bounded wake allowance and reaches this main only.
+        post(sessionId, { kind: 'result', from: 'ALP', assignment: approvalId, body: `Issue approval result: ${JSON.stringify(record.result)}` });
+      }
+    })();
+    return toolResult(true, { status: 'pending_approval', approvalId, repo, next: 'Continue other work. ALP sends the decision and posting result by mail; do not resubmit this draft.' });
   }
 
   /** Activity anywhere in a subtree keeps its ancestors' assignments alive. */
@@ -1645,6 +1737,10 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     if (session && !session.closed) {
       emit(sessionId, { type: 'mail', mail: publicEvent(mail) });
       session.mail.push(mail);
+      // New assignment progress deserves a fresh delivery allowance. Reset here,
+      // never on redelivery, so a failing turn cannot retry the same mail forever.
+      if (mail.kind === 'result' || mail.kind === 'question') session.wakes = 0;
+      if (mail.kind === 'result' || mail.kind === 'question' || mail.kind === 'checkin') session.wakeFailures = 0;
       deliver(sessionId, session);
     }
     return mail;
@@ -1673,7 +1769,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       if (session.mail.some(event => !event.deliveredTurn && !event.passive && !event.defer)) void steerMail(sessionId, session);
     } else if (!waking) {
       return;
-    } else if (!session.wakeBlocked && session.wakes < MAX_WAKES) {
+    } else if (!session.wakeBlocked && session.wakeFailures < MAX_WAKES && (session.wakes < MAX_WAKES || session.mail.some(event => !event.deliveredTurn && event.kind === 'checkin'))) {
       autoWake(sessionId, session);
     } else if (session.parent && !session.wakeBlocked && !held(session)) {
       // A child never gets the user prompt that resets its wakes; report instead of waiting out the watchdog.
@@ -1711,6 +1807,9 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
   function autoWake(sessionId: string, session: Session) {
     // Its runtime is paused or it is parked: the mail waits for resume.
     if (held(session)) { session.wakeHeld = true; return; }
+    // A check-in authorizes delivery of older mail too: the capped first batch
+    // may not reach the check-in itself. Keep that authorization through queuing.
+    const checkIn = session.mail.find(event => !event.deliveredTurn && event.kind === 'checkin');
     const batch = takeBatch(session.mail, () => true);
     if (!batch.length) return;
     for (const event of batch) event.deliveredTurn = STARTING;
@@ -1724,11 +1823,15 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
         release();
         return deliver(sessionId, session);
       }
+      // Earlier queued attempts may have consumed the allowance since delivery
+      // reserved this batch. Keep retries bounded at the actual start boundary.
+      if (session.wakeFailures >= MAX_WAKES || (session.wakes >= MAX_WAKES && (!checkIn || !session.mail.includes(checkIn)))) return release();
       if (!batch.every(event => event.kind === 'checkin')) session.wakes++;
       const id = `alp-wake-${randomUUID()}`;
       try {
         await startPrompt(sessionId, { clientMessageId: id, delivery: 'auto', content: [{ type: 'text', text: renderMail(batch, session.parentAgent) }] }, 'wake', batch);
       } catch {
+        session.wakeFailures++;
         release();
         deliver(sessionId, session);
       }
@@ -1842,6 +1945,21 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     }
   }
 
+  /**
+   * The user wrote in the chat while main's own alp_ask question to them waits (#116): the question
+   * ends now, so the message reaches main. Approvals, permission prompts and the hook-trust
+   * question keep waiting for the user's decision.
+   */
+  function releaseQuestions(sessionId: string) {
+    for (const { question, settle, asked } of [...userQuestions.values()]) {
+      if (question.sessionId !== sessionId || !asked) continue;
+      settle('canceled', undefined, 'the user wrote instead of answering', toolResult(true, {
+        status: 'user_wrote', userMessage: true, question: question.id,
+        next: `${USER_WROTE} Their message may be the answer to your question; if it is not, ask again later.`,
+      }));
+    }
+  }
+
   const assignmentSnapshot = (assignment: Assignment, status: string): AssignmentSnapshot => ({
     id: assignment.id,
     agent: assignment.agent,
@@ -2107,7 +2225,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     const pending = [...session.assignments.keys()].some(id => !ids || ids.has(id)) || takeBatch(session.mail, event => event.kind !== 'board' && !event.defer && accept(event)).length > 0;
     const events = pending ? await waitFor(sessionId, session, accept, Math.min(args.timeoutMs ?? 300_000, 900_000)) : [];
     if (events === 'user') return toolResult(true, { events: [], userMessage: true, running: running(session), next: USER_WROTE });
-    if (!events) return toolResult(false, { error: 'Turn ended' });
+    if (!events) return toolResult(false, session.closed || session.wakeBlocked ? { error: 'Turn ended' } : { error: TURN_ENDED, running: running(session) });
     return toolResult(true, { events: events.map(publicEvent), running: running(session) });
   }
 
@@ -2149,10 +2267,10 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
   }
 
   /** Asks the user; viewers show the question, and answer() or a timeout resolves it. */
-  function askUser(sessionId: string, session: Session, assignment: Assignment | undefined, body: string, options?: string[]) {
+  function askUser(sessionId: string, session: Session, assignment: Assignment | undefined, body: string, options?: string[], approval?: { id: string }, asked = false) {
     const rootId = rootOf(sessionId);
     const question: UserQuestion = {
-      id: `q-${randomUUID().slice(0, 8)}`,
+      id: approval?.id ?? `q-${randomUUID().slice(0, 8)}`,
       sessionId,
       rootId,
       agent: session.mapping.agent.name,
@@ -2180,7 +2298,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
             next: 'Decide, and record the assumption in your handoff or final message; or report that you are blocked.',
           })));
       };
-      userQuestions.set(question.id, { question, settle });
+      userQuestions.set(question.id, { question, settle, persistent: !!approval, asked });
       // The watchdog does not count time spent waiting for an answer.
       if (assignment) assignment.ask = { id: question.id, resolve: result => settle('canceled', undefined, undefined, result) };
       emit(sessionId, { type: 'question', question });
@@ -2198,10 +2316,10 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     post(session.parent, { kind: 'note', from: session.mapping.agent.name, assignment: sessionId, body: `[ALP, on behalf of ${session.mapping.agent.name}] ${body}` });
   }
 
-  /** Questions to the user end with the turn or session that asked them. */
-  function cancelQuestions(sessionId: string) {
-    for (const { question, settle } of [...userQuestions.values()]) {
-      if (question.sessionId === sessionId) settle('canceled', undefined, undefined, toolResult(false, { error: 'Turn ended' }));
+  /** Ordinary questions end with their turn; issue approvals survive until decision or session cancellation. */
+  function cancelQuestions(sessionId: string, turnOnly = false) {
+    for (const { question, settle, persistent } of [...userQuestions.values()]) {
+      if (question.sessionId === sessionId && (!turnOnly || !persistent)) settle('canceled', undefined, undefined, toolResult(false, { error: 'Turn ended' }));
     }
   }
 
@@ -2223,7 +2341,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     if (to === 'user' && session.parent && !session.userOpened) {
       return Promise.resolve(toolResult(false, { error: `Only main talks to the user; ask ${session.parentAgent ?? 'your requester'} with alp_ask instead` }));
     }
-    if (to === 'user') return askUser(sessionId, session, assignment, args.question, args.options);
+    if (to === 'user') return askUser(sessionId, session, assignment, args.question, args.options, undefined, true);
     if (!session.parent || !parent || !assignment) return Promise.resolve(toolResult(false, { error: 'This session has no requester; ask the user with to: "user"' }));
     const parentId = session.parent;
     return new Promise<unknown>(resolve => {
@@ -2415,9 +2533,11 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     const rootId = rootOf(sessionId);
     const root = sessions.get(rootId)!;
 
-    if (root.calls >= 16) {
+    const advisor = ['advisor', 'reviewer'].includes(roleOf(session.mapping, args.agent) ?? '') && childMode === 'read-only';
+    const budget = advisor ? 'advisorCalls' : 'calls';
+    if (root[budget] >= 16) {
       return toolResult(false, {
-        error: 'Delegation limit reached for this turn',
+        error: `${advisor ? 'Advisor' : 'Implementation'} delegation budget exhausted (16 starts across the root session tree since its last new user turn). Mail wakes and child turns do not reset it; a new accepted user prompt in root (including steering) resets both budgets.`,
       });
     }
 
@@ -2432,7 +2552,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     const continued = args.continueFrom !== undefined ? session.worktrees.get(args.continueFrom) : undefined;
     if (args.continueFrom !== undefined && !continued && !sharedContinuation) return toolResult(false, { error: `${args.continueFrom} was merged or discarded meanwhile` });
     if (continued) session.worktrees.delete(args.continueFrom);
-    root.calls++;
+    root[budget]++;
     if (peer) root.peerCount++;
 
     const childId = `alp-child-${randomUUID()}`;
@@ -2598,12 +2718,16 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     if (events === 'user') return toolResult(true, { assignmentId: childId, agent: args.agent, status: 'running', userMessage: true, next: USER_WROTE });
 
     if (!events) {
-      return toolResult(false, {
-        agent: args.agent,
-        assignmentId: childId,
-        status: 'canceled',
-        error: 'Parent assignment stopped',
-      });
+      // Only the user's stop or a closing session ends the assignment with the wait (#116).
+      if (session.closed || session.wakeBlocked || !session.assignments.has(childId)) {
+        return toolResult(false, {
+          agent: args.agent,
+          assignmentId: childId,
+          status: 'canceled',
+          error: 'Parent assignment stopped',
+        });
+      }
+      return toolResult(false, { agent: args.agent, assignmentId: childId, status: 'running', error: TURN_ENDED });
     }
 
     // A result that came with a check-in makes the check-in moot.
@@ -2702,10 +2826,12 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       peerCount: 0,
       assignments: new Map(),
       calls: 0,
+      advisorCalls: 0,
       mail: [],
       waiters: [],
       lastActivity: Date.now(),
       wakes: 0,
+      wakeFailures: 0,
       wakeBlocked: false,
 
       toolCalls: new Map(),
@@ -3054,7 +3180,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
    * root first, since each assignment needs its requester open. Each one continues
    * its turn, or waits parked when its runtime is paused or the user resumes recovery.
    */
-  async function recoverTree(rootId: string, continueRoot: boolean): Promise<RecoveryOutcome[]> {
+  async function recoverTree(rootId: string, continueRoot: boolean, parkedRoot?: string): Promise<RecoveryOutcome[]> {
     const root = sessions.get(rootId);
     if (!root || root.closed) throw new Error(`Session ${rootId} is not open`);
     const entries = inherited.filter(entry => entry.rootId === rootId).sort((a, b) => a.ancestry.length - b.ancestry.length);
@@ -3094,7 +3220,11 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       runLog(rootId, { event: 'assignment.recovered', assignmentId: entry.assignmentId, agent: entry.agent, ...(entry.taskId ? { taskId: entry.taskId } : {}) });
       proceed(entry.assignmentId, child, `ALP: ${cause} while you worked on this assignment, and reopened this session. Your earlier work in it${entry.worktree ? ' and your worktree' : ''} is intact; check where you stopped (for example with git status), then continue. Finish with alp_handoff as before.${listed(resumed.get(entry.assignmentId))}`);
     }
-    if (continueRoot) proceed(rootId, root, `ALP: ${cause} during your turn, and reopened this session. Continue the user's request where you stopped.${listed(resumed.get(rootId))}`);
+    if (parkedRoot) {
+      root.parked = { reason: parkedRoot, since: Date.now() };
+      emit(rootId, { type: 'session.updated', session: snapshot(rootId, root) });
+      if (options.autoResume !== false && options.recoveryResume !== false && !pauseOf(root.runtimeKind)) continueParked(rootId, root);
+    } else if (continueRoot) proceed(rootId, root, `ALP: ${cause} during your turn, and reopened this session. Continue the user's request where you stopped.${listed(resumed.get(rootId))}`);
     else for (const assignment of resumed.get(rootId) ?? []) post(rootId, { kind: 'note', from: assignment.agent, assignment: assignment.id, passive: true, body: `${cause}; ALP reopened this assignment and it continues. It reports when done.` });
     const failed = outcomes.filter(outcome => outcome.outcome === 'failed');
     if (entries.length || continueRoot) {
@@ -3154,6 +3284,11 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
 
     session.wakeBlocked = true;
     session.userStopped = true;
+    session.parked = undefined;
+    session.parkReason = undefined;
+    emit(sessionId, { type: 'session.updated', session: snapshot(sessionId, session) });
+    approvalCancellation.set(session, (approvalCancellation.get(session) ?? 0) + 1);
+    cancelQuestions(sessionId);
     // Codex keeps no output of an interrupted turn in its thread: remember what the user saw, by
     // thread, since a client that leaves closes the session and the next prompt opens it again.
     if (activeTurn && session.runtimeKind === 'codex' && session.threadId) {
@@ -3264,12 +3399,9 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       if (!wake) {
         session.handoff = undefined;
         session.wakes = 0;
+        session.wakeFailures = 0;
         session.wakeBlocked = false;
         session.userStopped = false;
-
-        if (!session.parent) {
-          session.calls = 0;
-        }
       }
     }
 
@@ -3335,6 +3467,12 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
 
       for (const event of mail) event.deliveredTurn = turnId;
 
+      // Only transport-accepted user input renews the root-tree budgets.
+      if (!session.parent && origin === 'user') {
+        session.calls = 0;
+        session.advisorCalls = 0;
+      }
+
       session.seen.add(
         prompt.clientMessageId,
       );
@@ -3352,7 +3490,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       if (origin === 'user' && !session.parent) session.userWaiting ??= Date.now();
       if (session.supervisor && origin === 'user') session.journal.push(stamp(`user ${prompt.delivery === 'steer' ? 'steered' : 'asked'} ${session.mapping.agent.name}: ${clip(text, 1500)}`));
       // The steer reaches the model once its waiting tool returns; return it now, not when the work ends.
-      if (prompt.delivery === 'steer' && origin === 'user' && !session.parent) releaseWaiters(session);
+      if (prompt.delivery === 'steer' && origin === 'user' && !session.parent) { releaseWaiters(session); releaseQuestions(sessionId); }
 
       emit(sessionId, {
         type: 'prompt.accepted',
@@ -3411,8 +3549,16 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     }),
 
     prompt: (sessionId, input) => enqueue(async () => {
+      const session = sessions.get(sessionId);
+      const parked = session?.parked;
       try {
-        await startPrompt(sessionId, input, 'user');
+        const prompt = session?.active && session.resumedTurn === session.active && input.delivery === 'auto'
+          ? { ...input, delivery: 'steer' as const } : input;
+        await startPrompt(sessionId, prompt, 'user');
+        if (session && parked && session.parked === parked) {
+          session.parked = undefined;
+          emit(sessionId, { type: 'session.updated', session: snapshot(sessionId, session) });
+        }
       } catch (error) {
         const session = sessions.get(sessionId);
         if (session?.seen.has(input.clientMessageId)) return;
@@ -3578,8 +3724,8 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       return [...inherited];
     },
 
-    recover(rootId, { continueRoot = false } = {}) {
-      return enqueue(() => recoverTree(rootId, continueRoot));
+    recover(rootId, { continueRoot = false, parkedRoot } = {}) {
+      return enqueue(() => recoverTree(rootId, continueRoot, parkedRoot));
     },
 
     async abandon(rootId, reason) {