[BUG] PI provider agents receive no bootstrap on spawn

[dlasher]

What happened?

Bug Report: PI provider agents receive no bootstrap on spawn

Filed: 2026-09-18
Reporter: god (Otto, orchestrator) via human owner
Severity: High — silently breaks PI agent onboarding, leaves agent confused and idle
Affected: All agents with provider: pi (ex: Toby, Meredith, Kelly, Jim's regenerated session)
Status: Open — no workaround in harness; manual paste required by operator

---

Summary

Agents spawned with provider: pi do not receive any bootstrap / system prompt on session start. They are created and invoked with only their first user-role turn as context, which is typically a dispatch from the orchestrator. They have no knowledge of the hive protocol, agent identity, inbox/outbox locations, fleet registry, PROTOCOL.md, or their own role.

This is inconsistent with opencode agents, which receive a full bootstrap via claude --append-system-prompt at spawn time and are fully oriented before their first model invocation.

---

Reproduction Steps

1. Write a spawn-request manifest that targets the pi provider. Example shape used on 2026-09-18:

   {
     "id": "spawn-toby-pi-test",
     "cwd": "W:\CODE\PROJECT",
     "provider": "pi",
     "model": "gpt-5",
     "name": "Toby",
     "character": "engineer",
     "accent": "neutral",
     "isolate": false
   }

   (full file: C:\Users\dev\PROJECT\hive\spawn-requests\.done\spawn-toby.json)

2. Place it in C:\Users\dev\PROJECT\hive\spawn-requests\ and let the harness process it. The agent's session JSONL is created under C:\Users\dev\PROJECT\hive\agents\<agent-id>\.pi-agent\sessions\<cwd-suffix>\<session-uuid>.jsonl.

3. Inspect the first line of that JSONL.

Expected (per opencode behavior): Turn 0 is a user message containing the full bootstrap block — beginning You are "<Name>" (<agent-id>), an autonomous agent in a collaborating office of AI agents. — followed by PROTOCOL summary, guardrails, capability list, env-var list.

Actual (PI): Turn 0 is either empty, the dispatch payload only. The bootstrap block is not present.

---

Evidence

Session A — Toby (toby-mu556kpk), 2026-09-18

Turn 0 (verbatim):

{"role":"user","content":[{"type":"text","text":"please check your INBOX"}]}

The USER had hand-typed "Check your INBOX" to validate the problem.

Toby's first thinking on the next turn (paraphrased from session log): "I'm not sure what INBOX means — let me look at the directory structure."

He did not know he was Toby, did not know his role, did not know the hive protocol.

Session B — Jim (jim-mu6afiqn), 2026-09-18 (regenerated)

Turn 0 (verbatim):

{"role":"user","content":[{"type":"text","text":"You are \"Jim\" (jim-mu6afiqn), an autonomous agent in a collaborating office of AI agents. ..."}]}

This session does contain a bootstrap-shaped user message. Operator confirmed: this was manually pasted after Toby misbehaved, not produced by the harness. The manual paste arrived at 22:32:47Z, after the session JSONL started at 22:22:06Z and after the agent's first heartbeat — confirming the harness did not inject it.

opencode baseline — Ryan (ryan-mu555ipq)

Opencode agents receive the bootstrap via claude --append-system-prompt "..." at spawn time (documented in C:\Users\dev\PROJECT\hive\COMMANDS.md:91). The bootstrap is merged into the system prompt and not visible in the session JSONL as a separate turn, but Ryan and Oscar both behave as if they received it (correct protocol adherence, correct identity, no confusion about INBOX).

---

Impact

• Symptom 1 — silent onboarding failure: The agent boots confused, has to discover its identity and role by reading the filesystem (e.g., find/ls the hive root). This burns tokens and time on the first turn.
• Symptom 2 — no protocol compliance: A confused agent does not know to read its inbox at the start of a task, does not know how to message god, and may take wrong actions on a dispatch (e.g., read the wrong file, target the wrong directory).
• Symptom 3 — circuit breaker risk: A confused agent may invoke tools in tight loops while trying to orient itself (e.g., repeated ls / read calls). This is exactly the pattern the per-agent circuit breaker watches for; Toby hit a CONSTRAIN-level breaker on 2026-09-18 22:28Z with 27× identical tool calls before the bootstrap gap was diagnosed.
• Symptom 4 — orchestrator is blind: god cannot detect this condition reliably from fleet.json alone. By the time the new agent registers, its first turn has already happened. There is no pre-invocation hook visible to the orchestrator.

---

Related Defects

R1: Mailbox notification has no reliable trigger (chicken-and-egg)

Even if god writes a JSON message into an agent's inbox/, the receiving agent has no signal to look. The agent only re-reads its inbox when its session receives a new user-role turn, which requires external stimulus (operator via UI, Slack thread, or harness idle-poll).

Consequence: A standing-down agent (idle, no active task) cannot be poked from god's seat via any in-hive mechanism. task_message only works on orchestrator-owned child tasks (subagents the orchestrator spawned itself), not peer agents in fleet.json.

This means: there is currently no way for god to recover a mis-spawned PI agent from its own session. Recovery requires a human operator to inject a turn via the UI, which is exactly what the operator did manually for Jim's regenerated session.

R2: Workaround of writing to outbox is a dead end

A naive fix — write the bootstrap to the agent's outbox and hope they pick it up — does not work, because a bootstrap-less agent does not know it has an outbox or what to do with one. The bootstrap gap and the mailbox notification gap compound each other.

---

Recommended Fixes

F1 (preferred): Spawn-time bootstrap injection in the PI provider path

In the harness spawn flow, after creating the new PI session JSONL and before invoking the model for the first time, write a turn-0 user message containing the bootstrap. The bootstrap text already exists for opencode (--append-system-prompt) — share it via a single source-of-truth file (e.g., C:\Users\dev\PROJECT\hive\bootstrap\agent-bootstrap.md) and have both provider paths read it.

This is a one-time edit and prevents the bug for every future PI spawn.

F2: Mailbox notification watcher

Add a small filesystem watcher (e.g., chokidar on inbox/*.json) inside the per-agent runtime hook (agy-hook.cjs for PI, equivalent for opencode). On a new file appearing, emit a "you have mail" event over HIVE_SOCK so the card UI can flag it, AND/OR have the receiving agent's next idle-poll prompt include a hint to re-read its inbox.

F3: Operator-facing diagnostic

Until F1 ships, expose a claude/spawn doctor (or hive CLI equivalent) that lists recent PI spawns and reports whether turn 0 of each session JSONL contains the bootstrap block. Operators can spot a bad spawn immediately without having to read session JSONLs by hand.

---

Operator Workaround (in use now)

Until the harness fix ships, the human operator manually pastes the bootstrap into a regenerated PI session after the first misbehavior is observed. This is documented in the 2026-09-18 22:30Z–23:00Z orchestration log between god and the operator.

This is fragile (depends on operator noticing the failure mode) and burns one full regeneration of every mis-spawned PI temp.

---

Related Files

File	Relevance
C:\Users\dev\PROJECT\hive\PROTOCOL.md	Full protocol that bootstrap should communicate
C:\Users\dev\PROJECT\hive\COMMANDS.md:91	Documents the opencode --append-system-prompt mechanism
C:\Users\dev\PROJECT\hive\bin\cth-hook.cjs	Claude Code runtime hook (status + tool-call bridge) — does NOT handle bootstrap
C:\Users\dev\PROJECT\hive\bin\hive-proxy.cjs	Anthropic-API proxy — does NOT handle bootstrap
C:\Users\dev\PROJECT\hive\bin\agy-hook.cjs	OpenAI/agy tool-call bridge for PI provider — does NOT handle bootstrap
C:\Users\dev\PROJECT\hive\agents\<id>\.pi-agent\sessions\<...>\*.jsonl	Per-session JSONL where bootstrap turn 0 is missing (PI) or present (opencode, in system prompt not visible in JSONL)
C:\Users\dev\PROJECT\hive\spawn-requests\.done\spawn-toby.json	Example PI spawn manifest
C:\Users\dev\PROJECT\hive\agents\god\memory.md	Orchestrator's memory of the incident

---

Originator Suggestion

Maintainers: please comment with the bootstrap-injection code path in the harness binary that handles opencode today, so the equivalent PI branch can be added without guesswork. A reproducer session JSONL is available on request.

Operators: please verify the workaround in the meantime. Don't disable the standalone PI agent without first checking whether the bootstrap arrives.

Steps to reproduce

Reproduction Steps

1. Write a spawn-request manifest that targets the pi provider. Example shape used on 2026-09-18:

   {
     "id": "spawn-toby-pi-test",
     "cwd": "W:\CODE\PROJECT",
     "provider": "pi",
     "model": "gpt-5",
     "name": "Toby",
     "character": "engineer",
     "accent": "neutral",
     "isolate": false
   }

   (full file: C:\Users\dev\PROJECT\hive\spawn-requests\.done\spawn-toby.json)

2. Place it in C:\Users\dev\PROJECT\hive\spawn-requests\ and let the harness process it. The agent's session JSONL is created under C:\Users\dev\PROJECT\hive\agents\<agent-id>\.pi-agent\sessions\<cwd-suffix>\<session-uuid>.jsonl.

3. Inspect the first line of that JSONL.

Expected (per opencode behavior): Turn 0 is a user message containing the full bootstrap block — beginning You are "<Name>" (<agent-id>), an autonomous agent in a collaborating office of AI agents. — followed by PROTOCOL summary, guardrails, capability list, env-var list.

Actual (PI): Turn 0 is either empty, the dispatch payload only. The bootstrap block is not present.

Screenshot or screen recording

^^ see above logs ^^

Logs / stack trace

Operating system

Windows

OS version

Windows 11-25

Munder Difflin version

0.5.2

Node version

na

Agent CLI and version (if relevant)

No response

Pre-flight

• I attached a screenshot or recording above.
• I'm on the latest release, or I've said above why I can't be.
• I re-ran npm install so node-pty is rebuilt for the current Electron ABI (source installs only).
• I searched existing issues and this isn't a duplicate.

[HsienW]

#560 This implements F1 at the existing provider bootstrap boundary. Instead of writing directly to Pi's private session JSONL, the fix uses Pi's supported positional initial prompt interface so the bootstrap is delivered before the first model turn.