codedeck 0.6.0 → 0.7.1

package/dist/plugin/agents/general.md

@@ -26,7 +26,7 @@ description: Do CodeDeck work directly in the current workspace, with evidence.
 
 - Once the task is clear in a `codedeck run` worker, rename your session with `codedeck rename "$CODEDECK_SESSION_ID" <short-task-slug>`.
 
-<!-- Source: ~/.claude/skills/commit/SKILL.md (vendored full text). Adaptations: (1) the create-branch skill reference is a one-line main/master rule below, the skill itself is not vendored; (2) any sentry-skills:commit reference points to the Commits section in this prompt; (3) Co-Authored-By names the harness that did the work, not Claude. -->
+<!-- Generated from skills/commit/SKILL.md by scripts/copy-plugin.mjs. Edit the skill, not the agent file. -->
 
 ## Commits
 
@@ -172,7 +172,7 @@ Reason: Caused performance regression in production.
 
 - [Sentry Commit Messages](https://develop.sentry.dev/engineering-practices/commit-messages/)
 
-<!-- Source: ~/.claude/skills/pr-writer/SKILL.md (vendored full text). Adaptations: (1) the create-branch skill reference is a one-line main/master rule, the skill itself is not vendored; (2) the sentry-skills:commit reference below points to the Commits section in this prompt; (3) Co-Authored-By names the harness that did the work, not Claude. -->
+<!-- Generated from skills/pr-writer/SKILL.md by scripts/copy-plugin.mjs. Edit the skill, not the agent file. -->
 
 ## Pull requests
 
@@ -251,6 +251,7 @@ Use this structure for PR descriptions (ignoring any repository PR templates):
 - Links to relevant issues or tickets
 - Context that isn't obvious from the code
 - Notes on specific areas that need careful review
+- Visual evidence when it passes the gate in Visual Evidence below
 
 ### Step 4: Create the PR
 
@@ -321,6 +322,36 @@ Reference issues in the PR body:
 | `Refs GH-1234` | Links without closing |
 | `Refs LINEAR-ABC-123` | Links Linear issue |
 
+## Visual Evidence
+
+Default to none. Add a visual only when a reviewer would otherwise have to check out the branch to see the change, or when the text needs a paragraph to describe what one picture shows. One visual per PR is the norm; never add one to fill space.
+
+| Change | Evidence |
+|--------|----------|
+| UI layout or styling | Screenshot, before/after when it changes existing UI |
+| Interaction or animation | GIF, 15s or less |
+| CLI/TUI output | Fenced text block with the real output, not a screenshot |
+| New flow across 3+ components, or a changed state machine | Mermaid diagram |
+| Refactor, config, deps, internal bug fix, tests | None |
+
+Rules:
+- Capture from the running app (Playwright for web, `ffmpeg` to turn a recording into a GIF). Never mock, edit or stage a screenshot.
+- A Mermaid diagram shows the mechanism the PR adds or changes, not the whole system. GitHub renders ` ```mermaid ` blocks natively.
+- Put each visual under the sentence it supports, with a one-line caption.
+
+Hosting images: `gh` cannot upload attachments, so push them to an orphan `pr-assets` branch and link them. Never commit them to the PR branch.
+
+```bash
+B=$(git branch --show-current)
+git fetch -q origin pr-assets:pr-assets 2>/dev/null || git branch pr-assets "$(git commit-tree "$(git mktree </dev/null)" -m 'chore: Start PR assets')"
+d=$(mktemp -d); git worktree add -q "$d" pr-assets
+mkdir -p "$d/$B"; cp shot.png "$d/$B/"
+git -C "$d" add -A && git -C "$d" commit -qm "chore: Add PR assets for $B" && git -C "$d" push -q origin pr-assets
+git worktree remove "$d"
+```
+
+Link as `![caption](https://github.com/OWNER/REPO/blob/pr-assets/BRANCH/shot.png?raw=true)`. This form also renders on private repos. For a video that must stay a video, leave the file path in your report and say the user has to drag it into the PR on GitHub.
+
 ## Guidelines
 
 - **One PR per feature/fix** - Don't bundle unrelated changes
@@ -338,14 +369,10 @@ gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER -f body="$(cat <<'EOF'
 Updated description here
 EOF
 )"
-```
 
-```bash
 # Update PR title
 gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER -f title='new: Title here'
-```
 
-```bash
 # Update both
 gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \
   -f title='new: Title' \

package/dist/plugin/hooks/pane-ticker.ts

@@ -0,0 +1,102 @@
+import type { PaneSnapshot } from "../mods/agents/types.js";
+
+const TICK_INTERVAL_MS = 1000;
+const REFRESH_INTERVAL_MS = 5000;
+const LIVE_STATUSES = new Set(["working", "starting", "needs_input"]);
+
+export interface PaneTickerOptions {
+  now: () => number;
+  setInterval: (callback: () => void, milliseconds: number) => unknown;
+  clearInterval: (handle: unknown) => void;
+  invalidate: () => unknown;
+  refresh: () => unknown;
+}
+
+export interface PaneTicker {
+  update(paneOpen: boolean, snapshot: PaneSnapshot | undefined): void;
+  refreshed(): void;
+}
+
+/** Schedules pane redraws and refresh requests while any worker card is live. */
+export function createPaneTicker(options: PaneTickerOptions): PaneTicker {
+  let running = false;
+  let handle: unknown;
+  let lastRefreshAt = 0;
+
+  const invoke = (action: () => unknown) => {
+    try {
+      void Promise.resolve(action()).catch(() => {});
+    } catch {
+      // Hook failures drop the drawing, so timer work must stay contained.
+    }
+  };
+
+  const tick = () => {
+    if (!running) return;
+    try {
+      invoke(options.invalidate);
+      const now = options.now();
+      if (!Number.isFinite(now) || now - lastRefreshAt < REFRESH_INTERVAL_MS) return;
+      lastRefreshAt = now;
+      invoke(options.refresh);
+    } catch {
+      // A failed timer callback must not escape into the hooks runtime.
+    }
+  };
+
+  const stop = () => {
+    if (!running) return;
+    running = false;
+    const currentHandle = handle;
+    handle = undefined;
+    try {
+      options.clearInterval(currentHandle);
+    } catch {
+      // Keep the module alive even if the timer host refuses a clear.
+    }
+  };
+
+  const start = () => {
+    if (running) return;
+    try {
+      const now = options.now();
+      if (!Number.isFinite(now)) return;
+      lastRefreshAt = now;
+      running = true;
+      handle = options.setInterval(tick, TICK_INTERVAL_MS);
+    } catch {
+      running = false;
+      handle = undefined;
+    }
+  };
+
+  const hasLiveRow = (snapshot: PaneSnapshot | undefined): boolean => {
+    try {
+      return (
+        snapshot !== undefined &&
+        Array.isArray(snapshot.rows) &&
+        snapshot.rows.some((row) => row != null && LIVE_STATUSES.has(row.status))
+      );
+    } catch {
+      return false;
+    }
+  };
+
+  return {
+    update(paneOpen, snapshot) {
+      if (paneOpen && hasLiveRow(snapshot)) {
+        start();
+        return;
+      }
+      stop();
+    },
+    refreshed() {
+      try {
+        const now = options.now();
+        if (Number.isFinite(now)) lastRefreshAt = now;
+      } catch {
+        // Keep the prior cadence if the injected clock fails.
+      }
+    },
+  };
+}

package/dist/plugin/hooks/register.tsx

@@ -7,6 +7,7 @@ import type { Register } from "claude-code";
 import { formatPane, paneButtonLabel, selectPane } from "../mods/agents/pane.js";
 import { parseRows } from "../mods/agents/parse.js";
 import type { PaneSnapshot } from "../mods/agents/types.js";
+import { createPaneTicker, type PaneTicker } from "./pane-ticker.js";
 import { togglePane } from "./pane-toggle.js";
 
 // Stable pane id: 1 to 64 letters, digits, "_" or "-". open carries it into
@@ -51,14 +52,17 @@ const toggleAgentsPane = async ($: Engine$, isOpen: boolean): Promise<boolean> =
 
 // Passing $ into a helper is allowed, verified. What the engine refuses is
 // pulling a namespace off it: `const P = $.process` fails to load the module.
-// So refresh takes $ as a parameter and the state register owns travels beside
-// it in this object. paneOpen never leaves register, so it stays a bare let.
+// refresh takes $ as a parameter; its state and paneOpen stay in this register.
 type PaneState = {
   // Last good snapshot; undefined until one refresh has fully succeeded, which
   // is how the pane draws nothing rather than a guess.
   snapshot: PaneSnapshot | undefined;
   inFlight: boolean;
   lastRefreshEndedAt: number;
+  ticker: PaneTicker | undefined;
+  paneOpen: boolean;
+  tickInvalidate: () => unknown;
+  tickRefresh: () => unknown;
   // True once session.start saw a CODEDECK_RUN_ID. Cached because ui.render
   // fires on every drawing pass and must not await an env read to decide
   // whether to draw one button.
@@ -67,6 +71,13 @@ type PaneState = {
 
 const TOOL_REFRESH_GAP_MS = 1500;
 
+function syncTicker($: Engine$, state: PaneState, refreshCompleted = false): void {
+  state.tickInvalidate = () => $.ui.invalidate("ui.render");
+  state.tickRefresh = () => refresh($, state);
+  if (refreshCompleted) state.ticker?.refreshed();
+  state.ticker?.update(state.paneOpen, state.snapshot);
+}
+
 const refresh = async ($: Engine$, state: PaneState): Promise<void> => {
   // Claim the slot before the first await. Guard and set must not straddle a
   // yield point: with the `$.env.get` read in between, two tool.call firings
@@ -103,6 +114,7 @@ const refresh = async ($: Engine$, state: PaneState): Promise<void> => {
   } finally {
     state.inFlight = false;
     state.lastRefreshEndedAt = Date.now();
+    syncTicker($, state, true);
   }
 };
 
@@ -112,10 +124,21 @@ export const register: Register = (on) => {
     inFlight: false,
     lastRefreshEndedAt: 0,
     hasRun: false,
+    ticker: undefined,
+    paneOpen: false,
+    tickInvalidate: () => undefined,
+    tickRefresh: () => undefined,
   };
-  let paneOpen = false;
+  state.ticker = createPaneTicker({
+    now: () => Date.now(),
+    setInterval: (callback, milliseconds) => setInterval(callback, milliseconds),
+    clearInterval: (handle) => clearInterval(handle as ReturnType<typeof setInterval>),
+    invalidate: () => state.tickInvalidate(),
+    refresh: () => state.tickRefresh(),
+  });
 
   on("session.start", async ($, e, next) => {
+    syncTicker($, state);
     // Not "agents": the engine refuses it with `$.command.register: "/agents"
     // refused: it is the built-in /agents`. "band", "deck" and
     // "codedeck-agents" were each verified free. The description is load
@@ -125,20 +148,15 @@ export const register: Register = (on) => {
       description: "toggle the codedeck agents pane",
       immediate: true,
     });
-    // Only open when there is actually a run behind the pane. A session that
-    // loads this plugin by manual --plugin-dir or a global install has no
-    // CODEDECK_RUN_ID, and the dock there is permanently empty while eating
-    // most of the screen for the whole session. /band stays the escape hatch
-    // for anyone who wants the pane anyway.
+    // Only show the button when there is actually a run behind the pane. A
+    // session that loads this plugin by manual --plugin-dir or a global
+    // install has no CODEDECK_RUN_ID, and its dock stays empty. /band remains
+    // available for anyone who wants to open it anyway.
     const runId = await $.env.get("CODEDECK_RUN_ID");
     state.hasRun = Boolean(runId);
     if (runId) {
-      // No width is requested: the engine sizes the dock itself and reports
-      // the usable content back as e.props.bodyColumns on every render.
-      await $.ui.open({ id: PANE_ID, side: "right" });
-      paneOpen = true;
-      // Populate before the first turn, or the pane stays blank through the
-      // whole opening exchange, which is exactly when the run is dispatched.
+      // Prime the button label without taking screen space when the session
+      // starts. The panel opens only on an explicit button press or /band.
       void refresh($, state);
     }
     return next(e);
@@ -150,9 +168,11 @@ export const register: Register = (on) => {
     // is the one call here not yet verified in a PTY session, paneOpen stays
     // true and the next /band retries the close, instead of the flag and the
     // pane desyncing for the rest of the session.
-    paneOpen = await toggleAgentsPane($, paneOpen);
+    state.paneOpen = await toggleAgentsPane($, state.paneOpen);
+    syncTicker($, state);
     await $.ui.invalidate("ui.render");
-    return { text: paneOpen ? "agents pane open" : "agents pane closed" };
+    if (state.paneOpen) void refresh($, state);
+    return { text: state.paneOpen ? "agents pane open" : "agents pane closed" };
   });
 
   on("turn.complete", async ($, e, next) => {
@@ -176,9 +196,10 @@ export const register: Register = (on) => {
     // A $ captured from a past render does work, verified, but it outlives the
     // event it came from and nothing promises how long.
     if ((e as { element?: string }).element === BUTTON_KEY) {
-      paneOpen = await toggleAgentsPane($, paneOpen);
+      state.paneOpen = await toggleAgentsPane($, state.paneOpen);
+      syncTicker($, state);
       await $.ui.invalidate("ui.render");
-      if (paneOpen) void refresh($, state);
+      if (state.paneOpen) void refresh($, state);
     }
     return await next(e);
   });

package/dist/plugin/hooks/session-id.sh

@@ -20,4 +20,4 @@ target=${CODEDECK_SESSION_FILE:-}
 id=$(grep -oE '"session_id":"[0-9a-fA-F-]+"' | head -1 | cut -d'"' -f4)
 [[ -n "$id" ]] || exit 0
 
-printf '%s' "$id" > "$target"
+printf '%s\n' "$id" >> "$target"