paperclip-harness/docs/ENVIRONMENT-FACTS.md

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: switched on 2026-11-10, and measured working

The instance first had them off. With the flags off, the project's request for a git worktree per task was silently ignored: AUD-159 worked in /tmp/pc-sandbox-2026-11-10 on main, and the task's executionWorkspaceId read null.

Then, with the person's approval, two experimental settings were switched on:

PATCH /api/instance/settings/experimental
{"enableIsolatedWorkspaces": true, "enableWorktreeRunExecution": true}
→ 200

enableIsolatedWorkspacesByDefault was deliberately left off. That flag would give every project without a policy of its own a worktree, which would change the other nine projects on this instance. Only projects that ask for one now get one.

The next task (AUD-160) made a real worktree, and Paperclip posted a "Workspace Ready" comment on the task naming it:

strategy   git_worktree
branch     AUD-160-milestone-1-t2-read-hello-txt
cwd        /tmp/pc-sandbox-2026-11-10/.paperclip/worktrees/AUD-160-milestone-1-t2-read-hello-txt
baseRef    main
deliveryState  merged_by_ancestry   (no commit was needed; the branch equals main)

git worktree list in the sandbox repository shows that path on that branch. So the worktree is Paperclip's job after all, once the instance allows it, and the terminal program never needs to run git worktree itself.

Fonts, 2026-11-10

Measured, because the answer was "I thought I had installed them":

• No Nerd Font was installed (fc-list | grep -i nerd returned nothing) and no JetBrains Mono either. Ghostty ships a plain JetBrains Mono of its own, which is why a terminal can look right while every icon renders as a box.
• Starship is not installed, and there is no ~/.config/starship.toml.
• TUIOS has four glyph sets — ascii, default, heavy, unicode — and default is active, which is ordinary Unicode, not Nerd Font icons.
• TUIOS has 30 themes including six Catppuccin variants, and no look is applied: tuios look show says "No look is applied". The session is not on Catppuccin.

What was changed:

• fonts.packages = [ nerd-fonts.jetbrains-mono ] and fonts.fontconfig.enable = true in /etc/nixos/configuration.nix, so every machine built from this flake gets it: .13, .27, .51. nix build --dry-run evaluates and wants nerd-fonts-jetbrains-mono-3.4.0+2.304. The rebuild is still to be run (sudo needs a password here).
• ~/.config/ghostty/config sets font-family = "JetBrainsMono Nerd Font".
• Rebuilt by the person on 2026-11-10: fc-list | grep -ci nerd now returns 96, and JetBrainsMonoNerdFont-Regular.ttf is present in the store. The font is installed on .13; .27 and .51 get it from the same flake on their next rebuild.
• The theme is now set: theme = 'catppuccin_mocha' in ~/.config/tuios/config.toml. tuios set-config refused for the running session ("would change this machine, not the session"), so the running session keeps its old chrome until it is restarted.

Toolchain

• Go is installed (2026-11-10), by nix profile install nixpkgs#go → go1.26.5 at /home/sam/.nix-profile/bin/go. That is the quick path: it works now, and it is not part of the system closure.
• The durable path is also prepared: go and gopls were added to environment.systemPackages in /etc/nixos/configuration.nix. nix flake check passes and the dry-run build evaluates. The rebuild has not been run, because sudo needs a password here. One command finishes it: sudo nixos-rebuild switch --flake /etc/nixos#nixos-desktop. Until then the profile copy is what runs.

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.

NixOS alignment for Pi, measured 2026-11-12

Goal: the same Pi on all three machines. pi-coding-agent comes from nixpkgs, so aligning used to mean bumping the whole system on each machine. That is what broke .13: nixos-rebuild switch restarts every changed unit in place, the network units restarted, the default route did not come back, and every service that needs the network died with it. Exit code 4 meant "units failed to start", not "the build failed" - the generation had already switched.

The rule that follows: on a machine someone is using, a nixpkgs-sized change goes in with nixos-rebuild boot and a reboot, never switch.

What was done instead, and why it is safe

Pi is one package. Instead of moving a whole system to a new nixpkgs, a second flake input pinned to one revision provides only that package:

nixpkgs-pi.url = "github:NixOS/nixpkgs/f4a03c008967841f2a0b3cb7c436fc6fc31671f6";
# in the let block
piPkgs = import nixpkgs-pi { inherit system; config.allowUnfree = true; };
# in home-manager users.${user}.home.packages
piPkgs.pi-coding-agent

and pi-coding-agent was removed from home/sam/home.nix so exactly one pi is on PATH. The system pin on those machines did not move, so nothing else in the system changes and no network or service unit is restarted. Remove the input once the system pins are aligned for real.

State, verified by building, not switching

machine	method	pi in the built system	store path
.13 nixos-desktop	full nixpkgs bump (2026-11-07), running	1.5.0	4yxlfj0sw5hlk7x1hiv0igm0dckg8rv9
.27 sam-4screen-desktop	nixpkgs-pi input, built, not yet switched	1.5.0	4yxlfj0sw5hlk7x1hiv0igm0dckg8rv9
.51 sam-thinkpad	nixpkgs-pi input, built, not yet switched	1.5.0	4yxlfj0sw5hlk7x1hiv0igm0dckg8rv9

One store path on all three: the same bytes of Pi, not merely the same version number.

Two other things measured on the way

• programs.zsh.initExtra is initContent in home-manager 2026-11. Both names evaluate on the older home-manager, so the rename is safe in either direction.

• lan-mouse 0.11.0 panics when LIBGIT2_NO_VENDOR is set and no system libgit2 exists; nixpkgs 2026-11-07 sets it. An overlay on pkgs.lan-mouse does not help. Building the flake's own package with the variable off does:

  lm = lan-mouse.packages.${system}.default.overrideAttrs (o: { LIBGIT2_NO_VENDOR = "0"; });
  

  .13 now lists lm in systemPackages instead of lan-mouse.

• .27's full-system bump failed in home-manager.users.sam.fonts.fontconfig.configFile.fonts.settings (recursiveUpdateUntil / head values). The nixpkgs-pi route avoids it entirely; it is still an open item for the day the system pins are aligned.