Address initial 0.4.5 issue feedback

Author: tomismeta

README.md

@@ -46,6 +46,12 @@ Then install the plugin with the command above.
 
 After install, open Paperclip and use the `Focus` entry in the sidebar.
 
+## Troubleshooting
+
+- If the sidebar shows a bordered placeholder instead of a native `Focus` entry, upgrade to Paperclip `2026.517.0` or newer and reinstall this plugin. `0.4.5` declares a host-rendered sidebar launcher instead of a custom sidebar slot.
+- `paperclipApiBase` is only needed for approval overlays. Use the Paperclip origin such as `https://HOST` or `http://127.0.0.1:3100`; leaving it empty disables approval overlay reads without disabling Focus.
+- On Windows, `spawn npm ENOENT` during `npx paperclipai plugin install @tomismeta/paperclip-aperture` comes from the Paperclip host installer failing to spawn npm. This package does not spawn npm during install. Make sure the Paperclip process can resolve `npm.cmd`, or upgrade Paperclip once the Windows installer fix is available.
+
 ## Napkin Diagram
 
 ```text

docs/RELEASE-0.4.5.md

@@ -12,6 +12,9 @@ uses the newer host attention contracts where they improve Focus judgment.
 - keeps planning-mode blockers calmer unless the host marks them urgent
 - preserves document lock metadata in review handoff copy and diagnostics
 - excludes plugin-operation issues from host reconciliation scans
+- uses a host-rendered sidebar launcher for the Focus entry
+- makes agent run failure cards acknowledgeable and clears issue-linked failures when the issue moves on
+- documents the Windows `spawn npm ENOENT` Paperclip installer failure mode
 
 ## Why This Matters
 
@@ -21,6 +24,8 @@ uses the newer host attention contracts where they improve Focus judgment.
   contracts
 - improves operator clarity around locked review artifacts and planning-mode
   work without changing the plugin boundary
+- closes the feedback loop for stale failure cards and broken sidebar entry
+  reports from early `0.4.4` installs
 
 ## Validation
 

src/aperture/event-mapper.ts

@@ -66,6 +66,15 @@ function makeTaskId(event: MappablePluginEvent): string {
   return createTaskId(entityType, entityId);
 }
 
+function relatedIssueTaskId(payload: unknown): string | null {
+  const issueId =
+    readPayloadString(payload, "issueId")
+    ?? readPayloadString(payload, "sourceIssueId")
+    ?? readPayloadString(payload, "parentIssueId")
+    ?? readStringArray(payload, "issueIds")?.[0];
+  return issueId ? createTaskId("issue", issueId) : null;
+}
+
 function makeSource(event: MappablePluginEvent): SourceRef {
   const entityType = event.entityType ?? "event";
 
@@ -452,41 +461,33 @@ export function mapPluginEventToAperture(event: MappablePluginEvent): ApertureEv
 
     case "agent.run.failed":
       {
+        const failureTaskId = relatedIssueTaskId(event.payload) ?? taskId;
         const title = readPayloadString(event.payload, "title") ?? "Agent run failed";
         const summary = readPayloadString(event.payload, "summary") ?? runFailedSummary();
         return {
         id: `${event.eventId}:run-failed`,
-        type: "human.input.requested",
-        taskId,
-        interactionId: createInteractionId(taskId, "run-failed"),
+        type: "task.updated",
+        taskId: failureTaskId,
         timestamp: event.occurredAt,
         source,
         toolFamily: "paperclip",
         activityClass: "tool_failure",
+        status: "failed",
         title,
         summary,
-        consequence: "high",
-        tone: "critical",
-        request: { kind: "approval" },
         semantic: interpretEventSemantic({
           id: `${event.eventId}:run-failed`,
-          type: "human.input.requested",
-          taskId,
-          interactionId: createInteractionId(taskId, "run-failed"),
+          type: "task.updated",
+          taskId: failureTaskId,
           timestamp: event.occurredAt,
           source,
           toolFamily: "paperclip",
           activityClass: "tool_failure",
           title,
           summary,
-          request: { kind: "approval" },
-          riskHint: "high",
+          status: "failed",
           semanticHints: runFailureSemanticHints(),
         }),
-        provenance: {
-          whyNow: runFailedWhyNow(),
-          factors: ["run failed", "operator review"],
-        },
       };
       }
 

src/manifest.ts

@@ -62,18 +62,29 @@ const manifest: PaperclipPluginManifestV1 = {
         exportName: "AttentionPage",
         routePath: "aperture"
       },
-      {
-        type: "sidebar",
-        id: "attention-sidebar-link",
-        displayName: "Focus",
-        exportName: "AttentionSidebarLink"
-      },
       {
         type: "dashboardWidget",
         id: "attention-widget",
         displayName: "Focus",
         exportName: "DashboardWidget"
       }
+    ],
+    launchers: [
+      {
+        id: "focus-sidebar",
+        displayName: "Focus",
+        description: "Open the Paperclip Aperture Focus surface.",
+        placementZone: "sidebar",
+        order: 40,
+        action: {
+          type: "navigate",
+          target: "/aperture"
+        },
+        render: {
+          environment: "hostRoute",
+          bounds: "full"
+        }
+      }
     ]
   }
 };

src/ui/frame-helpers.tsx

@@ -196,7 +196,14 @@ export function responseKind(frame: StoredAttentionFrame, lane: FrameLane): "app
     return "approval";
   }
 
-  if (lane !== "ambient" && (frame.responseSpec?.kind === "acknowledge" || frame.mode === "status")) {
+  if (
+    lane !== "ambient"
+    && (
+      frame.responseSpec?.kind === "acknowledge"
+      || frame.mode === "status"
+      || frame.responseSpec?.kind === "approval"
+    )
+  ) {
     return "acknowledge";
   }
 

src/ui/index.tsx

@@ -1,6 +1,5 @@
 import {
   type PluginPageProps,
-  type PluginSidebarProps,
   type PluginWidgetProps,
 } from "@paperclipai/plugin-sdk/ui";
 import { useEffect, useMemo, useState } from "react";
@@ -17,7 +16,6 @@ import {
   GENERIC_QUEUED_JUDGMENT,
 } from "../aperture/attention-language.js";
 import {
-  ACCENT_BG_STYLE,
   ACCENT_BORDER,
   ACCENT_COLOR,
   Accent,
@@ -35,7 +33,6 @@ import {
   useWideLayout,
 } from "./chrome.js";
 import {
-  actionableCount,
   actionableLabel,
   currentSurfaceBrand,
   formatRelativeTime,
@@ -45,7 +42,6 @@ import {
   type Posture,
   type QueueMovement,
   type SurfaceBrand,
-  unreadCount,
   useAttentionModel,
   useQueueMovement,
 } from "./focus-model.js";
@@ -764,73 +760,6 @@ export function DashboardWidget(props: PluginWidgetProps) {
   );
 }
 
-// ---------------------------------------------------------------------------
-// Sidebar link — already Paperclip-native
-// ---------------------------------------------------------------------------
-
-export function AttentionSidebarLink({ context }: PluginSidebarProps) {
-  const companyId = context.companyId;
-  const brand = currentSurfaceBrand();
-  const href = pluginPagePath(context.companyPrefix);
-  const isActive = typeof window !== "undefined" && window.location.pathname === href;
-  const model = useAttentionModel(companyId);
-  const merged = model.snapshot;
-  const actionable = merged ? actionableCount(merged) : 0;
-  const unread = unreadCount(merged);
-
-  return (
-    <a
-      href={href}
-      aria-current={isActive ? "page" : undefined}
-      className={cn(
-        "flex items-center gap-2.5 px-3 py-2 text-[13px] font-medium transition-colors",
-        isActive
-          ? "bg-accent text-foreground"
-          : "text-foreground/80 hover:bg-accent/50 hover:text-foreground",
-      )}
-    >
-      <span className="relative shrink-0" aria-hidden="true">
-        <svg
-          viewBox="0 0 24 24"
-          className="h-4 w-4"
-          fill="none"
-          stroke="currentColor"
-          strokeWidth="1.9"
-          strokeLinecap="round"
-          strokeLinejoin="round"
-        >
-          <circle cx="12" cy="12" r="9" />
-          <path d="m14.3 8 5.2 9" />
-          <path d="M9.7 8h10.4" />
-          <path d="m7.4 12 5.2-9" />
-          <path d="m9.7 16-5.2-9" />
-          <path d="M14.3 16H3.9" />
-          <path d="m16.6 12-5.2 9" />
-        </svg>
-        {unread > 0 ? (
-          <span
-            className="absolute -right-1 -top-1 h-2 w-2 rounded-full"
-            style={{ backgroundColor: ACCENT_COLOR }}
-          />
-        ) : null}
-      </span>
-      <span className="flex-1 truncate">{brand.wordmark}</span>
-      {actionable > 0 ? (
-        <span className="inline-flex items-center justify-center rounded-full px-1.5 py-0.5 text-xs leading-none font-medium text-white" style={ACCENT_BG_STYLE}>
-          {actionable}
-        </span>
-      ) : unread > 0 ? (
-          <span
-            className="inline-flex items-center justify-center rounded-full border px-1.5 py-0.5 text-xs leading-none font-medium"
-            style={{ color: ACCENT_COLOR, borderColor: ACCENT_BORDER, backgroundColor: "transparent" }}
-          >
-            {unread}
-          </span>
-      ) : null}
-    </a>
-  );
-}
-
 // ---------------------------------------------------------------------------
 // Attention page — single-column, calm operator surface
 // ---------------------------------------------------------------------------

tests/plugin.spec.ts

@@ -9,8 +9,10 @@ import type {
   AttentionReplayScenario,
   AttentionReviewState,
   AttentionSnapshot,
+  StoredAttentionFrame,
 } from "../src/aperture/types.js";
 import type { ApprovalRecord } from "../src/aperture/approval-frames.js";
+import { responseKind } from "../src/ui/frame-helpers.js";
 import plugin from "../src/worker.js";
 import {
   ATTENTION_STATE_KEY,
@@ -258,6 +260,21 @@ function mockApprovalApi(
 }
 
 describe("paperclip aperture", () => {
+  it("declares a host-rendered Focus sidebar launcher", () => {
+    expect(manifest.ui?.slots?.some((slot) => slot.type === "sidebar")).toBe(false);
+    expect(manifest.ui?.launchers).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        id: "focus-sidebar",
+        displayName: "Focus",
+        placementZone: "sidebar",
+        action: expect.objectContaining({
+          type: "navigate",
+          target: "/aperture",
+        }),
+      }),
+    ]));
+  });
+
   it("maps approval events into attention state and clears them on acknowledgement", async () => {
     const harness = createTestHarness({ manifest });
     await plugin.definition.setup(harness.ctx);
@@ -463,6 +480,73 @@ describe("paperclip aperture", () => {
     const snapshot = await harness.getData<AttentionSnapshot>("attention-summary", { companyId: "company-2" });
     expect(snapshot.now?.consequence).toBe("high");
     expect(snapshot.now?.title).toContain("Build failed");
+    expect(snapshot.now?.mode).toBe("status");
+    expect(snapshot.now?.responseSpec?.kind).toBe("acknowledge");
+  });
+
+  it("clears issue-linked run failures when the issue moves out of an actionable state", async () => {
+    const harness = createTestHarness({ manifest });
+    await plugin.definition.setup(harness.ctx);
+
+    await harness.emit(
+      "agent.run.failed",
+      {
+        issueId: "issue-77",
+        title: "Issue run failed",
+        summary: "The issue run failed during validation.",
+      },
+      { companyId: "company-run-issue", entityId: "run-77", entityType: "run" },
+    );
+
+    const failed = await harness.getData<AttentionSnapshot>("attention-summary", { companyId: "company-run-issue" });
+    expect(failed.now?.taskId).toBe("issue:issue-77");
+    expect(failed.now?.responseSpec?.kind).toBe("acknowledge");
+
+    await harness.emit(
+      "issue.updated",
+      {
+        title: "Issue run recovered",
+        status: "done",
+        summary: "The issue is done.",
+      },
+      { companyId: "company-run-issue", entityId: "issue-77", entityType: "issue" },
+    );
+
+    const recovered = await harness.getData<AttentionSnapshot>("attention-summary", { companyId: "company-run-issue" });
+    expect(recovered.now).toBeNull();
+    expect(recovered.next).toHaveLength(0);
+  });
+
+  it("keeps legacy non-approval approval frames acknowledgeable", () => {
+    const frame: StoredAttentionFrame = {
+      id: "frame:run:run-77:run-failed",
+      taskId: "run:run-77",
+      interactionId: "run:run-77:run-failed",
+      source: {
+        id: "paperclip:run",
+        kind: "paperclip",
+        label: "Paperclip run",
+      },
+      version: 1,
+      mode: "approval",
+      tone: "critical",
+      consequence: "high",
+      title: "Build failed",
+      summary: "The deploy pipeline crashed during tests.",
+      responseSpec: {
+        kind: "approval",
+        actions: [
+          { id: "approve", label: "Approve", kind: "approve", emphasis: "primary" },
+          { id: "reject", label: "Reject", kind: "reject", emphasis: "danger" },
+        ],
+      },
+      timing: {
+        createdAt: "2026-05-08T09:21:47.000Z",
+        updatedAt: "2026-05-08T09:21:47.000Z",
+      },
+    };
+
+    expect(responseKind(frame, "now")).toBe("acknowledge");
   });
 
   it("preserves budget override semantics for approval frames", async () => {