avtc-pi-featyard 1.1.0

package/src/integrations/subagent-integration.ts

@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Subagent integration layer — connects featyard-specific
+ * dependencies to the generic pi-subagent extension.
+ *
+ * This is the ONLY file that imports from both pi-subagent (via vendored drop-in)
+ * and featyard internals (settings, template-substitution, logging).
+ *
+ * Exports initSubagentIntegration(pi) which calls subscribeToSubagent
+ * with featyard-specific hooks (transformPrompt, etc.).
+ */
+
+import * as path from "node:path";
+import { agentLoop } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { _kanbanModelRef } from "../kanban/kanban-bridge.js";
+import { generateTopic } from "../kanban/kanban-generate-topic.js";
+import { log } from "../log.js";
+import { getLoopCountForPhase } from "../phases/phase-transitions.js";
+import { substitutePlaceholders } from "../prompts/template-engine.js";
+import { DEFAULT_GLOBAL_DIR, loadFeatyardConfig, resolveStageModelOnly } from "../settings/settings-ui.js";
+import { getActiveFeatureSlug, getHandlerRef } from "../shared/workflow-refs.js";
+import { subscribeToSubagent } from "../snippets/vendored/subscribe-to-subagent.js";
+import { slugifyTaskDesignation } from "../state/artifact-paths.js";
+
+/** The extension name featyard reports when registering agents via the pi-subagent
+ *  addAgentsPaths API. Lets extension-provided name-collision messages (in avtc-pi-subagent)
+ *  identify featyard as the contributor. */
+const SUBAGENT_EXTENSION_NAME = "avtc-pi-featyard";
+
+/** Fork context injected into an agent's system prompt when it runs in a forked
+ * (branched-session) subagent. Agent-specific entries take precedence over the
+ * generic fallback. Only the placeholder agent files reference this; resolution
+ * lives here because the `isFork` signal is only available on the subagent path. */
+const FORK_CONTEXT_BY_AGENT: Record<string, string> = {
+  "fy-design-reviewer":
+    "Pay special attention to:\n" +
+    "- Decisions discussed but not captured in the final document\n" +
+    "- Implicit assumptions that are clear from conversation but missing from the doc\n" +
+    "- Changes in direction that weren't fully reflected",
+  "fy-plan-reviewer":
+    "Also check for:\n" + "- **Context gaps:** Discussed constraints or decisions not reflected in the plan",
+};
+
+/** Generic fork-context fallback for agents that have the
+ * `{{PI_FY_FORK_CONTEXT_INJECTION}}` placeholder but no dedicated entry above. */
+const FORK_CONTEXT_FALLBACK =
+  "Pay special attention to:\n" +
+  "- Decisions discussed but not captured in the written documents\n" +
+  "- Implicit assumptions clear from conversation but missing from formal output";
+
+/** Resolve the `{{PI_FY_FORK_CONTEXT_INJECTION}}` placeholder in an agent system prompt.
+ * Injects agent-specific (or fallback) bullets when forking; empty string otherwise. */
+function resolveForkContextInjection(systemPrompt: string, agentName: string, isFork: boolean): string {
+  if (!systemPrompt.includes("{{PI_FY_FORK_CONTEXT_INJECTION}}")) return systemPrompt;
+  if (!isFork) {
+    return systemPrompt.replaceAll("{{PI_FY_FORK_CONTEXT_INJECTION}}", "");
+  }
+  const baseName = agentName.replace(/-fork$/, "");
+  const injection = FORK_CONTEXT_BY_AGENT[baseName] ?? FORK_CONTEXT_FALLBACK;
+  return systemPrompt.replaceAll("{{PI_FY_FORK_CONTEXT_INJECTION}}", injection);
+}
+
+/**
+ * Resolve the current plan-task designation (set by task_ready_advance) from the
+ * in-memory handler feature-state (the durable source of truth). Returns the raw task
+ * string (e.g. '3. Wire the login form'), or undefined when no task has been advanced to
+ * yet. Path builders slugify this value.
+ */
+function resolveCurrentTaskName(): string | undefined {
+  return getHandlerRef()?.getActiveFeatureState()?.implement.currentTask ?? undefined;
+}
+
+/**
+ * Resolve the loop index for a subagent invocation.
+ *
+ * Three cases:
+ * 1. Per-task verify/review (fy-task-verifier or fy-general-reviewer during implement
+ *    phase) — PURE READ of the task's taskReviewRounds on the active feature record.
+ *    (task_ready_advance's gate is the sole incrementer; this only reads the current round
+ *    to give each round a unique report file path.)
+ * 2. Review agents (name contains "review") — reads the phase-aware loop count from
+ *    feature state (the durable source of truth).
+ * 3. All other agents — no loop index.
+ */
+export function _resolveReviewLoopIndex(
+  agentName: string,
+  _slug: string | undefined,
+  taskName: string | undefined,
+): number | undefined {
+  const handler = getHandlerRef();
+  const featureState = handler?.getActiveFeatureState() ?? null;
+  const stage = handler?.getWorkflowState()?.currentPhase ?? null;
+
+  // Case 1: Per-task verify/review during implement phase — PURE READ.
+  // task_ready_advance's gate is the sole incrementer of taskReviewRounds; this function
+  // only reads the current round so per-task reports render numbered paths. Covers both
+  // fy-general-reviewer and fy-task-verifier.
+  if ((agentName === "fy-general-reviewer" || agentName === "fy-task-verifier") && taskName) {
+    if (stage === "implement" && featureState) {
+      const key = slugifyTaskDesignation(taskName);
+      return featureState.implement.taskReviewRounds[key] ?? 0;
+    }
+  }
+
+  // Case 2: Review agents — read phase-aware loop count from feature state
+  if (agentName.includes("review") && stage) {
+    return getLoopCountForPhase(featureState, stage);
+  }
+  return undefined;
+}
+
+export function initSubagentIntegration(pi: ExtensionAPI): void {
+  subscribeToSubagent(
+    pi,
+    async (systemPrompt, context) => {
+      // Resolve slug, current plan-task designation, loopIndex from featyard context.
+      // All read from the in-memory handler feature-state (the durable source of truth);
+      // the only env var consulted here is PI_FY_FEATURE as a slug fallback when no
+      // handler is wired (the child loads its feature-state file from that slug on start).
+      const slug = getActiveFeatureSlug() ?? process.env.PI_FY_FEATURE;
+      const taskName = resolveCurrentTaskName();
+      const loopIndex = _resolveReviewLoopIndex(context.agentName, slug, taskName);
+
+      // Generate topic from task when no slug/feature is active
+      let topic: string | undefined;
+      if (!slug && context.task) {
+        try {
+          topic = await generateTopic(context.task, { agentLoop, modelRef: _kanbanModelRef });
+        } catch (err) {
+          log.warn(`generateTopic failed: ${err instanceof Error ? err.message : err}`);
+        }
+      }
+
+      // Resolve FORK_CONTEXT_INJECTION first — needs context.isFork, only
+      // available on this subagent path (not in substitutePlaceholders).
+      systemPrompt = resolveForkContextInjection(systemPrompt, context.agentName, context.isFork);
+
+      return substitutePlaceholders(systemPrompt, {
+        agentName: context.agentName,
+        slug,
+        loopIndex,
+        taskName,
+        topic,
+      });
+    },
+    () => {
+      // explicitModel is NOT consulted here: pi-subagent's Phase 0 short-circuits an
+      // explicit --model param before any Phase 2 hook runs, so this hook is only
+      // reached when explicitModel === undefined. This hook yields a stage-model
+      // (rotating by review-loop index) for the workflow's current stage, else
+      // undefined so pi-subagent's Phase 3 default-model applies.
+      const config = loadFeatyardConfig(DEFAULT_GLOBAL_DIR, process.cwd());
+      const handler = getHandlerRef();
+      const featureState = handler?.getActiveFeatureState() ?? null;
+      const stage = handler?.getWorkflowState()?.currentPhase ?? null;
+      const loopIdx = stage ? getLoopCountForPhase(featureState, stage) : 0;
+      return resolveStageModelOnly(stage, loopIdx, config) ?? undefined;
+    },
+    [path.resolve(__dirname, "..", "..", "skills")],
+    [path.resolve(__dirname, "..", "..", "agents")],
+    SUBAGENT_EXTENSION_NAME,
+  );
+}

package/src/integrations/todo-integration.ts

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Feature-flow integration layer for pi-todo.
+ *
+ * Wires the generic pi-todo extension to featyard-specific infrastructure:
+ * - disableBuiltInFollowUp: featyard handles followUp via session_compact + the todo getters
+ *
+ * Exports initTodoIntegration(pi) which calls subscribeToTodo from vendored drop-in
+ * and returns the sync lazy proxy with getCompletedItemId/getInProgressItem/disableBuiltInFollowUp.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { subscribeToTodo } from "../snippets/vendored/subscribe-to-todo.js";
+
+/** Module-level ref for todo API, populated by initTodoIntegration. */
+let _todoApi: ReturnType<typeof subscribeToTodo> | null = null;
+
+/** @internal Test override for areAllTodosDone — when set, takes precedence over _todoApi. */
+let _areAllTodosDoneOverride: boolean | null = null;
+
+/** Disable built-in followUp — featyard handles it via session_compact + the todo getters */
+const DISABLE_BUILTIN_FOLLOW_UP = true;
+
+export function initTodoIntegration(pi: ExtensionAPI): ReturnType<typeof subscribeToTodo> {
+  _todoApi = subscribeToTodo(pi, DISABLE_BUILTIN_FOLLOW_UP);
+  return _todoApi;
+}
+
+/** Id of the item just completed by the todo_complete that triggered the current compaction (consume-on-read),
+ *  or null when this compaction was not triggered by item completion. Null if pi-todo is not loaded. */
+export function getTodoCompletedItemId(): string | null {
+  return _todoApi?.getCompletedItemId() ?? null;
+}
+
+/** The current in-progress todo item formatted for followUp (`In progress: ▶ id: name\ndetails`),
+ *  or null if none / pi-todo not loaded. */
+export function getTodoInProgressItem(): string | null {
+  return _todoApi?.getInProgressItem() ?? null;
+}
+
+/** Returns true if all todo items are in a terminal state (completed or decomposed). True when no items. */
+export function areAllTodosDone(): boolean {
+  if (_areAllTodosDoneOverride !== null) return _areAllTodosDoneOverride;
+  return _todoApi?.areAllTodosDone() ?? true;
+}
+
+/** @internal Set override for areAllTodosDone (test only). Pass null to clear. */
+export function _setAreAllTodosDoneOverride(value: boolean | null): void {
+  _areAllTodosDoneOverride = value;
+}
+
+/** Reset module-level state for test isolation. */
+export function resetTodoIntegration(): void {
+  _todoApi = null;
+  _areAllTodosDoneOverride = null;
+}

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

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Utility functions for auto-agent cleanup.
+ */
+
+import { log } from "../../log.js";
+import type { GracePeriodManager } from "./auto-agent-grace-period.js";
+
+/**
+ * Remove the stopped/error agent, clean up its timers,
+ * and remove the terminal input listener if no agent remains.
+ * Called with no arguments — reads from globalThis.__piKanban.autoAgent.
+ */
+export function cleanupStoppedAgents(): void {
+  const sm = globalThis.__piKanban?.autoAgent;
+  if (!sm) return;
+  if (sm.getState() === "stopped" || sm.getState() === "error") {
+    sm.stopHeartbeat();
+    sm.stopPollingTimer();
+    if (globalThis.__piKanban) globalThis.__piKanban.autoAgent = null;
+    log.info(`[kanban] cleaned up ${sm.getRole()} agent (state: ${sm.getState()})`);
+    // If this agent was in grace-period, stop the GPM immediately
+    const gpm = globalThis.__piKanban?.gracePeriod as GracePeriodManager | undefined;
+    if (gpm?.isActive()) gpm.stop();
+  }
+  // Clean up terminal input listener if no agent is running
+  const currentAgent = globalThis.__piKanban?.autoAgent;
+  if (!currentAgent || ["stopped", "error"].includes(currentAgent.getState())) {
+    const unsub = globalThis.__piKanban?.terminalInputUnsubscribe as (() => void) | undefined;
+    if (unsub) {
+      unsub();
+      if (globalThis.__piKanban) globalThis.__piKanban.terminalInputUnsubscribe = null;
+    }
+  }
+}

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

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Agent-lifecycle domain module — the agent_start and agent_end handler bodies
+ * as callable methods (no pi.on registration).
+ *
+ * agent_start re-arms the finish-phase guardrail whitelist (worktree policy +
+ * worktree path) at the start of every agent turn while finish is active, and
+ * signals a fresh turn to the compaction module. agent_end clears the guardrail,
+ * resets the once-per-turn phase_ready guard, flags the agent finished, and
+ * notifies the auto-agent on non-retryable execution-phase errors.
+ *
+ * The events/agent/ routers own the pi.on registration and call these methods.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { setFinishPhaseWhitelisted } from "../../git/worktrees/worktree-lifecycle.js";
+import { log, NO_ERROR } from "../../log.js";
+import { getSettings } from "../../settings/settings-ui.js";
+import type { IAgentLifecycle, ICompaction, IPhaseReady } from "../../shared/workflow-types.js";
+import type { FeatureSession } from "../../state/feature-session.js";
+import { schedulePostTurnDrain } from "../../state/post-turn-dispatch.js";
+import { isSubagentSession } from "../../state/state-persistence.js";
+import type { AutoAgentCallback } from "./auto-agent-state-machine.js";
+
+/** Find the last assistant message in a message list (reverse-search for role === "assistant"). Generic over the message type so it avoids cross-package SDK imports. */
+function findLastAssistantMessage<TMessage extends { role: string; stopReason?: string; errorMessage?: string }>(
+  messages: readonly TMessage[],
+): TMessage | undefined {
+  return [...messages].reverse().find((m) => m.role === "assistant");
+}
+
+/** Regex for retryable errors (transient network/API failures) */
+const RETRYABLE_ERROR_RE =
+  /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|http2 request did not get a response|timed? out|timeout|terminated|retry delay/i;
+
+export interface AgentLifecycleDeps {
+  pi: ExtensionAPI;
+  handler: FeatureSession;
+  compaction: ICompaction;
+  phaseReady: IPhaseReady;
+  getAutoAgentCallback: () => AutoAgentCallback | null;
+}
+
+/**
+ * Construct the agent-lifecycle domain object. The returned methods are the
+ * agent_start / agent_end handler bodies — the events/agent/ routers call them.
+ */
+export function createAgentLifecycle(deps: AgentLifecycleDeps): IAgentLifecycle {
+  const { pi, handler, compaction, phaseReady, getAutoAgentCallback } = deps;
+
+  async function onAgentStart(): Promise<void> {
+    compaction.setAgentFinished(false);
+    // Re-arm the finish-phase guardrail whitelist at the start of every turn while
+    // the finish phase is active (worktree policy + worktree path). The agent_end
+    // handler clears it at turn end (crash safety + clears when leaving finish), so
+    // re-arming here keeps it alive across the multi-turn interactive finish flow
+    // (turn 1 presents the option menu → turn 2 executes the merge). Sole arming site.
+    if (!isSubagentSession()) {
+      const ws = handler.getWorkflowState();
+      const fs = handler.getActiveFeatureState();
+      if (ws?.currentPhase === "finish" && getSettings().branchPolicy === "worktree" && fs?.git?.worktreePath) {
+        setFinishPhaseWhitelisted(true);
+      }
+    }
+    log.info("[workflow] agent_start: resetting skill tracking");
+  }
+
+  async function onAgentEnd(
+    event: { messages?: ReadonlyArray<{ role: string; stopReason?: string; errorMessage?: string }> },
+    _ctx: ExtensionContext,
+  ): Promise<void> {
+    // Clear finish-phase guardrail whitelist flag on agent end
+    setFinishPhaseWhitelisted(false);
+    // Reset the once-per-agent-turn phase_ready guard. This is the per-cycle
+    // boundary for the guard: each low-level run (including retry / compact /
+    // followUp continuations) ends with its own agent_end, so the guard is cleared
+    // here between every cycle. NOT reset on turn_end: a pi "turn" is one LLM
+    // response, and a confused model's repeated phase_ready calls span multiple
+    // turns within one agent run (those repeats must stay collapsed until the run
+    // truly ends). The phase-transition followUp itself is drained at
+    // agent_settled (see onAgentSettled), not here.
+    phaseReady.resetTracking();
+    // Don't trigger finish-done detection if Pi will auto-retry — the agent hasn't truly finished.
+    // Pi emits agent_end before its own retry check, so we must detect this ourselves.
+    let lastError: string | undefined;
+    if (event.messages?.length) {
+      const lastAssistant = findLastAssistantMessage(event.messages);
+
+      if (
+        lastAssistant &&
+        lastAssistant.stopReason === "error" &&
+        lastAssistant.errorMessage &&
+        RETRYABLE_ERROR_RE.test(lastAssistant.errorMessage)
+      ) {
+        return;
+      }
+      if (lastAssistant && lastAssistant.stopReason === "error" && lastAssistant.errorMessage) {
+        lastError = lastAssistant.errorMessage;
+      }
+    }
+
+    compaction.setAgentFinished(true);
+
+    if (isSubagentSession()) return;
+
+    const latestState = handler.getWorkflowState();
+    log.info(
+      `[workflow] agent_end fired, activeFeatureSlug=${handler.getActiveFeatureSlug()}, currentPhase=${latestState?.currentPhase}`,
+    );
+    if (!latestState) return;
+
+    // Notify auto-agent of non-retryable errors during execution phases
+    if (lastError) {
+      const errorSlug = handler.getActiveFeatureSlug();
+      if (errorSlug && ["implement", "verify", "review"].includes(latestState.currentPhase ?? "")) {
+        try {
+          const autoAgentCb = getAutoAgentCallback();
+          if (autoAgentCb) {
+            log.info(`[workflow] auto-agent callback: notifying feature error for ${errorSlug}`);
+            autoAgentCb.onFeatureError(errorSlug, lastError);
+          }
+        } catch (err) {
+          log.error(`[workflow] auto-agent onFeatureError callback error: ${err}`, NO_ERROR);
+        }
+      }
+    }
+  }
+
+  async function onAgentSettled(): Promise<void> {
+    // pi will not continue automatically — deliver any phase-transition followUp
+    // staged during the run (design/plan review iterations, phase handoffs). The
+    // drain is DEFERRED (see post-turn-dispatch.ts): a synchronous sendUserMessage
+    // here would re-enter _runAgentPrompt before the outer run's finally unwinds,
+    // and the delay lets a user message typed at settle time start its turn first
+    // (the staged followUp then enqueues behind it instead of racing it).
+    schedulePostTurnDrain(pi);
+  }
+
+  return { onAgentStart, onAgentEnd, onAgentSettled };
+}

package/src/kanban/auto-agent/auto-agent-grace-period.ts

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+import { log } from "../../log.js";
+
+/** Options for GracePeriodManager. durationMs defaults to 30_000 when omitted. */
+export type GracePeriodOpts = { durationMs?: number };
+
+export class GracePeriodManager {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private remainingMs: number = 0;
+  private readonly durationMs: number;
+  private readonly tickMs = 1000;
+  private active = false;
+  private paused = false;
+
+  constructor(
+    private readonly onExpired: () => Promise<void>,
+    private readonly onTick: (remainingSeconds: number) => void,
+    private readonly onEnd: () => void,
+    opts: GracePeriodOpts,
+  ) {
+    this.durationMs = opts.durationMs ?? 30_000;
+  }
+
+  start(): void {
+    this.stop();
+    this.active = true;
+    this.remainingMs = this.durationMs;
+
+    this.timer = setInterval(() => {
+      if (this.paused) return;
+      this.remainingMs -= this.tickMs;
+      this.onTick(Math.max(0, Math.ceil(this.remainingMs / 1000)));
+
+      if (this.remainingMs <= 0) {
+        this.stop();
+        this.onExpired().catch((err) => {
+          log.error("[GracePeriodManager] onExpired error:", err);
+        });
+      }
+    }, this.tickMs);
+
+    this.onTick(Math.ceil(this.remainingMs / 1000));
+    log.info(`[grace-period] started (${this.durationMs}ms)`);
+  }
+
+  onUserActivity(): void {
+    if (!this.active) return;
+    this.remainingMs = this.durationMs;
+    if (!this.paused) {
+      this.onTick(Math.ceil(this.durationMs / 1000));
+    }
+  }
+
+  pause(): void {
+    this.paused = true;
+  }
+
+  resume(): void {
+    this.paused = false;
+  }
+
+  stop(): void {
+    const wasActive = this.active;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.active = false;
+    this.paused = false;
+    // Only call onEnd if we were actually active — avoids spurious onEnd during start()'s cleanup
+    if (wasActive) this.onEnd();
+  }
+
+  isActive(): boolean {
+    return this.active;
+  }
+
+  getRemainingSeconds(): number {
+    return Math.max(0, Math.ceil(this.remainingMs / 1000));
+  }
+}