# 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.