Brings the wiki-expansion pages onto current main WITHOUT the stale baggage the
original feature/wiki-expansion branch carried (it predated the rename + date
PRs and would have reverted them). Cherry-picked only the 9 genuinely-new pages:
contracts, store-schema, external-mcp, operator-cli, tui, runtime-inventory,
skills-catalog, vault-provision, deployment. Added them to index.md.
Fixed on the way in: vault-provision referenced the pre-rename
VAULT-PROVISION-FIRST-PROOF → repointed to VAULT-PROVISION-RUNBOOK. (No US dates
in these pages.)
Gates: wiki-lint --strict clean (131 pass); markdown format clean.
- ZOT-RPC-TRANSCRIPT.md → AGENT-EVENTS-REFERENCE.md: neutral, per-harness event
reference (currently documents zot; pi uses pi --mode json). Avoids baking the
current default harness into a name — same lesson as the pi_* renames. Adds a
'Developer reference — operators can skip' header.
- VAULT-PROVISION-FIRST-PROOF.md → VAULT-PROVISION-RUNBOOK.md: it's a runbook;
'first-proof' was redundant.
- Updated referrers: spawner.rs, wiki/agent-harness.md, docs/README.md.
- wiki/naming-decisions.md: new 'Naming principle — harness-agnostic by default'
section (neutral concept → neutral name + configurable value; harness-specific
→ harness in the name, kept symmetric zot_/pi_).
- Fixed US/ISO prose dates → DD.mon.YYYY (21.jun.2026) per AGENTS.md; left the
literal JSON "time" timestamps in the captured transcript as-is (data).
Gates: wiki-lint --strict clean; markdown format clean.
- New docs/wiki/mother-hive.md — thin decisions page covering forced-command
SSH boundary, single-home-in-colibri, hive_nodes rationale, peer auth,
key-on-seed, and daemon-user design. Links to MOTHER-SETUP.md for setup
instructions; never duplicates them.
- Flip wiki-lint to --strict in ci-checks.sh — drift failures now block the
gate the same as clippy warnings. 42 PASS / 0 FAIL, clean since merge.
- New scripts/pre-push — runs ci-checks.sh on every git push to main. Install
once: ln -sf ../../scripts/pre-push .git/hooks/pre-push. Bypass only with
--no-verify. Closes the gap that let pi_binary reach main (gate existed but
nobody was forced through it).
- Updated AGENTS.md, quality-gates.md, and index.md to reflect all three.
Residue item #1: rename the pi-era `pi_type` field/param to `event_type` in
colibri-glasspane. It names the normalized event-type string (zot events map
onto the same taxonomy), so the harness-neutral name is correct. Internal only
— PiStreamUpdate is not serialized — so no wire impact.
Wiki ledger updated:
- pi_type → event_type added to Shipped (now enforced by wiki-lint).
- Residue items resolved and recorded under Structural decisions:
- FEATURE_COLIBRI is an internal build-time escape hatch, not a user-facing
flag — README clarified (clawdie-iso #130).
- clawdie-gui is the stable operator command; clawdie-startx retained as a
back-compat alias (both installed) — verified intentional, not drift.
- Known residue now down to the dangling ADR reference only.
Verified: ci-checks.sh green (fmt/clippy/test/markdown); wiki-lint --strict clean.
The 'resurrected old names' check was non-functional: it ran in a pipeline
subshell (fail/pass counts and --strict exit were lost), accumulated hit files
with literal \\n (so the per-file filter never matched), and hardcoded the old
names — already stale (missing usb_nodes, the rename that motivated this).
Planting hermes-agent + usb_nodes + COLIBRI_AUTOSPAWN_PI in a source file
passed clean under --strict.
Rewrite:
- Parse old names from the Shipped table of naming-decisions.md (self-updating;
no hardcoded list to rot).
- Loop in the main shell (read from a file) so counters and --strict propagate.
- xargs grep -nHF across the file list; filter legit contexts case-insensitively
(migration/rename/back-compat/alias/changelog) so the serde alias and the
setup-mother migration code don't false-positive.
- Move usb_nodes → hive_nodes from In-flight to Shipped (colibri #161 merged) so
it is now enforced.
Verified: clean run exits 0 (PASS 37); planting hermes-agent/usb_nodes/
COLIBRI_AUTOSPAWN_PI now FAILs and --strict exits 1. Fixed a serde-alias
false-positive (multi-line attribute). sh -n + markdown gate green.
Records the dedup decision + the cross-repo drift lesson (an injectable
node-register-mcp copy reached iso main). The kind of regression a lint pass
should catch.
Pilot step 1 of the Karpathy LLM-Wiki pattern, scoped to decision-dense areas:
an agent-maintained docs/wiki/ that records WHAT was decided and links to WHERE
it lives in code (code stays the source of truth; pages link, don't duplicate).
Pages:
- index.md — purpose, conventions (the 'schema'), lint workflow, catalog
- agent-harness — zot (agent) + Colibri (control plane); autospawn + RPC driver
- naming-decisions — ledger of harness-neutral/architecture renames (shipped,
in-flight, and known residue) — the drift tracker
- quality-gates — ci-checks.sh as the pre-merge gate; why drift reached main
Intent: make the 'lingering old decision' bookkeeping near-zero-cost and
lintable. Lint tool itself (advisory, flag-don't-rewrite) is the next pilot step.
Already records real open drift (e.g. the dangling ADR reference).
Markdown gate green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Treat zot tool_use_start as the canonical tool_execution_start event and skip the later standalone tool_call so Glasspane does not double-fire tool starts. Update the real-key transcript notes to mark the double-fire issue resolved.\n\nValidation: ./scripts/check-format.sh; cargo fmt --check; cargo test -p colibri-glasspane; cargo test -p colibri-daemon glasspane -- --nocapture; cargo test -p colibri-daemon pi_spawn_path_produces_correct_glasspane_state -- --nocapture; cargo clippy -p colibri-glasspane -p colibri-daemon --all-targets -- -D warnings.
The raw stdout shows only tool_use_* + tool_progress + tool_result for the tool
cycle — no standalone {"type":"tool_call"} line. Downgrade the double-fire
note from a 'verified fact' to an open question, and mark the tool_call table
row as mapped-but-not-observed. Keeps the doc's 'observed, not inferred'
section honest. 14/15 types remain validated against real output.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Step 1 of colibri#143 complete. Complete tool call cycle captured
with valid DEEPSEEK_API_KEY: 61 lines, 2 turns, 1 bash tool call.
All 15 event types observed and mapped — no glasspane gaps.
Notable: tool_call and tool_use_start both map to tool_execution_start
(double-fire on real runs). Verified facts replace 'name matches source.'
Full raw transcript at /tmp/zot_transcript_full.txt (OSA).
Pre-existing gate offender (PR #141 slipped check-format.sh). Table-alignment
whitespace only, no content change. Restores a green ./scripts/check-format.sh.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The bare underscored names (tool_call, tool_use_*, text_delta, assistant_*)
were read as markdown emphasis and mangled by prettier; wrap them in code
spans so they render literally and stay prettier-immune.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Step 1 of colibri#143. Captured with zot rpc --provider deepseek.
Wire format: bare event objects (no JSON-RPC envelope), matches
glasspane's zot_event_type parser. All 6 observed types mapped.
Remaining types (tool_call, text_delta, etc.) need a live API key
but type names match zot source.
Verdict: glasspane parser is correct. Steps 2-3 unblocked.
Honor an optional pkg-list-jails path/URL argument, allow comments inside the agent-jail section, and apply Prettier to docs/README.md. This preserves the cross-repo gate for the jq addition.\n\nValidation: ./scripts/check-format.sh; cargo fmt --check; ./packaging/freebsd/port/check-cargo-crates.sh; ./packaging/freebsd/check-agent-jail-pkgs.sh /home/clawdie/ai/clawdie-iso/packages/pkg-list-jails.txt; sh -n packaging/freebsd/agent-jail-bootstrap.sh packaging/freebsd/mother-sync-hive-keys.sh; cargo check -p colibri-daemon -p colibri-client -p colibri-mcp.
Run the mandatory markdown format gate (check-format.sh / prettier@3) on the
doc — table column padding only, no content change. Makes the PR pass the gate.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Closes#135. The daemon stages per-spawn launch.sh/env.sh under the jail root;
the previous location /var/run/colibri-stage is root-owned, so the daemon
(running as clawdie) could not create per-spawn subdirs there — the second
jail-spawn EACCES, worked around in #134 by pre-creating the dir in
agent-jail-bootstrap.sh.
Move the default staging root to the daemon user's home,
/home/clawdie/.cache/colibri/stage, which clawdie owns by construction of the
jail account. create_dir_all now succeeds with no privileged pre-creation step,
and /home is persistent (unlike a tmpfs /var/run). The path is overridable via
COLIBRI_JAIL_STAGE_DIR, matching the daemon's other env-configurable paths.
- spawner.rs: const → staged_jail_run_dir() resolver; updated unit test.
- agent-jail-bootstrap.sh: drop the now-unnecessary install -d staging block
and DAEMON_USER var (the #134 workaround).
- docs: update jailed-spawn design + truss analysis to the new location.
clippy clean; spawner suite green (21 tests); sh -n clean; touched docs pass
the markdown gate.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Two root causes found via truss:
1. Bare command names (sudo, jexec) unresolved under daemon(8) PATH
→ fixed by resolve_program() in PR #131
2. Jail staging directory owned by root, unwritable by clawdie
→ fixed by chmod 777 <jail_root>/var/run/colibri-stage
Trace saved at /tmp/daemon.truss (1964 lines, successful spawn).
Move the backoff spawn operation into a named async helper so older tooling does not trip over || async syntax, and add a jail sudo wrapping unit test. Document sudo as an interim validated-host privilege mode.\n\nValidation: ./scripts/check-format.sh; cargo fmt --check; cargo check -p colibri-daemon; cargo test -p colibri-daemon jail_tests -- --nocapture.
1. VAULT-PROVISION-FIRST-PROOF.md — refresh to the clean CLI now that the
three gaps are closed (#101/#102 via PR #107; #92 via PR #119):
- Step 3: raw SQLite INSERT →
- Step 4: raw JSON →
- Status header: mark all three closed; note the proof validates the
production deployment pattern (bare-metal Clawdie service runs this model)
- Chain-resolution section: document the #92/#119 containment guard
(canonicalize + assert under COLIBRI_JAIL_ROOT_BASE before any write)
- Follow-ups: record what landed vs. what's still open (no delete-tenant
verb; CI runner intermittently down)
2. Sweep markdown corruption introduced by #126 (merged while CI runner was
down, so the prettier gate never ran):
- AGENTS.md — prettier reflow
- COLIBRI-SKILLS-PLAN.md — Ownership table had a row split across two
lines ('consumer.' orphan + a duplicated Agents row); restored to 5
clean logical rows
Checks: npx prettier@3 --check across all docs + AGENTS.md + README.md →
0 warnings; cargo fmt --check clean.
Co-Authored-By: Hermes & Sam <hello@clawdie.si>
PR #124 applied the positive-instruction-framing convention across docs but
was self-merged without the markdown format gate, leaving 6 files failing
prettier and a few structural defects. This repairs them:
- prettier --write on the 6 files that failed ./scripts/check-format.sh
(AGENTS.md, CLAWDIE-STUDIO-PROPOSAL, COLIBRI-SKILLS-PLAN, HEADROOM-SIDECAR,
MULTI-AGENT-HOST-PLAN, VAULT-PROVISION-FIRST-PROOF).
- COLIBRI-SKILLS-PLAN.md: fix a table row split across two lines by a stray
newline injected mid-cell.
- CLAWDIE-STUDIO-PROPOSAL.md: remove an orphaned "together." left dangling
by a reworded sentence; restore the editor-bridge (MCP) guardrail bullet
that was dropped, reworded positively; restore the guardrail list structure.
- CLAWDIE-STUDIO-PROPOSAL.md: plain-language the three implementation
guardrails (MCP foundation, opt-in/guarded tools, set-cost-mode scope).
./scripts/check-format.sh -> green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Convert 'do not', 'cannot', 'never', 'avoid', 'don't' patterns across
AGENTS.md, README.md, and 11 docs/*.md files into positive,
actionable instructions that tell the reader what TO do.
Preserved: hard safety constraints (MUST NOT agent boundaries,
vault credential confinement intent) — these are enforceable
guardrails where the prohibition IS the instruction.
docs/MULTI-AGENT-HOST-PLAN.md and docs/README.md had table-column formatting
drift that fails the markdown CI gate (prettier --check '**/*.md') on main.
Formatting only — pure table-padding re-alignment, no content change. Unblocks
the markdown job so the CI pipeline goes green again.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Correct the raw socket spawn example to use the bootstrapped colibri-test-agent in the jail instead of the default remote-provider agent binary. Use a harmless FIRST_PROOF_KEY item for the throwaway collection.\n\nAlso convert packaging/freebsd/colibri-agent-loop.md to normal Markdown so the repository formatting gate passes.\n\nChecks: ./scripts/check-format.sh; git diff --check
Documents how to prove the spawn -> vault-provision -> .env chain live on osa,
honestly surfacing that it isn't CLI-drivable yet:
- the chain is wired + unit-tested, but tenant registration is raw-SQLite-only
(#101) and jailed spawn is raw-socket-JSON-only (#102)
- runbook uses the interim manual path (sqlite insert + raw spawn-agent JSON)
- scratch jail + test collection per first-proof policy; bootstrap creds never
enter the jail
- documents exact resolution: collection name = tenant_id, jail_root must match
Continues an osa-agent investigation (verified against origin/main).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
New doc: docs/MULTI-AGENT-HOST-PLAN.md — gap analysis of the multi-host
coordination stack after PR #83 (socat bridge + Python pollers). Defines 5
phases: Phase 1 (multi-agent task-board tests), Phase 2 (merge CLI surface
gaps), Phase 3 (agent presence schema, deferred), Phase 4 (polling workflow
test, deferred), Phase 5 (TCP bridge validation, FreeBSD-only).
Immediate scope: Phases 1-2, all Linux-testable.
Updated PRIORITY-HANDOFF-ISO-SPAWN-COST.md to mark Priorities 2 (poll_tasks)
and 3 (cost mode enforcement) as done, fix stale test count (164 → 211), and
cross-reference the new plan as the next sprint.
211 tests pass, clippy clean, fmt clean.
Return an error from the socket server when another daemon owns the Unix socket or bind setup fails, and broadcast shutdown so the daemon does not stay alive without a control socket. Also format the PR docs.\n\nChecks: cargo fmt --check; ./scripts/check-format.sh; git diff --check; cargo test -p colibri-daemon clear_stale_socket -- --nocapture; cargo test -p colibri-daemon --test sigterm_shutdown -- --nocapture.
Six bugs found in deep-dive analysis of FreeBSD rc.d/rc.conf after the
live-copy-safe fix (7d23905):
1. colibri_cost_mode → colibri_daemon_cost_mode: naming broke rc.subr
${name}_ convention — operator setting colibri_daemon_cost_mode=fast
in rc.conf was silently ignored. Fixed in rc.d, staging script,
rc.conf.sample, and all docs.
2. Removed redundant chmod 660 on socket in poststart: Rust code already
sets 0770 with documented rationale. The poststart override to 0660
was conflicting, fragile, and had no comment.
3. Removed unnecessary chmod 644 on pidfile in poststart: pidfile lives
in a 0750 directory — world-readable permission is pointless and
security-negative.
4. Fixed ISO-SERVICE-LAYOUT.md: socket perms were wrong (said 750, actual
770), colibri-daemon.pid was labeled supervisor pidfile (it's the
child), supervisor pidfile was missing entirely, shutdown behavior
didn't mention custom stop_cmd targeting the supervisor.
5. health_cmd now checks for non-empty daemon response instead of just
connectvity — a hung daemon accepting connections but returning
garbage was reported healthy.
6. rc.conf.sample hostname path: $ (hostname) → $(/bin/hostname) for
consistency with rc.d script and early-boot PATH safety.
Checks: sh -n OK, cargo fmt --check OK, cargo clippy clean,
cargo test --workspace 207 passed.
Rename the local deterministic launch helper from colibri-smoke-agent to colibri-test-agent, update CLI/TUI/tests/docs, and teach the FreeBSD rc.d service to source /usr/local/etc/colibri/provider.env plus set a service PATH for local spawns.\n\nChecks: cargo fmt --check; ./scripts/check-format.sh; git diff --check; cargo check -p colibri-daemon -p colibri-client -p colibri-glasspane-tui; cargo check -p colibri-client --bins; cargo test -p colibri-client --test live_socket_check -- --nocapture.
The layered-soul skills importer globbed skills/**/*.md, pulling references/ and
templates/ in as separate skills. Import each skills/**/SKILL.md instead
(frontmatter name/description, category 'soul'); supporting files are not skills.
Verified against the populated layered-soul: 9 skills imported, idempotent,
curated memory deferred. Doc updated to match.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Match the docs to the shipped staged-env code: add the JailConfig root_path
field, a 'Staged env payloads' section (prepare_spawn_command writes env.sh/
launch.sh under /var/run/colibri-stage/<id>/), resolve the mdo-env-passthrough
open item, and add root_path to the external-MCP example.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
