supipowers 2.0.2 → 2.1.0

package/src/mempalace/upstream-limits.ts

@@ -0,0 +1,69 @@
+/**
+ * Upstream MemPalace pin.
+ *
+ * Single source of truth for the `mempalace` PyPI package version and
+ * the parameter limits the upstream package enforces. Keeping these in
+ * one place — instead of sprinkling `"3.3.4"` / `500` / `100` / `128`
+ * magic literals across the config defaults, schema, hooks, and tests —
+ * makes a version bump a one-line edit and guarantees our tool surface
+ * advertises the same bounds the upstream MCP server enforces.
+ *
+ * # Bump procedure
+ * 1. Update `MEMPALACE_PACKAGE_VERSION` below.
+ * 2. Re-verify each `MEMPALACE_MAX_*` constant against the cited
+ *    upstream source path. Update any that drifted.
+ * 3. If the upstream MCP API surface (function names, parameter names)
+ *    changed, update the dispatch table in
+ *    `src/mempalace/python/mempalace_bridge.py` and its header comment.
+ * 4. Run `bun ci`. All consumers — including tests — read from these
+ *    constants, so a mismatch surfaces as a test failure rather than
+ *    silent runtime drift.
+ */
+
+/**
+ * Exact PyPI version installed by the managed setup pipeline. Flows into
+ * `DEFAULT_CONFIG.mempalace.packageVersion` and, from there, into the
+ * `mempalace==<version>` argument handed to `uv pip install`.
+ */
+export const MEMPALACE_PACKAGE_VERSION = "3.3.5";
+
+/**
+ * Upper bound applied internally by `tool_search` and `tool_list_drawers`
+ * to the `limit` argument. Any value above this is silently clamped.
+ *
+ * Source: `mempalace/mcp_server.py` `_MAX_RESULTS = 100`.
+ */
+export const MEMPALACE_MAX_RESULTS = 100;
+
+/**
+ * Maximum search-query length. `tool_search` runs `sanitize_query`, which
+ * truncates anything over this threshold (worst case: keeps only the
+ * trailing N characters). Above this, prompt-contamination patterns
+ * start dominating the embedding signal — see upstream Issue #333.
+ *
+ * Source: `mempalace/query_sanitizer.py` `MAX_QUERY_LENGTH = 250`.
+ */
+export const MEMPALACE_MAX_QUERY_LENGTH = 250;
+
+/**
+ * Maximum length for wing / room / predicate / entity-style identifiers.
+ * `sanitize_name` and `sanitize_kg_value` raise `ValueError` above this.
+ *
+ * Source: `mempalace/config.py` `MAX_NAME_LENGTH = 128`.
+ */
+export const MEMPALACE_MAX_NAME_LENGTH = 128;
+
+/**
+ * Maximum drawer / diary content length. `sanitize_content` defaults
+ * to this when no explicit override is passed.
+ *
+ * Source: `mempalace/config.py` `sanitize_content(..., max_length: int = 100_000)`.
+ */
+export const MEMPALACE_MAX_CONTENT_LENGTH = 100_000;
+
+/**
+ * Upper bound applied internally by `tool_traverse_graph` to `max_hops`.
+ *
+ * Source: `mempalace/mcp_server.py` `tool_traverse_graph` — `max(1, min(max_hops, 10))`.
+ */
+export const MEMPALACE_MAX_HOPS = 10;

package/src/planning/approval-flow.ts

@@ -186,7 +186,7 @@ export function buildTodoWriteOpsForPlan(plan: Plan): { ops: TodoWriteOp[] } {
  * When `plan` is provided and has tasks, the prompt also embeds the
  * exact `todo_write` payload the agent must call before doing any work.
  */
-function buildExecutionPrompt(
+export function buildExecutionPrompt(
   planContent: string,
   planPath: string,
   plan?: Plan,
@@ -313,7 +313,7 @@ async function executeApproveFlow(
  */
 export function registerPlanApprovalHook(platform: Platform): void {
   platform.on("agent_end", async (_event: any, ctx: any) => {
-    if (!planningActive || !ctx?.hasUI || approvalPending) return;
+    if (!planningActive || approvalPending) return;
 
     // Detect newly written plan files
     const plansNow = listPlans(platform.paths, planCwd);
@@ -407,6 +407,29 @@ export function registerPlanApprovalHook(platform: Platform): void {
         cwd: planCwd,
       });
     } catch {}
+    if (!ctx?.hasUI) {
+      const message = [
+        `Plan saved to \`${planPath}\`.`,
+        "Interactive approval is unavailable in this runtime, so no execution was started.",
+        `To continue manually, explicitly send: \`Execute the saved plan at ${planPath} step by step; verify each step before proceeding.\``,
+      ].join("\n");
+      debugLogger?.log("approval_flow_no_ui", {
+        planName,
+        planPath,
+      });
+      ctx?.ui?.notify?.("Plan saved; interactive approval is required before execution.", "warning");
+      platform.sendMessage(
+        {
+          customType: "supi-plan-awaiting-interactive-approval",
+          content: [{ type: "text", text: message }],
+          display: true,
+        },
+        { deliverAs: "steer", triggerTurn: false },
+      );
+      cancelPlanTracking();
+      return;
+    }
+
     const approvalOptions = [
       "Approve and execute",
       "Refine plan",

package/src/planning/planning-ask-tool.ts

@@ -4,10 +4,16 @@ import { isUiDesignActive, recordUiDesignReviewApproval } from "../ui-design/ses
 
 /**
  * Register a `planning_ask` tool — identical to the built-in `ask` tool
- * but with **no timeout**. OMP's built-in ask tool applies the user's
- * `ask.timeout` setting (default 30s) and only disables it for OMP's
- * native plan mode. Since `/supi:plan` is not native plan mode, planning
- * questions would auto-dismiss. This tool bypasses that limitation.
+ * but with **no timeout**, regardless of the user's `ask.timeout` setting.
+ * OMP 14.9.5 changed the `ask.timeout` default from 30s to 0 (wait
+ * indefinitely), but a user-configured non-zero value still applies to the
+ * generic `ask` tool; this wrapper keeps planning-mode questions blocking
+ * for any such configuration.
+ *
+ * Also records the chosen option into the ui-design session ledger via
+ * `recordUiDesignReviewApproval` and pairs with
+ * `registerPlanningAskToolGuard`, which redirects generic `ask` calls back
+ * to this tool during planning / ui-design sessions.
  *
  * The tool is always registered (lightweight) but the planning system
  * prompt directs the model to use it only during planning sessions.
@@ -62,6 +68,22 @@ export function registerPlanningAskTool(platform: Platform): void {
         };
       }
 
+      if (ctx?.hasUI === false || typeof ctx?.ui?.select !== "function") {
+        const result = {
+          error: "interactive_planning_question_unavailable",
+          message: "Interactive planning questions cannot be answered in this runtime. Present this question and its options to the user instead of choosing a default.",
+          question: params.question,
+          options: labels,
+          recommended: params.recommended ?? null,
+        };
+        return {
+          content: [{ type: "text", text: JSON.stringify(result) }],
+          details: result,
+          error: true,
+        };
+      }
+
+
       const choice = await ctx.ui.select(params.question, labels, {
         initialIndex: params.recommended,
         // No timeout — planning decisions need unlimited time
@@ -107,6 +129,14 @@ function getAskRedirectReason(): string | null {
  */
 export function registerPlanningAskToolGuard(platform: Platform): void {
   platform.on("tool_call", (event) => {
+    if (event.toolName === "exit_plan_mode" && isPlanningActive()) {
+      return {
+        block: true,
+        reason:
+          "Planning mode: /supi:plan uses a file-based approval hook. Do not call exit_plan_mode because it is OMP's native approval path and bypasses supipowers plan tracking.",
+      };
+    }
+
     if (event.toolName !== "ask") return;
 
     const reason = getAskRedirectReason();

package/src/planning/system-prompt.ts

@@ -233,7 +233,7 @@ function buildPlanningCriticalBlock(options: PlanningSystemPromptOptions): strin
     "## Plan submission",
     "",
     "This is NOT native OMP plan mode.",
-    "You **MUST NOT** call `exit_plan_mode` or `ExitPlanMode` — it will fail.",
+    "You **MUST NOT** call `exit_plan_mode` or `ExitPlanMode` — that is OMP's native approval path and bypasses supipowers' file-based approval hook.",
     `You **MUST NOT** write plans to \`local://PLAN.md\` — that is OMP's native plan location and will not trigger the approval flow.`,
     `You **MUST** save the plan to \`${options.plansDir}/YYYY-MM-DD-<feature-name>.md\` using the Write tool.`,
     "After saving, tell the user the plan path, then **stop and yield your turn**.",

package/src/tool-catalog/active-tool-controller.ts

@@ -4,17 +4,11 @@ import { getMetricsStore, getSessionId } from "../context-mode/hooks.js";
 import { getProjectStateDir } from "../workspace/state-paths.js";
 import type { Platform } from "../platform/types.js";
 import { normalizeSystemPromptBlocks, systemPromptText } from "../platform/system-prompt.js";
-import type { McpRegistry } from "../mcp/types.js";
 import type { SupipowersConfig } from "../types.js";
 import { planActiveTools } from "./active-tool-planner.js";
 import { detectContextMode } from "../context-mode/detector.js";
 import { getShadowedNativeTools } from "../context-mode/routing.js";
 
-export interface ActiveToolControllerDeps {
-  loadMcpRegistryForCwd(cwd: string): McpRegistry;
-  consumePendingTags(): string[];
-}
-
 type BeforeAgentStartEventLike = {
   prompt?: string;
   systemPrompt?: string | string[];
@@ -33,7 +27,6 @@ type BeforeAgentStartContextLike = {
 export function registerActiveToolController(
   platform: Platform,
   config: SupipowersConfig,
-  _deps: ActiveToolControllerDeps,
 ): void {
   if (!config.contextMode.enabled || !config.contextMode.lazyTools.enabled) return;
 
@@ -46,19 +39,6 @@ export function registerActiveToolController(
     if (typeof ctx.getSystemPrompt !== "function") return undefined;
 
     const cwd = typeof ctx.cwd === "string" && ctx.cwd.length > 0 ? ctx.cwd : process.cwd();
-    let registry: McpRegistry = { schemaVersion: 1, servers: {} };
-    try {
-      registry = _deps.loadMcpRegistryForCwd(cwd);
-    } catch (error) {
-      (platform as any).logger?.warn?.("supi-lazy-tools: failed to load MCP registry", error);
-    }
-
-    let pendingTags: string[] = [];
-    try {
-      pendingTags = _deps.consumePendingTags();
-    } catch (error) {
-      (platform as any).logger?.warn?.("supi-lazy-tools: failed to consume MCP tags", error);
-    }
 
     let plan;
     try {
@@ -67,8 +47,6 @@ export function registerActiveToolController(
         currentActive: platform.getActiveTools(),
         allTools: platform.getAllTools(),
         lazyTools: config.contextMode.lazyTools,
-        mcpServers: registry.servers,
-        pendingTags,
         cacheHandlesEnabled: config.contextMode.cacheHandles.enabled,
       });
     } catch (error) {

package/src/tool-catalog/active-tool-planner.ts

@@ -1,10 +1,7 @@
-import { computeActiveServers } from "../mcp/activation.js";
-import type { ServerConfig } from "../mcp/types.js";
 import type { ContextModeLazyToolsConfig } from "../types.js";
 import {
   BALANCED_KEYWORD_TOOLS,
   CONTEXT_MODE_TOOL_NAMES,
-  MCPC_MANAGER_TOOL_NAME,
   isSupiOwnedTool,
   orderOwnedTools,
 } from "./tool-groups.js";
@@ -12,8 +9,6 @@ import {
 export interface ActiveToolPlannerDiagnostics {
   unknownConfiguredTools: string[];
   unavailableTools: string[];
-  unmatchedTags: string[];
-  missingMcpGatewayTools: string[];
 }
 
 export interface PlanActiveToolsInput {
@@ -21,8 +16,6 @@ export interface PlanActiveToolsInput {
   currentActive: string[];
   allTools: string[];
   lazyTools: ContextModeLazyToolsConfig;
-  mcpServers?: Record<string, ServerConfig>;
-  pendingTags?: string[];
   cacheHandlesEnabled?: boolean;
 }
 
@@ -41,8 +34,6 @@ export function planActiveTools(input: PlanActiveToolsInput): ActiveToolPlan {
   const diagnostics: ActiveToolPlannerDiagnostics = {
     unknownConfiguredTools: [],
     unavailableTools: [],
-    unmatchedTags: [],
-    missingMcpGatewayTools: [],
   };
 
   const addRegisteredTool = (toolName: string, source: "config" | "policy"): void => {
@@ -69,7 +60,6 @@ export function planActiveTools(input: PlanActiveToolsInput): ActiveToolPlan {
     for (const toolName of CONTEXT_MODE_TOOL_NAMES) {
       if (!RARE_CONTEXT_TOOLS.has(toolName)) addRegisteredTool(toolName, "policy");
     }
-    addRegisteredTool(MCPC_MANAGER_TOOL_NAME, "policy");
   }
 
   for (const toolName of getTriggeredTools(input.prompt, BALANCED_KEYWORD_TOOLS)) {
@@ -81,20 +71,6 @@ export function planActiveTools(input: PlanActiveToolsInput): ActiveToolPlan {
   }
 
 
-  const mcpServers = input.mcpServers ?? {};
-  const pendingTags = input.pendingTags ?? [];
-  const knownServerNames = new Set(Object.keys(mcpServers));
-  for (const tag of pendingTags) {
-    if (!knownServerNames.has(tag)) diagnostics.unmatchedTags.push(tag);
-  }
-  for (const serverName of computeActiveServers(mcpServers, input.prompt, pendingTags)) {
-    const gatewayToolName = `mcpc_${serverName}`;
-    if (registeredOwnedTools.has(gatewayToolName)) {
-      selectedOwnedTools.add(gatewayToolName);
-    } else {
-      diagnostics.missingMcpGatewayTools.push(gatewayToolName);
-    }
-  }
   for (const toolName of getCommandAllowlistTools(input.prompt, input.lazyTools.commandAllowlist)) {
     addRegisteredTool(toolName, "config");
   }
@@ -206,7 +182,5 @@ function dedupeDiagnostics(diagnostics: ActiveToolPlannerDiagnostics): ActiveToo
   return {
     unknownConfiguredTools: [...new Set(diagnostics.unknownConfiguredTools)],
     unavailableTools: [...new Set(diagnostics.unavailableTools)],
-    unmatchedTags: [...new Set(diagnostics.unmatchedTags)],
-    missingMcpGatewayTools: [...new Set(diagnostics.missingMcpGatewayTools)],
   };
 }

package/src/tool-catalog/tool-groups.ts

@@ -14,9 +14,6 @@ export const CONTEXT_MODE_TOOL_NAMES = [
 
 export type ContextModeToolName = (typeof CONTEXT_MODE_TOOL_NAMES)[number];
 
-export const MCPC_MANAGER_TOOL_NAME = "mcpc_manager";
-export const MCPC_TOOL_PREFIX = "mcpc_";
-
 export const OWNED_TOOL_PRIORITY = [
   "ctx_execute",
   "ctx_search",
@@ -29,7 +26,6 @@ export const OWNED_TOOL_PRIORITY = [
   "ctx_purge",
   "ctx_repomap",
   "ctx_symbol",
-  MCPC_MANAGER_TOOL_NAME,
 ] as const;
 
 const CONTEXT_MODE_TOOL_SET = new Set<string>(CONTEXT_MODE_TOOL_NAMES);
@@ -81,12 +77,8 @@ export function isContextModeTool(name: string): boolean {
   return CONTEXT_MODE_TOOL_SET.has(name);
 }
 
-export function isMcpcGatewayTool(name: string): boolean {
-  return name.startsWith(MCPC_TOOL_PREFIX) && /^mcpc_[^_].+/.test(name);
-}
-
 export function isSupiOwnedTool(name: string): boolean {
-  return isContextModeTool(name) || name === MCPC_MANAGER_TOOL_NAME || isMcpcGatewayTool(name);
+  return isContextModeTool(name);
 }
 
 export function orderOwnedTools(names: Iterable<string>): string[] {

package/src/types.ts

@@ -545,12 +545,6 @@ export interface ContextModeConfig {
   memory: ContextModeMemoryConfig;
 }
 
-/** MCP management settings */
-export interface McpManagementConfig {
-  /** Close mcpc sessions on agent shutdown (default: false) */
-  closeSessionsOnExit: boolean;
-}
-
 /** MemPalace native integration default wing derivation mode */
 export type MempalaceWingStrategy = "repo-name" | "project-slug" | "explicit";
 
@@ -590,10 +584,19 @@ export interface MempalaceConfig {
      * one-line refresher instead. `1` = always inject (legacy behavior).
      */
     wakeUpInjectionEvery: number;
+    /** Minimum cosine similarity (0–1) for a hit to be injected by auto-search. Default 0.55. */
+    autoSearchSimilarityFloor: number;
+    /** Minimum BM25 score for a hit to be injected by auto-search. Default 0.3. */
+    autoSearchBm25Floor: number;
   };
   timeouts: {
     setupMs: number;
     bridgeMs: number;
+    /**
+     * Per-hook bridge timeout in milliseconds. Keep this at or above 6000
+     * when autoSearchOnPrompt is enabled; MemPalace 3.3.5 can sleep before
+     * retrying a transient search-index lookup.
+     */
     hookMs: number;
   };
 }
@@ -665,7 +668,6 @@ export interface SupipowersConfig {
   };
   ultraplan: UltraPlanConfig;
   contextMode: ContextModeConfig;
-  mcp: McpManagementConfig;
   mempalace: MempalaceConfig;
 }
 
@@ -1542,6 +1544,7 @@ export type HarnessStage =
   | "design"
   | "plan"
   | "implement"
+  | "docs"
   | "validate";
 
 /** Operational status of a harness stage. Mirrors UltraPlanAuthoringStageStatus. */
@@ -1682,6 +1685,38 @@ export interface HarnessConfig {
   backend?: HarnessAntiSlopBackend;
   /** Threshold above which Implement defers to ultraplan batch. Default 10. */
   implement_in_session_threshold?: number;
+  /** Per-layer agent-docs stage config. Absent → defaults treated as "simple" tier. */
+  docs?: HarnessDocsConfig;
+}
+
+/** Per-layer agent-docs configuration. */
+export interface HarnessDocsConfig {
+  /**
+   * Doc tier toggle. `simple` makes the `docs` stage a no-op (Tier 1 docs unchanged);
+   * `extensive` fans out one subagent per layer to produce `docs/layers/<id>.md` and a
+   * mechanical `docs/README.md` index.
+   */
+  tier: "simple" | "extensive";
+  /** Hard cap on total LOC per per-layer doc, including frontmatter. Default 150. */
+  max_per_doc_loc: number;
+  /** Hard cap on the `## Agent context` section LOC. Default 30. */
+  agent_context_loc: number;
+  /** Hard cap on `docs/README.md` LOC. Default 50. */
+  max_index_loc: number;
+  /** Defensive cap on the number of layers the stage will process. Default 12. */
+  max_units: number;
+  /**
+   * Concurrency cap for subagent dispatch. `null` = unbounded (bounded only by `max_units`);
+   * any positive integer caps `Promise.all` parallelism.
+   */
+  max_concurrent_subagents: number | null;
+  /** Validate-stage drift warning toggle. */
+  drift_warning: { enabled: boolean };
+  /**
+   * Minimum stale-layer count before bare-entry Harden surfaces the pre-regen preview.
+   * Default 1 (always show when any layer is stale).
+   */
+  regen_preview_threshold: number;
 }
 
 /** Discover artifact (`<session>/discover.json`). */
@@ -1704,7 +1739,6 @@ export interface HarnessDiscoverArtifact {
     hasSupipowers: boolean;
     skills: string[];
     reviewAgents: string[];
-    mcpServers: string[];
     plansCount: number;
   };
   /** Existing anti-slop tooling. */
@@ -1762,6 +1796,18 @@ export interface HarnessQualityGate {
   failSafe: string;
 }
 
+/** Configuration for the PR sticky comment posted by `/supi:harness pr-comment`. */
+export interface HarnessPrCommentConfig {
+  /** When false, the workflow step is a no-op (still safe to call). */
+  enabled: boolean;
+  /**
+   * Post cadence:
+   *  - "every-push": update the sticky comment on every CI run.
+   *  - "on-status-change": only re-post when status (passed/warned/failed) flips.
+   */
+  mode: "every-push" | "on-status-change";
+}
+
 /** CI and local counterpart wiring chosen during harness design. */
 export interface HarnessCiConfig {
   provider: "github-actions";
@@ -1772,6 +1818,14 @@ export interface HarnessCiConfig {
   localCommand: string;
   /** CI workflow path relative to repo root. */
   workflowPath: string;
+  /**
+   * Optional PR comment behaviour. When absent the subcommand falls back to built-in
+   * defaults (mode `every-push`); the explicit invocation of `/supi:harness pr-comment`
+   * is treated as the user opt-in. Set `enabled: false` to suppress posting outside
+   * `--dry-run`. The CI workflow permission warning in `ci-local-wiring` is gated on
+   * an explicit truthy `enabled`, so legacy specs do not trip it.
+   */
+  prComment?: HarnessPrCommentConfig;
 }
 
 
@@ -1880,6 +1934,8 @@ export interface HarnessSession {
   iteration: number;
   /** Re-run mode user chose at bare entry (when applicable). */
   reRunMode?: HarnessReRunMode;
+  /** Per-layer agent-docs tier resolved at end-of-Design. Absent → treated as "simple". */
+  docsTier?: "simple" | "extensive";
   /** Recorded blocker, if any. */
   blocker: { code: string; message: string; detectedAt: string } | null;
   /** Artifacts produced so far (relative to <session>/). */
@@ -1895,6 +1951,29 @@ export interface HarnessArtifactRefs {
   plan?: string;
   implementLog?: string;
   validateReport?: string;
+  /** Per-layer agent docs (relative to <session>/docs/layers/<id>.md). */
+  docs?: { layerId: string; path: string }[];
+}
+
+/**
+ * Metadata describing a single per-layer agent knowledge document. Used by the docs stage
+ * to track provenance, source-hash invalidation, and atomic promotion to the repo. The
+ * canonical rendered doc lives at `docs/layers/<id>.md`; this record is part of the
+ * stage's run result and the session staging artifacts.
+ */
+export interface HarnessDocsArtifact {
+  /** Layer id this doc covers (matches HarnessLayerRule.layer). */
+  layerId: string;
+  /** Layer glob list, copied verbatim from the layer rule at render time. */
+  layerGlobs: string[];
+  /** Hash of every input that should invalidate the doc when changed. */
+  sourceHash: string;
+  /** Hash of the doc body after the provenance marker (excludes the marker itself). */
+  contentHash: string;
+  /** ISO timestamp the doc was generated. */
+  generatedAt: string;
+  /** Session that generated the doc. */
+  sessionId: string;
 }
 
 /** Append-only pipeline log entry. */

package/src/ui-design/session.ts

@@ -108,15 +108,19 @@ function snapshotSessionProgress(sessionDir: string): string | null {
     for (const entry of entries) {
       const absolutePath = path.join(currentDir, entry.name);
       const relativePath = path.relative(sessionDir, absolutePath);
-      const stats = fs.statSync(absolutePath);
-
       if (entry.isDirectory()) {
-        hash.update(`dir:${relativePath}:${stats.mtimeMs}\n`);
+        hash.update("dir\0");
+        hash.update(relativePath);
+        hash.update("\0");
         visit(absolutePath);
         continue;
       }
 
-      hash.update(`file:${relativePath}:${stats.size}:${stats.mtimeMs}\n`);
+      hash.update("file\0");
+      hash.update(relativePath);
+      hash.update("\0");
+      hash.update(fs.readFileSync(absolutePath));
+      hash.update("\0");
     }
   };
 
@@ -765,6 +769,106 @@ function discardSessionDir(sessionDir: string): void {
   }
 }
 
+function buildCompletionRepairSteer(
+  sessionDir: string,
+  manifest: Manifest,
+  completionIssues: string[],
+): string {
+  return manifest.backend === "pencil-mcp"
+    ? REPAIR_COMPLETE_STEER_TEMPLATE_PENCIL(sessionDir, manifest.penFilePath, completionIssues)
+    : REPAIR_COMPLETE_STEER_TEMPLATE(sessionDir, completionIssues);
+}
+
+function sendNoUiPauseMessage(
+  platform: Platform,
+  sessionDir: string,
+  status: ManifestStatus,
+): void {
+  const message = [
+    `ui-design session paused with status \`${status}\` in a no-UI runtime.`,
+    `Artifacts were preserved at \`${sessionDir}\`.`,
+    "Interactive review is unavailable here. Continue manually by inspecting that directory or rerun `/supi:ui-design` in an interactive TUI.",
+  ].join("\n");
+  platform.sendMessage(
+    {
+      customType: "supi-ui-design-paused-no-ui",
+      content: [{ type: "text", text: message }],
+      display: true,
+    },
+    { deliverAs: "steer", triggerTurn: false },
+  );
+}
+
+async function handleNoUiUiDesignAgentEnd(
+  platform: Platform,
+  ctx: any,
+  session: UiDesignSession,
+  manifest: Manifest | null,
+): Promise<void> {
+  const sessionDir = session.dir;
+
+  if (!manifest) {
+    await runCleanup();
+    ctx?.ui?.notify?.(
+      `ui-design session state is unreadable; artifacts preserved at ${sessionDir}.`,
+      "warning",
+    );
+    cancelUiDesignTracking("manifest_missing_no_ui");
+    return;
+  }
+
+  if (manifest.status === "complete") {
+    const completion = validateCompletionProof(sessionDir, manifest);
+    const validatedManifest = completion.validatedManifest;
+    if (
+      !sameCritiqueSummary(manifest.critique, validatedManifest.critique) ||
+      manifest.approvedAt !== validatedManifest.approvedAt
+    ) {
+      writeManifest(sessionDir, validatedManifest);
+    }
+
+    if (completion.issues.length > 0) {
+      await resumeSession(
+        platform,
+        ctx,
+        session,
+        buildCompletionRepairSteer(sessionDir, manifest, completion.issues),
+      );
+      return;
+    }
+
+    writeManifest(sessionDir, { ...validatedManifest, acknowledged: true });
+    await runCleanup();
+    ctx?.ui?.notify?.(`ui-design complete; artifacts kept at ${sessionDir}.`, "info");
+    cancelUiDesignTracking("complete_no_ui");
+    return;
+  }
+
+  if (manifest.status === "discarded") {
+    await runCleanup();
+    discardSessionDir(sessionDir);
+    cancelUiDesignTracking("discarded_no_ui");
+    return;
+  }
+
+  if (
+    manifest.status === "in-progress" ||
+    manifest.status === "critiquing" ||
+    manifest.status === "awaiting-review"
+  ) {
+    if (sessionMadeProgress(sessionDir)) {
+      await resumeSession(platform, ctx, session, RESUME_STEER_TEMPLATE(sessionDir));
+      return;
+    }
+
+    sendNoUiPauseMessage(platform, sessionDir, manifest.status);
+    ctx?.ui?.notify?.(`ui-design paused; artifacts preserved at ${sessionDir}.`, "warning");
+    await runCleanup();
+    cancelUiDesignTracking("paused_no_ui");
+  }
+}
+
+
 function getUiDesignWritePaths(toolName: string, input: Record<string, unknown>): string[] | undefined {
   switch (toolName) {
     case "write":
@@ -850,11 +954,15 @@ export function registerUiDesignToolGuard(platform: Platform): void {
 export function registerUiDesignApprovalHook(platform: Platform): void {
   platform.on("agent_end", async (_event: any, ctx: any) => {
     const session = activeSession;
-    if (!session || !ctx?.hasUI) return;
+    if (!session) return;
 
     const sessionDir = session.dir;
     const manifest = readManifest(sessionDir);
 
+    if (!ctx?.hasUI) {
+      await handleNoUiUiDesignAgentEnd(platform, ctx, session, manifest);
+      return;
+    }
     // Missing / unparseable manifest — unsafe to resume
     if (!manifest) {
       const choice = await ctx.ui.select(
@@ -888,9 +996,7 @@ export function registerUiDesignApprovalHook(platform: Platform): void {
           // Pencil manifests always cite pencil artifacts in their repair steer,
           // even when `penFilePath` is missing — the HTML template would point
           // at files pencil sessions never produce.
-          const repairSteer = manifest.backend === "pencil-mcp"
-            ? REPAIR_COMPLETE_STEER_TEMPLATE_PENCIL(sessionDir, manifest.penFilePath, completion.issues)
-            : REPAIR_COMPLETE_STEER_TEMPLATE(sessionDir, completion.issues);
+          const repairSteer = buildCompletionRepairSteer(sessionDir, manifest, completion.issues);
           await resumeSession(
             platform,
             ctx,