author: zenchant

text: "yo


author: claude

text: yo back 👋 — comment system confirmed working


author: ZenchantLive

text: this is a multi word test comment


text: we


text: this is a multi word test via full shell path


author: zenchantlive

text: "this


text: "multi


text: hello helloo


text: we need to make sure that we are corectly calculating blocked and anywhere wher eitis reffenced that it saccurate.


text: this is a multi word comment after the fix


issue_id: beadboard-izs

text:
izs.1 audit — existing bb coordination stack and integration contract

Files audited:
1) tools/bb.ts
2) src/lib/agent-mail.ts
3) src/lib/agent-registry.ts
4) src/lib/agent-reservations.ts
5) src/cli/beadboard-cli.ts

A) Existing command surface (source of truth)

1) Internal bb agent CLI in tools/bb.ts (node:util parseArgs)
- Domain routing: `bb agent <command>` only
- Supported commands:
  - identity: `register`, `list`, `show`, `activity-lease`
  - mail: `send`, `inbox`, `read`, `ack`
  - reservations: `reserve`, `release`, `status`
- Shared optional output flag: `--json`
- Passive heartbeat behavior: when any command includes an agent id (`--agent` / `--from` / `--name`), `extendActivityLease()` is attempted as side-effect (except register/activity-lease).

2) Global npm CLI in src/cli/beadboard-cli.ts
- Current public command surface: `doctor`, `self-update`, `uninstall`, and help text mentions runtime commands (`start/open/status`) via wrapper routing.
- Not currently wired to expose `bb agent ...` coordination subcommands.
- CLI parsing style is custom lightweight argv parsing (`command = first non-flag arg`), returns structured `CliResult` and JSON-friendly output.

B) Storage model + paths (confirmed)

1) Mail storage (src/lib/agent-mail.ts)
- Root: `~/.beadboard/agent/messages/` where `~` resolves as:
  - `process.env.USERPROFILE?.trim()` if present, else `os.homedir()`
- Inbox per recipient: `~/.beadboard/agent/messages/<agent>.jsonl`
- Message index (authoritative mutable record): `~/.beadboard/agent/messages/index/<message_id>.json`
- Read path behavior:
  - Inbox lists parse JSONL lines, then hydrate each line from index JSON if present.
  - Message state transitions (`read`, `ack`) update index JSON, not inbox JSONL lines.

2) Reservation storage (src/lib/agent-reservations.ts)
- Root: `~/.beadboard/agent/reservations/` using same USERPROFILE->homedir resolution.
- Active reservations snapshot: `~/.beadboard/agent/reservations/active.json`
- History append log: `~/.beadboard/agent/reservations/history.jsonl`
- Lock file for mutation serialization: `~/.beadboard/agent/reservations/.lock`

C) Integration contract for downstream tasks

1) izs.2 (global CLI wiring contract)
- Global `bb`/`beadboard` CLI must expose a passthrough/adapter for:
  - `agent register|list|show|activity-lease|send|inbox|read|ack|reserve|release|status`
- Preserve internal flag semantics from tools/bb.ts:
  - register: `--name --role [--display] [--force-update]`
  - send: `--from --to --bead --category --subject --body [--thread]`
  - inbox: `--agent [--state] [--bead] [--limit]`
  - read/ack: `--agent --message`
  - reserve: `--agent --scope --bead [--ttl] [--takeover-stale]`
  - release: `--agent --scope`
  - status: `[--agent] [--bead]`
- Output contract: return the same command response envelope:
  - `{ ok, command, data, error }`

2) izs.3 (API routes contract)
Target routes:
- `/api/agents/mail`
- `/api/agents/reservations`

Recommended HTTP contracts mapped to existing libs (no domain logic reimplementation):

`/api/agents/mail`
- POST (create/send):
  - body: `{ action: "send", from, to, bead, category, subject, body, thread? }`
  - calls `sendAgentMessage`
  - 200 on success, 4xx for validation/not-found codes, 5xx for internal error
- GET (list/inbox):
  - query: `agent` (required), `state?`, `bead?`, `limit?`
  - calls `inboxAgentMessages`
- PATCH (state transitions):
  - body:
    - `{ action: "read", agent, message }` -> `readAgentMessage`
    - `{ action: "ack", agent, message }` -> `ackAgentMessage`
- Response envelope for all operations: `{ ok, command, data, error }`
- Note on CRUD: no delete semantics in current mail engine; lifecycle is unread -> read -> acked.

`/api/agents/reservations`
- POST (create/reserve):
  - body: `{ action: "reserve", agent, scope, bead, ttl?, takeoverStale? }`
  - calls `reserveAgentScope`
- DELETE (logical release):
  - body: `{ action: "release", agent, scope }`
  - calls `releaseAgentReservation`
- GET (status/list):
  - query: `agent?`, `bead?`
  - calls `statusAgentReservations`
- Response envelope for all operations: `{ ok, command, data, error }`
- Note on CRUD: release is logical state transition + history append; no destructive delete.

3) izs.5 (bd mail delegate contract)
- `bd mail` should delegate to same coordination primitives used by `bb agent` (mail + reservations + registry path).
- Session preflight should verify:
  - agent identity exists/registered
  - path root is writable (`~/.beadboard/agent/...`)
  - JSONL/index storage accessible
- Delegate path should preserve command response envelope + error codes to keep UI/CLI behavior consistent.

D) API/error semantics that must stay consistent

Mail categories: `HANDOFF | BLOCKED | DECISION | INFO`
- requires_ack=true for HANDOFF and BLOCKED (from `requiresAck()` in agent-mail.ts).

Mail states: `unread | read | acked`

Representative error codes to propagate (not remap silently):
- mail: `UNKNOWN_SENDER`, `UNKNOWN_RECIPIENT`, `MISSING_BEAD_ID`, `INVALID_CATEGORY`, `INVALID_MESSAGE`, `AGENT_NOT_FOUND`, `INVALID_STATE`, `INVALID_LIMIT`, `MESSAGE_NOT_FOUND`, `INVALID_MESSAGE_ID`, `READ_FORBIDDEN`, `ACK_FORBIDDEN`, `INTERNAL_ERROR`
- reservations: `AGENT_NOT_FOUND`, `INVALID_ARGS`, `RESERVATION_CONFLICT`, `RESERVATION_STALE_FOUND`, `RESERVATION_NOT_FOUND`, `RELEASE_FORBIDDEN`, `INTERNAL_ERROR`

E) Platform/path risks (Windows USERPROFILE vs Linux HOME)

Observed:
- agent-mail.ts and agent-reservations.ts use USERPROFILE first, then os.homedir().
- beadboard-cli.ts runtime path resolution passes HOME fallback to os.homedir().

Risk:
- In mixed WSL/Windows sessions, USERPROFILE may point to a Windows path while HOME/homedir for running process differs, causing CLI/runtime artifacts and agent mail/reservation artifacts to diverge across roots.

Recommendation for izs stream:
- Centralize path-root resolution in one shared helper used by CLI + mail + reservations.
- Add explicit diagnostics to show the resolved coordination root path in doctor/status outputs.
- Add contract tests for path parity under mocked env combinations:
  - USERPROFILE set + HOME unset
  - USERPROFILE unset + HOME set
  - both set to different roots

F) Entry points and framework notes
- Internal coordination CLI entry: `tools/bb.ts` (parseArgs-based command router).
- Global CLI implementation: `src/cli/beadboard-cli.ts`; package `bin` routes `bb` and `beadboard` to `bin/beadboard.js` wrapper that invokes CLI logic.

This audit is the contract baseline for izs.2, izs.3, izs.5.


text: Confirmed delegate syntax from help/cli/bd_help.txt and bd mail --help: environment vars BEADS_MAIL_DELEGATE/BD_MAIL_DELEGATE and config key mail.delegate. Implemented skill preflight wiring to set mail.delegate to node bb-mail-shim.mjs delegate path.