ftown 0.26.0 → 0.28.0

package/dist/local-api-server.js

@@ -15,18 +15,28 @@ import { MailDeliveryService, sanitizeMessageText, parseNativeWakeRegistration,
 import { AUTOMATION_REMOVED_CODE, AUTOMATION_REMOVED_MESSAGE, isRetiredAutomationSession } from './retired-automation.js';
 import { SessionController } from './session-controller.js';
 import { registerSessionConversation, resolveSessionIdByConversation, resolveSessionIdFromHookPayload, } from './session-registry.js';
-import { canResumeStoredSession, createFtownSession, deriveRelaunchCommand, parseCreateSessionBody, ProviderAuthMissingError, WorkingDirMissingError, } from './create-ftown-session.js';
+import { canResumeStoredSession, createFtownSession, deriveRelaunchCommand, parseCreateSessionBody, PlanItemError, ProviderAuthMissingError, WorkingDirMissingError, } from './create-ftown-session.js';
 import { removeFtownSession } from './remove-ftown-session.js';
 import { collectSessionUsage } from './usage-collector.js';
 import { toWireSession } from './session-wire.js';
 import { CardValidationError } from './coordination/contract.js';
+import { PARENT_UNAVAILABLE_NOTE, RouteError, WorktreeError, } from './coordination/contract-b.js';
+import { decideRoute, deliverAttentionAnswer, formatParentQuestionMail, markArchivedWorktreeRetained, } from './coordination/attention-routing.js';
+import { handleBriefRoutes } from './coordination/routes-brief.js';
+import { createPlanRoutes } from './coordination/routes-plan.js';
+import { createWorktreeRoutes } from './coordination/routes-worktrees.js';
 import { createCoordination, rootOf } from './coordination/wiring.js';
+import { GitWorktrees } from './worktrees.js';
 function jsonResponse(res, status, data) {
     res.writeHead(status, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify(data));
 }
 class BadRequestError extends Error {
 }
+/** PLAN_ROUTES paths: /api/sessions/:id/plan and /api/sessions/:id/plan/:itemId. */
+function isPlanRoutePath(path) {
+    return /^\/api\/sessions\/[^/]+\/plan(?:\/[^/]+)?$/.test(path);
+}
 /**
  * A blocked provider create/revive (mapped flavor with no machine token anywhere)
  * is a client-fixable 422, not a 500. The body carries the provider, the
@@ -254,8 +264,10 @@ export class LocalApiServer extends EventEmitter {
         });
         await this.security.revalidate(message.principal);
         void this.handleApiRoute(request, response, new URL(route.path, 'http://localhost').pathname, new URL(route.path, 'http://localhost')).catch(error => {
-            if (error instanceof BadRequestError)
+            if (error instanceof BadRequestError || error instanceof WorktreeError || error instanceof PlanItemError)
                 jsonResponse(response, 400, { error: error.message });
+            else if (error instanceof RouteError)
+                jsonResponse(response, error.status, { error: error.message });
             else if (error instanceof AttentionError)
                 jsonResponse(response, error.status, { error: error.message, code: error.code });
             else
@@ -269,10 +281,32 @@ export class LocalApiServer extends EventEmitter {
     coordination = null;
     defaultCoordination = null;
     mailStore = null;
+    attentionPushHandler;
+    /** In-flight parent-routed creates. Pushes are held, then dropped only for that item id. */
+    parentPushAttempt = 0;
+    parentPushAttempts = new Map();
+    heldAttentionPushes = [];
     recoveryEpoch = 0;
     recoveryStartedAt = -1;
     recoveryStopped = false;
     runnerReadyListener = null;
+    worktreeRoutes = createWorktreeRoutes({
+        listLive: async () => (this.store ? this.store.listSessions() : []),
+        listArchived: async () => this.store
+            ? (await this.store.listArchived()).map((record) => {
+                const sanitized = { ...record };
+                delete sanitized.env;
+                delete sanitized.previewSource;
+                return sanitized;
+            })
+            : [],
+        worktrees: new GitWorktrees(),
+        markRetained: async (sessionId, reason) => {
+            if (!this.store)
+                return;
+            await markArchivedWorktreeRetained((id) => this.store.sessionDir(id), sessionId, reason);
+        },
+    });
     setBrowserAccess(access) {
         this.browserAccess = access;
     }
@@ -282,6 +316,311 @@ export class LocalApiServer extends EventEmitter {
     setAttentionStore(store) {
         this.attention = store;
         this.defaultCoordination = null;
+        // onNotification is a private constructor parameter. It is still an own
+        // instance property at runtime; the cast is the only way to wrap it.
+        const internal = store;
+        const original = internal.onNotification;
+        this.attentionPushHandler = original;
+        if (original) {
+            internal.onNotification = (sessionId, notice) => {
+                const attempts = this.parentPushAttempts.get(sessionId);
+                if (attempts && attempts.size > 0) {
+                    this.heldAttentionPushes.push({
+                        sessionId,
+                        notice,
+                        owners: new Set(attempts),
+                        dropped: false,
+                    });
+                    return;
+                }
+                original(sessionId, notice);
+            };
+        }
+    }
+    /** Dashboard notice + push for an item that is reaching the human now. */
+    publishHumanAttention(sessionId, item) {
+        if (item.type === 'ask_user' || item.prompt?.channel === 'hook') {
+            this.emit('event', {
+                sessionId,
+                eventName: 'PreToolUse',
+                source: 'api',
+                data: {
+                    hook_event_name: 'PreToolUse',
+                    attentionId: item.id,
+                    attentionSequence: item.sequence,
+                    attentionCreatedAt: item.createdAt,
+                    ...(item.prompt ? { attentionPrompt: item.prompt } : {}),
+                },
+            });
+        }
+        else {
+            this.emit('event', {
+                sessionId,
+                eventName: 'Notification',
+                source: 'api',
+                data: {
+                    notification_type: 'agent_needs_input',
+                    title: item.title,
+                    message: item.message,
+                    notification_id: item.id,
+                    attentionId: item.id,
+                    attentionSequence: item.sequence,
+                    attentionCreatedAt: item.createdAt,
+                    ...(item.prompt ? { attentionPrompt: item.prompt } : {}),
+                },
+            });
+        }
+        try {
+            this.attentionPushHandler?.(sessionId, {
+                kind: 'question',
+                eventKey: `question:${item.id}`,
+                title: item.title,
+                message: item.message,
+                occurredAt: item.escalatedAt ?? item.createdAt,
+            });
+        }
+        catch {
+            // Optional push delivery cannot fail escalation.
+        }
+    }
+    readCallerSessionId(req) {
+        const callerHeader = req.headers['x-ftown-session-id'];
+        return typeof callerHeader === 'string' && callerHeader.trim()
+            ? callerHeader.trim()
+            : undefined;
+    }
+    readAttentionTarget(body) {
+        if (!Object.prototype.hasOwnProperty.call(body, 'to'))
+            return undefined;
+        if (body.to === 'human')
+            return 'human';
+        throw new BadRequestError("Invalid attention target");
+    }
+    async resolveAttentionRouting(child, to) {
+        if (!this.store || !child.parentSessionId) {
+            return { route: 'human', parent: null };
+        }
+        const parent = await this.store.loadSession(child.parentSessionId);
+        const parentRunning = !!parent &&
+            (typeof this.runner?.isRunning === 'function'
+                ? this.runner.isRunning(parent.id)
+                : parent.status === 'running');
+        const route = decideRoute(child, parent, parentRunning, to);
+        return { route, parent };
+    }
+    /** Hold pushes for this session until the created item id is known. */
+    beginParentPushHold(sessionId) {
+        const attempt = ++this.parentPushAttempt;
+        let attempts = this.parentPushAttempts.get(sessionId);
+        if (!attempts) {
+            attempts = new Set();
+            this.parentPushAttempts.set(sessionId, attempts);
+        }
+        attempts.add(attempt);
+        return attempt;
+    }
+    /** Drop only `question:<suppressItemId>`. Every other held notice is delivered. */
+    finishParentPushHold(sessionId, attempt, suppressItemId) {
+        const attempts = this.parentPushAttempts.get(sessionId);
+        attempts?.delete(attempt);
+        if (attempts && attempts.size === 0)
+            this.parentPushAttempts.delete(sessionId);
+        const suppressKey = suppressItemId ? `question:${suppressItemId}` : undefined;
+        for (let index = this.heldAttentionPushes.length - 1; index >= 0; index--) {
+            const held = this.heldAttentionPushes[index];
+            if (!held.owners.has(attempt))
+                continue;
+            held.owners.delete(attempt);
+            if (suppressKey && held.notice.eventKey === suppressKey)
+                held.dropped = true;
+            if (held.owners.size === 0) {
+                this.heldAttentionPushes.splice(index, 1);
+                if (!held.dropped) {
+                    try {
+                        this.attentionPushHandler?.(held.sessionId, held.notice);
+                    }
+                    catch { /* Optional push delivery cannot fail the request. */ }
+                }
+            }
+        }
+    }
+    /** Apply a parent route only when the item was just created. Repeats keep their stored route. */
+    async applyParentRoute(session, item, created, route, parent) {
+        if (created && route === 'parent' && parent && this.attention) {
+            const routed = await this.attention.setRoute(session.id, item.id, {
+                route: 'parent',
+                routedTo: parent.id,
+            });
+            if (!routed)
+                return { item, skipNotice: false };
+            const fallback = await this.sendParentQuestionMail(session, parent, routed);
+            // The create push is the parent's to swallow. A mail failure publishes its own.
+            return { item: fallback ?? routed, skipNotice: true, suppressPushId: item.id };
+        }
+        if (!created && item.route === 'parent')
+            return { item, skipNotice: true };
+        return { item, skipNotice: false };
+    }
+    /** Mail the parent. On failure, route the item to the human and publish now. Returns that item. */
+    async sendParentQuestionMail(child, parent, item) {
+        let failed = false;
+        try {
+            const accepted = await this.acceptSessionMail(parent, {
+                from: child.id,
+                fromName: child.name,
+                type: 'escalation',
+                threadId: item.id,
+                body: formatParentQuestionMail(child, item),
+            });
+            if (!accepted.ok) {
+                console.error('[Bridge] Failed to mail parent question:', accepted.error);
+                failed = true;
+            }
+        }
+        catch (err) {
+            console.error('[Bridge] Failed to mail parent question:', err instanceof Error ? err.message : err);
+            failed = true;
+        }
+        if (!failed || !this.attention)
+            return undefined;
+        const updated = await this.attention.setRoute(child.id, item.id, {
+            route: 'human',
+            escalatedAt: new Date().toISOString(),
+            escalationNote: PARENT_UNAVAILABLE_NOTE,
+        }, 'parent');
+        if (updated && !updated.resolvedAt && updated.route === 'human') {
+            this.publishHumanAttention(child.id, updated);
+            return updated;
+        }
+        try {
+            return await this.attention.waitForItem(child.id, item.id, 0);
+        }
+        catch {
+            return item;
+        }
+    }
+    /** Caller must be the child's parent. Returns the parent session, or null after writing 403. */
+    async loadParentCaller(req, res, child) {
+        const caller = this.readCallerSessionId(req);
+        if (!this.store || !child.parentSessionId || caller !== child.parentSessionId) {
+            jsonResponse(res, 403, { error: 'Only the parent session can do this', code: 'forbidden' });
+            return null;
+        }
+        const parent = await this.store.loadSession(child.parentSessionId);
+        if (!parent || parent.id !== child.parentSessionId) {
+            jsonResponse(res, 403, { error: 'Only the parent session can do this', code: 'forbidden' });
+            return null;
+        }
+        return parent;
+    }
+    async dispatchCoordinationRoutes(req, res, path, url) {
+        if (!this.store)
+            return false;
+        const store = this.store;
+        let responded = false;
+        const ctx = {
+            req,
+            res,
+            method: req.method ?? 'GET',
+            path,
+            query: url.searchParams,
+            callerSessionId: this.readCallerSessionId(req),
+            parseBody: () => parseBody(req),
+            json: (status, body) => {
+                responded = true;
+                jsonResponse(res, status, body);
+            },
+            loadSession: (id) => store.loadSession(id),
+            saveSession: (session) => store.saveSession(session),
+            publishSession: (session) => {
+                if (this.centrifugo && this.userId) {
+                    void this.centrifugo.publishSessionUpdate(this.userId, session);
+                }
+            },
+        };
+        try {
+            if (await handleBriefRoutes(ctx))
+                return true;
+            if (isPlanRoutePath(path)) {
+                const plan = this.getCoordination()?.plan;
+                if (plan && await createPlanRoutes(plan)(ctx))
+                    return true;
+            }
+            if (await this.worktreeRoutes(ctx))
+                return true;
+            return false;
+        }
+        catch (error) {
+            if (error instanceof RouteError) {
+                if (!responded && !res.headersSent)
+                    ctx.json(error.status, { error: error.message });
+                return true;
+            }
+            throw error;
+        }
+    }
+    async handleParentAttentionAction(req, res, childId, eventId, action) {
+        if (req.method !== 'POST') {
+            jsonResponse(res, 405, { error: 'Method not allowed' });
+            return;
+        }
+        if (!this.store) {
+            jsonResponse(res, 503, { error: 'Server not ready' });
+            return;
+        }
+        const child = await this.store.loadSession(childId);
+        if (!child) {
+            jsonResponse(res, 404, { error: 'Session not found', code: 'unknown_session' });
+            return;
+        }
+        if (!this.attention) {
+            jsonResponse(res, 503, { error: 'Attention store not ready', code: 'attention_not_ready' });
+            return;
+        }
+        const parent = await this.loadParentCaller(req, res, child);
+        if (!parent)
+            return;
+        if (action === 'answer') {
+            const body = await parseBody(req);
+            if (!body || typeof body !== 'object' || Array.isArray(body)
+                || Object.keys(body).some((key) => key !== 'answers')) {
+                throw new BadRequestError('Invalid attention answer');
+            }
+            const { item, waiterLive } = await this.attention.answer(child.id, eventId, body.answers, undefined, { kind: 'session', sessionId: parent.id, name: parent.name });
+            await deliverAttentionAnswer({
+                child,
+                item,
+                waiterLive,
+                sender: { from: parent.id, fromName: parent.name },
+                acceptMail: (session, mailBody) => this.acceptSessionMail(session, mailBody),
+            });
+            jsonResponse(res, 200, { event: item });
+            return;
+        }
+        const body = await parseBody(req);
+        if (!body || typeof body !== 'object' || Array.isArray(body)
+            || Object.keys(body).some((key) => key !== 'note')) {
+            throw new BadRequestError('Invalid escalation');
+        }
+        if (body.note !== undefined && (typeof body.note !== 'string' || body.note.length > 500)) {
+            throw new BadRequestError('Invalid escalation note');
+        }
+        const current = await this.attention.waitForItem(child.id, eventId, 0);
+        if (current.resolvedAt || current.route !== 'parent') {
+            jsonResponse(res, 409, { error: 'Attention request is already with the human', code: 'attention_conflict' });
+            return;
+        }
+        const updated = await this.attention.setRoute(child.id, eventId, {
+            route: 'human',
+            escalatedAt: new Date().toISOString(),
+            ...(typeof body.note === 'string' ? { escalationNote: body.note } : {}),
+        }, 'parent');
+        if (!updated || updated.resolvedAt || updated.route !== 'human') {
+            jsonResponse(res, 409, { error: 'Attention request is already with the human', code: 'attention_conflict' });
+            return;
+        }
+        this.publishHumanAttention(child.id, updated);
+        jsonResponse(res, 200, { event: updated });
     }
     setCoordination(coordination) {
         this.coordination = coordination;
@@ -307,6 +646,8 @@ export class LocalApiServer extends EventEmitter {
                 list: async (id) => this.attention
                     ? this.attention.list(id)
                     : { activity: { state: 'unknown' }, openCount: 0 },
+                listRouted: async (childId) => this.attention ? this.attention.listRouted(childId) : [],
+                setRoute: async (sessionId, eventId, fields, expectRoute) => this.attention ? this.attention.setRoute(sessionId, eventId, fields, expectRoute) : undefined,
             },
             prStatus: async () => null,
             mail: {
@@ -325,6 +666,9 @@ export class LocalApiServer extends EventEmitter {
                 }
             },
             now: Date.now,
+            onAttentionEscalated: (sessionId, item) => {
+                this.publishHumanAttention(sessionId, item);
+            },
         });
         return this.defaultCoordination;
     }
@@ -427,6 +771,11 @@ export class LocalApiServer extends EventEmitter {
             publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
             removeSession: (id, options) => removeFtownSession({ store, runner, centrifugo, userId }, id, options),
             collectUsage: (session) => collectSessionUsage(session),
+            onSessionEnding: async (session) => {
+                const coordination = this.getCoordination();
+                if (coordination)
+                    await coordination.onSessionExit(session.id, session);
+            },
             ...(this.sessionDeps ? { sessionFactory: this.sessionDeps } : {}),
         });
         return this.sessionController;
@@ -612,7 +961,17 @@ export class LocalApiServer extends EventEmitter {
                 if (caller?.shellType)
                     body.shellType = caller.shellType;
             }
-            const input = parseCreateSessionBody(body, useCallerAsParent ? callerSessionId : undefined);
+            let input;
+            try {
+                input = parseCreateSessionBody(body, useCallerAsParent ? callerSessionId : undefined);
+            }
+            catch (err) {
+                if (err instanceof WorktreeError || err instanceof PlanItemError) {
+                    jsonResponse(res, 400, { error: err.message });
+                    return;
+                }
+                throw err;
+            }
             if (!input.command && !input.shellType && !input.prompt) {
                 jsonResponse(res, 400, {
                     error: 'Provide shellType, prompt, and/or command',
@@ -629,6 +988,10 @@ export class LocalApiServer extends EventEmitter {
                 jsonResponse(res, 201, { session: toWireSession(session) });
             }
             catch (err) {
+                if (err instanceof WorktreeError || err instanceof PlanItemError) {
+                    jsonResponse(res, 400, { error: err.message });
+                    return;
+                }
                 if (err instanceof ProviderAuthMissingError) {
                     const r = providerAuthMissingResponse(err);
                     jsonResponse(res, r.status, r.body);
@@ -674,6 +1037,13 @@ export class LocalApiServer extends EventEmitter {
             jsonResponse(res, 200, { sessionId });
             return;
         }
+        if (await this.dispatchCoordinationRoutes(req, res, path, url))
+            return;
+        const parentAttentionMatch = path.match(/^\/api\/sessions\/([a-zA-Z0-9_-]+)\/attention\/([A-Za-z0-9_-]{1,100})\/(answer|escalate)$/);
+        if (parentAttentionMatch) {
+            await this.handleParentAttentionAction(req, res, parentAttentionMatch[1], parentAttentionMatch[2], parentAttentionMatch[3]);
+            return;
+        }
         const attentionMatch = path.match(/^\/api\/sessions\/([a-zA-Z0-9_-]+)\/attention(?:\/([A-Za-z0-9_-]+))?$/);
         if (attentionMatch) {
             const id = attentionMatch[1];
@@ -688,6 +1058,28 @@ export class LocalApiServer extends EventEmitter {
             }
             const attentionSub = attentionMatch[2];
             const attentionAction = attentionSub === 'ack' || attentionSub === 'resolve' ? attentionSub : undefined;
+            if (attentionSub === 'routed') {
+                if (req.method !== 'GET') {
+                    jsonResponse(res, 405, { error: 'Method not allowed' });
+                    return;
+                }
+                const caller = this.readCallerSessionId(req);
+                if (caller !== id) {
+                    jsonResponse(res, 403, { error: 'Only the parent session can do this', code: 'forbidden' });
+                    return;
+                }
+                const sessions = await this.store.listSessions();
+                const items = [];
+                for (const child of sessions) {
+                    if (child.parentSessionId !== id || child.id === id)
+                        continue;
+                    const routed = await this.attention.listRouted(child.id);
+                    for (const event of routed)
+                        items.push({ sessionId: child.id, sessionName: child.name, event });
+                }
+                jsonResponse(res, 200, { items });
+                return;
+            }
             if (attentionSub === 'ask') {
                 if (req.method !== 'POST') {
                     jsonResponse(res, 405, { error: 'Method not allowed' });
@@ -699,26 +1091,43 @@ export class LocalApiServer extends EventEmitter {
                 }
                 const body = await parseBody(req);
                 if (!body || typeof body !== 'object' || Array.isArray(body)
-                    || Object.keys(body).some((key) => !['toolName', 'toolUseId', 'toolInput'].includes(key)))
+                    || Object.keys(body).some((key) => !['toolName', 'toolUseId', 'toolInput', 'to'].includes(key)))
                     throw new BadRequestError('Invalid ask arguments');
                 if (typeof body.toolName !== 'string' || !body.toolName.trim() || body.toolName.length > 200)
                     throw new BadRequestError('Invalid toolName');
                 if (typeof body.toolUseId !== 'string' || !body.toolUseId.trim() || body.toolUseId.length > 200)
                     throw new BadRequestError('Invalid toolUseId');
+                const to = this.readAttentionTarget(body);
+                const { route, parent } = await this.resolveAttentionRouting(session, to);
                 const toolData = { tool_name: body.toolName, tool_use_id: body.toolUseId, tool_input: body.toolInput };
-                const { item, created } = await this.attention.recordDetailed(id, 'PreToolUse', toolData);
-                // When ftown's ordinary (async) PreToolUse hook is missing or late, this is the only signal the UI gets.
-                // Same stamped payload as /hook; deduped asks publish nothing, and the agent is not marked busy.
-                if (item && created) {
-                    this.emit('event', { sessionId: id, eventName: 'PreToolUse', source: 'api', data: {
-                            hook_event_name: 'PreToolUse', ...toolData,
-                            attentionId: item.id, attentionSequence: item.sequence, attentionCreatedAt: item.createdAt,
-                        } });
-                    if (session.parentSessionId) {
-                        await this.getCoordination()?.emit(session, 'attention', item.title, item.id);
+                const hold = route === 'parent' ? this.beginParentPushHold(id) : undefined;
+                let suppressItemId;
+                try {
+                    const { item, created } = await this.attention.recordDetailed(id, 'PreToolUse', toolData);
+                    // When ftown's ordinary (async) PreToolUse hook is missing or late, this is the only signal the UI gets.
+                    // Same stamped payload as /hook; deduped asks publish nothing, and the agent is not marked busy.
+                    // Only a newly created parent-routed item skips that notice and the push.
+                    let responseItem = item;
+                    if (item && created) {
+                        const applied = await this.applyParentRoute(session, item, created, route, parent);
+                        responseItem = applied.item;
+                        suppressItemId = applied.suppressPushId;
+                        if (!applied.skipNotice) {
+                            this.emit('event', { sessionId: id, eventName: 'PreToolUse', source: 'api', data: {
+                                    hook_event_name: 'PreToolUse', ...toolData,
+                                    attentionId: applied.item.id, attentionSequence: applied.item.sequence, attentionCreatedAt: applied.item.createdAt,
+                                } });
+                        }
+                        if (session.parentSessionId) {
+                            await this.getCoordination()?.emit(session, 'attention', applied.item.title, applied.item.id);
+                        }
                     }
+                    jsonResponse(res, 200, { event: responseItem && responseItem.prompt ? responseItem : null });
+                }
+                finally {
+                    if (hold !== undefined)
+                        this.finishParentPushHold(id, hold, suppressItemId);
                 }
-                jsonResponse(res, 200, { event: item && item.prompt ? item : null });
                 return;
             }
             if (attentionSub && !attentionAction) {
@@ -754,12 +1163,13 @@ export class LocalApiServer extends EventEmitter {
                 }
                 const body = await parseBody(req);
                 if (!body || typeof body !== 'object' || Array.isArray(body)
-                    || Object.keys(body).some((key) => !['title', 'message', 'questions'].includes(key)))
+                    || Object.keys(body).some((key) => !['title', 'message', 'questions', 'to'].includes(key)))
                     throw new BadRequestError('Invalid attention arguments');
                 if (typeof body.message !== 'string' || !body.message.trim() || body.message.trim().length > 2000)
                     throw new BadRequestError('Invalid attention message');
                 if (body.title !== undefined && (typeof body.title !== 'string' || !body.title.trim() || body.title.trim().length > 200))
                     throw new BadRequestError('Invalid attention title');
+                const to = this.readAttentionTarget(body);
                 const title = sanitizeAttentionText(typeof body.title === 'string' ? body.title : 'Session needs your input', 200);
                 const message = sanitizeAttentionText(body.message, 2000);
                 if (!title || !message)
@@ -773,20 +1183,37 @@ export class LocalApiServer extends EventEmitter {
                     }
                     prompt = parsed.value;
                 }
-                const event = await this.attention.record(id, 'Notification', { notification_type: 'agent_needs_input', title, message }, prompt ? { prompt } : undefined);
-                if (!event)
-                    throw new AttentionError('attention_storage_error', 'Attention history could not be persisted', 500);
-                // Durable commit precedes publication; the live stream carries only
-                // the sanitized request and its exact committed record identifier.
-                this.emit('event', { sessionId: id, eventName: 'Notification', source: 'api', data: {
-                        notification_type: 'agent_needs_input', title: event.title, message: event.message, notification_id: event.id,
-                        attentionId: event.id, attentionSequence: event.sequence, attentionCreatedAt: event.createdAt,
-                        ...(event.prompt ? { attentionPrompt: event.prompt } : {}),
-                    } });
-                if (session.parentSessionId) {
-                    await this.getCoordination()?.emit(session, 'attention', event.title, event.id);
+                const { route, parent } = await this.resolveAttentionRouting(session, to);
+                const hold = route === 'parent' ? this.beginParentPushHold(id) : undefined;
+                let suppressItemId;
+                try {
+                    const event = await this.attention.record(id, 'Notification', { notification_type: 'agent_needs_input', title, message }, prompt ? { prompt } : undefined);
+                    if (!event)
+                        throw new AttentionError('attention_storage_error', 'Attention history could not be persisted', 500);
+                    // record() only reports the item. A newly created row starts at one occurrence;
+                    // a repeat increments it and must keep the route it already has.
+                    const applied = await this.applyParentRoute(session, event, event.occurrences === 1, route, parent);
+                    suppressItemId = applied.suppressPushId;
+                    // Durable commit precedes publication; the live stream carries only
+                    // the sanitized request and its exact committed record identifier.
+                    // A new parent-routed item skips the dashboard notice. A repeat keeps
+                    // its stored route, so a human-routed repeat still publishes.
+                    if (!applied.skipNotice) {
+                        this.emit('event', { sessionId: id, eventName: 'Notification', source: 'api', data: {
+                                notification_type: 'agent_needs_input', title: applied.item.title, message: applied.item.message, notification_id: applied.item.id,
+                                attentionId: applied.item.id, attentionSequence: applied.item.sequence, attentionCreatedAt: applied.item.createdAt,
+                                ...(applied.item.prompt ? { attentionPrompt: applied.item.prompt } : {}),
+                            } });
+                    }
+                    if (session.parentSessionId) {
+                        await this.getCoordination()?.emit(session, 'attention', applied.item.title, applied.item.id);
+                    }
+                    jsonResponse(res, 200, { event: applied.item });
+                }
+                finally {
+                    if (hold !== undefined)
+                        this.finishParentPushHold(id, hold, suppressItemId);
                 }
-                jsonResponse(res, 200, { event });
                 return;
             }
             if (!attentionSub && req.method === 'GET') {
@@ -1207,9 +1634,23 @@ export class LocalApiServer extends EventEmitter {
                 jsonResponse(res, 404, { error: 'Session not found' });
                 return;
             }
-            await controller.remove(sessionId);
+            const worktreeValues = url.searchParams.getAll('worktree');
+            if (worktreeValues.length > 1)
+                throw new BadRequestError('Invalid worktree mode');
+            let worktreeMode = 'auto';
+            if (worktreeValues.length === 1) {
+                const mode = worktreeValues[0];
+                if (mode !== 'keep' && mode !== 'force')
+                    throw new BadRequestError('Invalid worktree mode');
+                worktreeMode = mode;
+            }
+            const removed = await controller.remove(sessionId, undefined, worktreeMode);
             this.mail.markSessionEnded(sessionId);
-            jsonResponse(res, 200, { removed: true, sessionId });
+            jsonResponse(res, 200, {
+                removed: true,
+                sessionId,
+                ...(removed.worktreeOutcome ? { worktreeOutcome: removed.worktreeOutcome } : {}),
+            });
             return;
         }
         // POST /api/sessions/:id/revive — recreate a removed session from its tombstone
@@ -1717,7 +2158,7 @@ export class LocalApiServer extends EventEmitter {
                 committedAttention = await this.attention.record(ftownSessionId, hookEventName, rest, isPromptSubmit ? { promptOrigin: injected ? 'injected' : 'human' } : undefined);
             }
             if (hookEventName === 'UserPromptSubmit' || hookEventName === 'PreToolUse' || hookEventName === 'PostToolUse')
-                this.mail.markAgentBusy(ftownSessionId);
+                this.mail.markAgentBusy(ftownSessionId, hookEventName);
             else if (hookEventName === 'Stop')
                 this.mail.markAgentIdle(ftownSessionId);
             else if (hookEventName === 'SessionEnd') {