paperclip-harness/docs/PAPERCLIP-API-NOTES.md

Paperclip API — read-only probe, 2026-11-09

Probe only: no writes, no task created, nothing in the existing projects touched. All requests were GET with Authorization: Bearer $PAPERCLIP_API_KEY read from the environment; the key is never printed here.

Where it runs

• Local server: http://127.0.0.1:3100, pid 1588, started 2026-11-05. From ~/.paperclip/instances/default/runtime-info.json.
• Public URL: https://paperclip.lab.audasmedia.com.au.
• Postgres: postgres://paperclip@127.0.0.1:5433/paperclip (embedded, local).
• CLI: paperclipai 2026.916.1, managed install under ~/.paperclip/cli/installs.

Endpoints that answered

Request	Result
GET /api/health	200, 899 bytes
GET /api/openapi.json	200, 1.1 MB — 685 paths
GET /api/agents/me	200 — identity, company, adapter
GET /api/companies/{companyId}/issues?limit=200	200 — 145 issues
GET /api/issues/{id}	200
GET /api/issues/{id}/comments	200
GET /api/issues/{id}/activity	200
GET /api/issues/{id}/cost-summary	200
GET /api/issues?limit=5	400 — "Missing companyId in path"

The identity the API answered as

name: Hub, role: general, status: idle, adapterType: **pi_local**, model omni/deepseek/deepseek-v4-flash. So Pi is the installed worker adapter, not something we must write.

What already exists in this instance

• 10 projects, 145 issues: 139 done, 2 blocked, 2 in_progress, 1 todo, 1 backlog.
• Every status the four-screen TUI needs is already a first-class value.

Endpoints the TUI and the executor will need (from the 685 in the spec)

• Read: /api/companies/{companyId}/issues, /api/issues/{id}, /api/issues/{id}/comments, /api/issues/{id}/activity, /api/issues/{id}/children, /api/issues/{id}/diagnostics/blockers, /api/issues/{id}/cost-summary, /api/issues/{id}/runs, /api/issues/{id}/heartbeat-context, /api/agents/me/inbox-lite.
• Write (later, not in this probe): /api/issues, /api/issues/{id}/comments, /api/issues/{id}/checkout, /api/issues/{id}/release, /api/approvals/{id}/approve|reject|request-revision, /api/cases/{caseId}/blockers, /api/issues/{id}/interactions/{interactionId}/respond.
• Trees and holds: /api/issues/{id}/tree-control/state|preview, /api/issues/{id}/tree-holds, /api/issues/{id}/diagnostics/subtree.

Hypotheses

• H1 — the control plane answers. PASS. Health, identity, 145 issues.
• H2 — task with a blocker via API. NOT TESTED (a write; out of scope for a read-only probe). Note: the two blocked issues returned blockedByIssueIds: None, so the blocker relation may live in /api/cases/{caseId}/blockers or /api/issues/{id}/diagnostics/blockers rather than on the issue row. This must be established before trusting screen 1.
• H3 — a comment wakes an agent. NOT TESTED. The wake plumbing is visible in the spec (heartbeat-context, inbox-lite, queued-comments/steer, diagnostics/wakes), and agents run on heartbeats, so the shape is right. Unproven.
• H4 — Pi can be a worker. Likely PASS: adapterType: pi_local is the identity's own adapter, and Pi is listed as a supported runtime upstream.
• H5 — cost and run history readable. PASS. /api/issues/{id}/cost-summary returns costCents, inputTokens, cachedInputTokens, outputTokens, runCount.

What this changes

The premise holds: there is a live control plane, with the statuses, threads, activity, cost and blocker diagnostics a four-screen TUI needs, and Pi is already the adapter. The work that remains is small and specific: prove a blocker edge by API, prove a comment wakes an agent, and write the executor that puts a task into a git worktree, runs it and reports back.

Sandbox writes, 2026-11-09 (approved in advance)

Sandbox created: project spike-2026-11-09 (9e3f61f6-cce9-49b1-8083-3130345a04a5), status backlog, workspace git_repo at /tmp/pc-sandbox (a throwaway repo with one commit). It is safe to delete.

Two issues created by API, status todo:

• AUD-157 Spike T1 — write a file (2ce09ea8-…)
• AUD-158 Spike T2 — read that file (abc5d318-…)

The permission rule, learned the hard way

With PAPERCLIP_API_KEY (the agent Hub), every write returned 403:

"Cross-issue writes need a run to attribute them to (Heartbeat run context). Every agent comment and task update is attributed to a heartbeat run so the cross-issue cap can be counted and the audit trail can name who acted for whom."

So an agent key is only usable inside a heartbeat run, with X-Paperclip-Run-Id. A cockpit acting for the person must use the user credential (PAPERCLIP_BOARD_KEY), not the agent key. That is a design fact, not an obstacle: the TUI is the person's surface, and the audit trail correctly refuses anonymous agent writes.

H2 — a task with a blocker: PASS

PATCH /api/issues/{id} with {"blockedByIssueIds":["<t1>"]} → 200, and the edge reads back. GET /api/issues/{id}/diagnostics/blockers returns:

readiness: { allBlockersDone: false, isDependencyReady: false, unresolvedBlockerCount: 1 }
blockers:  [ "Spike T1 — write a file" ]

Note: the blocker edge is not on the issue list rows (blockedByIssueIds: 0 there). A tree view must read diagnostics/blockers (or the single-issue GET) per task, not the list. That is the one place screen 1 could have lied to us.

H3 — a comment lands on a blocked task: PASS

POST /api/issues/{id}/comments with the user key → 201, authorType: user, and the comment is on the thread of the blocked task. What this does not yet prove is that a comment wakes an agent: that requires a real agent on the task and a heartbeat. The wake plumbing is present in the spec (heartbeat-context, inbox-lite, queued-comments/steer, diagnostics/wakes); the wake itself is unproven.

Updated verdict

H1 pass, H2 pass, H3 partly (comment lands; wake unproven), H4 likely (Pi is the adapter), H5 pass. The remaining proof is one real agent doing one task, which is Milestone 1 of plan/92-paperclip-spike.md, not a probe.

One more thing worth knowing

A project can be created with an executionWorkspacePolicy whose workspaceStrategy.type is git_worktree, with baseRef, branchTemplate, worktreeParentDir, provision and teardown commands. Paperclip may already do the worktrees we assumed we would build. That deserves its own probe before any executor is written.

---

Milestone 1 measured, 2026-11-10 (writes, sandbox only)

Everything below was run with the user key (PAPERCLIP_BOARD_KEY). The key is never printed. The sandbox is spike-2026-11-10 and its scratch repository /tmp/pc-sandbox-2026-11-10. Both are safe to delete.

The order that works

The board guide's rule holds: never create a task and assign it in the same action. The four calls, in order, with the result each one returned:

Call	Result
POST /api/companies/{company}/projects	201, project 17adbb47-f966-4a82-a8ef-e48c941443ea, workspace 4d4eb32a-08a8-4e3e-88c9-2a8cedfc288b
POST /api/companies/{company}/issues ×2	201, AUD-159 34abf83f-…, AUD-160 21d1f49e-…, both todo, unassigned
PATCH /api/issues/AUD-160 {"blockedByIssueIds":["34abf83f-…"]}	200, echoed blockedBy with AUD-159; diagnostics then said unresolvedBlockerCount: 1
PATCH /api/issues/AUD-159 {"assigneeAgentId":"403de1f7-…"}	200, todo

The activity record of the assignment names the person, not an agent: actorType: "user", authorizationReason: "allow_board_actor". That is the audit trail the user key exists for.

The wake, timed

00:01:24.891Z  PATCH assigneeAgentId -> 200
00:01:24.937Z  wake requested  source=assignment  reason=issue_assigned  status=claimed
00:01:25.036Z  run aae77e89-7059-43b4-9154-972282770212 started, issue -> in_progress
00:01:51.351Z  comment posted by agent 403de1f7-…
00:01:53.153Z  issue -> done
00:01:59.377Z  run -> succeeded  (resultJson.stopReason = "completed")

GET /api/issues/AUD-159/diagnostics/wakes returned that single wake request and the plain-English line "The most recent wake for AUD-159 is currently claimed for issue_assigned." This endpoint answers the question we used to have to guess at: it names each wake, the run it produced, and why a wake did not happen.

H3 is now PASS: a real agent woke on assignment, worked, commented and closed the task with no person in the loop and no timer.

What the agent reported

Comment 822f2924-dd2f-4f26-9046-c7801f2196a9, author agent, id 403de1f7-…:

Created hello.txt … Commit hash b093301148b62ab0f2a34bec4f31d97a26a212e9 … Working directory (absolute path): /tmp/pc-sandbox-2026-11-10 … Branch: main.

Checked on disk: git log --oneline shows b093301 add hello.txt on main, the file holds the expected line, and git status is clean.

Cost, read back

GET /api/issues/AUD-159/cost-summary → costCents: 1, inputTokens: 101002, outputTokens: 1515, runCount: 1, runtimeMs: 34341. The run's own usageJson says costUsd: 0.00749434.

No worktree was created, and why

The task's executionWorkspaceId and currentExecutionWorkspace are null. The run worked in the project folder on main, so a second task would collide rather than work on its own copy.

Cause, measured: GET /api/instance/settings/experimental returns enableIsolatedWorkspaces: false and enableWorktreeRunExecution: false. With the first flag off, Paperclip throws away the task's workspace settings before dispatch, so the mode resolves to the shared project folder even though the project asked for git_worktree.

The supporting code is in the installed server: dist/services/heartbeat.js sets issueExecutionWorkspaceSettings = null when the flag is off, and dist/services/workspace-runtime.js is where git worktree add would run. Default worktree location is <repo>/.paperclip/worktrees/<branch>; default branch template is {{issue.identifier}}-{{slug}}.

Consequence for the plan. The "Paperclip makes the worktree for us" assumption is true only with an experimental instance setting switched on. Until a person turns it on, every task shares one folder and merges happen on main with no branch and no review step. That is a decision to put to the person, not a bug to work around.

Second task left where it is

AUD-160 stayed todo, unassigned, blocked by a task that is now done. Nothing woke, because no agent is assigned to it. Whether the issue_blockers_resolved wake fires for an assigned dependent task is still unmeasured.

---

Worktrees switched on, measured, 2026-11-10

The first worktree attempt proved the flags, not the strategy: with enableIsolatedWorkspaces: false the project's git_worktree policy was discarded before dispatch. That is recorded above and is worth keeping, because it is what an operator will see on any fresh instance.

After switching on enableIsolatedWorkspaces and enableWorktreeRunExecution (and leaving enableIsolatedWorkspacesByDefault off, so the other projects are untouched), the same project produced a real worktree on the next task:

Fact	Value
Task	AUD-160, run 11a94551-dd12-4b13-92fe-835ea63d7753
Workspace id	7900dbf1-692c-4217-aebb-5d539c30aa98
Mode / strategy	isolated_workspace / git_worktree
Branch	AUD-160-milestone-1-t2-read-hello-txt
Path	/tmp/pc-sandbox-2026-11-10/.paperclip/worktrees/AUD-160-milestone-1-t2-read-hello-txt
Base	main at b093301
Delivery state	merged_by_ancestry (the task made no commit)

Paperclip wrote its own comment on the task, titled Workspace Ready, naming the strategy, the branch and the working directory. git worktree list shows the new path, and git branch shows the new branch. The file hello.txt from the first task was present in the worktree, so the branch really was cut from the finished work.

Two consequences worth remembering:

• Name the branch with a template. The default is {{issue.identifier}}-{{slug}}; usable placeholders include {{issue.identifier}}, {{slug}}, and the project and agent. Without a template every worktree of the same task would land on the same name.
• merged_by_ancestry is not a merge. A task that changes nothing leaves its branch at the base commit, and Paperclip marks it delivered because the branch adds nothing. A task that does commit will stay unmerged until something merges it. That is the state the review gate will read.

Budgets as they stand

Read from GET /api/companies/{companyId}/agents:

Agent	Monthly budget (cents)	Spent (cents)
Builder	5000	2
Chief of Staff	5000	0
System	3000	0
researcher	2000	0
Documenter	2000	0
Hub	0	1

The company's budgetMonthlyCents is 0. There is no currency field anywhere in the payload: Paperclip counts cents and does not name a currency, so "5000" is a number, not "$50 AUD".