[codex] Add issue monitor liveness controls (#4988)
## Thinking Path
> - Paperclip is a control plane for autonomous AI companies where work
must stay observable, governable, and recoverable.
> - The task/heartbeat subsystem owns agent execution continuity, issue
state transitions, and visible recovery behavior.
> - Waiting on an external service is not the same as being blocked when
the assignee still owns a future check.
> - The gap was that agents had no first-class one-shot monitor state
for external-service waits, so recovery could look stalled or require ad
hoc comments.
> - This pull request adds bounded issue monitors that can wake the
owner, clear exhausted waits, and produce explicit recovery behavior.
> - It also surfaces monitor status in the board UI and documents when
to use monitors versus `blocked`.
> - The benefit is clearer liveness semantics for asynchronous waits
without weakening single-assignee task ownership.
## What Changed
- Added issue monitor fields, shared types, validators, constants, and
an idempotent `0075` migration for scheduled monitor state.
- Added server-side monitor scheduling, dispatch, recovery bounds,
activity logging, and external-ref redaction.
- Added board/agent route coverage for monitor permissions and child
monitor scheduling.
- Added issue detail/property UI for monitor state, a monitor activity
card, and Storybook stories for review surfaces.
- Documented monitor semantics and recovery policy behavior in
`doc/execution-semantics.md`.
- Addressed Greptile review feedback by preserving monitor state in
skipped-stage builders and making board monitor saves send `scheduledBy:
"board"`.
## Verification
- `pnpm install --frozen-lockfile`
- `pnpm run preflight:workspace-links && pnpm exec vitest run
server/src/__tests__/issue-execution-policy-routes.test.ts
server/src/__tests__/issue-execution-policy.test.ts
server/src/__tests__/issue-monitor-scheduler.test.ts
server/src/__tests__/recovery-classifiers.test.ts
ui/src/components/IssueMonitorActivityCard.test.tsx
ui/src/components/IssueProperties.test.tsx
ui/src/lib/activity-format.test.ts`
- First run passed 5 files and failed to collect 2 server suites because
the worktree was missing the optional `acpx/runtime` dependency.
- After `pnpm install --frozen-lockfile`, reran the 2 failed suites
successfully.
- `pnpm exec vitest run
server/src/__tests__/issue-monitor-scheduler.test.ts
server/src/__tests__/recovery-classifiers.test.ts`
- `pnpm --filter @paperclipai/shared typecheck && pnpm --filter
@paperclipai/db typecheck && pnpm --filter @paperclipai/server typecheck
&& pnpm --filter @paperclipai/ui typecheck`
- `pnpm exec vitest run
server/src/__tests__/issue-execution-policy.test.ts
ui/src/components/IssueProperties.test.tsx`
- `pnpm --filter @paperclipai/server typecheck && pnpm --filter
@paperclipai/ui typecheck`
- `pnpm exec vitest run
ui/src/components/IssueMonitorActivityCard.test.tsx
ui/src/components/IssueProperties.test.tsx`
- `pnpm --filter @paperclipai/ui typecheck`
- Storybook screenshot captured from
`http://127.0.0.1:6006/iframe.html?viewMode=story&id=product-issue-monitor-surfaces--monitor-surfaces`
with Playwright.
## Screenshots

## Risks
- Medium: this changes heartbeat recovery behavior for scheduled
external-service waits, so regressions could affect wake timing or
recovery issue creation.
- Migration risk is reduced by using `IF NOT EXISTS` for the new issue
monitor columns and index.
- External monitor references are treated as secret-adjacent and are
intentionally omitted from visible activity/wake payloads.
> 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 coding agent with repository tool use and terminal
execution.
## 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
- [x] If this change affects the UI, I have included before/after
screenshots or Storybook review surfaces
- [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>
2026-05-03 08:58:53 -05:00
|
|
|
// @vitest-environment jsdom
|
|
|
|
|
|
|
|
|
|
import { act } from "react";
|
|
|
|
|
import { createRoot } from "react-dom/client";
|
|
|
|
|
import type { Issue } from "@paperclipai/shared";
|
|
|
|
|
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
|
|
|
|
import { IssueMonitorActivityCard } from "./IssueMonitorActivityCard";
|
|
|
|
|
|
|
|
|
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
|
|
|
(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
|
|
|
|
|
|
|
|
|
|
function createIssue(overrides: Partial<Issue> = {}): Issue {
|
|
|
|
|
return {
|
|
|
|
|
id: "issue-1",
|
|
|
|
|
companyId: "company-1",
|
|
|
|
|
projectId: null,
|
|
|
|
|
projectWorkspaceId: null,
|
|
|
|
|
goalId: null,
|
|
|
|
|
parentId: null,
|
|
|
|
|
title: "Watch deploy",
|
|
|
|
|
description: null,
|
|
|
|
|
status: "in_progress",
|
|
|
|
|
priority: "medium",
|
|
|
|
|
assigneeAgentId: "agent-1",
|
|
|
|
|
assigneeUserId: null,
|
|
|
|
|
checkoutRunId: null,
|
|
|
|
|
executionRunId: null,
|
|
|
|
|
executionAgentNameKey: null,
|
|
|
|
|
executionLockedAt: null,
|
|
|
|
|
createdByAgentId: null,
|
|
|
|
|
createdByUserId: "local-board",
|
|
|
|
|
issueNumber: 1,
|
|
|
|
|
identifier: "PAP-1",
|
|
|
|
|
requestDepth: 0,
|
|
|
|
|
billingCode: null,
|
|
|
|
|
assigneeAdapterOverrides: null,
|
|
|
|
|
executionPolicy: {
|
|
|
|
|
mode: "normal",
|
|
|
|
|
commentRequired: true,
|
|
|
|
|
stages: [],
|
|
|
|
|
monitor: {
|
|
|
|
|
nextCheckAt: "2026-04-11T12:30:00.000Z",
|
|
|
|
|
notes: "Check deployment health",
|
|
|
|
|
scheduledBy: "board",
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
executionState: {
|
|
|
|
|
status: "idle",
|
|
|
|
|
currentStageId: null,
|
|
|
|
|
currentStageIndex: null,
|
|
|
|
|
currentStageType: null,
|
|
|
|
|
currentParticipant: null,
|
|
|
|
|
returnAssignee: null,
|
|
|
|
|
reviewRequest: null,
|
|
|
|
|
completedStageIds: [],
|
|
|
|
|
lastDecisionId: null,
|
|
|
|
|
lastDecisionOutcome: null,
|
|
|
|
|
monitor: {
|
|
|
|
|
status: "scheduled",
|
|
|
|
|
nextCheckAt: "2026-04-11T12:30:00.000Z",
|
|
|
|
|
lastTriggeredAt: null,
|
|
|
|
|
attemptCount: 0,
|
|
|
|
|
notes: "Check deployment health",
|
|
|
|
|
scheduledBy: "board",
|
|
|
|
|
clearedAt: null,
|
|
|
|
|
clearReason: null,
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
monitorNextCheckAt: new Date("2026-04-11T12:30:00.000Z"),
|
|
|
|
|
monitorLastTriggeredAt: null,
|
|
|
|
|
monitorAttemptCount: 0,
|
|
|
|
|
monitorNotes: "Check deployment health",
|
|
|
|
|
monitorScheduledBy: "board",
|
|
|
|
|
executionWorkspaceId: null,
|
|
|
|
|
executionWorkspacePreference: null,
|
|
|
|
|
executionWorkspaceSettings: null,
|
|
|
|
|
startedAt: null,
|
|
|
|
|
completedAt: null,
|
|
|
|
|
cancelledAt: null,
|
|
|
|
|
hiddenAt: null,
|
|
|
|
|
createdAt: new Date("2026-04-11T10:00:00.000Z"),
|
|
|
|
|
updatedAt: new Date("2026-04-11T10:00:00.000Z"),
|
|
|
|
|
...overrides,
|
Add planning mode for issue work (#5353)
## Thinking Path
> - Paperclip is a control plane for autonomous AI companies.
> - Issues are the core unit of work, and issue comments are how board
users and agents coordinate execution.
> - Some issue conversations need to produce plans and approvals instead
of immediate implementation work.
> - The existing issue contract did not distinguish standard execution
comments from planning-oriented issue work.
> - This pull request adds an issue work-mode contract and board UI
affordances for standard vs planning mode.
> - The benefit is that planning-mode issues can be created, displayed,
discussed, and carried through agent heartbeat context without losing
the normal issue workflow.
## What Changed
- Added `standard` / `planning` issue work-mode contracts across DB,
shared validators/types, server issue flows, plugin protocol, and
adapter heartbeat payloads.
- Added an idempotent `0081_optimal_dormammu` migration for
`issues.work_mode`, ordered after current `public-gh/master` migrations.
- Updated heartbeat/context summaries and issue-thread interaction
behavior so planning work mode is preserved when creating suggested
follow-up issues.
- Added UI support for planning-mode issue creation, issue rows, detail
composer styling, and composer work-mode toggles.
- Added focused server/shared/UI tests plus a Playwright visual
verification spec for planning-mode surfaces.
- Rebased the branch onto current `public-gh/master` and added durable
planning-mode screenshots under `doc/assets/pap-3368/`.
## Verification
- `pnpm --filter @paperclipai/db run check:migrations`
- `pnpm exec vitest run --project @paperclipai/shared
packages/shared/src/validators/issue.test.ts`
- `pnpm exec vitest run --project @paperclipai/server
server/src/__tests__/heartbeat-context-summary.test.ts
server/src/__tests__/issue-thread-interactions-service.test.ts
server/src/__tests__/issues-goal-context-routes.test.ts --pool=forks
--poolOptions.forks.isolate=true`
- `pnpm exec vitest run --project @paperclipai/ui
ui/src/components/IssueChatThread.test.tsx
ui/src/components/NewIssueDialog.test.tsx
ui/src/components/IssueRow.test.tsx ui/src/pages/IssueDetail.test.tsx`
- `pnpm exec vitest run --project @paperclipai/adapter-utils
packages/adapter-utils/src/server-utils.test.ts`
- `PAPERCLIP_E2E_SKIP_LLM=true npx playwright test --config
tests/e2e/playwright.config.ts
tests/e2e/planning-mode-visual-verification.spec.ts`
## Screenshots
Desktop planning detail:

Desktop planning row:

Desktop staged standard toggle:

Mobile planning detail:

Mobile planning row:

## Risks
- Medium migration risk: this adds a non-null issue column. The
migration uses `ADD COLUMN IF NOT EXISTS` so installations that applied
an older branch-local migration number can still apply the final
numbered migration safely.
- Medium contract risk: issue payloads, plugin payloads, and adapter
heartbeat payloads now include work mode; compatibility is handled by
defaulting missing values to `standard`.
- UI risk is moderate because composer controls changed; focused
component tests and visual e2e coverage exercise standard vs planning
display and toggle behavior.
> 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 coding agent in a local Paperclip worktree, with
shell/tool use. Exact context-window size is not exposed in this
runtime.
## 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
- [x] 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>
2026-05-06 07:01:28 -05:00
|
|
|
workMode: overrides.workMode ?? "standard",
|
[codex] Add issue monitor liveness controls (#4988)
## Thinking Path
> - Paperclip is a control plane for autonomous AI companies where work
must stay observable, governable, and recoverable.
> - The task/heartbeat subsystem owns agent execution continuity, issue
state transitions, and visible recovery behavior.
> - Waiting on an external service is not the same as being blocked when
the assignee still owns a future check.
> - The gap was that agents had no first-class one-shot monitor state
for external-service waits, so recovery could look stalled or require ad
hoc comments.
> - This pull request adds bounded issue monitors that can wake the
owner, clear exhausted waits, and produce explicit recovery behavior.
> - It also surfaces monitor status in the board UI and documents when
to use monitors versus `blocked`.
> - The benefit is clearer liveness semantics for asynchronous waits
without weakening single-assignee task ownership.
## What Changed
- Added issue monitor fields, shared types, validators, constants, and
an idempotent `0075` migration for scheduled monitor state.
- Added server-side monitor scheduling, dispatch, recovery bounds,
activity logging, and external-ref redaction.
- Added board/agent route coverage for monitor permissions and child
monitor scheduling.
- Added issue detail/property UI for monitor state, a monitor activity
card, and Storybook stories for review surfaces.
- Documented monitor semantics and recovery policy behavior in
`doc/execution-semantics.md`.
- Addressed Greptile review feedback by preserving monitor state in
skipped-stage builders and making board monitor saves send `scheduledBy:
"board"`.
## Verification
- `pnpm install --frozen-lockfile`
- `pnpm run preflight:workspace-links && pnpm exec vitest run
server/src/__tests__/issue-execution-policy-routes.test.ts
server/src/__tests__/issue-execution-policy.test.ts
server/src/__tests__/issue-monitor-scheduler.test.ts
server/src/__tests__/recovery-classifiers.test.ts
ui/src/components/IssueMonitorActivityCard.test.tsx
ui/src/components/IssueProperties.test.tsx
ui/src/lib/activity-format.test.ts`
- First run passed 5 files and failed to collect 2 server suites because
the worktree was missing the optional `acpx/runtime` dependency.
- After `pnpm install --frozen-lockfile`, reran the 2 failed suites
successfully.
- `pnpm exec vitest run
server/src/__tests__/issue-monitor-scheduler.test.ts
server/src/__tests__/recovery-classifiers.test.ts`
- `pnpm --filter @paperclipai/shared typecheck && pnpm --filter
@paperclipai/db typecheck && pnpm --filter @paperclipai/server typecheck
&& pnpm --filter @paperclipai/ui typecheck`
- `pnpm exec vitest run
server/src/__tests__/issue-execution-policy.test.ts
ui/src/components/IssueProperties.test.tsx`
- `pnpm --filter @paperclipai/server typecheck && pnpm --filter
@paperclipai/ui typecheck`
- `pnpm exec vitest run
ui/src/components/IssueMonitorActivityCard.test.tsx
ui/src/components/IssueProperties.test.tsx`
- `pnpm --filter @paperclipai/ui typecheck`
- Storybook screenshot captured from
`http://127.0.0.1:6006/iframe.html?viewMode=story&id=product-issue-monitor-surfaces--monitor-surfaces`
with Playwright.
## Screenshots

## Risks
- Medium: this changes heartbeat recovery behavior for scheduled
external-service waits, so regressions could affect wake timing or
recovery issue creation.
- Migration risk is reduced by using `IF NOT EXISTS` for the new issue
monitor columns and index.
- External monitor references are treated as secret-adjacent and are
intentionally omitted from visible activity/wake payloads.
> 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 coding agent with repository tool use and terminal
execution.
## 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
- [x] If this change affects the UI, I have included before/after
screenshots or Storybook review surfaces
- [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>
2026-05-03 08:58:53 -05:00
|
|
|
};
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
describe("IssueMonitorActivityCard", () => {
|
|
|
|
|
let container: HTMLDivElement;
|
|
|
|
|
|
|
|
|
|
beforeEach(() => {
|
|
|
|
|
vi.useFakeTimers();
|
|
|
|
|
vi.setSystemTime(new Date("2026-04-11T12:00:00.000Z"));
|
|
|
|
|
container = document.createElement("div");
|
|
|
|
|
document.body.appendChild(container);
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
afterEach(() => {
|
|
|
|
|
vi.useRealTimers();
|
|
|
|
|
container.remove();
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
it("renders the scheduled monitor details and check-now action", () => {
|
|
|
|
|
const onCheckNow = vi.fn();
|
|
|
|
|
const root = createRoot(container);
|
|
|
|
|
|
|
|
|
|
act(() => {
|
|
|
|
|
root.render(<IssueMonitorActivityCard issue={createIssue()} onCheckNow={onCheckNow} />);
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
expect(container.textContent).toContain("Monitor scheduled");
|
|
|
|
|
expect(container.textContent).toContain("Next check");
|
|
|
|
|
expect(container.textContent).toContain("in 30m");
|
|
|
|
|
expect(container.textContent).toContain("Check deployment health");
|
|
|
|
|
|
|
|
|
|
const button = Array.from(container.querySelectorAll("button")).find((candidate) =>
|
|
|
|
|
candidate.textContent?.includes("Check now"),
|
|
|
|
|
);
|
|
|
|
|
expect(button).toBeTruthy();
|
|
|
|
|
|
|
|
|
|
act(() => {
|
|
|
|
|
button?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
expect(onCheckNow).toHaveBeenCalledTimes(1);
|
|
|
|
|
|
|
|
|
|
act(() => root.unmount());
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
it("does not render external references from monitor metadata", () => {
|
|
|
|
|
const root = createRoot(container);
|
|
|
|
|
|
|
|
|
|
act(() => {
|
|
|
|
|
root.render(
|
|
|
|
|
<IssueMonitorActivityCard
|
|
|
|
|
issue={createIssue({
|
|
|
|
|
executionPolicy: {
|
|
|
|
|
mode: "normal",
|
|
|
|
|
commentRequired: true,
|
|
|
|
|
stages: [],
|
|
|
|
|
monitor: {
|
|
|
|
|
nextCheckAt: "2026-04-11T12:30:00.000Z",
|
|
|
|
|
notes: "Check deployment health",
|
|
|
|
|
scheduledBy: "board",
|
|
|
|
|
serviceName: "Deploy provider",
|
|
|
|
|
externalRef: "https://provider.example/deploy/123?token=secret",
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
})}
|
|
|
|
|
/>,
|
|
|
|
|
);
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
expect(container.textContent).toContain("Deploy provider");
|
|
|
|
|
expect(container.textContent).not.toContain("provider.example");
|
|
|
|
|
expect(container.textContent).not.toContain("token=secret");
|
|
|
|
|
|
|
|
|
|
act(() => root.unmount());
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
it("renders nothing when the issue has no scheduled monitor", () => {
|
|
|
|
|
const root = createRoot(container);
|
|
|
|
|
|
|
|
|
|
act(() => {
|
|
|
|
|
root.render(
|
|
|
|
|
<IssueMonitorActivityCard
|
|
|
|
|
issue={createIssue({
|
|
|
|
|
executionPolicy: {
|
|
|
|
|
mode: "normal",
|
|
|
|
|
commentRequired: true,
|
|
|
|
|
stages: [],
|
|
|
|
|
},
|
|
|
|
|
executionState: {
|
|
|
|
|
status: "idle",
|
|
|
|
|
currentStageId: null,
|
|
|
|
|
currentStageIndex: null,
|
|
|
|
|
currentStageType: null,
|
|
|
|
|
currentParticipant: null,
|
|
|
|
|
returnAssignee: null,
|
|
|
|
|
reviewRequest: null,
|
|
|
|
|
completedStageIds: [],
|
|
|
|
|
lastDecisionId: null,
|
|
|
|
|
lastDecisionOutcome: null,
|
|
|
|
|
monitor: null,
|
|
|
|
|
},
|
|
|
|
|
monitorNextCheckAt: null,
|
|
|
|
|
monitorNotes: null,
|
|
|
|
|
})}
|
|
|
|
|
/>,
|
|
|
|
|
);
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
expect(container.textContent).toBe("");
|
|
|
|
|
|
|
|
|
|
act(() => root.unmount());
|
|
|
|
|
});
|
|
|
|
|
});
|