Facts about this machine, checked 2026-11-09

Everything here was measured with a command. Anything not measured is marked unproven.

Paperclip

Running locally: http://127.0.0.1:3100. Public UI: https://paperclip.lab.audasmedia.com.au.
Company: d4921013-e5da-4d88-8016-57d5746e2d03
Agents, all running the Pi adapter (pi_local), all idle:
- Hub — 108c6220-c9e1-4b62-9e0a-6a763e0d28fd (this is the identity of PAPERCLIP_API_KEY)
- Builder — 403de1f7-645c-4d35-bc7e-19b01d77bacc
- Chief of Staff — 232f1f9e-bac0-4185-8a0e-eddbead33e04
- Documenter — 706ffc88-120f-46c4-a5d9-ffa12e2ad5f0
- researcher — a6a2c0ee-570e-4f89-a977-83136b534a2f
- System — fe7a1881-1df9-481b-af74-87292fef288c
Writes need the user key: PAPERCLIP_BOARD_KEY. The agent key PAPERCLIP_API_KEY is refused with 403 outside a heartbeat run.
Blockers live at GET /api/issues/{id}/diagnostics/blockers, not on the task list.

The sandbox project

spike-2026-11-09 is archived: status cancelled, renamed spike-2026-11-09 (deleted), id 9e3f61f6-cce9-49b1-8083-3130345a04a5.
DELETE /api/projects/{id} returned 500, so it was archived instead. Its two tasks (AUD-157, AUD-158) remain inside the archived project. Deleting an archived project is still untested.
Its scratch repo /tmp/pc-sandbox was removed.
To make a fresh sandbox, use the payload recorded in PAPERCLIP-API-NOTES.md: POST /api/companies/{companyId}/projects with name, status: "backlog" and workspace: { name, sourceType: "git_repo", cwd, isPrimary: true }.

Does a heartbeat wake an agent? PROVEN, 2026-11-10

It does, and the wake is not a timer. Assigning a task woke Builder within one tenth of a second, with no call to heartbeat/invoke.

Measured on spike-2026-11-10 / AUD-159:

00:01:24.891Z  PATCH /api/issues/AUD-159 {"assigneeAgentId":"403de1f7-..."}  -> 200 todo
00:01:24.937Z  wake request recorded: source=assignment reason=issue_assigned
00:01:25.036Z  run aae77e89-... claimed, adapter pi_local, issue -> in_progress
00:01:51.351Z  agent comment posted (commit b093301)
00:01:53.153Z  issue -> done
00:01:59.377Z  run -> succeeded

So the four documented wake sources all reach an agent: a timer tick, an assignment or a new comment on its own task, a person clicking wake, and a routine firing. The timer is opt-in and is off for most agents; Builder currently has heartbeat.enabled: true, so it also polls. Assignment alone is enough.

POST /api/agents/{id}/heartbeat/invoke was never needed and remains untested. The documented manual wake is POST /api/agents/{id}/wakeup with {"source":"on_demand","triggerDetail":"manual","forceFreshSession":...}.

A wake can still be refused without any error reaching us. Read GET /api/issues/{id}/diagnostics/wakes — it shows each wake request, its claimed run, and a plain-English diagnosis. Refusal reasons seen in the documentation: the agent is paused, its budget is exhausted, its cooldown has not elapsed, or its run slot is full.

Isolated workspaces are switched off on this instance

The project was created asking for a git worktree per task (executionWorkspacePolicy with workspaceStrategy.type: "git_worktree"). No worktree was made. The run worked directly in /tmp/pc-sandbox-2026-11-10 and committed onto main. The task's executionWorkspaceId and currentExecutionWorkspace both read null.

GET /api/instance/settings/experimental returns:

"enableIsolatedWorkspaces": false,
"enableIsolatedWorkspacesByDefault": false,
"enableWorktreeRunExecution": false,

With enableIsolatedWorkspaces false, Paperclip discards a task's workspace settings before the run is dispatched, so the mode falls back to the shared project folder. The worktree code is present in the server (git worktree add in dist/services/workspace-runtime.js). Switching it on is an instance-wide experimental setting and a decision for the person, not a setting for one project.

Toolchain

Go is not installed on this machine. go version → not found. The terminal program needs it. Under Nix, add go to /etc/nixos/configuration.nix and rebuild; do not install it by hand.

The new repository

Local git repo only, one commit, no remote. It is not on Gitea. Push it somewhere before relying on it, or accept that only this machine has it.

4.3 KiB Raw Blame History