sam/paperclip-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Milestone 1 measured: assignment wakes Pi, task ran end to end; no worktree because isolated workspaces are off

Browse Source
This commit is contained in:
Sam
2026-11-10 11:03:05 +11:00
parent b6f0cb572b
commit a60a4a3067
3 changed files with 150 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
docs/PAPERCLIP-API-NOTES.md
View File

@@ -133,3 +133,90 @@ A project can be created with an `executionWorkspacePolicy` whose `workspaceStra
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.