avtc-pi-featyard 1.1.0

package/src/kanban/auto-agent/auto-agent-lifecycle.ts

@@ -0,0 +1,497 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Auto-agent feature lifecycle functions.
+ *
+ * Each function receives its dependencies explicitly rather than via closure.
+ */
+
+import * as fs from "node:fs";
+
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { log, NO_ERROR } from "../../log.js";
+import { clearActiveFeatureEnv } from "../../phases/env-sync.js";
+import { type Phase, SKILL_TO_PHASE } from "../../phases/phase-progression.js";
+import { expandSkillCommand } from "../../prompts/skill-block-builder.js";
+import { substitutePlaceholders } from "../../prompts/template-engine.js";
+import { getSettings } from "../../settings/settings-ui.js";
+import { trackSessionFileInState } from "../../state/feature-management.js";
+import type { FeatureState } from "../../state/feature-state.js";
+import type { KanbanDatabase } from "../data/kanban-database.js";
+import type { Feature } from "../data/kanban-types.js";
+import { DEFAULT_NOTIFY_LEVEL } from "../kanban-bridge.js";
+import type { KanbanTools } from "../kanban-operations.js";
+import { cleanupStoppedAgents } from "./auto-agent-cleanup.js";
+import type { GracePeriodManager } from "./auto-agent-grace-period.js";
+import { type AutoAgentStateMachine, computeTargetLane, startAgentHeartbeat } from "./auto-agent-state-machine.js";
+
+/** Compute the skill-injection message for a freshly-matched feature: resolves the target phase + builds the expandSkillCommand text (skill + feature title + optional description). Shared by the two activate paths. */
+function buildFeatureActivationMessage(
+  result: { feature: Feature; skill: string },
+  substituteFn: (text: string) => string,
+): { targetPhase: Phase; skillMessage: string } {
+  const targetPhase: Phase = SKILL_TO_PHASE[result.skill] ?? "design";
+  const desc = result.feature.description ? `\n${result.feature.description}` : "";
+  const skillMessage = expandSkillCommand(
+    `/skill:${result.skill} Work on feature: ${result.feature.title}${desc}`,
+    substituteFn,
+  );
+  return { targetPhase, skillMessage };
+}
+
+// --- Constants ---
+
+/** Lanes where features enter the workflow (need skill injection) */
+const ENTRY_LANES = new Set(["design", "ready"]);
+
+/** Type for the createGracePeriodManager factory stored on globalThis */
+type CreateGracePeriodManagerFn = (sm: AutoAgentStateMachine, tools: KanbanTools) => GracePeriodManager;
+
+// --- Context types for extracted functions ---
+
+/** Shared workflow-lifecycle callbacks injected into both ActivateFeatureDeps and OnFeatureCompleteDeps. */
+export interface WorkflowLifecycleDeps {
+  activateWorkflowForFeature: (slug: string, phase: Phase, ctx: ExtensionContext | null) => Promise<void>;
+  resumeWorkflowForFeature: (slug: string, ctx: ExtensionContext | null) => Promise<FeatureState | null>;
+  setWorkflowInitiatedNewSession: (message: string | null) => void;
+}
+
+/** Dependencies needed by activateFeature */
+export interface ActivateFeatureDeps extends WorkflowLifecycleDeps {
+  database: KanbanDatabase;
+  sm: AutoAgentStateMachine;
+  getTools: () => Promise<KanbanTools>;
+}
+
+/** Dependencies needed by onFeatureComplete */
+export interface OnFeatureCompleteDeps extends WorkflowLifecycleDeps {
+  getDatabase: () => Promise<KanbanDatabase>;
+  getTools: () => Promise<KanbanTools>;
+  notify: (msg: string, level: "info" | "warning" | "error") => void;
+  pi: ExtensionAPI;
+}
+
+// --- Extracted functions ---
+
+/**
+ * Run an auto-agent-initiated session replacement (newSession/switchSession) with the
+ * autoAgentInitiatingReplacement flag held high. session_start fires (via rebind, before
+ * withSession) while this flag is set, so the kanban session_start handler treats the
+ * replacement as auto-initiated and does not pause the orphaned agent. The flag clears
+ * on settle — by then withSession has refreshed __piCtx with a live command context.
+ */
+function withAutoAgentReplacement<T>(fn: () => Promise<T>): Promise<T> {
+  if (globalThis.__piKanban) globalThis.__piKanban.autoAgentInitiatingReplacement = true;
+  return fn().finally(() => {
+    if (globalThis.__piKanban) globalThis.__piKanban.autoAgentInitiatingReplacement = false;
+  });
+}
+
+/**
+ * Common helper: start heartbeat, wait timeout, bootstrap feature state,
+ * load existing session if available, and inject skill for entry lanes.
+ */
+export async function activateFeature(
+  result: { feature: Feature; skill: string; kanbanFeatureId: number },
+  piCtx: { sendUserMessage: (msg: string, options?: { deliverAs?: "steer" | "followUp" }) => void },
+  deps: ActivateFeatureDeps,
+): Promise<void> {
+  const {
+    database,
+    sm,
+    getTools,
+    activateWorkflowForFeature,
+    resumeWorkflowForFeature,
+    setWorkflowInitiatedNewSession,
+  } = deps;
+
+  // Use session guard (refreshed by session_start events and withSession callbacks)
+  // instead of captured agentCtx — agentCtx goes stale after newSession/switchSession.
+  const guard = globalThis.__piCtx;
+  const ctx = {
+    switchSession: guard?.switchSession,
+    newSession: guard?.newSession,
+    sessionManager: guard?.sessionManager,
+  };
+  // Clean up expired locks from crashed agents before activating
+  try {
+    const timeoutMs = getSettings().autoLockTimeoutMs ?? 1_800_000;
+    const cleaned = database.cleanupExpiredLocks(timeoutMs);
+    if (cleaned > 0) {
+      log.info(`[kanban] cleaned up ${cleaned} expired lock(s)`);
+    }
+  } catch (err) {
+    log.warn(`[kanban] expired lock cleanup failed: ${err}`);
+  }
+  startAgentHeartbeat(sm, result.kanbanFeatureId, getTools);
+
+  const slug = result.feature.slug;
+  if (!slug) {
+    log.warn("[kanban] activateFeature: feature has no slug, skipping activation");
+    return;
+  }
+  const originalLane = sm.getCurrentFeatureLane() ?? result.feature.lane;
+  const isEntryLane = ENTRY_LANES.has(originalLane);
+
+  // Bootstrap feature state file from kanban if it doesn't exist yet
+  let existingState: FeatureState | null = null;
+  try {
+    const { loadFeatureState, saveFeatureState, createFeatureStateFromKanban, stateDir, stateFilePath } = await import(
+      "../../state/feature-state.js"
+    );
+    existingState = loadFeatureState(slug, stateDir());
+    if (!existingState) {
+      const state = createFeatureStateFromKanban(slug, { lane: result.feature.lane, branch: null, worktreePath: null });
+      state.featureId = result.kanbanFeatureId;
+      saveFeatureState(state, stateDir());
+      existingState = state;
+    } else if (existingState.featureId === null) {
+      // Backfill kanbanFeatureId for state files created before kanban tracking
+      existingState.featureId = result.kanbanFeatureId;
+      saveFeatureState(existingState, stateDir());
+      log.info(`[kanban] backfilled kanbanFeatureId=${result.kanbanFeatureId} for existing state ${slug}`);
+    }
+    // Ensure state_file is populated on the kanban feature. NOTE: the DB `state_file` column
+    // stores an ABSOLUTE path captured at creation; after the one-time relocation to
+    // .featyard/feature-state/ older rows point at the legacy.pi path and are stale.
+    // This is benign — the card renders from DB metadata; resume uses stateDir/scanActiveFeatures
+    // as ground truth. Only freshly-created (no state_file) rows get the current path here.
+    const feature = database.getFeature(result.kanbanFeatureId);
+    if (feature && !feature.state_file) {
+      database.updateFeature({
+        featureId: result.kanbanFeatureId,
+        stateFile: stateFilePath(slug, stateDir()),
+      });
+    }
+  } catch (err) {
+    log.warn(`[kanban] failed to bootstrap feature state for ${result.feature.slug}: ${err}`);
+  }
+
+  // --- Session management: ensure feature has a session file tracked ---
+  const lastSession = existingState?.sessionFiles?.at(-1);
+
+  // Placeholder substitution function for skill expansion.
+  // Uses the closure's `slug` (from result.feature.slug), NOT process.env.PI_FY_FEATURE
+  // (the env var is deleted before this point).
+  const substituteFn = (text: string) => substitutePlaceholders(text, { slug });
+
+  const hasSession = !!(lastSession && fs.existsSync(lastSession) && ctx.switchSession);
+  log.info(
+    `[kanban] activateFeature: session decision for ${slug} — hasSession=${hasSession}, lastSession=${lastSession ?? "none"}, hasNewSession=${!!ctx.newSession}, hasSwitchSession=${!!ctx.switchSession}`,
+  );
+  // Track whether skill injection was already handled (newSession path sends via session_start)
+  let skillHandled = false;
+
+  if (hasSession) {
+    // Clear the previous feature's env var before switching to prevent session_start
+    // from binding the new session to the old feature.
+    clearActiveFeatureEnv();
+    log.info(`[kanban] activateFeature: loading session ${lastSession} for feature ${slug}`);
+    const _desc = result.feature.description ? `\n${result.feature.description}` : "";
+    const _skillMessage = expandSkillCommand(
+      `/skill:${result.skill} Work on feature: ${result.feature.title}${_desc}`,
+      substituteFn,
+    );
+    const _continuationMessage = `Continuing work on feature: ${result.feature.title}. Pick up where you left off.`;
+    const _targetPhase: Phase = SKILL_TO_PHASE[result.skill] ?? "design";
+    // All post-switch work MUST happen inside withSession — the old ctx/pi are stale after switchSession.
+    const sessionToLoad = lastSession;
+    if (sessionToLoad) {
+      await withAutoAgentReplacement(async () => {
+        await ctx.switchSession?.(sessionToLoad, {
+          withSession: async (newCtx) => {
+            // Refresh stash with fresh command context from the new session
+            globalThis.__piCtx?.refresh(newCtx as unknown as ExtensionCommandContext);
+            if (isEntryLane) {
+              log.info(`[kanban] activateFeature: activating phase ${_targetPhase} for ${slug} in resumed session`);
+              await activateWorkflowForFeature(slug, _targetPhase, newCtx);
+              log.info(`[kanban] activateFeature: sending skill command into resumed session for ${slug}`);
+              newCtx.sendUserMessage(_skillMessage, { deliverAs: "followUp" });
+            } else {
+              // Mid-workflow: reconstruct state without advancing phase, then continue.
+              await resumeWorkflowForFeature(slug, newCtx);
+              log.info(`[kanban] activateFeature: resuming mid-workflow feature ${slug} from session`);
+              newCtx.sendUserMessage(_continuationMessage, { deliverAs: "followUp" });
+            }
+            trackSessionFileInState(newCtx, slug);
+          },
+        });
+      });
+      skillHandled = true;
+    }
+  } else if (ctx.newSession) {
+    log.info(`[kanban] activateFeature: creating new session for feature ${slug}`);
+    clearActiveFeatureEnv();
+    const parentSession = ctx.sessionManager?.getSessionFile?.();
+
+    const newSession = ctx.newSession;
+    if (isEntryLane) {
+      const { targetPhase, skillMessage } = buildFeatureActivationMessage(result, substituteFn);
+      setWorkflowInitiatedNewSession(skillMessage);
+      const res = await withAutoAgentReplacement(() =>
+        newSession({
+          parentSession: parentSession || undefined,
+          withSession: async (newCtx) => {
+            globalThis.__piCtx?.refresh(newCtx as unknown as ExtensionCommandContext);
+            await activateWorkflowForFeature(slug, targetPhase, newCtx);
+            trackSessionFileInState(newCtx, slug);
+            skillHandled = true;
+            log.info(`[kanban] activateFeature: new session created and tracked for ${slug}`);
+          },
+        }),
+      );
+      if (res?.cancelled) {
+        log.info(`[kanban] activateFeature: new session cancelled for ${slug}`);
+        await activateWorkflowForFeature(slug, targetPhase, ctx as unknown as ExtensionContext);
+        trackSessionFileInState(ctx as unknown as ExtensionContext, slug);
+      }
+    } else {
+      const _continuationMsg = `Continuing work on feature: ${result.feature.title}. Pick up where you left off.`;
+      setWorkflowInitiatedNewSession(_continuationMsg);
+      const res = await withAutoAgentReplacement(() =>
+        newSession({
+          parentSession: parentSession || undefined,
+          withSession: async (newCtx) => {
+            globalThis.__piCtx?.refresh(newCtx as unknown as ExtensionCommandContext);
+            await resumeWorkflowForFeature(slug, newCtx);
+            trackSessionFileInState(newCtx, slug);
+            skillHandled = true;
+            log.info(`[kanban] activateFeature: new session created for mid-workflow feature ${slug}`);
+          },
+        }),
+      );
+      if (res?.cancelled) {
+        await resumeWorkflowForFeature(slug, ctx as unknown as ExtensionContext);
+        trackSessionFileInState(ctx as unknown as ExtensionContext, slug);
+      }
+    }
+  } else {
+    trackSessionFileInState(ctx as unknown as ExtensionContext, slug);
+  }
+
+  // Skill injection (skip if already handled by switchSession/newSession paths above)
+  if (!skillHandled) {
+    if (isEntryLane) {
+      const { targetPhase, skillMessage } = buildFeatureActivationMessage(result, substituteFn);
+      await activateWorkflowForFeature(slug, targetPhase, piCtx as unknown as ExtensionContext);
+
+      log.info("[kanban] activateFeature: sending skill command via sendUserMessage");
+      piCtx.sendUserMessage(skillMessage, { deliverAs: "followUp" });
+      log.info(`[kanban] activateFeature: skill command dispatched successfully for ${result.feature.slug}`);
+    } else {
+      await resumeWorkflowForFeature(slug, piCtx as unknown as ExtensionContext);
+      log.info(`[kanban] activateFeature: continuing mid-workflow feature ${slug} without session`);
+      piCtx.sendUserMessage(`Continuing work on feature: ${result.feature.title}. Pick up where you left off.`, {
+        deliverAs: "followUp",
+      });
+    }
+  }
+}
+
+/**
+ * Handle feature completion notification from workflow-monitor.
+ * Called when a feature's workflow completes (all phases done).
+ */
+export async function onFeatureComplete(slug: string, deps: OnFeatureCompleteDeps): Promise<void> {
+  const { getDatabase, getTools, notify, pi } = deps;
+
+  log.info(`[kanban] onFeatureComplete called for slug "${slug}"`);
+  const current = globalThis.__piKanban?.autoAgent;
+  if (current) {
+    log.info(
+      `[kanban] onFeatureComplete: agent state=${current.getState()}, featureId=${current.getCurrentFeatureId()}, role=${current.getRole()}`,
+    );
+  }
+  // Match working, paused, and waiting agents.
+  const { findAnyActiveAgent } = await import("../../commands/kanban-commands.js");
+  const match = await findAnyActiveAgent(slug, current ?? null, getDatabase);
+  log.info(`[kanban] onFeatureComplete: findAnyActiveAgent result=${match ? "found" : "not found"}`);
+  if (!match) {
+    // Check actual lock state to give accurate warning
+    try {
+      const { detectProject } = await import("../data/kanban-detect-project.js");
+      const database = await getDatabase();
+      const projectId = await detectProject(database, process.cwd());
+      const feature = database.findFeatureBySlug(slug, projectId ?? undefined);
+      if (feature?.locked_at) {
+        log.warn(
+          `[kanban] onFeatureComplete: no agent found for slug "${slug}" — feature will stay locked (agent may have moved to another feature)`,
+        );
+      } else {
+        log.info(
+          `[kanban] onFeatureComplete: no agent found for slug "${slug}" — lock already released (duplicate or late completion event)`,
+        );
+      }
+    } catch {
+      log.warn(`[kanban] onFeatureComplete: no agent found for slug "${slug}" — lock status unknown`);
+    }
+    return;
+  }
+  if (match.sm.projectId === undefined) {
+    log.warn(`[kanban] onFeatureComplete: agent for slug "${slug}" has undefined projectId`);
+    return;
+  }
+  const { sm, featureId } = match;
+  log.info(`[kanban] onFeatureComplete: found agent for slug "${slug}", featureId=${featureId}, role=${sm.getRole()}`);
+
+  try {
+    const tools = await getTools();
+    const settings = getSettings();
+    const designApprovalEnabled = settings.designApprovalEnabled;
+
+    const currentFeatureLane = sm.getCurrentFeatureLane();
+    if (!currentFeatureLane) {
+      log.warn(`[kanban] onFeatureComplete: no currentFeatureLane for slug "${slug}"`);
+      try {
+        sm.complete();
+      } catch {}
+      if (sm.getState() === "idle") {
+        sm.start();
+        sm.noFeatureAvailable();
+      }
+      const pollingFn = sm.getStartPollingFn();
+      if (pollingFn) pollingFn();
+      cleanupStoppedAgents();
+      return;
+    }
+
+    // Check actual current lane in DB — user may have moved the card while agent worked
+    const actualDb = await getDatabase();
+    const actualFeature = actualDb.getFeature(featureId);
+    const actualLane = actualFeature?.lane;
+
+    if (actualLane && actualLane !== "design") {
+      log.info(
+        `[kanban] onFeatureComplete: feature ${featureId} is in lane "${actualLane}" (not design), skipping move`,
+      );
+      try {
+        tools.kanbanRelease({ featureId });
+      } catch {}
+      sm.complete();
+      if (sm.start()) {
+        const projectId = sm.projectId;
+        if (projectId === undefined) {
+          log.warn("[kanban] onFeatureComplete: state machine has no projectId, cannot pick next feature");
+        } else {
+          const nextResult = sm.pickNextFeature(tools, projectId, sm.sessionId);
+          if (nextResult) {
+            const doActivate = globalThis.__piKanban?.activateFeature;
+            if (!doActivate) {
+              log.error("[kanban] activateFeature not available on __piKanban bridge", NO_ERROR);
+              return;
+            }
+            notify(`✅ Auto-${sm.getRole()} finished: "${slug}". Activating next feature...`, DEFAULT_NOTIFY_LEVEL);
+            await doActivate(nextResult, pi);
+            return;
+          }
+        }
+      }
+      const pollingFn2 = sm.getStartPollingFn();
+      if (pollingFn2) pollingFn2();
+      cleanupStoppedAgents();
+      return;
+    }
+
+    // Feature is still in design — normal completion flow
+    const targetLane = computeTargetLane(currentFeatureLane, designApprovalEnabled);
+    const useGracePeriod = currentFeatureLane === "design" && targetLane === "design-approval";
+
+    let nextFeature: { feature: Feature; skill: string; kanbanFeatureId: number } | null;
+    try {
+      if (sm.projectId === undefined) {
+        throw new Error("auto-agent state machine has no projectId");
+      }
+      nextFeature = sm.handleFeatureCompletion(tools, featureId, sm.sessionId, sm.projectId, {
+        designApprovalEnabled,
+        completeOnly: useGracePeriod,
+      });
+    } catch (err) {
+      log.error(`[kanban] onFeatureComplete: handleFeatureCompletion failed for slug "${slug}"`, err);
+      const pollingFn = sm.getStartPollingFn();
+      if (pollingFn) pollingFn();
+      cleanupStoppedAgents();
+      return;
+    }
+
+    // Grace period path (→ design-approval)
+    if (useGracePeriod && sm.getState() !== "stopped") {
+      if (sm.start()) {
+        const createGpm = globalThis.__piKanban?.createGracePeriodManager as CreateGracePeriodManagerFn | undefined;
+        if (createGpm) {
+          const gpm = createGpm(sm, tools);
+          gpm.start();
+          sm.enterGracePeriod();
+          notify(
+            `✅ Auto-${sm.getRole()} finished: "${slug}" → ${targetLane}. Searching for next feature in 30s...`,
+            DEFAULT_NOTIFY_LEVEL,
+          );
+        } else {
+          log.warn("[kanban] onFeatureComplete: createGracePeriodManager not available, falling back to polling");
+          const pollingFn = sm.getStartPollingFn();
+          if (pollingFn) pollingFn();
+        }
+      }
+      return;
+    }
+
+    // Point B: design → ready, no next feature (immediate new session)
+    if (currentFeatureLane === "design" && targetLane === "ready" && !nextFeature) {
+      const resetFn = globalThis.__piWorkflowMonitor?.performWorkflowReset;
+      if (resetFn) resetFn();
+
+      const guard = globalThis.__piCtx;
+      const newSession = guard?.newSession;
+      if (newSession) {
+        await withAutoAgentReplacement(() =>
+          newSession({
+            parentSession: guard?.sessionManager?.getSessionFile?.() || undefined,
+            withSession: async (newCtx) => {
+              globalThis.__piCtx?.refresh(newCtx as unknown as ExtensionCommandContext);
+              const resetFn2 = globalThis.__piWorkflowMonitor?.performWorkflowReset;
+              if (resetFn2) resetFn2();
+              notify(
+                `✅ Auto-${sm.getRole()} finished: "${slug}" → ready. New session started, polling for next design feature...`,
+                DEFAULT_NOTIFY_LEVEL,
+              );
+            },
+          }),
+        );
+      } else {
+        notify(
+          `✅ Auto-${sm.getRole()} finished: "${slug}" → ready. Polling for next design feature...`,
+          DEFAULT_NOTIFY_LEVEL,
+        );
+      }
+
+      const pollingFn = sm.getStartPollingFn();
+      if (pollingFn) pollingFn();
+      cleanupStoppedAgents();
+      return;
+    }
+
+    // Standard path: next feature found
+    if (nextFeature) {
+      log.info(`[kanban] onFeatureComplete: picked next feature "${nextFeature.feature.title}"`);
+      notify(`✅ Auto-${sm.getRole()} finished: "${slug}". Activating next feature...`, DEFAULT_NOTIFY_LEVEL);
+      const doActivate = globalThis.__piKanban?.activateFeature;
+      if (!doActivate) {
+        log.error("[kanban] activateFeature not available on __piKanban bridge", NO_ERROR);
+        return;
+      }
+      await doActivate(nextFeature, pi);
+      return;
+    }
+
+    // No next feature — enter polling
+    log.info(`[kanban] onFeatureComplete: no next feature available after "${slug}"`);
+    notify(`💤 Auto-${sm.getRole()} finished: "${slug}". Waiting for new features...`, DEFAULT_NOTIFY_LEVEL);
+  } catch (err) {
+    log.error(`[kanban] onFeatureComplete: handleFeatureCompletion failed for slug "${slug}"`, err);
+  }
+
+  const pollingFn = sm.getStartPollingFn();
+  if (pollingFn) pollingFn();
+  log.info("[kanban] auto-agent: no more features available, polling...");
+  cleanupStoppedAgents();
+}

package/src/kanban/auto-agent/auto-agent-notify.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Auto-agent notification helpers.
+ *
+ * Notify the auto-agent state machine when the agent is blocked
+ * waiting for user input or when user provides input.
+ */
+
+import type { AutoAgentCallback } from "./auto-agent-state-machine.js";
+
+/** Module-level ref to getAutoAgentCallback, set during initialization */
+let _getAutoAgentCallback: (() => AutoAgentCallback | null) | null = null;
+
+/** Set the getAutoAgentCallback implementation (called by orchestrator) */
+export function setAutoAgentCallbackGetter(getter: () => AutoAgentCallback | null): void {
+  _getAutoAgentCallback = getter;
+}
+
+/** Notify auto-agent that the agent is blocked waiting for user input */
+export function notifyAutoAgentBlocked(slug: string): void {
+  try {
+    const autoAgentCb = _getAutoAgentCallback?.();
+    if (autoAgentCb?.onBlock) {
+      autoAgentCb.onBlock(slug);
+    }
+  } catch {
+    // Auto-agent notification must not disrupt workflow
+  }
+}
+
+/** Notify auto-agent that user provided input and agent can continue */
+export function notifyAutoAgentUnblocked(slug: string): void {
+  try {
+    const autoAgentCb = _getAutoAgentCallback?.();
+    if (autoAgentCb?.onUnblock) {
+      autoAgentCb.onUnblock(slug);
+    }
+  } catch {
+    // Auto-agent notification must not disrupt workflow
+  }
+}

package/src/kanban/auto-agent/auto-agent-pause.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Pause an orphaned auto-agent after an external session replacement.
+ *
+ * newSession/switchSession are command-context-only: they cannot be refreshed from
+ * a session_start event ctx (ExtensionContext), so a manual /new, /resume, /fork,
+ * or /reload leaves them pinned to the now-dead runner. Rather than crash on the
+ * next feature pick, pause the agent and ask the user to re-run its start command,
+ * which mints a fresh command context and resumes the loop.
+ */
+
+import { log } from "../../log.js";
+import type { AutoAgentRole } from "./auto-agent-state-machine.js";
+
+/** Map an auto-agent role to its resume command + display name. */
+function roleResumeInfo(role: AutoAgentRole): { command: string; display: string } {
+  const command = role === "worker" ? "fy:auto-worker" : role === "designer" ? "fy:auto-designer" : "fy:auto-agent";
+  return { command, display: `Auto-${role}` };
+}
+
+/**
+ * Pause an orphaned auto-agent if one is in an active state.
+ *
+ * @param requestWidgetUpdate  Request a widget re-render after pausing.
+ * @returns true if an agent was paused, false if none was active.
+ */
+export function pauseOrphanedAutoAgent(requestWidgetUpdate: () => void): boolean {
+  const sm = globalThis.__piKanban?.autoAgent;
+  if (!sm) return false;
+  const state = sm.getState();
+  // Only pause states that rely on newSession/switchSession for the next activation.
+  // paused/stopped/error/idle are left untouched.
+  if (state !== "working" && state !== "polling" && state !== "waiting" && state !== "grace-period") return false;
+  const gpm = globalThis.__piKanban?.gracePeriod;
+  if (gpm) gpm.stop();
+  const { command, display } = roleResumeInfo(sm.getRole());
+  sm.pause();
+  globalThis.__piCtx?.notify(`${display} paused after manual session change. Re-run /${command} to resume.`, "warning");
+  requestWidgetUpdate();
+  log.info(`[kanban] session_start: orphaned ${display} paused after external session replacement (was ${state})`);
+  return true;
+}