fix: prevent Paperclip heartbeat spam, stable thread per task

Root cause: deployed agents had no runtimeConfig, so Paperclip's
default heartbeat scheduler could fire repeatedly. Each heartbeat
created a new AF thread (using runId), causing thread spam.

Fixes:
- Deploy now sets runtimeConfig.heartbeat.intervalSec=0 (on-demand
  only, no automatic timer). Configurable via --heartbeat-interval.
- Paperclip connector uses issueId as threadId (not runId), so
  repeated triggers for the same task reuse the same AF conversation
  thread, preserving context instead of creating duplicates.
- Added --heartbeat-interval flag to `af paperclip deploy`

Verified by sub-agent: 2 triggers for same issue → same thread_id,
2 comments (not 50), conversation continuity preserved.

Author: seanphan

packages/cli/src/cli/gateway/connectors/paperclip.ts

@@ -61,13 +61,16 @@ export class PaperclipConnector implements ChannelConnector {
 
     if (parts.length === 0) parts.push("Heartbeat triggered. Check your inbox for work.");
 
+    // Use issueId as threadId so repeated heartbeats for the same task
+    // reuse the same AF conversation thread (continuity, not duplication)
     const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    const stableThreadId = issueId && uuidRe.test(issueId) ? issueId : undefined;
 
     return {
       afAgentId,
       afStreamUrl,
       message: parts.join("\n"),
-      threadId: uuidRe.test(payload.runId) ? payload.runId : undefined,
+      threadId: stableThreadId,
       label: (ctx.taskKey as string) ?? issueId ?? "heartbeat",
       replyContext: { issueId, agentId: payload.agentId },
     };

packages/cli/src/cli/main.ts

@@ -4336,6 +4336,7 @@ export function createProgram(): Command {
     .option("--company-name <name>", "Create a new Paperclip company with this name")
     .option("--role <role>", "Paperclip agent role", "general")
     .option("--budget <cents>", "Monthly budget in cents", "0")
+    .option("--heartbeat-interval <seconds>", "Auto-heartbeat interval in seconds (0 = on-demand only)", "0")
     .option("--reports-to <id>", "Paperclip agent ID this agent reports to")
     .action(async (opts) => {
       const client = buildClient(program.opts());
@@ -4416,6 +4417,13 @@ export function createProgram(): Command {
             messages: [{ content: "Execute your assigned task.", role: "user" }],
           },
         },
+        runtimeConfig: {
+          heartbeat: {
+            enabled: true,
+            intervalSec: Number.parseInt(opts.heartbeatInterval as string, 10) || 0,
+            wakeOnDemand: true,
+          },
+        },
         budgetMonthlyCents: Number.parseInt(opts.budget, 10) || 0,
         reportsTo: opts.reportsTo,
         metadata,