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

docs/ENVIRONMENT-FACTS.md

@@ -29,26 +29,56 @@ Everything here was measured with a command. Anything not measured is marked unp
   `POST /api/companies/{companyId}/projects` with `name`, `status: "backlog"` and
   `workspace: { name, sourceType: "git_repo", cwd, isPrimary: true }`.
 
-## The unproven step: does a heartbeat wake an agent?
+## Does a heartbeat wake an agent? PROVEN, 2026-11-10
 
-Measured: a task can be created, given a blocker, and commented on. **Not** measured: that
-assigning a task causes Pi to wake and work.
+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`.
 
-The endpoint that should start it exists:
+Measured on `spike-2026-11-10` / `AUD-159`:
 
 ```
-POST /api/agents/{id}/heartbeat/invoke      (empty body)
+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
 ```
 
-Test in this order, and write down the response at each step:
+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.
 
-1. Assign a task: `PATCH /api/issues/{id}` with `{"assigneeAgentId":"<agent id>"}`.
-2. Either wait for a scheduled heartbeat, or force one:
-   `POST /api/agents/{agentId}/heartbeat/invoke`.
-3. Read `GET /api/issues/{id}/runs` and `GET /api/issues/{id}/activity` to see whether a
-   run started.
-4. If no run appears, the wake needs something we have not configured (a routine, a
-   schedule, or a wake trigger). Record the facts; do not build a workaround.
+`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