# Pi Team Bright evergreen context Updated: 2026-10-14 Published versions and their evidence live in [GitHub Releases](https://github.com/deephbz/pi-team-bright/releases) and the npm dist-tags. This file does not track them. From versions before `0.19.0`, named model roles replace model profiles and raw Worker defaults. Finish or stop live Teams on their original version. Preserve their stores and native Session logs, update settings, then restart Pi and start new Team epochs. The [release notes](../release/v0.19.0-release-notes.md) give the upgrade steps. Parent composition and installed settings remain separate from publication. Lifecycle stage: **hardening** for DAG-native Task coordination and Worker model roles. The Membership-observation surface remains in **sharing**. ## Lead guidance: delegation boundary and second opinion [Decision 0017](../decisions/0017-delegation-boundary-and-second-opinion.md) keeps one lead, sets a fact/opinion delegation boundary, and makes independent review an opt-in `second-opinion` Worker requested by the user. The packaged skill and `AGENTS.md` carry the procedure; the settings example names the role. Runtime code is unchanged. Real-Team verification of both behaviors is pending. ## Lead guidance: elapsed time, fluid delegation, owner reporting [Decision 0025](../decisions/0025-elapsed-time-delegation-and-owner-reporting.md) makes elapsed time the cost. Workers are cheap, so parallel and speculative starts are the default. The lead does a lone high-stakes Task itself. Repair never waits for a busy builder. Owner reports use three states: Delivered, Blocked, and In progress. The skill and `AGENTS.md` carry the procedure. The leader-only Alert `interrupt` flag is the one runtime addition. Real-Team verification is pending. So is evidence that a superseded Attempt's Worker stops promptly. ## Compact identity labels and HUD New Team creation uses a local date prefix by default. Global `pi_team_bright.team.date_prefix` disables it. Leader pane labels and terminal titles use `leader-`; Workers use ``. PTB enforces the bound Worker Session name `/` only when it differs. Leader and unbound Session names remain owned by the human or Rarebit. Binding refresh and native Session name events reapply terminal titles. Clear cancels pending title retries and asks Pi to restore its default title by re-emitting the unchanged Session name. Exact Session/Membership binding feeds `team.member` through the inline [HUD contract](../../src/utils/team-hud.ts). A composer owns the TUI footer while present; PTB uses a role-only wrapper when absent. Replay rechecks the binding and fences late results. [Decision 0019](../decisions/0019-compact-identity-and-hud.md) owns the intent and ownership rule. Focused tests cover these projections. Real-Pi HUD integration remains pending. The new in-process slot flow changes presentation composition; authority, persistence, and deployment stay unchanged. ## Delivery around compaction The [delivery gate](../../extensions/compaction-delivery-gate.ts) holds Task, Alert, team_sync, and doctor sends during native compaction and external `hc.delivery-hold` windows. Native compaction and each external token have independent ownership. Repeated external begin signals renew a 30-minute lease. Expiry removes only that token and warns through `ctx.ui.notify`. Session reset clears holds and old-target sends. The [operator guide](../../README.md#delivery-holds) states the fail-open limit. Pi 0.83 reports no failed compaction; a 15-minute native hold limit covers that case. The [journal entry](../journal/2026-09-29-compaction-delivery-gate.md) records the native-compaction runtime evidence. The external hold has focused gate and adapter tests; real-Pi integration remains pending. The external signal adds a delivery-control flow from hc-auto-compact into PTB. Task and Team authority, persistence, and deployment remain unchanged. Automatic compaction has no real-provider run yet. ## Session discovery isolation Session discovery reads Membership identity before validating matching Team settings. Unsupported settings in an unrelated Team cannot block an exact Session lookup. Unreadable Membership identity and invalid matching records still refuse. Team creation also refuses ambiguous and stale bindings. [`preview-team-authority.test.ts`](../../src/utils/preview-team-authority.test.ts) and the durable model-tool tests verify these boundaries. ## v0.19.0: model roles The accepted [model-role decision](../decisions/0015-model-role-settings.md) replaces profile aliases and raw defaults with one named map and a default reference. Implementation and independent verification are complete. Public naming is `model_roles`, `default_model_role`, and `model_role`. Each role has one qualified model reference plus thinking and usage guidance. The [canonical example](../examples/pi-team-bright.settings.json) is the setup entry point. The [work record](../projects/model-role-settings.md) tracks the base, scope, verification, and remaining work. ## Stable Worker system-prompt addition The Worker system-prompt addition contains Worker and Team identity, the lead name, the standing Worker profile, and the Task work contract. It excludes the configured model assignment, model-role alias, runtime model, and thinking level. The adapter captures the complete addition on the first successful Worker-profile read in a Session. It reuses those bytes for the rest of that Session. A failed read before capture leaves the standing profile absent and retries on the next run. A successful read with no profile captures that absence. Later read failures and profile edits cannot change a captured addition. Profile edits take effect when a new or recovered Session starts. Capture is in memory; no stored Session or Team record changes. The Session query port exposes only the standing profile prompt. The lead's model projection in Team snapshots remains unchanged. Pi Session history still owns continued model selection; model-role creation and recovery policy remain unchanged. Architecture impact: **changed** in PTB's model-facing prompt contract. Topology and persistence boundaries remain unchanged. The HyperCarrier diagram keeps PTB internals opaque. The registered `before_agent_start` handler in [`pi-team-session-adapter.ts`](../../extensions/pi-team-session-adapter.ts) owns this projection. The same-Session regression in [`pi-session-adapter.characterization.test.ts`](../../src/utils/pi-session-adapter.characterization.test.ts) checks model and thinking changes, read failures, profile edits, recovery, retained role/profile/Task text, and absence of model facts. ## Branch-held Team observation Accepted Proposal A, recorded in [Decision 0020](../decisions/0020-branch-held-team-cursor.md), supersedes the delivery mechanics of [Decision 0016](../decisions/0016-framework-team-synchronization.md). The lead's selected native Session branch owns delivery position. The adapter publishes `ptb.team-update` only while idle. Native persistence commits presentation; provider success has no role. `team_sync` returns immediately. A missing branch cursor selects a snapshot, which captures its journal watermark before Task and Worker hydration. The service revalidates the Team epoch and lead binding. Snapshots also recover recent received Alerts through a non-consuming Alert-authority inbox query for the exact Membership. This read is independent of the journal watermark. Direct delivery still presents new Alerts. Task-authority reconciliation runs after semantically empty journal pages; stale Task and retired Worker events cannot hide an authority revision. An in-memory reservation prevents competing reads of one page. Persistence, branch or binding change, or a bounded failure timer releases it. Compaction does not undo delivery; a snapshot restores model context. Forked entries do not bind the new Session. Hidden-observation stores and provider ACKs are removed. The in-memory authority fixture composes the production Coordination reader. Native results and custom messages name their event page and next action. A failed automatic send stays suppressed until branch change; `/ptb sync` can retry. Architecture impact: **changed** inside PTB's observation persistence boundary. The HyperCarrier diagram keeps PTB internals opaque. Focused branch, publisher, and registered-tool tests cover the contract. The isolated real-Pi S1, S3, S5, and S6 checks pass with a loopback scripted provider: native compaction, custom publication, context loss, and historical reload. See the [scenario method](../maintainers/scenario-verification.md). Remote-provider validation remains unclaimed. Live settings and parent adoption remain unchanged. ## v0.19.0: Task timeline view `/pi-team-graph` keeps its dependency DAG as the initial view. The same pane can show a waterfall of recorded Attempts. Both views share one validated Task source, selection, recent limit, and state filter. The graph authority records transition times; the view derives elapsed and blocked spans from those records. Old Attempts without complete timing remain unavailable. The [work record](../projects/task-timeline-view.md) gives scope and verification. This changes internal recorded evidence and presentation; the public Membership observation protocol and HyperCarrier integration boundary remain unchanged. ## Graph-only Task authority [Decision 0024](../decisions/0024-graph-only-task-authority.md) removes the legacy Task backend and model-checker lane. Graph snapshots own all Task reads, transitions, views, lifecycle guards, and startup delivery recovery. New Teams persist an explicit empty snapshot before creation succeeds. Established Teams with a missing or corrupt snapshot remain unavailable; they never appear empty. Valid graph snapshots override obsolete backend fields. A retained `task-authority/` directory or graph-revision retirement record identifies a lost graph even when obsolete backend fields remain. Restore that authority before continuing. Graph mutations hold the exact Membership lease and recheck its Session binding before commit. Delivery currentness requires the graph; a retained spool or derived fence cannot authorize presentation. Targetless recovery binds one exact recipient durably before enqueue and retains it across replay. Graphless Teams that keep Tasks in Beads are unsupported. The refusal states: “This Team keeps its Tasks in Beads. PTB 0.24 does not support it. The data stays in .beads/.” Runtime never reads or writes that Task data. No migration or export path remains. Historical native Session and delivery records retain their readers; they never authorize legacy Task mutations. Registered Worker stop and Team shutdown return typed unavailable outcomes when Task guards cannot read authority. `/ptb status` names unsupported storage without a graph-path claim. Independent adversarial and process-recovery tests remain. The [purge record](../journal/2026-10-13-legacy-purge.md) owns removal scope and verification evidence. Architecture impact: **changed** inside PTB. HyperCarrier keeps PTB internals opaque. No publication or deployment is implied. ## v0.19.0: doctor command `/ptb doctor` loads the packaged repair guide and local Team metadata into a visible diagnostic turn. It can inspect an explicitly named Team without a current binding. The command changes no Team authority and leaves the existing slash commands in place. The [work record](../projects/ptb-doctor.md) owns its scope and verification. ## v0.20.0: command palette The owner requested one `/ptb` command with an interactive palette for commands and configuration. The palette uses the same action handlers as direct subcommands. Its settings editor validates and replaces only the PTB namespace in the existing global or trusted-project Pi settings file. It creates no new configuration store and does not modify live Team records. The [operator guide](../../README.md#command-palette) owns the human workflow; [`ptb-command.ts`](../../src/utils/ptb-command.ts) owns command syntax. This work builds on the composable mock review galleries. Architecture impact: none at the HyperCarrier boundary; PTB adds an internal configuration editor. ## v0.20.0: brand and website [`brand/brand.js`](../../brand/brand.js) is the single source for colour and type tokens, product copy, drawing primitives, the mark, and the lockup. `brand/build.mjs` derives the logo, favicon set, banners, tokens, and the GitHub Pages site; the promo video draws with the same primitives. Each product claim in the copy names its source anchor. The `pages.yml` workflow checks generated assets and deploys the site from `main`. Architecture impact: none; the brand is outside the npm package. ## v0.20.1: demo and early-start guidance The README links a demo thumbnail to the release MP4. Release notes embed the video through a GitHub editor attachment. The reproducible source bundle lives in [`brand/promo-video/`](../../brand/promo-video/). The packaged lead skill now asks agents to start independent and reversible work early while preserving actual dependencies and approval boundaries. Runtime code is unchanged. The full-history privacy scan still reports inherited findings from before the privacy baseline. The larger hostile Herdr campaign is not claimed complete. This is the maintained context a new human or agent should read first. It contains only intent, decisions still in force, current status, constraints, and next steps. Executable contracts live in source and tests; private dated evidence remains in the repository history rather than the npm artifact. ## Product intent Pi Team Bright turns one Pi Session into the lead of a Team of stable Workers, with Task-first teams visible in terminal panes. A Task plus its assignee is the only executable work contract. `team_sync` reads available Team changes. The lead ends its turn to wait for `ptb.team-update`. Typed Alerts are exceptional clarification, attention, or announcement; they never assign, advance, block, or complete work. The product deliberately excludes a general agent directory, cross-Team routing, freeform work-by-message, inbox polling, runtime polling as progress, and terminal activity as Task evidence. Exact current Membership and Pi Session binding determine who may act; matching names, processes, panes, or environment variables do not. ## Sources of truth | Concern | Authority | |---|---| | Public tool selection and TUI message projection | [`src/model-tool-contract/result-projection.ts`](../../src/model-tool-contract/result-projection.ts), [`src/model-tool-contract/tui-projection.ts`](../../src/model-tool-contract/tui-projection.ts), [`src/model-tool-contract/tui-message-projection.ts`](../../src/model-tool-contract/tui-message-projection.ts), and [`extensions/index.ts`](../../extensions/index.ts). The executable review inventory is [`tui-message-gallery.ts`](../../src/model-tool-contract/tui-message-gallery.ts). | | Model-role settings and diagnostics | [`src/utils/model-role-settings.ts`](../../src/utils/model-role-settings.ts) | | Worker-only settings resource projection | [`src/utils/worker-resource-projection.ts`](../../src/utils/worker-resource-projection.ts) and its focused tests | | Tool parameters, descriptions, guards, and execution | TypeBox registrations in [`extensions/index.ts`](../../extensions/index.ts) | | Machine result schema | Raw catalog unions and model projection schemas in [`src/model-tool-contract/result-projection.ts`](../../src/model-tool-contract/result-projection.ts) | | Team, Membership, Task, Alert, and event types | Authority-owned contracts in [`team-authority`](../../src/team-authority/contracts.ts), [`task-authority`](../../src/task-authority/task-domain.ts), [`alert-authority`](../../src/alert-authority/contracts.ts), and [`coordination`](../../src/coordination/contracts.ts) | | Team authority, exact Session binding, and logical Worker persistence | [`src/utils/teams.ts`](../../src/utils/teams.ts) | | Branch-held observation position | [`src/coordination/branch-observation.ts`](../../src/coordination/branch-observation.ts) | | Read-only Membership observation protocol | [`src/public/observation.ts`](../../src/public/observation.ts), exported as `@hypercarrier/pi-team-bright/observation`; [`src/team-authority/membership-observation-reader.ts`](../../src/team-authority/membership-observation-reader.ts) is its private read-only decoder | | Read-only Task observation | [`src/public/tasks.ts`](../../src/public/tasks.ts), re-exported by the same public observation entry point; card projection and ready selection remain inside Task authority | | Canonical Task card and opaque TaskVersionRef | [`src/task-authority/task-domain.ts`](../../src/task-authority/task-domain.ts) and [`src/task-authority/task-version-ref.ts`](../../src/task-authority/task-version-ref.ts) | | Task authority, reads, and mutation semantics | [`graph-control.ts`](../../src/task-authority/graph-control.ts) owns graph revisions, Attempts, derived state, bounded failure traversal, replay, and recovery. [`durable-graph-task-authority.ts`](../../src/adapters/durable-graph-task-authority.ts) owns the Team snapshot. [`graph-orchestration.ts`](../../src/task-authority/graph-orchestration.ts) owns publication and ready delivery through [`publication.ts`](../../src/task-authority/publication.ts). [`durable-task-mutation-publication.ts`](../../src/adapters/durable-task-mutation-publication.ts) implements the Coordination and delivery bridge. | | Semantic-hardening status and dependency evidence | Maintained [`context`](../projects/semantic-hardening/context.md), [`subsystem audit`](../projects/semantic-hardening/subsystem-boundary-audit.md), and machine [`dependency map`](../projects/semantic-hardening/subsystem-dependency-map.json) | | Event cursor, wait, filtering, and paging semantics | [`src/coordination/event-journal.ts`](../../src/coordination/event-journal.ts) | | Exact recipient Session delivery lifecycle | [`src/utils/recipient-delivery-lifecycle.ts`](../../src/utils/recipient-delivery-lifecycle.ts), composed by [`extensions/pi-team-session-adapter.ts`](../../extensions/pi-team-session-adapter.ts); Alert and Task engines retain watch, replay, acknowledgement, and binding fences | | Human operating introduction | [Repository README](../../README.md) | | Agent operating procedure | [`skills/pi-team-bright/SKILL.md`](../../skills/pi-team-bright/SKILL.md) | The [contract source map](../reference.md) gives one-hop navigation without restating executable definitions. ## Decisions still in force - Accepted [Decision 0023](../decisions/0023-received-alert-recovery.md) makes received Alerts recoverable: the `team_sync` snapshot lists the newest 10 Alerts that the caller's exact Membership received, from its inbox, with 2000-point previews and an omitted count. `updates.alerts` stays empty. - Accepted [Decision 0022](../decisions/0022-carrier-harness-migration.md) keeps multiplexer and agent-harness migration open. The generic layer holds PTB's intrinsic ontology; adapters hold knowledge that depends on Herdr, Pi or the OS, and migration replaces adapters. - Accepted [v3.1 Proposal B](../journal/2026-10-12-state-ownership-and-liveness-proposal.md) and its [lead rulings](../journal/2026-10-12-v31-implementation-plan.md) amend Decision 0018 as [Decision 0021](../decisions/0021-carrier-observation-liveness.md) records. `CarrierObserver` owns process-generation observations. A live shell never proves a live Worker. Unknown evidence fails closed. For a bound tokenless generation, `ensure_worker` returns `legacy_unverified` attention with `ask_human`. The carrier projection and `team_sync` also show that attention with the PID and probe result. An absent PID needs human restart of the Worker's Pi in its pane or a Worker stop. A present PID permits reload or adoption in `/ptb status`. Unknown probe evidence needs verification first. The shared advice puts the human action before evidence. `ensure_worker` retains its model safety rule; human toasts, status, and worker-change text omit that rule. Snapshot `connected` means Session binding only; its attention field preserves unresolved process evidence. Pending or stalled launch evidence cannot replace this attention. It never spawns a replacement. A missing macOS verifier helper takes precedence with `generation_helper_missing` and `ask_human`. The model result, collapsed TUI, and native admission refusal name the helper and build command. Launch records the launch ID before the pane split and the target before Herdr agent start. It returns a receipt without waiting for readiness. Elapsed time and start errors keep the pane. The same-generation `live`/`stopping` reload pair stays silent while durable `lastStop` says `reload`. Verified death always journals. Local shutdown intent survives verifier failure; an exact stop-ID check fences older admission work. Session switches require attention; stopping that Membership keeps its pane. Each observation source owns its sample time. Samples expire to unknown after six seconds, including collection failure. Legacy attention then changes its probe to unknown and asks for verification before repair. Historical journal messages retain their sampled evidence. A stalled read remains single-flight. The visible event journal is the sole publication baseline, including after observer restart. Coordinates are Membership, generation, launch ID, field, and terminal target (backend, kind, ID). Each coordinate starts at `unknown`. Binding, launch, process, terminal, and activity changes journal in sample order. Terminal present/unknown and activity changes use `wait` without a human toast. Herdr `done` maps to activity `idle`; unknown wire statuses retain their raw value. Legacy attention journals even from an `unknown` baseline and deduplicates unchanged evidence across polls and observer restart. Debounced blocked attention remains separate. Legacy pane-only events do not establish a baseline for a typed terminal target. Publication rereads the journal under the Membership lease and fences the exact generation and terminal target. Failed appends leave the accepted baseline unchanged; healthy polling retries the current source difference. A transient observation lost before append is not durable. There are no hidden observation checkpoints. Journal failure does not delay the source projection. Worker admission publishes a verified predecessor exit before it replaces that generation's runtime record. It holds the Membership lease through both steps. Polling and admission use the same accepted journal baseline. An exit-publication failure preserves the predecessor record and prevents replacement. One ten-second receipt deadline covers claim, nested leases, Herdr preparation, and target CAS. Expiry returns attention and prevents late startup. Prepared targets reconcile asynchronously, in process, under the exact Membership and launch ID. Restart orphan reconciliation is pending; a lead restart does not yet recover an unfinished launch. Only decisive shell-busy refusal retries on the same pane and launch ID. The shared Herdr reply reader preserves error codes and text from stderr when stdout is empty. Placement treats only structured `pane_not_found` as absence. A readiness timeout remains unknown and never authorizes another spawn. A first launch remains outstanding until Session binding. A recovery remains outstanding while its runtime record is absent or still names its prior process generation. Pending and stalled checks share this rule. An outstanding started or unknown launch with no Herdr agent in its pane returns `launch_stalled` attention after 15 seconds. An admitted successor retains its planner reason after process exit. The human can authorize `worker_stop` before retry. A missing Herdr row never authorizes another spawn. Linux reads procfs. Probes A7 and A9 pass on one Linux host; a full Linux Team with real Pi and Herdr has not run. On macOS, npm `postinstall` builds the dependency-free helper from packaged source with `rustc` and Xcode Command Line Tools. `npm run build:process-generation` repairs installs with disabled lifecycle scripts. Missing `rustc` leaves installation successful. Npm can hide the postinstall diagnostic. On macOS, Pi startup emits one native missing-helper warning per extension load with the Rust/Xcode remedy and build command. The warning creates no model turn or Session entry. A missing helper yields unknown process evidence and never authorizes a spawn. Exact Session-bound re-entry by the same PID remains `already_current` without the helper. Different-PID replacement still refuses with `ask_human`. A prepared claim has no completed Session binding and keeps its existing admission fence. `/ptb status` persists one human-only transcript entry with carrier, stop, and nonterminal Task evidence. Unknown process and launch states include their decisive evidence facts. Inline facts are bounded; expansion shows their full text. It batches explicit adoption of tokenless records, excludes records with an absent PID probe, and remembers a decline within the exact Session runtime. Herdr outage attention reaches both the human and `team_sync`. Architecture impact: **changed** inside Pi Team Bright. HyperCarrier keeps these internals opaque. - [Decision 0017](../decisions/0017-delegation-boundary-and-second-opinion.md) keeps one lead, delegates facts and keeps opinions with the lead, and makes the second opinion opt-in. It narrows Decision 0014's persistent-reviewer sentence to user request. - [Decision 0015](../decisions/0015-model-role-settings.md) supersedes the profile naming, default fallback, and repeated TUI examples from Decision 0014. Fixed Worker bindings and native Session recovery remain in force. - [Decision 0014](../decisions/0014-worker-model-profiles.md) accepts fixed Worker model profiles, compact alias discovery, valid-choice error hints, and human-only TUI settings guidance. It removes per-Task model selection without compatibility. The implementation passed independent verification and is published in `0.18.0`. Same-Session recovery preserves the model and thinking level recorded by Pi, including human overrides. The [result and evidence](../projects/worker-model-profiles-verification.md) include a real two-profile DAG and operator-override recovery, full-lane and package checks, and focused trust/prebinding regressions. - `TaskCard` and opaque `TaskVersionRef` remain public Task coordinates. `TaskMutationPublicationPort` isolates graph orchestration from concrete Coordination, failed-hint, and delivery writers. Team authority owns durable lead-Session discovery; Pi composition owns environment precedence and hooks. Historical internal re-export facades are removed. Consumers import contracts from their semantic owners. - Displayed extension messages use one audience projection with explicit status, summary, body, source, and diagnostic detail fields. The renderer shows a short `PTB ·` header, an explicit status line, and a concise summary in collapsed mode. Expanded mode shows human-readable content first, then diagnostic JSON. Tool results, delivered messages, framework sync, and `/ptb doctor` use the same theme roles, padding, background, and Pi expansion affordance. The non-mutating gallery calls this renderer and supports deterministic dark and light review themes. Historical message identities remain read-compatible. This supersedes [decision 0011](../decisions/0011-unified-tui-message-projection.md). - Assigned Tasks are the sole durable work-delegation protocol; Alerts remain exceptional coordination. Team, Worker, and Task have distinct lifecycles. A Team aligns with a project or durable coordination boundary and remains alive until the owner or operator explicitly ends or resets it. A Worker aligns with coherent semantic scope or deliberate perspective isolation; a Task aligns with one bounded outcome. New Workers must unlock independent parallel work, establish reusable scope, or isolate perspective. Do not infer Team shutdown from completed Tasks, an empty ready front, or idle time. - Task authority, Team/Membership authority, Pi Session identity, event evidence, delivery presentation, runtime observation, and terminal surfaces remain distinct. `pi-teams-observation/1` is recorded Membership evidence, never OS liveness. - Team topology and lifecycle mutations are lead-only. Shutdown deactivates a Membership only after exact stop evidence. Task history and authority remain. Alert and Task delivery share one exact recipient Session fence. Each engine has an independent failure and retry outcome. Initial starts retain Alert-first ordering for the shared lease. A failed start, context observation, acknowledgement, or background scan stops only that engine. Retries use capped backoff while the binding stays current. Unsupported Beads Task storage is terminal for that engine. It publishes degradation without `retryAt`, which means no automatic retry. Alert delivery continues. A later Session activation can try Task delivery once again. The runtime record carries each engine's degradation for its exact generation. `team_sync` snapshots, unsettled results, and `/ptb status` expose that fact. Runtime diagnostics update on each retry. The recipient pane toasts when an engine first becomes degraded, when retries stop, and when it recovers. A terminal failure says delivery stopped and will not retry. The human toast and status detail direct the owner to finish the Team with its original PTB version or start a new Team. The model-facing refusal message remains unchanged. Initial create and resume activate delivery. Binding replacement, admission refusal, Session shutdown, and successful full Team shutdown stop both engines and their retries. Partial shutdown retains the current leader delivery. Full shutdown ends only the exact lead runtime generation and fails closed around malformed or foreign evidence. - An accepted Alert is stored for its recipient. The receipt proves neither presentation nor processing. It includes known current-generation delivery degradation as diagnostic evidence. Missing or degraded delivery never refuses durable acceptance. Diagnostic evidence does not enter the inbox payload. - Coordination advice for an idle Worker with an `in_progress` Task names that Task and asks the lead to inspect its blocker and evidence before deciding. Carrier facts stay unchanged. Idle alone authorizes no spawn or replacement. Known limit: this advice appears only on the activity-change event. A snapshot after compaction does not repeat it. - `team_sync` preserves `caught_up` for current quiescence. `unsettled` names Workers whose activity or missing runtime/delivery evidence needs attention. Both advance the lead's branch cursor once the native entry commits. Pi `>=0.83` is the supported boundary for exact Worker `agent_start` and `agent_settled` evidence. Global `pi_team_bright.team` settings resolve the internal wait interval and automatic-sync delay/count policy once per Team epoch. The canonical settings example owns copyable configuration. - Pane placement is a typed terminal-adapter responsibility. Herdr and tmux receive the durable leader pane plus current Worker panes from [`src/utils/team-pane-placement.ts`](../../src/utils/team-pane-placement.ts), rather than terminal focus. They keep the leader left at at least the configured share, which must be greater than 0.1 and less than 1 and defaults to 0.6. They prove later targets still share its tab and Worker region before splitting, and stop only exact Worker panes. Pi 0.83.0 support now loads the exact working-tree extension while retaining normal unrelated extension and Skill discovery. A disposable Herdr Team with a harmless discovered extension and Skill proved two Worker Session bindings, Task-tool use, and exact stops. A distinct globally discovered Pi Team Bright copy can still conflict with explicit `-e` through duplicate tool registration; it remains an installation risk, not a Team storage-version boundary or a reason to suppress normal resources. Herdr preserves its established Pi launch environment allowlist. After `pane split`, the adapter uses the exact returned pane handle with official `pane rename` before `agent start`. A label failure records a payload-free launch stage and warning but does not block coordination. The extra local CLI call measured 24.72 ms and does not change admission evidence. Decision 0018 owns the hang ceiling. Other adapters retain existing behavior without this guarantee; the executable contract is [`TeamPanePlacement`](../../src/utils/terminal-adapter.ts). This changes the Pi Team Bright adapter contract, but no depicted component, dependency, or topology, so the Structurizr DSL is unchanged. - Package release identity is not a Team persistence capability. New Team epochs do not persist a package version. Historical optional `implementationVersion` values remain readable as provenance and never gate Team operations. A future incompatible persistence change must name and test its actual schema or capability plus migration behavior. Fresh Team epochs persist an opaque epoch identity and stable logical Worker name/scope records separately from replaceable Membership, Session, process, and terminal carriers. The model-tool surface derives its cursor from the authorized Session branch; it never becomes Team or Task authority. Since `0.17.0-rc.3`, `ensure_worker.separate_window` is deliberately absent: durable Team configuration exclusively owns placement policy. A launch receipt may report exact bounded startup observation, but never Worker readiness or progress. Existing absent/false settings mean panes. A Team epoch captures its resolved `pane_layout` once: explicit `team_create.pane_layout`, trusted project `pi_team_bright.team.pane_layout`, global settings, then `{ leader_share: 0.6, worker_tiling: "linear" }`. Settings changes do not move live Teams. Herdr supports `linear` and live `adaptive` placement. Both exclude absent registered panes and use the first-Worker split from the leader when none remain. Other pane-query failures stop the launch. Adaptive ranks only present registered Worker panes in the leader tab and region by `max(width / columns_per_row, height)`, defaults bias `columns_per_row` to 2, and splits the longer visual dimension 50/50. It skips children below 20 columns or 5 rows and reports insufficient geometry when no candidate remains. `grid` remains read-compatible for historical records. An optional `worker_limit` caps current active Worker Memberships; omitted preserves the historical unlimited behavior. Other pane backends refuse adaptive/grid. Never edit a live TeamConfig or pass a Worker placement override. ## Current status and anchors - The selected stable source now contains the graph-native production path. `task_graph_apply` replaces `task_create` without adding a leader tool. A Team-scoped snapshot stores complete graph revisions, immutable Attempts and replay receipts. Worker profiles own initial model selection; native Pi Session history owns continued model selection. `dependency_waiting` and `ready` are derived; only `goal_achieved` releases a prerequisite, while `goal_failed` applies a bounded failure edge. Runtime composition includes recovery, ready delivery, Coordination reads, lifecycle guards, and Worker transitions. The explicit empty graph snapshot supports reads before the first graph apply. No backend fallback remains. This changes internal Task authority, persistence, dispatch, and model contracts. HyperCarrier's diagram stays unchanged because it keeps Pi Team Bright opaque. - The current source uses the real main extension as its local switch. Leader processes register the nine-tool DAG-native model surface, with `ensure_worker` and exact Session binding removing low-level Team locators. Workers keep the narrow `task_read`, `task_update`, and `alert_send` surface; runtime Team binding supplies the Team identity, so Worker calls do not select `team_name`. Worker `alert_send` derives its only recipient, `team-lead`; its schema has no recipient field. Worker launch must retain normal unrelated extension and Skill discovery while loading its exact Pi Team Bright extension. Worker settings cannot re-enable leader tools. No parallel extension or store exists. A real ten-tool smoke exposed a release-blocking result-projection mismatch: model-tool semantic results entered the old generic renderer and could produce false human summaries. The accepted revamp now keeps raw semantic details as truth and derives separate validated model, collapsed TUI, expanded TUI, and exact QA projections. Canonical Task-card `goal` uses the shared limit in [`task-limits.ts`](../../src/task-authority/task-limits.ts) across graph input, runtime validation, and returned Task cards. Global `pi_team_bright.task.goal_max_length` configures it; the default is 1600 TypeBox string-length units. Restart all Team Pi processes after an edit. Canonical `current_context` uses the TypeBox schema in [`task-domain.ts`](../../src/task-authority/task-domain.ts): one to 2,000 units. Owned writes keep these limits. Historical record projections bound display fields without changing their source: title and current context use structured `projection_warnings`, while an oversized executable goal is marked incomplete and remains visible with its identity, status, assignee, version, and Worker index coordinates, but is not executable. Structural Task events can advance `team_sync` without narrative evidence; journal entries still require committed task evidence. These public Task-card invariants change the contract, but no depicted component, flow, or topology, so the Structurizr DSL is unchanged. Successful TUI results remain concise semantic projections. Execution and result-projection errors stay concise when collapsed and add one copyable raw `content` and `details` report in detail mode, with a warning to review sensitive fields before sharing. The renderer no longer hides the source error behind a generic missing-semantic-result message. It removes the old `/1` result envelope and compatibility path rather than preserving them. The internal diagnostic schema remains `pi-teams-status/1`. See the durable [projection contract](../projects/model-invoked-tool-contract.md) and [parity checklist](../release/model-tool-parity-checklist.md). - `0.17.0-rc.14` is the published liveness and Worker-recovery base at exact release code `8bb517bd32d8687e97b96a531db15833fd64420a`. Selected stable `0.17.0` source adds atomic graph creation, mechanical ready-front dispatch, graph control, the read-only Task graph pane, and Worker-startup hardening. Its earlier eight-Worker stress closed 117/117 Tasks and stopped all Workers. The maintained [DAG-native context](../projects/dag-native/context.md) owns graph evidence. The pane has a fixed full-component sentinel, orthogonal routes, a concise HUD, pan and selection modes, spatial navigation, bounded Task details, and explicit unknown-history timing. It pins its TypeScript project when Herdr launches from another cwd. Status colors use terminal-owned semantic ANSI slots, so Colorstack and other terminal themes control light and dark color. The configurable [DAG gallery](../../src/task-graph-view/gallery/default.json) covers all seven graph states across disconnected islands without changing Task authority. TB routes now use an outside right repair lane, while LR routes use an outside lower repair lane. Arrows remain outside intact node borders, and the legend plus retry badge carry edge meaning without inline labels overwriting topology. Exact executable source `3ee1d4c5` passed the one allowed 1,004-test aggregate, all release-specific gates, a 197-file package dry run, candidate-range privacy, and a proxy-backed real Team canary. The canary mechanically advanced `A -> B`, recorded Worker-authored accepted Attempts, reused the same stable Worker, and shut down cleanly. The rebased routing follow-up passed exact graph-path comparison, typecheck, 35 focused tests, both sentinels, gallery/export, and package verification. Stable source then passed 142 aggregate files and 1,007 tests, package and lane gates, and a fresh all-tool Team E2E. Main CI, immutable package integrity, registry, provenance, tag, and GitHub Release evidence are complete in the stable `v0.17.0` release receipt. - Patch `0.17.1` resolves the graph-pane origin from the exact live Herdr pane rather than inherited tab and workspace coordinates. It keeps the resolved live location for split and close fencing. Missing, non-exact, or moved child panes still refuse. This is an internal terminal-adapter fix with architecture impact: **none**. The accepted evidence is [`graph-pane-origin-fix.md`](../journal/artifacts/2026-08-15-pi0842/graph-pane-origin-fix.md). - Patch `0.17.1` also repairs a stale-lock recovery TOCTOU: after a losing exclusive claim create, a missing fixed claim is ordinary contention and retries. A present stale malformed claim still fails closed. This changes an internal lock guard only; architecture impact: **none**. - Worker startup hardening removes two avoidable serial costs without weakening admission. Launch returns a receipt at once and does not wait for readiness. The bounded `herdr agent start` RPC runs asynchronously under the hang ceiling from Decision 0018. Exact current Membership, Session, and runtime-generation binding remains the commit point. Liveness comes from the process-generation verifier, never from a pane or shell check; exact failed events still fence the launch. Configured Worker defaults use the invocation-local model registry. `ensure_worker` no longer runs a leader Task scan; Session start, Task transitions, and periodic recovery own ready delivery. Real stable-Worker reuse measured 31/33 ms p50/p95, while normal fresh Pi RPC bootstrap measured 448/461 ms. Keep stable Workers bound. Do not add a generic warm pool or Node compile cache. The maintained [performance project](../projects/worker-startup-performance.md), superseding [official Herdr decision](../decisions/0013-official-herdr-ready-start.md), and [final 2026-08-14 assessment](../journal/2026-08-14-worker-startup-final-assessment.md) own the evidence and limits. - `npm test` type-checks and runs the fast deterministic lane, not the full contract/lifecycle/integration suite. CI runs it, `test:exhaustive-only`, typecheck, and package verification once per source tree as parallel shards (fast lane on Node 22/24, exhaustive on Node 24); publish reuses that result for the tagged tree and only verifies the package. `npm run verify:package` installs the packed artifact in a clean temporary project and probes the scoped observation import in CommonJS and TypeScript. - `team_sync({view:"updates"})` returns `caught_up` for current quiescence and `unsettled` for activity or missing evidence. Both return immediately. Native `team_sync` result details and automatic update messages stamp the page they present. The branch reader ignores entries without a stamp. The executable anchors are [`sync-continuity.test.ts`](../../src/coordination/sync-continuity.test.ts) and [`team-update.test.ts`](../../extensions/team-update.test.ts). - Task publication records payload-light failed-event hints and durable delivery recovery records. Startup recovery reads current graph cards and checks version, retirement, and exact recipient binding before enqueue. A failed event append cannot hide an authoritative Task change. An unavailable Task snapshot publishes no semantic observation. - The release source validates the Pi 0.84 footer subscription-auth boundary through the shared context registry. A resumed leader binds its exact Session before nudge-debt reads; the focused proof covers one presentation, fork and stale-binding suppression, and the durable/model/TUI projection boundary. - Worker resource settings are a Worker-process projection only. The executable parser plus Worker tool and CLI aggregate projection are [`src/utils/worker-resource-projection.ts`](../../src/utils/worker-resource-projection.ts), wired at Worker session and launch composition in [`extensions/index.ts`](../../extensions/index.ts). It reads the active Pi global directory and trusted project settings under `pi_team_bright.worker`. The launch requires explicit trust before reading project settings. A saved decision for a different Worker cwd wins; otherwise the Worker inherits the leader's resolved trust. Unknown trust uses global settings. Model selection comes from the model-role catalog and its default reference. The resolved creation binding belongs to the logical Worker; invalid selection refuses before Worker creation. Same-Session recovery preserves Pi's recorded model and thinking. Settings do not rewrite Task or public observation records. The Worker resource boundary remains in [decision 0008](../decisions/0008-worker-resource-projection.md); [decision 0015](../decisions/0015-model-role-settings.md) owns model selection. - Worker admission remains a two-phase external-actuation protocol. Herdr acceptance is positive actuation evidence, not Worker authority. Exact Membership, Session, and runtime-generation binding is the linearization point. Ceiling expiry remains suspicion. Launch-ID compare-and-swap fences late completion. The async ready-start call retains its pane on failure. Accepted Proposal B supersedes Decision 0018's cleanup timing. Pane and process liveness never prove Worker readiness. - One current Membership admits one live Pi process generation. The executable rule is [`src/utils/runtime.ts`](../../src/utils/runtime.ts), lifecycle wiring is [`extensions/index.ts`](../../extensions/index.ts), and focused evidence is in [`src/utils/runtime-startup-admission.test.ts`](../../src/utils/runtime-startup-admission.test.ts) and [`src/utils/session-lifecycle.test.ts`](../../src/utils/session-lifecycle.test.ts). Intent is in [decision 0007](../decisions/0007-one-live-process-binding.md); the independent receipt is [`2026-07-30-one-live-process-binding.json`](../journal/artifacts/2026-07-30-one-live-process-binding.json). ## Active Projects Four audit-driven Projects are active. Each routes through maintained Project artifacts; dated evidence remains in the journal. They do not replace this repository-level context or the executable contract sources. - [Semantic hardening](../projects/semantic-hardening/context.md) is in consolidation and hardening. Accepted uncommitted Task read and `TaskChangeDelivery` ports keep native reads and exact-recipient delivery leases behind explicit external adapters. The delivery port is mandatory and covers send and acknowledgement leases, ordering, replacement refusal, and replay parity. Independent acceptance and re-verification passed focused checks, typecheck, public/persistence diffs, and source fences; no aggregate ran in that historical review. Pi Session Team-query ports remain accepted. Native branch observation supersedes the Coordination hidden-observation port. Task/Team reverse dependencies and Coordination runtime, event, and nudge-actuation seams remain open. The maintained [subsystem audit](../projects/semantic-hardening/subsystem-boundary-audit.md) and machine [dependency map](../projects/semantic-hardening/subsystem-dependency-map.json) own current structural evidence. - [Model-invoked tool contract](../projects/model-invoked-tool-contract.md) is in hardening under the one-leader/multiple-Worker topology. The owner accepted `team_create`, `ensure_worker`, and `team_sync` as the initial end-to-end journey. The raw semantic result remains machine truth. The accepted projection boundary sends the model only decision-relevant validated JSON, renders concise allowlisted TUI views, and keeps exact raw/model comparisons in QA. Singleton Task results do not expose batch nesting. The retired result envelope, pass-through model projection, and generic legacy renderer are removed from the current surface. The model-tool surface has no model-managed Team locator, cursor, count cap, or paging. The durable model-tool surface composes Team epochs, logical Worker meaning, exact lead-Session binding, graph snapshots, structured events, native branch position, authoritative Task reconciliation, and the Worker launch bridge. Team events, sync actions, and Task reads use canonical Task cards. Graph authority owns expected-version checks and operation replay. Publication reuses its committed post-state card. Delivery accepts opaque TaskVersionRef coordinates and checks exact Membership and Session binding. The Worker mutation surface remains the bounded three-tool projection. - [Task-engine performance](../projects/task-engine-performance.md) is in hardening measurement. It owns trace repair, benchmark design, current performance assessment, and optimization selection. - [Worker startup performance](../projects/worker-startup-performance.md) has a hardening result. Stable bound-Worker reuse is the supported sub-100 ms path. Fresh Pi remains about 450 ms before exact Worker binding. Accepted actuation, in-process model validation, and removal of leader Task reconciliation are selected. Generic pooling, resource exclusions, bundling, and compile caching remain rejected. ## Constraints and open work The required observation invariant remains one complete coordination observation or no semantic observation. An unavailable Task authority must not advance the branch cursor, report zero Tasks, or present the last complete projection as fresh. Historical backend benchmarks do not establish graph snapshot capacity. Next steps: 1. Keep released tags and package bytes immutable. HyperCarrier adopts a version through its own composition change. 2. Decide whether graph persistence needs an append-only transaction store and exact Coordination publication outbox. 3. Measure the graph snapshot path before making a Worker-capacity claim. 4. Keep malformed-event diagnostics distinct from normal structural Task events; structural creation, assignment, status, and relation events now sync without narrative evidence. 5. Add payload-free outer-operation trace correlation before the representative performance epoch. 6. Benchmark snapshot and update views at 1, 20, and 60 Tasks, both idle and under concurrent writes. These workload points are not public count limits. 7. Keep stable Workers bound when low-latency repeated work matters. The separate [`worker-ensure-concurrency.md`](../projects/worker-ensure-concurrency.md) context defers batched sibling-launch optimization for later design. Add public Pi phase tracing before another cold-start optimization. 8. Do not add generic warm capacity, a reusable Pi Session, a Node compile cache, a Bun bundle, or Worker resource exclusions. A future strict 100 ms new-Worker SLO needs a separately shaped one-use sealed launcher with a profile digest, CAS reservation, activation identity, exact fences, destroy-on-outcome behavior, lost-actuation reconciliation, and measured stockout and replenishment distributions. ## Verification probes and fake drift The v3.1 simulator models Herdr, Pi, Linux, and filesystem behaviour with fakes. Each fake cites a probe fixture. The [simulation plan](../journal/2026-10-12-deterministic-simulation-verification.md#fake-drift-control) owns the fake list. Probe policy (owner decision D3=B, 2026-10-13): - A refuted real-world probe blocks a release only when a safety property depends on the faked assumption. - Otherwise a refuted probe blocks changes to that fake. The docs mark the assumption unverified. Platform status: - macOS: probes A1–A6 cover their recorded versions and paths. A8 is inconclusive. - Linux: probes A7 and A9 hold on Ubuntu 24.04, kernel 6.8, ext4 ([journal](../journal/2026-10-13-linux-host-probes.md)). A9 covers process crash only; host-crash durability is unclaimed. A full Linux Team with real Pi and Herdr has not run. - macOS: A9 holds for process crash on APFS. The helper has no PID-reuse probe. ## Test lanes `npm test` is fast and non-exhaustive; `test:exhaustive-only` is its CI complement, `test:full` runs everything, and `test:lanes` verifies closure. Use `test:external` for external runtime diagnostics, `qa:agent-surface` for the agent-surface artifact, and `qa:tool-results` for receipt QA. CI runs it, `test:exhaustive-only`, typecheck, and package verification once per source tree as parallel shards (fast lane on Node 22/24, exhaustive on Node 24); a tree that already passed is skipped, so the release tag reuses main's result and publish only verifies and publishes the package.