Skip to content

The open-source app everyone uses to manage agents at work

feat(skills): add confirmed inbox gardening workflow (#10462)

Dottaa5d252d058ff
diff --git a/.agents/skills/garden-inbox/SKILL.md b/.agents/skills/garden-inbox/SKILL.md
new file mode 100644
index 0000000000..10fd653c18
--- /dev/null
+++ b/.agents/skills/garden-inbox/SKILL.md
@@ -0,0 +1,98 @@
+---
+name: garden-inbox
+description: Scan a Paperclip user's Mine inbox, classify reversible archive candidates, request checkbox confirmation, and archive only accepted selections. Use when asked to garden, clean up, prune, or tidy a Paperclip inbox without changing issues, branches, or workspaces.
+---
+
+# Garden Inbox
+
+Use the bundled script for every stage. Keep the workflow strictly ordered: `scan` → `confirm` → `apply`.
+
+## Safety contract
+
+- Treat `scan` as read-only. It may read inbox, workspace, close-readiness, and local Git metadata only.
+- Treat `confirm` as a confirmation-card write only. It must not archive inbox entries or mutate issue fields, branches, or workspaces.
+- Run `apply` only after a resolved `request_checkbox_confirmation` interaction. It archives only accepted option IDs that also occur in the originating `candidates.json`.
+- Remember that inbox archive state is per-user presentation state. It is reversible and does not change the underlying issue.
+- Never substitute issue status changes, branch deletion, workspace cleanup, or issue deletion for inbox archiving.
+
+## Inputs
+
+Require `PAPERCLIP_API_URL` and `PAPERCLIP_API_KEY`. The script strips a trailing `/api` from the URL. It resolves the target user from the run JWT payload's `responsible_user_id`; use `--user-id <uuid>` only for an explicit target override.
+
+Use a run-owned output directory when available:
+
+```bash
+RUN_DIR="${PAPERCLIP_RUN_SCRATCH_DIR:-${PAPERCLIP_TASK_SCRATCH_DIR:-.}}/garden-inbox"
+mkdir -p "$RUN_DIR"
+```
+
+## 1. Scan
+
+```bash
+node .agents/skills/garden-inbox/scripts/garden-inbox.mjs scan \
+ --output-dir "$RUN_DIR" \
+ --stale-days 60
+```
+
+Inspect `garden-inbox-report.md` and `candidates.json`. The report groups every inbox row into exactly one bucket:
+
+The scan reads Mine separately for each included issue status so the endpoint's global 500-row cap does not silently omit older rows. If any single-status query reaches that cap, both outputs mark coverage as possibly truncated; do not treat that scan as complete.
+
+- A: merged/archived workspace and all linked work terminal; selected by default.
+- B: terminal or workspace-gone work idle beyond the threshold; selected by default.
+- C: stale work with commits ahead of base; never selected by default.
+- D: keep; never offered for archiving.
+
+Do not manually promote bucket D entries into the candidate file.
+
+## 2. Confirm
+
+Post checkbox interactions on the driving issue:
+
+```bash
+node .agents/skills/garden-inbox/scripts/garden-inbox.mjs confirm \
+ --issue-id "$PAPERCLIP_TASK_ID" \
+ --candidates "$RUN_DIR/candidates.json"
+```
+
+The script posts sequential cards when a scan has more than 200 candidates. Re-running `confirm` with the same scan file is idempotent. Leave the driving issue in the waiting posture required by the surrounding Paperclip heartbeat workflow.
+
+For development or payload review, suppress the POST:
+
+```bash
+node .agents/skills/garden-inbox/scripts/garden-inbox.mjs confirm \
+ --issue-id "$PAPERCLIP_TASK_ID" \
+ --candidates "$RUN_DIR/candidates.json" \
+ --dry-run
+```
+
+## 3. Apply accepted selections
+
+After an interaction-resolution wake, take the resolved interaction ID from the wake payload and run:
+
+```bash
+node .agents/skills/garden-inbox/scripts/garden-inbox.mjs apply \
+ --issue-id "$PAPERCLIP_TASK_ID" \
+ --interaction-id "$INTERACTION_ID" \
+ --candidates "$RUN_DIR/candidates.json"
+```
+
+On rejection, expiry, or an accepted empty selection, the script archives nothing. Apply preserves the scan file's target user, including an explicit `--user-id` override. Its summary includes the API undo path and target-user body for every archived row.
+
+Test `apply` without API writes by supplying a saved interaction response:
+
+```bash
+node .agents/skills/garden-inbox/scripts/garden-inbox.mjs apply \
+ --issue-id "$PAPERCLIP_TASK_ID" \
+ --interaction-file resolved-interaction.json \
+ --candidates "$RUN_DIR/candidates.json" \
+ --dry-run
+```
+
+## Verify the bundled logic
+
+Run the zero-dependency Node tests after changing classification or selection safety:
+
+```bash
+node --test .agents/skills/garden-inbox/scripts/garden-inbox.test.mjs
+```
diff --git a/.agents/skills/garden-inbox/scripts/garden-inbox.mjs b/.agents/skills/garden-inbox/scripts/garden-inbox.mjs
new file mode 100755
index 0000000000..d196b71d11
--- /dev/null
+++ b/.agents/skills/garden-inbox/scripts/garden-inbox.mjs
@@ -0,0 +1,699 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const TERMINAL_STATUSES = new Set(["done", "cancelled"]);
+const OFFERED_BUCKETS = new Set(["A", "B", "C"]);
+const DEFAULT_STALE_DAYS = 60;
+const INTERACTION_LIMIT = 200;
+const INBOX_MINE_STATUSES = ["backlog", "todo", "in_progress", "in_review", "blocked", "done"];
+const INBOX_QUERY_CAP = 500;
+
+class ApiError extends Error {
+ constructor(status, message, body = null) {
+ super(`${status}: ${message}`);
+ this.name = "ApiError";
+ this.status = status;
+ this.body = body;
+ }
+}
+
+function usage() {
+ return `Usage:
+ garden-inbox.mjs [scan] [--user-id UUID] [--stale-days 60] [--output-dir DIR]
+ garden-inbox.mjs confirm [--issue-id ID] [--candidates FILE] [--dry-run]
+ garden-inbox.mjs apply [--issue-id ID] (--interaction-id ID | --interaction-file FILE) [--candidates FILE] [--dry-run]
+
+Common environment:
+ PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_RUN_ID, PAPERCLIP_TASK_ID`;
+}
+
+function parseArgs(argv) {
+ const args = [...argv];
+ let command = "scan";
+ if (args[0] && !args[0].startsWith("-")) command = args.shift();
+ if (!["scan", "confirm", "apply"].includes(command)) throw new Error(`Unknown command: ${command}`);
+
+ const options = {};
+ while (args.length > 0) {
+ const token = args.shift();
+ if (token === "--help" || token === "-h") {
+ options.help = true;
+ continue;
+ }
+ if (!token.startsWith("--")) throw new Error(`Unexpected argument: ${token}`);
+ const key = token.slice(2).replaceAll("-", "_");
+ if (key === "dry_run") {
+ options[key] = true;
+ continue;
+ }
+ const value = args.shift();
+ if (value === undefined || value.startsWith("--")) throw new Error(`${token} requires a value`);
+ if (options[key] === undefined) options[key] = value;
+ else options[key] = Array.isArray(options[key]) ? [...options[key], value] : [options[key], value];
+ }
+ return { command, options };
+}
+
+function required(value, name) {
+ if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} is required`);
+ return value.trim();
+}
+
+function normalizeApiBase(value) {
+ let base = required(value, "PAPERCLIP_API_URL").replace(/\/+$/, "");
+ if (base.endsWith("/api")) base = base.slice(0, -4);
+ return base;
+}
+
+function runtime(options, { requireApi = true } = {}) {
+ const apiUrl = options.api_url ?? process.env.PAPERCLIP_API_URL;
+ const apiKey = options.api_key ?? process.env.PAPERCLIP_API_KEY;
+ return {
+ apiBase: requireApi ? normalizeApiBase(apiUrl) : (apiUrl ? normalizeApiBase(apiUrl) : null),
+ apiKey: requireApi ? required(apiKey, "PAPERCLIP_API_KEY") : apiKey ?? null,
+ runId: options.run_id ?? process.env.PAPERCLIP_RUN_ID ?? null,
+ };
+}
+
+async function apiRequest(context, path, { method = "GET", body } = {}) {
+ const headers = { Accept: "application/json", Authorization: `Bearer ${context.apiKey}` };
+ if (body !== undefined) headers["Content-Type"] = "application/json";
+ if (method !== "GET" && context.runId) headers["X-Paperclip-Run-Id"] = context.runId;
+ const response = await fetch(`${context.apiBase}/api${path}`, {
+ method,
+ headers,
+ body: body === undefined ? undefined : JSON.stringify(body),
+ });
+ const text = await response.text();
+ let parsed = null;
+ if (text) {
+ try { parsed = JSON.parse(text); } catch { parsed = text; }
+ }
+ if (!response.ok) {
+ const message = parsed && typeof parsed === "object"
+ ? parsed.error ?? parsed.message ?? response.statusText
+ : parsed ?? response.statusText;
+ throw new ApiError(response.status, String(message), parsed);
+ }
+ return parsed;
+}
+
+function decodeJwtPayload(token) {
+ const parts = required(token, "PAPERCLIP_API_KEY").split(".");
+ if (parts.length < 2) throw new Error("PAPERCLIP_API_KEY is not a JWT; pass --user-id explicitly");
+ try {
+ return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+ } catch {
+ throw new Error("Could not decode the PAPERCLIP_API_KEY JWT payload; pass --user-id explicitly");
+ }
+}
+
+function resolveUserId(options, apiKey) {
+ if (options.user_id) return required(options.user_id, "--user-id");
+ const userId = decodeJwtPayload(apiKey).responsible_user_id;
+ if (typeof userId !== "string" || userId.trim() === "") {
+ throw new Error("Run JWT has no responsible_user_id; pass --user-id explicitly");
+ }
+ return userId.trim();
+}
+
+function parsePositiveInteger(value, fallback, name) {
+ if (value === undefined) return fallback;
+ const parsed = Number(value);
+ if (!Number.isInteger(parsed) || parsed < 1 || parsed > 3650) {
+ throw new Error(`${name} must be an integer from 1 to 3650`);
+ }
+ return parsed;
+}
+
+function validDate(value) {
+ if (!value) return null;
+ const date = new Date(value);
+ return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function latestDate(...values) {
+ return values.flat().map(validDate).filter(Boolean).sort((left, right) => right.getTime() - left.getTime())[0] ?? null;
+}
+
+function runGit(args, cwd) {
+ try {
+ return execFileSync("git", ["-C", cwd, ...args], {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "ignore"],
+ timeout: 5_000,
+ }).trim();
+ } catch {
+ return "";
+ }
+}
+
+function gitLastCommitAt(branchName, roots) {
+ if (!branchName) return null;
+ for (const root of [...new Set(roots.filter(Boolean))]) {
+ const parsed = validDate(runGit(["log", "-1", "--format=%cI", branchName], root));
+ if (parsed) return parsed;
+ }
+ return null;
+}
+
+function findLocalBranch(identifier, roots) {
+ if (!identifier) return null;
+ const needle = identifier.toLowerCase();
+ for (const root of [...new Set(roots.filter(Boolean))]) {
+ const branches = runGit(["for-each-ref", "--format=%(refname:short)", "refs/heads"], root)
+ .split("\n").map((branch) => branch.trim()).filter(Boolean)
+ .filter((branch) => branch.toLowerCase().includes(needle));
+ if (branches.length === 1) return branches[0];
+ }
+ return null;
+}
+
+async function mapLimit(values, limit, mapper) {
+ const results = new Array(values.length);
+ let cursor = 0;
+ async function worker() {
+ while (cursor < values.length) {
+ const index = cursor++;
+ results[index] = await mapper(values[index], index);
+ }
+ }
+ await Promise.all(Array.from({ length: Math.min(limit, values.length) }, worker));
+ return results;
+}
+
+async function fetchMineInboxRows(context, userId) {
+ const statusResults = await Promise.all(INBOX_MINE_STATUSES.map(async (status) => {
+ const query = new URLSearchParams({ userId, status });
+ const rows = await apiRequest(context, `/agents/me/inbox/mine?${query}`);
+ if (!Array.isArray(rows)) throw new Error(`Inbox API returned a non-array response for status ${status}`);
+ return { status, rows };
+ }));
+ const rowsById = new Map();
+ const statusCounts = {};
+ const cappedStatuses = [];
+ let duplicateCount = 0;
+ for (const { status, rows } of statusResults) {
+ statusCounts[status] = rows.length;
+ if (rows.length >= INBOX_QUERY_CAP) cappedStatuses.push(status);
+ for (const issue of rows) {
+ if (rowsById.has(issue.id)) duplicateCount += 1;
+ rowsById.set(issue.id, issue);
+ }
+ }
+ return {
+ rows: [...rowsById.values()],
+ coverage: {
+ strategy: "per_status",
+ queryCap: INBOX_QUERY_CAP,
+ statusCounts,
+ cappedStatuses,
+ duplicateCount,
+ complete: cappedStatuses.length === 0,
+ },
+ };
+}
+
+async function inspectWorkspace(context, workspaceId, issueIdentifiers, gitRoot) {
+ let workspace = null;
+ let readiness = null;
+ let gone = false;
+ let error = null;
+ try {
+ workspace = await apiRequest(context, `/execution-workspaces/${encodeURIComponent(workspaceId)}`);
+ } catch (caught) {
+ if (caught instanceof ApiError && caught.status === 404) gone = true;
+ else error = caught.message;
+ }
+ if (workspace) {
+ try {
+ readiness = await apiRequest(context, `/execution-workspaces/${encodeURIComponent(workspaceId)}/close-readiness`);
+ } catch (caught) {
+ error = error ?? caught.message;
+ }
+ }
+
+ const roots = [workspace?.cwd, workspace?.providerRef, readiness?.git?.repoRoot, readiness?.git?.workspacePath, gitRoot];
+ let branchName = workspace?.branchName ?? readiness?.git?.branchName ?? null;
+ if (!branchName && gone) {
+ const matches = issueIdentifiers.map((identifier) => findLocalBranch(identifier, roots)).filter(Boolean);
+ if (new Set(matches).size === 1) branchName = matches[0];
+ }
+ const branchCommitAt = gitLastCommitAt(branchName, roots);
+ return {
+ id: workspaceId,
+ gone,
+ error,
+ status: workspace?.status ?? null,
+ branchName,
+ lastUsedAt: workspace?.lastUsedAt ?? null,
+ branchCommitAt: branchCommitAt?.toISOString() ?? null,
+ readiness,
+ };
+}
+
+function reason(code, message, facts = {}) {
+ return { code, message, facts };
+}
+
+function classify(issue, workspaceInfo, staleDays, now) {
+ const terminal = TERMINAL_STATUSES.has(issue.status);
+ const workspaceArchived = workspaceInfo?.status === "archived";
+ const workspaceGone = Boolean(workspaceInfo?.gone);
+ const readiness = workspaceInfo?.readiness ?? null;
+ const linkedIssues = Array.isArray(readiness?.linkedIssues) ? readiness.linkedIssues : [];
+ const allLinkedIssuesTerminal = Boolean(readiness) && linkedIssues.every((linked) => linked.isTerminal === true);
+ const mergedIntoBase = readiness?.git?.isMergedIntoBase === true;
+ const aheadCount = Number.isInteger(readiness?.git?.aheadCount) ? readiness.git.aheadCount : null;
+ const blockerAttention = issue.blockerAttention?.state;
+ const hasOpenBlockers = issue.status === "blocked"
+ || (Array.isArray(issue.blockedBy) && issue.blockedBy.some((blocker) => !TERMINAL_STATUSES.has(blocker.status)))
+ || (typeof blockerAttention === "string" && blockerAttention !== "none");
+ const awaitingUser = issue.blockedInboxAttention?.state === "awaiting_decision"
+ || (issue.status === "in_review" && Boolean(issue.assigneeUserId));
+ const issueActivity = latestDate(issue.lastActivityAt, issue.updatedAt, issue.createdAt);
+ const branchActivity = latestDate(workspaceInfo?.branchCommitAt, workspaceInfo?.lastUsedAt);
+ const lastActivity = latestDate(issueActivity, branchActivity) ?? new Date(0);
+ const cutoff = new Date(now.getTime() - staleDays * 86_400_000);
+ const stale = lastActivity.getTime() <= cutoff.getTime();
+ const facts = {
+ issueStatus: issue.status,
+ workspaceStatus: workspaceInfo?.status ?? null,
+ workspaceGone,
+ workspaceInspectionError: workspaceInfo?.error ?? null,
+ mergedIntoBase,
+ allLinkedIssuesTerminal,
+ aheadCount,
+ staleDays,
+ };
+
+ if (workspaceInfo?.error) {
+ return {
+ bucket: "D",
+ reason: reason("workspace_inspection_failed", "Keep: workspace archive safety could not be verified.", facts),
+ lastActivity,
+ };
+ }
+ if (hasOpenBlockers) return { bucket: "D", reason: reason("open_blockers", "Keep: the issue has unresolved blocker or liveness attention.", facts), lastActivity };
+ if (awaitingUser) return { bucket: "D", reason: reason("pending_user_action", "Keep: the issue is awaiting a user decision or review.", facts), lastActivity };
+ if (!terminal) {
+ const code = issue.status === "in_review" ? "pending_interaction_or_review" : "non_terminal_status";
+ return { bucket: "D", reason: reason(code, `Keep: issue status ${issue.status} is not terminal.`, facts), lastActivity };
+ }
+ if ((mergedIntoBase || workspaceArchived) && allLinkedIssuesTerminal) {
+ const code = workspaceArchived ? "workspace_archived_finished" : "merged_finished";
+ return { bucket: "A", reason: reason(code, "Archive candidate: work is merged or archived and every linked issue is terminal.", facts), lastActivity };
+ }
+ if (!stale) return { bucket: "D", reason: reason("recent_activity", `Keep: activity is newer than ${staleDays} days.`, facts), lastActivity };
+ if (aheadCount !== null && aheadCount > 0) {
+ return { bucket: "C", reason: reason("stale_unmerged_commits", `Review manually: stale branch is ${aheadCount} commit(s) ahead of base.`, facts), lastActivity };
+ }
+ if (terminal || workspaceGone) {
+ return { bucket: "B", reason: reason("stale_terminal_or_workspace_gone", `Archive candidate: no issue or branch activity for at least ${staleDays} days and the issue is terminal or workspace is gone.`, facts), lastActivity };
+ }
+ return { bucket: "D", reason: reason("insufficient_archive_evidence", "Keep: archive safety conditions were not met.", facts), lastActivity };
+}
+
+function candidateFrom(issue, workspace, classification) {
+ return {
+ issueId: issue.id,
+ identifier: issue.identifier ?? null,
+ title: issue.title,
+ bucket: classification.bucket,
+ reason: classification.reason,
+ executionWorkspaceId: issue.executionWorkspaceId ?? null,
+ workspaceStatus: workspace?.status ?? null,
+ workspaceGone: Boolean(workspace?.gone),
+ branchName: workspace?.branchName ?? null,
+ lastActivityAt: classification.lastActivity.toISOString(),
+ };
+}
+
+function markdownEscape(value) {
+ return String(value ?? "").replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+function renderReport(scanResult) {
+ const labels = {
+ A: "A — merged and finished (default checked)",
+ B: "B — stale (default checked)",
+ C: "C — stale but unmerged (default unchecked)",
+ D: "D — keep (not offered)",
+ };
+ const lines = [
+ "# Garden inbox scan", "",
+ `- Generated: ${scanResult.generatedAt}`,
+ `- Target user: \`${scanResult.userId}\``,
+ `- Stale threshold: ${scanResult.staleDays} days`,
+ `- Inbox rows classified: ${scanResult.items.length}`,
+ `- Archive candidates: ${scanResult.candidates.length}`,
+ `- Scan coverage: ${scanResult.coverage.complete ? "complete across per-status queries" : "possibly truncated"}`,
+ ];
+ if (!scanResult.coverage.complete) {
+ lines.push(
+ "",
+ "> [!WARNING]",
+ `> Coverage may be incomplete: ${scanResult.coverage.cappedStatuses.map((status) => `\`${status}\``).join(", ")} returned at least ${scanResult.coverage.queryCap} rows, the Mine endpoint cap.`,
+ );
+ }
+ for (const bucket of ["A", "B", "C", "D"]) {
+ const items = scanResult.items.filter((item) => item.bucket === bucket);
+ lines.push("", `## ${labels[bucket]} (${items.length})`, "");
+ if (items.length === 0) {
+ lines.push("_None._");
+ continue;
+ }
+ lines.push("| Issue | Title | Reason | Workspace / branch | Last activity |", "|---|---|---|---|---|");
+ for (const item of items) {
+ const issue = item.identifier ? `\`${markdownEscape(item.identifier)}\`` : `\`${item.issueId}\``;
+ const workspace = [item.workspaceStatus, item.branchName].filter(Boolean).join(" / ") || (item.workspaceGone ? "gone" : "none");
+ lines.push(`| ${issue} | ${markdownEscape(item.title)} | \`${item.reason.code}\` — ${markdownEscape(item.reason.message)} | ${markdownEscape(workspace)} | ${item.lastActivityAt} |`);
+ }
+ }
+ lines.push("");
+ return lines.join("\n");
+}
+
+function writeText(path, contents) {
+ const target = resolve(path);
+ mkdirSync(dirname(target), { recursive: true });
+ writeFileSync(target, contents);
+ return target;
+}
+
+function readJson(path) {
+ return JSON.parse(readFileSync(resolve(path), "utf8"));
+}
+
+function stableScanId(scanResult) {
+ const fingerprint = {
+ userId: scanResult.userId,
+ staleDays: scanResult.staleDays,
+ generatedAt: scanResult.generatedAt,
+ candidates: scanResult.candidates.map((item) => ({
+ issueId: item.issueId,
+ bucket: item.bucket,
+ reason: item.reason.code,
+ lastActivityAt: item.lastActivityAt,
+ })),
+ };
+ return createHash("sha256").update(JSON.stringify(fingerprint)).digest("hex").slice(0, 24);
+}
+
+async function scan(options) {
+ const context = runtime(options);
+ const userId = resolveUserId(options, context.apiKey);
+ const staleDays = parsePositiveInteger(options.stale_days, DEFAULT_STALE_DAYS, "--stale-days");
+ const now = options.now ? validDate(options.now) : new Date();
+ if (!now) throw new Error("--now must be an ISO date");
+ const outputDir = options.output_dir ?? ".";
+ const candidatesPath = options.candidates ?? resolve(outputDir, "candidates.json");
+ const reportPath = options.report ?? resolve(outputDir, "garden-inbox-report.md");
+
+ const { rows, coverage } = await fetchMineInboxRows(context, userId);
+ const issuesByWorkspace = new Map();
+ for (const issue of rows) {
+ if (!issue.executionWorkspaceId) continue;
+ const identifiers = issuesByWorkspace.get(issue.executionWorkspaceId) ?? [];
+ if (issue.identifier) identifiers.push(issue.identifier);
+ issuesByWorkspace.set(issue.executionWorkspaceId, identifiers);
+ }
+ const workspaceIds = [...issuesByWorkspace.keys()];
+ const inspected = await mapLimit(workspaceIds, 8, (workspaceId) => inspectWorkspace(
+ context, workspaceId, issuesByWorkspace.get(workspaceId), options.git_root ?? process.cwd(),
+ ));
+ const workspaceById = new Map(inspected.map((entry) => [entry.id, entry]));
+ const items = rows.map((issue) => {
+ const workspace = issue.executionWorkspaceId ? workspaceById.get(issue.executionWorkspaceId) ?? null : null;
+ return candidateFrom(issue, workspace, classify(issue, workspace, staleDays, now));
+ });
+ const scanResult = {
+ schemaVersion: 1,
+ generatedAt: now.toISOString(),
+ userId,
+ staleDays,
+ sourceCount: rows.length,
+ coverage,
+ items,
+ candidates: items.filter((item) => OFFERED_BUCKETS.has(item.bucket)),
+ };
+ scanResult.scanId = stableScanId(scanResult);
+ const output = {
+ schemaVersion: 1,
+ scanId: scanResult.scanId,
+ generatedAt: scanResult.generatedAt,
+ userId,
+ staleDays,
+ sourceCount: rows.length,
+ coverage,
+ candidates: scanResult.candidates,
+ kept: items.filter((item) => item.bucket === "D"),
+ };
+ const candidatesFile = writeText(candidatesPath, `${JSON.stringify(output, null, 2)}\n`);
+ const report = renderReport(scanResult);
+ const reportFile = writeText(reportPath, report);
+ process.stdout.write(`${report}\nCandidates JSON: ${candidatesFile}\nReport: ${reportFile}\n`);
+ return output;
+}
+
+function truncate(value, limit) {
+ const text = String(value ?? "").trim();
+ if (text.length <= limit) return text;
+ return `${text.slice(0, Math.max(0, limit - 1)).trimEnd()}…`;
+}
+
+function candidateFile(options) {
+ const data = readJson(options.candidates ?? "candidates.json");
+ if (data?.schemaVersion !== 1
+ || typeof data.scanId !== "string"
+ || typeof data.userId !== "string"
+ || data.userId.trim() === ""
+ || !Array.isArray(data.candidates)) {
+ throw new Error("Candidates file is not a garden-inbox schemaVersion 1 scan");
+ }
+ for (const item of data.candidates) {
+ if (!item?.issueId || !OFFERED_BUCKETS.has(item.bucket)) {
+ throw new Error("Candidates file contains an invalid or non-offered item");
+ }
+ }
+ return data;
+}
+
+function archiveTargetBody(scanData) {
+ return { userId: scanData.userId };
+}
+
+function chunk(values, size) {
+ const chunks = [];
+ for (let index = 0; index < values.length; index += size) chunks.push(values.slice(index, index + size));
+ return chunks;
+}
+
+function confirmationBody(scanData, candidates, index, count) {
+ const options = candidates.map((candidate) => ({
+ id: candidate.issueId,
+ label: truncate(`${candidate.identifier ?? candidate.issueId} — ${candidate.title}`, 120),
+ description: truncate(`${candidate.reason.message} Last activity: ${candidate.lastActivityAt}.`, 500),
+ }));
+ const part = count > 1 ? ` (${index + 1}/${count})` : "";
+ return {
+ kind: "request_checkbox_confirmation",
+ idempotencyKey: `garden-inbox:${scanData.scanId}:${index + 1}:${count}`,
+ title: `Confirm inbox archive candidates${part}`,
+ summary: `Choose which reversible inbox entries to archive${part}.`,
+ continuationPolicy: "wake_assignee",
+ payload: {
+ version: 1,
+ prompt: `Select the inbox entries to archive${part}. Unchecked entries will remain visible.`,
+ options,
+ defaultSelectedOptionIds: candidates
+ .filter((candidate) => candidate.bucket === "A" || candidate.bucket === "B")
+ .map((candidate) => candidate.issueId),
+ minSelected: 0,
+ acceptLabel: "Archive selected",
+ rejectLabel: "Keep everything",
+ detailsMarkdown: `Scan \`${scanData.scanId}\` used a ${scanData.staleDays}-day stale threshold. Buckets A and B start checked; stale branches with unmerged commits (C) start unchecked. Archiving changes only this user's inbox visibility and is reversible.`,
+ },
+ };
+}
+
+async function confirm(options) {
+ const data = candidateFile(options);
+ const drivingIssueId = options.issue_id ?? process.env.PAPERCLIP_TASK_ID;
+ if (!options.dry_run) required(drivingIssueId, "--issue-id or PAPERCLIP_TASK_ID");
+ const groups = chunk(data.candidates, INTERACTION_LIMIT);
+ if (groups.length === 0) {
+ process.stdout.write("No archive candidates; no confirmation interaction created.\n");
+ return [];
+ }
+ const bodies = groups.map((candidates, index) => confirmationBody(data, candidates, index, groups.length));
+ if (options.dry_run) {
+ process.stdout.write(`${JSON.stringify({ dryRun: true, issueId: drivingIssueId ?? null, interactions: bodies }, null, 2)}\n`);
+ return bodies;
+ }
+
+ const context = runtime(options);
+ const created = [];
+ for (const body of bodies) {
+ created.push(await apiRequest(context, `/issues/${encodeURIComponent(drivingIssueId)}/interactions`, {
+ method: "POST",
+ body,
+ }));
+ }
+ process.stdout.write(`${JSON.stringify({
+ scanId: data.scanId,
+ createdInteractions: created.map((item) => ({
+ id: item.id,
+ status: item.status,
+ idempotencyKey: item.idempotencyKey,
+ })),
+ }, null, 2)}\n`);
+ return created;
+}
+
+function flattenInteractionFile(value) {
+ if (Array.isArray(value)) return value;
+ if (Array.isArray(value?.interactions)) return value.interactions;
+ if (value?.interaction && typeof value.interaction === "object") return [value.interaction];
+ return value && typeof value === "object" ? [value] : [];
+}
+
+function optionValues(value) {
+ if (value === undefined) return [];
+ return Array.isArray(value) ? value : [value];
+}
+
+async function resolveInteractions(options, context, drivingIssueId) {
+ const files = optionValues(options.interaction_file);
+ const ids = optionValues(options.interaction_id);
+ const fromFiles = files.flatMap((file) => flattenInteractionFile(readJson(file)));
+ if (ids.length === 0) return fromFiles;
+ required(drivingIssueId, "--issue-id or PAPERCLIP_TASK_ID");
+ const live = await apiRequest(context, `/issues/${encodeURIComponent(drivingIssueId)}/interactions`);
+ if (!Array.isArray(live)) throw new Error("Interactions API returned a non-array response");
+ const byId = new Map(live.map((interaction) => [interaction.id, interaction]));
+ for (const id of ids) {
+ if (!byId.has(id)) throw new Error(`Interaction ${id} was not found on the driving issue`);
+ fromFiles.push(byId.get(id));
+ }
+ return fromFiles;
+}
+
+function acceptedCandidates(interaction, scanData, candidateById) {
+ if (interaction?.kind !== "request_checkbox_confirmation") {
+ throw new Error(`Interaction ${interaction?.id ?? "(unknown)"} is not request_checkbox_confirmation`);
+ }
+ if (typeof interaction.idempotencyKey !== "string"
+ || !interaction.idempotencyKey.startsWith(`garden-inbox:${scanData.scanId}:`)) {
+ throw new Error(`Interaction ${interaction.id ?? "(unknown)"} does not belong to scan ${scanData.scanId}`);
+ }
+ if (interaction.status !== "accepted" || interaction.result?.outcome !== "accepted") return [];
+ const selected = interaction.result?.selectedOptionIds ?? [];
+ if (!Array.isArray(selected)) throw new Error("Accepted interaction has invalid selectedOptionIds");
+ const optionIds = new Set((interaction.payload?.options ?? []).map((option) => option.id));
+ const seen = new Set();
+ return selected.map((issueId) => {
+ if (seen.has(issueId)) throw new Error(`Interaction selected duplicate option id ${issueId}`);
+ seen.add(issueId);
+ if (!optionIds.has(issueId)) throw new Error(`Selected id ${issueId} was not an option in the interaction`);
+ const candidate = candidateById.get(issueId);
+ if (!candidate || !OFFERED_BUCKETS.has(candidate.bucket)) {
+ throw new Error(`Selected id ${issueId} is not an offered candidate in the originating scan`);
+ }
+ return candidate;
+ });
+}
+
+function renderApplySummary(results, interactions, dryRun, userId) {
+ const lines = [
+ `# Garden inbox ${dryRun ? "dry-run " : ""}apply summary`, "",
+ `- Interactions inspected: ${interactions.length}`,
+ `- Entries ${dryRun ? "that would be archived" : "archived"}: ${results.filter((result) => result.ok).length}`,
+ `- Failures: ${results.filter((result) => !result.ok).length}`,
+ ];
+ if (results.length === 0) {
+ lines.push("", "Nothing was archived: the interaction was rejected, unresolved, expired, or accepted with no selections.");
+ }
+ for (const result of results) {
+ lines.push("", `- ${result.ok ? "OK" : "FAILED"}: ${result.identifier ?? result.issueId} — ${result.message}`);
+ if (result.ok) {
+ lines.push(` Undo: \`DELETE /api/issues/${result.issueId}/inbox-archive\` with body \`${JSON.stringify({ userId })}\`, or use **Unarchive** in the issue properties pane.`);
+ }
+ }
+ return `${lines.join("\n")}\n`;
+}
+
+async function applyAccepted(options) {
+ const data = candidateFile(options);
+ const drivingIssueId = options.issue_id ?? process.env.PAPERCLIP_TASK_ID ?? null;
+ const needsLiveApi = optionValues(options.interaction_id).length > 0 || !options.dry_run;
+ const context = runtime(options, { requireApi: needsLiveApi });
+ const interactions = await resolveInteractions(options, context, drivingIssueId);
+ if (interactions.length === 0) throw new Error("Provide --interaction-id or --interaction-file");
+ const candidateById = new Map(data.candidates.map((candidate) => [candidate.issueId, candidate]));
+ const accepted = [];
+ const seen = new Set();
+ for (const interaction of interactions) {
+ for (const candidate of acceptedCandidates(interaction, data, candidateById)) {
+ if (!seen.has(candidate.issueId)) accepted.push(candidate);
+ seen.add(candidate.issueId);
+ }
+ }
+
+ const results = [];
+ for (const candidate of accepted) {
+ if (options.dry_run) {
+ results.push({ ...candidate, ok: true, message: "would archive this accepted inbox entry" });
+ continue;
+ }
+ try {
+ await apiRequest(context, `/issues/${encodeURIComponent(candidate.issueId)}/inbox-archive`, {
+ method: "POST",
+ body: archiveTargetBody(data),
+ });
+ results.push({ ...candidate, ok: true, message: "archived accepted inbox entry" });
+ } catch (error) {
+ results.push({ ...candidate, ok: false, message: error.message });
+ }
+ }
+
+ const summary = renderApplySummary(results, interactions, Boolean(options.dry_run), data.userId);
+ process.stdout.write(summary);
+ if (options.summary) writeText(options.summary, summary);
+ if (results.some((result) => !result.ok)) process.exitCode = 1;
+ return results;
+}
+
+export {
+ acceptedCandidates,
+ archiveTargetBody,
+ classify,
+ confirm,
+ decodeJwtPayload,
+ fetchMineInboxRows,
+ normalizeApiBase,
+ scan,
+};
+
+async function main() {
+ const { command, options } = parseArgs(process.argv.slice(2));
+ if (options.help) {
+ process.stdout.write(`${usage()}\n`);
+ return;
+ }
+ if (command === "scan") await scan(options);
+ else if (command === "confirm") await confirm(options);
+ else await applyAccepted(options);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ main().catch((error) => {
+ process.stderr.write(`garden-inbox: ${error.message}\n`);
+ process.exitCode = 1;
+ });
+}
diff --git a/.agents/skills/garden-inbox/scripts/garden-inbox.test.mjs b/.agents/skills/garden-inbox/scripts/garden-inbox.test.mjs
new file mode 100644
index 0000000000..6ceec11f6d
--- /dev/null
+++ b/.agents/skills/garden-inbox/scripts/garden-inbox.test.mjs
@@ -0,0 +1,157 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ acceptedCandidates,
+ archiveTargetBody,
+ classify,
+ decodeJwtPayload,
+ fetchMineInboxRows,
+ normalizeApiBase,
+} from "./garden-inbox.mjs";
+
+const now = new Date("2026-07-29T00:00:00.000Z");
+
+function issue(overrides = {}) {
+ return {
+ id: "issue-1",
+ identifier: "PAP-1",
+ title: "Example",
+ status: "done",
+ updatedAt: "2025-01-01T00:00:00.000Z",
+ blockedBy: [],
+ ...overrides,
+ };
+}
+
+function workspace(overrides = {}) {
+ return {
+ gone: false,
+ error: null,
+ status: "active",
+ branchCommitAt: "2025-01-01T00:00:00.000Z",
+ readiness: {
+ git: { isMergedIntoBase: false, aheadCount: 0 },
+ linkedIssues: [{ isTerminal: true }],
+ },
+ ...overrides,
+ };
+}
+
+test("classifies each archive and keep condition into one bucket", () => {
+ const merged = workspace({
+ readiness: {
+ git: { isMergedIntoBase: true, aheadCount: 0 },
+ linkedIssues: [{ isTerminal: true }],
+ },
+ });
+ assert.equal(classify(issue(), merged, 60, now).bucket, "A");
+ assert.equal(classify(issue(), workspace(), 60, now).bucket, "B");
+ assert.equal(classify(issue(), workspace({
+ readiness: {
+ git: { isMergedIntoBase: false, aheadCount: 2 },
+ linkedIssues: [{ isTerminal: true }],
+ },
+ }), 60, now).bucket, "C");
+ assert.equal(classify(issue({ status: "in_progress" }), workspace(), 60, now).bucket, "D");
+});
+
+test("keeps candidates when workspace safety inspection fails", () => {
+ const result = classify(issue(), workspace({ error: "503 Service Unavailable", readiness: null }), 60, now);
+ assert.equal(result.bucket, "D");
+ assert.equal(result.reason.code, "workspace_inspection_failed");
+});
+
+test("returns only accepted options from the originating scan", () => {
+ const candidate = { issueId: "issue-1", bucket: "A" };
+ const scan = { scanId: "scan-1" };
+ const interaction = {
+ id: "interaction-1",
+ kind: "request_checkbox_confirmation",
+ idempotencyKey: "garden-inbox:scan-1:1:1",
+ status: "accepted",
+ payload: { options: [{ id: "issue-1" }] },
+ result: { outcome: "accepted", selectedOptionIds: ["issue-1"] },
+ };
+ assert.deepEqual(acceptedCandidates(interaction, scan, new Map([[candidate.issueId, candidate]])), [candidate]);
+});
+
+test("preserves an overridden scan user for archive and undo requests", () => {
+ assert.deepEqual(archiveTargetBody({ userId: "target-user" }), { userId: "target-user" });
+});
+
+test("rejects selected ids that were not offered", () => {
+ const scan = { scanId: "scan-1" };
+ const interaction = {
+ id: "interaction-1",
+ kind: "request_checkbox_confirmation",
+ idempotencyKey: "garden-inbox:scan-1:1:1",
+ status: "accepted",
+ payload: { options: [{ id: "issue-1" }] },
+ result: { outcome: "accepted", selectedOptionIds: ["issue-2"] },
+ };
+ assert.throws(
+ () => acceptedCandidates(interaction, scan, new Map()),
+ /was not an option in the interaction/,
+ );
+});
+
+test("decodes the responsible user and normalizes API URLs locally", () => {
+ const payload = Buffer.from(JSON.stringify({ responsible_user_id: "user-1" })).toString("base64url");
+ assert.equal(decodeJwtPayload(`header.${payload}.signature`).responsible_user_id, "user-1");
+ assert.equal(normalizeApiBase("https://paperclip.example/api/"), "https://paperclip.example");
+});
+
+test("scans Mine once per status and merges rows by issue id", async (t) => {
+ const requestedStatuses = [];
+ t.mock.method(globalThis, "fetch", async (url) => {
+ const parsed = new URL(url);
+ const status = parsed.searchParams.get("status");
+ requestedStatuses.push(status);
+ const rows = status === "todo"
+ ? [issue({ id: "shared", status: "todo" })]
+ : status === "done"
+ ? [issue({ id: "shared", status: "done" }), issue({ id: "done-only" })]
+ : [];
+ return new Response(JSON.stringify(rows), { status: 200 });
+ });
+
+ const result = await fetchMineInboxRows({
+ apiBase: "https://paperclip.example",
+ apiKey: "secret",
+ }, "user-1");
+
+ assert.deepEqual(requestedStatuses, ["backlog", "todo", "in_progress", "in_review", "blocked", "done"]);
+ assert.equal(result.rows.length, 2);
+ assert.equal(result.rows.find((row) => row.id === "shared").status, "done");
+ assert.equal(result.coverage.duplicateCount, 1);
+ assert.equal(result.coverage.complete, true);
+ assert.deepEqual(result.coverage.statusCounts, {
+ backlog: 0,
+ todo: 1,
+ in_progress: 0,
+ in_review: 0,
+ blocked: 0,
+ done: 2,
+ });
+});
+
+test("warns when an individual status query reaches the Mine endpoint cap", async (t) => {
+ t.mock.method(globalThis, "fetch", async (url) => {
+ const status = new URL(url).searchParams.get("status");
+ const rows = status === "done"
+ ? Array.from({ length: 500 }, (_, index) => issue({ id: `done-${index}` }))
+ : [];
+ return new Response(JSON.stringify(rows), { status: 200 });
+ });
+
+ const result = await fetchMineInboxRows({
+ apiBase: "https://paperclip.example",
+ apiKey: "secret",
+ }, "user-1");
+
+ assert.equal(result.rows.length, 500);
+ assert.equal(result.coverage.complete, false);
+ assert.deepEqual(result.coverage.cappedStatuses, ["done"]);
+ assert.equal(result.coverage.queryCap, 500);
+});