[codex] Roll up May 17 branch changes (#6210)

## Thinking Path

> - Paperclip is the control plane for autonomous AI companies, so agent
work needs visible ownership, recovery, and operator controls.
> - This local branch had accumulated several related control-plane
reliability and operator-experience fixes across recovery actions,
watchdog folding, model-profile defaults, mentions, markdown editing,
plugin launchers, and small UI polish.
> - The branch needed to be converted into a PR against the current
`origin/master` without losing dirty work or including lockfile/workflow
churn.
> - The safest standalone shape is a single rollup PR because the
recovery/server/UI files overlap heavily across the local commits and
splitting would create avoidable conflicts.
> - This pull request replays the local branch onto latest
`origin/master`, preserves the uncommitted work as logical commits, and
adds a Zod 4 validator compatibility fix found during verification.
> - The benefit is that the May 17 local branch can be reviewed and
merged as one coherent, conflict-free branch under the 100-file Greptile
limit.

## What Changed

- Rebased the local May 17 branch work onto current `origin/master` in a
dedicated worktree.
- Preserved and committed previously dirty changes for recovery retry
handling, plugin/sidebar launcher polish, and `.herenow` ignores.
- Added recovery-action behavior for returning source issues to `todo`
when retrying source-scoped recovery.
- Included the existing local recovery/liveness/watchdog fold, Codex
cheap-profile, markdown/mention, duplicate-agent, and UI polish commits
from the branch.
- Normalized shared validator `z.record(...)` schemas to explicit
string-key records for Zod 4 compatibility.
- Confirmed the PR has no `pnpm-lock.yaml` or `.github/workflows/*`
changes and stays below the 100-file Greptile limit.

## Verification

- `pnpm install --frozen-lockfile --ignore-scripts`
- `npm run install` in
`node_modules/.pnpm/sqlite3@5.1.7/node_modules/sqlite3` to build the
local native sqlite3 binding after installing with scripts disabled
- `pnpm exec vitest run packages/shared/src/validators/issue.test.ts
packages/shared/src/project-mentions.test.ts
packages/adapter-utils/src/server-utils.test.ts
server/src/__tests__/heartbeat-model-profile.test.ts
server/src/__tests__/issue-recovery-actions.test.ts
server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts
server/src/__tests__/heartbeat-active-run-output-watchdog.test.ts
server/src/__tests__/plugin-local-folders.test.ts
ui/src/components/IssueRecoveryActionCard.test.tsx
ui/src/components/Sidebar.test.tsx
ui/src/components/SidebarAccountMenu.test.tsx
ui/src/components/IssueProperties.test.tsx
ui/src/components/MarkdownEditor.test.tsx
ui/src/components/MarkdownBody.test.tsx
ui/src/lib/duplicate-agent-payload.test.ts
ui/src/pages/Routines.test.tsx`
- First pass: 13 files passed with 201 passing tests; 3 server files
failed before sqlite3 native binding was built.
- After rebuilding sqlite3:
`server/src/__tests__/heartbeat-model-profile.test.ts`,
`server/src/__tests__/issue-recovery-actions.test.ts`, and
`server/src/__tests__/heartbeat-active-run-output-watchdog.test.ts`
passed/loaded; embedded Postgres tests were skipped by the local host
guard.
- `pnpm --filter @paperclipai/shared typecheck`
- `pnpm --filter @paperclipai/adapter-utils typecheck`
- `pnpm --filter @paperclipai/server typecheck`
- `pnpm --filter @paperclipai/ui typecheck`

## Risks

- Medium risk: this is a broad rollup PR across recovery semantics,
server tests, shared validators, and UI surfaces.
- Some embedded Postgres tests skipped locally due the host guard, so CI
should provide the stronger database-backed signal.
- UI changes were covered by component tests, but no browser screenshot
was captured in this PR creation pass.
- This branch may overlap with existing recovery/liveness PR work; merge
this PR independently or restack/close overlapping branches rather than
merging duplicate implementations together.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, GPT-5-based coding agent, tool-enabled local repository
and GitHub workflow, medium reasoning effort.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/src/lib/activity-format.ts

@@ -61,6 +61,8 @@ const ACTIVITY_ROW_VERBS: Record<string, string> = {
   "agent.runtime_session_reset": "reset session for",
   "heartbeat.invoked": "invoked heartbeat for",
   "heartbeat.cancelled": "cancelled heartbeat for",
+  "heartbeat.output_stale_source_resolved": "system-folded stale run on",
+  "heartbeat.output_stale_recovery_recursion_refused": "refused recovery-on-recovery for",
   "approval.created": "requested approval",
   "approval.approved": "approved",
   "approval.rejected": "rejected",
@@ -115,6 +117,8 @@ const ISSUE_ACTIVITY_LABELS: Record<string, string> = {
   "agent.terminated": "terminated the agent",
   "heartbeat.invoked": "invoked a heartbeat",
   "heartbeat.cancelled": "cancelled a heartbeat",
+  "heartbeat.output_stale_source_resolved": "System folded a stale run",
+  "heartbeat.output_stale_recovery_recursion_refused": "Refused recovery-on-recovery escalation",
   "approval.created": "requested approval",
   "approval.approved": "approved",
   "approval.rejected": "rejected",

ui/src/lib/duplicate-agent-payload.test.ts

@@ -0,0 +1,85 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+import { buildDuplicateAgentPayload, duplicateAgentName } from "./duplicate-agent-payload";
+import type { AgentDetail } from "@paperclipai/shared";
+
+const baseAgent: AgentDetail = {
+  id: "agent-1",
+  companyId: "company-1",
+  name: "Senior Product Engineer",
+  urlKey: "senior-product-engineer",
+  role: "engineer",
+  title: "Senior Product Engineer",
+  icon: "code",
+  status: "idle",
+  reportsTo: "manager-1",
+  capabilities: "Builds product features.",
+  adapterType: "codex_local",
+  adapterConfig: {
+    model: "gpt-5.3-codex",
+    instructionsBundleMode: "managed",
+    instructionsRootPath: "/tmp/original/instructions",
+    instructionsEntryFile: "AGENTS.md",
+    instructionsFilePath: "/tmp/original/instructions/AGENTS.md",
+    promptTemplate: "legacy prompt",
+    bootstrapPromptTemplate: "legacy bootstrap",
+  },
+  runtimeConfig: {
+    heartbeat: { enabled: true },
+  },
+  defaultEnvironmentId: "environment-1",
+  budgetMonthlyCents: 500,
+  spentMonthlyCents: 123,
+  pauseReason: null,
+  pausedAt: null,
+  permissions: { canCreateAgents: true },
+  lastHeartbeatAt: null,
+  metadata: { source: "test" },
+  createdAt: new Date("2026-05-10T00:00:00.000Z"),
+  updatedAt: new Date("2026-05-10T00:00:00.000Z"),
+  chainOfCommand: [],
+  access: {
+    canAssignTasks: true,
+    taskAssignSource: "explicit_grant",
+    membership: null,
+    grants: [],
+  },
+};
+
+describe("duplicate agent payload", () => {
+  it("suffixes duplicate names", () => {
+    expect(duplicateAgentName("Senior Product Engineer")).toBe("Senior Product Engineer Copy");
+    expect(duplicateAgentName("   ")).toBe("Agent Copy");
+  });
+
+  it("copies agent fields while removing original instruction paths", () => {
+    const payload = buildDuplicateAgentPayload(baseAgent, {
+      entryFile: "AGENTS.md",
+      files: {
+        "AGENTS.md": "You are a copy.",
+      },
+    });
+
+    expect(payload).toMatchObject({
+      name: "Senior Product Engineer Copy",
+      role: "engineer",
+      title: "Senior Product Engineer",
+      icon: "code",
+      reportsTo: "manager-1",
+      capabilities: "Builds product features.",
+      adapterType: "codex_local",
+      adapterConfig: { model: "gpt-5.3-codex" },
+      runtimeConfig: { heartbeat: { enabled: true } },
+      defaultEnvironmentId: "environment-1",
+      budgetMonthlyCents: 500,
+      permissions: { canCreateAgents: true },
+      metadata: { source: "test" },
+      instructionsBundle: {
+        entryFile: "AGENTS.md",
+        files: { "AGENTS.md": "You are a copy." },
+      },
+    });
+    expect(payload.adapterConfig).not.toHaveProperty("instructionsFilePath");
+    expect(payload.adapterConfig).not.toHaveProperty("promptTemplate");
+  });
+});

ui/src/lib/duplicate-agent-payload.ts

@@ -0,0 +1,78 @@
+import type { AgentDetail } from "@paperclipai/shared";
+
+const INSTRUCTION_CONFIG_KEYS = [
+  "instructionsBundleMode",
+  "instructionsRootPath",
+  "instructionsEntryFile",
+  "instructionsFilePath",
+  "agentsMdPath",
+  "promptTemplate",
+  "bootstrapPromptTemplate",
+] as const;
+
+export type DuplicateInstructionsBundle = {
+  entryFile: string;
+  files: Record<string, string>;
+};
+
+type DuplicateAgentSource = Pick<
+  AgentDetail,
+  | "name"
+  | "role"
+  | "title"
+  | "icon"
+  | "reportsTo"
+  | "capabilities"
+  | "adapterType"
+  | "adapterConfig"
+  | "runtimeConfig"
+  | "defaultEnvironmentId"
+  | "budgetMonthlyCents"
+  | "permissions"
+  | "metadata"
+>;
+
+function cloneRecord(value: Record<string, unknown> | null | undefined): Record<string, unknown> {
+  if (!value) return {};
+  return JSON.parse(JSON.stringify(value)) as Record<string, unknown>;
+}
+
+export function duplicateAgentName(name: string): string {
+  const trimmed = name.trim();
+  return `${trimmed || "Agent"} Copy`;
+}
+
+export function buildDuplicateAgentPayload(
+  agent: DuplicateAgentSource,
+  instructionsBundle?: DuplicateInstructionsBundle | null,
+): Record<string, unknown> {
+  const adapterConfig = cloneRecord(agent.adapterConfig);
+  for (const key of INSTRUCTION_CONFIG_KEYS) {
+    delete adapterConfig[key];
+  }
+
+  const payload: Record<string, unknown> = {
+    name: duplicateAgentName(agent.name),
+    role: agent.role,
+    adapterType: agent.adapterType,
+    adapterConfig,
+    runtimeConfig: cloneRecord(agent.runtimeConfig),
+    defaultEnvironmentId: agent.defaultEnvironmentId ?? null,
+    budgetMonthlyCents: agent.budgetMonthlyCents ?? 0,
+    permissions: {
+      canCreateAgents: Boolean(agent.permissions?.canCreateAgents),
+    },
+  };
+
+  if (agent.title) payload.title = agent.title;
+  if (agent.icon) payload.icon = agent.icon;
+  if (agent.reportsTo) payload.reportsTo = agent.reportsTo;
+  if (agent.capabilities) payload.capabilities = agent.capabilities;
+  if (agent.metadata) payload.metadata = cloneRecord(agent.metadata);
+
+  if (instructionsBundle && Object.keys(instructionsBundle.files).length > 0) {
+    payload.instructionsBundle = instructionsBundle;
+  }
+
+  return payload;
+}

ui/src/lib/mention-chips.ts

@@ -3,6 +3,7 @@ import {
   parseAgentMentionHref,
   parseIssueReferenceHref,
   parseProjectMentionHref,
+  parseRoutineMentionHref,
   parseSkillMentionHref,
   parseUserMentionHref,
 } from "@paperclipai/shared";
@@ -32,6 +33,10 @@ export type ParsedMentionChip =
       kind: "skill";
       skillId: string;
       slug: string | null;
+    }
+  | {
+      kind: "routine";
+      routineId: string;
     };
 
 const iconMaskCache = new Map<string, string>();
@@ -84,6 +89,14 @@ export function parseMentionChipHref(href: string): ParsedMentionChip | null {
     };
   }
 
+  const routine = parseRoutineMentionHref(href);
+  if (routine) {
+    return {
+      kind: "routine",
+      routineId: routine.routineId,
+    };
+  }
+
   return null;
 }
 
@@ -135,6 +148,7 @@ export function clearMentionChipDecoration(element: HTMLElement) {
     "paperclip-mention-chip--agent",
     "paperclip-mention-chip--issue",
     "paperclip-mention-chip--project",
+    "paperclip-mention-chip--routine",
     "paperclip-mention-chip--user",
     "paperclip-mention-chip--skill",
     "paperclip-project-mention-chip",

ui/src/lib/source-resolved-watchdog-fold.ts

@@ -0,0 +1,134 @@
+import type { HeartbeatRun } from "@paperclipai/shared";
+
+export type SourceResolvedFoldCleanupOutcome =
+  | "terminated"
+  | "termination_sent_still_running"
+  | "failed"
+  | "not_running"
+  | "no_process_metadata"
+  | "skipped_non_local_adapter"
+  | string;
+
+export interface SourceResolvedFoldCleanup {
+  attempted: boolean;
+  outcome: SourceResolvedFoldCleanupOutcome;
+  adapterType: string | null;
+  pid: number | null;
+  processGroupId: number | null;
+  error: string | null;
+}
+
+export interface SourceResolvedWatchdogFold {
+  sourceIssueId: string;
+  sourceIssueIdentifier: string | null;
+  sourceIssueStatus: string;
+  sameRunEvidenceKind: string;
+  sameRunEvidenceId: string;
+  sameRunEvidenceAt: string;
+  silenceStartedAt: string | null;
+  silenceAgeMs: number | null;
+  evaluationIssueId: string | null;
+  evaluationIssueIdentifier: string | null;
+  cleanup: SourceResolvedFoldCleanup;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function asFiniteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function asBoolean(value: unknown): boolean {
+  return value === true;
+}
+
+function parseCleanup(value: unknown): SourceResolvedFoldCleanup {
+  const record = asRecord(value);
+  if (!record) {
+    return {
+      attempted: false,
+      outcome: "no_process_metadata",
+      adapterType: null,
+      pid: null,
+      processGroupId: null,
+      error: null,
+    };
+  }
+  return {
+    attempted: asBoolean(record.attempted),
+    outcome: asString(record.outcome) ?? "no_process_metadata",
+    adapterType: asString(record.adapterType),
+    pid: asFiniteNumber(record.pid),
+    processGroupId: asFiniteNumber(record.processGroupId),
+    error: asString(record.error),
+  };
+}
+
+export function parseSourceResolvedWatchdogFold(value: unknown): SourceResolvedWatchdogFold | null {
+  const record = asRecord(value);
+  if (!record) return null;
+  const sourceIssueId = asString(record.sourceIssueId);
+  const sourceIssueStatus = asString(record.sourceIssueStatus);
+  if (!sourceIssueId || !sourceIssueStatus) return null;
+  const evidenceKind = asString(record.sameRunEvidenceKind);
+  const evidenceId = asString(record.sameRunEvidenceId);
+  const evidenceAt = asString(record.sameRunEvidenceAt);
+  if (!evidenceKind || !evidenceId || !evidenceAt) return null;
+  return {
+    sourceIssueId,
+    sourceIssueIdentifier: asString(record.sourceIssueIdentifier),
+    sourceIssueStatus,
+    sameRunEvidenceKind: evidenceKind,
+    sameRunEvidenceId: evidenceId,
+    sameRunEvidenceAt: evidenceAt,
+    silenceStartedAt: asString(record.silenceStartedAt),
+    silenceAgeMs: asFiniteNumber(record.silenceAgeMs),
+    evaluationIssueId: asString(record.evaluationIssueId),
+    evaluationIssueIdentifier: asString(record.evaluationIssueIdentifier),
+    cleanup: parseCleanup(record.cleanup),
+  };
+}
+
+export function readSourceResolvedWatchdogFold(
+  resultJson: HeartbeatRun["resultJson"] | Record<string, unknown> | null | undefined,
+): SourceResolvedWatchdogFold | null {
+  const record = asRecord(resultJson);
+  if (!record) return null;
+  return parseSourceResolvedWatchdogFold(record.sourceResolvedWatchdogFold);
+}
+
+const CLEANUP_OUTCOME_LABELS: Record<string, string> = {
+  terminated: "terminated",
+  termination_sent_still_running: "termination sent (still running)",
+  failed: "failed",
+  not_running: "not running",
+  no_process_metadata: "no process metadata",
+  skipped_non_local_adapter: "skipped (non-local adapter)",
+};
+
+export function formatCleanupOutcome(outcome: string): string {
+  return CLEANUP_OUTCOME_LABELS[outcome] ?? outcome.replace(/_/g, " ");
+}
+
+export function formatSilenceAgeMs(ms: number | null | undefined): string | null {
+  if (!ms || ms <= 0) return null;
+  const totalMinutes = Math.floor(ms / 60_000);
+  if (totalMinutes < 1) return "under 1 minute";
+  if (totalMinutes < 60) return `${totalMinutes} minute${totalMinutes === 1 ? "" : "s"}`;
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (minutes === 0) return `${hours} hour${hours === 1 ? "" : "s"}`;
+  return `${hours}h ${minutes}m`;
+}
+
+export function shortenEvidenceId(id: string): string {
+  if (id.length <= 12) return id;
+  return id.slice(0, 8);
+}