pi-session-orchestrator 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Jadczyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,307 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/Pi-extension-0ea5e9?style=flat-square" alt="Pi extension" />
+  <img src="https://img.shields.io/badge/coordination-explicit-18181b?style=flat-square" alt="Explicit coordination" />
+  <img src="https://img.shields.io/badge/session%20depth-max%202-22c55e?style=flat-square" alt="Maximum session depth two" />
+</p>
+
+<p align="center">
+  <img src="./assets/pi-session-orchestrator-thumbnail-pi-sessions.png" width="720" alt="Pi sessions coordinated through a root and domain hierarchy" />
+</p>
+
+<h1 align="center">Pi Session Orchestrator</h1>
+
+<p align="center">
+  Durable, explicit coordination for independently running Pi sessions.<br />
+  Keep focused work focused while preserving ownership, context boundaries, and human authority.
+</p>
+
+<p align="center">
+  <a href="#why">Why</a> ·
+  <a href="#coordination-model">Coordination model</a> ·
+  <a href="#use">Use</a> ·
+  <a href="#safety-boundaries">Safety</a> ·
+  <a href="docs/README.md">Documentation</a> ·
+  <a href="https://github.com/davidjadczyk/pi-session-orchestrator/blob/main/CONTRIBUTING.md">Contributing</a> ·
+  <a href="https://github.com/davidjadczyk/pi-session-orchestrator/blob/main/CODE_OF_CONDUCT.md">Code of Conduct</a> ·
+  <a href="docs/release-version-preparation.md">Release preparation</a>
+</p>
+
+---
+
+`pi-session-orchestrator` is a local coordination layer for existing Pi sessions. It records explicit assignments, injects concise role context, and keeps handoffs inspectable across reloads and resumes.
+
+It does **not** spawn sessions, create worktrees, merge changes, or replace Pi, Gentle Pi, OpenSpec/SDD, Orca, `pi-subagents`, or [`pi-intercom`](./docs/pi-intercom.md). `pi-intercom` is an optional companion transport, not a package dependency.
+
+## Why
+
+Large work often needs two things that conflict:
+
+- a session that retains the broad view across repositories, features, and worktrees;
+- sessions that stay concentrated on one bounded outcome.
+
+This extension separates those responsibilities without inventing authority. Every managed relationship is explicit, durable, and bound to a canonical repository/worktree identity.
+
+| Without coordination state | With `pi-session-orchestrator` |
+| --- | --- |
+| A session tree or working directory implies a relationship. | Assignment, role, scope, and binding are recorded explicitly. |
+| Focused work accumulates cross-cutting context. | Coordinators route cross-boundary decisions; focused sessions retain narrow context. |
+| “Done” can mean an unowned result. | A handoff is durable evidence awaiting explicit acceptance or return. |
+| A footer can be mistaken for authority. | The footer is display-only; persisted assignment state remains authoritative. |
+
+## Coordination model
+
+The hierarchy is deliberately small and explicit. Git repository and worktree topology limits *where* a session may operate; it never infers *who* coordinates whom.
+
+```mermaid
+flowchart TD
+    root["🧭 Root coordinator<br/>Cross-repository and integration decisions"]
+    direct["🎯 Focused session<br/>Direct bounded work"]
+    domain["🧭 Domain coordinator<br/>Delegated repository or subsystem"]
+    coreA["🎯 Focused session<br/>Bounded Core work"]
+    coreB["🎯 Focused session<br/>Tests or verification"]
+    human(["Human authority<br/>Product, cost, security, destructive decisions"])
+
+    root -->|direct assignment| direct
+    root -->|delegated boundary| domain
+    domain -->|focused assignment| coreA
+    domain -->|focused assignment| coreB
+    root -. consequential decision .-> human
+    domain -. cross-boundary decision .-> root
+    direct -. local blocker or decision .-> root
+    coreA -. local blocker or decision .-> domain
+
+    classDef coordinator fill:#0e7490,color:#fff,stroke:#155e75;
+    classDef focused fill:#334155,color:#fff,stroke:#1e293b;
+    classDef human fill:#4d7c0f,color:#fff,stroke:#3f6212;
+    class root,domain coordinator;
+    class direct,coreA,coreB focused;
+    class human human;
+```
+
+| Role | Owns | May create managed children |
+| --- | --- | --- |
+| **Root coordinator** | Cross-feature, cross-repository, and integration decisions. | Domain coordinators or direct focused sessions. |
+| **Domain coordinator** | A delegated repository or subsystem boundary. | Focused sessions only. |
+| **Focused session** | One bounded objective, its evidence, and its handoff. | None. |
+| **Unmanaged session** | Normal Pi behavior. | Outside this extension. |
+
+### Hard limits
+
+```text
+root coordinator → domain coordinator → focused session
+```
+
+- The maximum managed depth is two edges.
+- Root coordinators may assign focused sessions directly.
+- Domain coordinators cannot create another domain coordinator.
+- Focused sessions cannot create managed children.
+- Every relationship is explicitly attached and validated against the active repository/worktree binding.
+
+## What it supports
+
+| Capability | What it provides |
+| --- | --- |
+| **Explicit assignment** | Durable coordinator, target-session, role, objective, allowed-scope, and canonical-binding records. |
+| **Explicit opt-in delegation baseline** | A concise named additive prompt section permits small known work inline; requires an explicit durable assignment for orchestration/delegation; and directs oversized work to fast focused delegation. |
+| **Role-aware context** | A separate concise named role section appears after an explicit durable transition. |
+| **Bounded hierarchy** | Root, domain, and focused roles with a hard depth limit. |
+| **Durable lifecycle** | Assignment state and handoff evidence survive reload and resume. |
+| **Decision routing** | Typed progress, blocker, decision-request, handoff, and review-result records. |
+| **Display-only status** | Compact footer status derived from persisted state, never from UI state or inference. |
+| **Unmanaged fallback** | Sessions without a valid explicit attachment receive only the universal baseline, no role context, and no footer. |
+
+### What it deliberately does not do
+
+- Infer relationships from conversation text, a session tree, a repository, or a worktree.
+- Replace `pi-intercom` transport, generic messaging, or Pi subagent supervision.
+- Transfer RDD lineages between sessions.
+- Authorize edits, commits, pushes, reviews, merges, deployments, or cleanup.
+- Create processes, sessions, branches, or worktrees automatically.
+- Support managed hierarchies deeper than root → domain → focused.
+
+## Install and discover
+
+The published package is discoverable in the Pi package gallery through the `pi-package` keyword. Its `pi.extensions` manifest points Pi at `./src/index.ts`, while the gallery image is hosted from the public `main` branch.
+
+After a release, install it in Pi with:
+
+```text
+pi install npm:pi-session-orchestrator
+```
+
+For local development, install dependencies and run the extension through Pi from this repository:
+
+```bash
+npm install
+npm test
+```
+
+Release preparation and the protected-branch publishing procedure are documented in [Release and version preparation](docs/release-version-preparation.md).
+
+### Agent control plane
+
+Agents use two narrow tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `orchestrator_status` | Read the current role, footer, pending attachment, direct assignments, and valid next context. |
+| `orchestrator_update` | Explicitly register, adopt existing sessions, attach, transition lifecycle, request a decision, submit a handoff, settle, or end an assignment. |
+| `orchestrator_ledger` | Read a bounded per-root ledger of typed assignments, events, handoffs, and presence for explicit analysis. |
+
+The universal baseline permits small, known work to remain inline. It never infers an orchestrator from a session creation, conversation, repository, or worktree; orchestration or delegation requires an explicit durable assignment. A successful update returns the state delta immediately; role-specific prompt context applies on the next model run.
+
+### User-visible orchestration events
+
+The extension projects only explicit durable mutations as subtle UI event cards: coordinator registration, assignment lifecycle changes, handoffs, blockers, decision requests, and effective presence transitions. Repeated unchanged presence observations do not create events. Cards are custom session entries excluded from LLM context; when that renderer is unavailable, Pi's widget/notification UI is used without injecting event prose into prompts. The footer remains assignment-derived, so a registered coordinator with no matching assignment still shows `Root · 0 children`.
+
+If the actual situation is an existing focused session that has not been assigned, repair it from the coordinator session instead of relying on a session tree or prompt text:
+
+```text
+orchestrator_update({
+  operation: "assign-existing",
+  assignments: [{ sessionId: "<focused-session-uuid>", role: "focused-session", objective: "<bounded objective>", allowedScope: "<allowed scope>" }]
+})
+```
+
+Then, in the focused session, validate its binding and run `orchestrator_update({ operation: "attach", assignmentId: "<assignment-id>" })`, followed by `orchestrator_update({ operation: "start" })` when work begins. No generic Pi subagent, process, session, repository, worktree, or prompt observation creates an orchestration event or relationship.
+
+### 1. Register a root coordinator
+
+An agent records the current session deliberately:
+
+```text
+orchestrator_update({ operation: "register-root" })
+```
+
+The equivalent human recovery command remains available:
+
+```text
+/orchestrator coordinator
+```
+
+### 2. Adopt existing sessions explicitly
+
+After Pi, Orca, or a human creates a session through its normal mechanism, a root can adopt one or more known session IDs in one atomic update. Both `orchestrator_update({ operation: "assign-existing" })` and `/orchestrator assign` require a full canonical Pi session UUID; abbreviated display IDs are rejected. Optional `worktree` values bind each target to its own canonical Git worktree.
+
+```text
+orchestrator_update({
+  operation: "assign-existing",
+  assignments: [
+    { sessionId: "11111111-1111-4111-8111-111111111111", role: "focused-session", objective: "Implement the bounded UI change", allowedScope: "src/ui/**", worktree: "/repo/ui" },
+    { sessionId: "22222222-2222-4222-8222-222222222222", role: "domain-coordinator", objective: "Coordinate Core migration", allowedScope: "core/**", worktree: "/repo/core" }
+  ]
+})
+```
+
+Each target remains unmanaged until it validates and accepts its own assignment:
+
+```text
+orchestrator_status()
+orchestrator_update({ operation: "attach", assignmentId: "<assignment-id>" })
+orchestrator_update({ operation: "start" })
+```
+
+A domain coordinator registers itself after attachment, then may adopt focused sessions only. The human `/orchestrator assign` and `/orchestrator attach` commands remain available for manual bootstrap and recovery.
+
+### 3. Work, hand off, and settle explicitly
+
+Focused work starts and submits its bounded outcome:
+
+```text
+/orchestrator start
+/orchestrator handoff {"outcome":"Implemented validation","changedSurfaces":["src/validation.ts"],"checks":["npm test"],"risks":[]}
+```
+
+The coordinating session explicitly accepts or returns the handoff:
+
+```text
+/orchestrator accept <assignment-id>
+/orchestrator return <assignment-id> <reason>
+```
+
+A handoff is coordination evidence only. It never authorizes delivery.
+
+## Decision routing
+
+Do not use the parent as a progress relay. Focused sessions should work independently until a meaningful boundary is reached.
+
+| Situation | Route |
+| --- | --- |
+| Routine implementation choice inside the assigned scope | Decide locally using repository evidence and governing instructions. |
+| Local blocker, dependency, scope conflict, or sibling coordination | Ask the immediate coordinator. |
+| Cross-feature, cross-repository, or integration decision | Route to the root coordinator. |
+| Product priority, cost, security, secret, destructive, or other human-authority decision | Ask the human directly when governing policy requires it. |
+| Coordinator unavailable and waiting creates material risk | Escalate directly to the human with the blocked action and evidence. |
+
+[`pi-intercom`](./docs/pi-intercom.md) can remain the optional live transport. This extension owns the typed orchestration record, not a second messaging system, and does not depend on `pi-intercom`.
+
+## Lifecycle and handoffs
+
+```mermaid
+stateDiagram-v2
+    [*] --> created
+    created --> attached: target validates binding
+    attached --> active: explicit start
+    active --> handoff_submitted: submit outcome and evidence
+    handoff_submitted --> accepted: coordinator accepts
+    handoff_submitted --> returned: coordinator returns with reason
+    active --> blocked: dependency or decision required
+    active --> abandoned: explicit discontinuation
+    handoff_submitted --> blocked: explicit follow-up required
+```
+
+| State | Meaning |
+| --- | --- |
+| `created` | A coordinator recorded an assignment. |
+| `attached` | The target session validated its repository/worktree binding. |
+| `active` | The bounded objective is in progress. |
+| `handoff-submitted` | Immutable outcome evidence awaits coordinator disposition. |
+| `accepted` / `returned` | The coordinator accepted the outcome or returned it with a reason. |
+| `blocked` / `abandoned` | Evidence is preserved and explicit follow-up is required. |
+
+## Prompt context and footer
+
+Prompt injection is additive. Every session receives a concise named universal baseline that advertises explicit coordination tools and forbids inferred roles. Managed sessions additionally receive a named role section; neither section replaces the full system prompt or overrides higher-authority Pi and project instructions.
+
+| Session | Prompt context | Footer |
+| --- | --- | --- |
+| Root coordinator | Direct active assignments and coordination obligations. | `🧭 Root coordinator · N focused` |
+| Domain coordinator | Direct local assignments and delegated-boundary obligations. | `🧭 Domain coordinator · N focused` |
+| Focused session | Parent identity, objective, scope, binding, escalation rules, and handoff format. | `🎯 Focused session` |
+| Unmanaged | Universal coordination baseline only. | None. |
+
+The root footer aggregates active focused sessions from direct assignments and domain descendants. It intentionally provides one count rather than a complex hierarchy breakdown.
+
+For the exact injection contract, see [`docs/prompt-injection.md`](./docs/prompt-injection.md). The [documentation index](./docs/README.md) links stable coordination and operational references, contributor guidance, optional transport, the exploratory decision model, and local [release/version preparation](./docs/release-version-preparation.md).
+
+## Safety boundaries
+
+- One writer owns one writable checkout at a time.
+- A role relationship narrows coordination context; it does not grant operational authority.
+- Attachment rejects a mismatched repository/worktree binding.
+- RDD ownership remains with the session that opened the lineage; it cannot transfer through a handoff.
+- A message delivery acknowledgement is not acceptance, completion, or ownership transfer.
+- Unmanaged sessions retain normal Pi behavior.
+
+## Development
+
+```bash
+npm test
+npm run build
+```
+
+The test suite covers canonical Git binding resolution, explicit attachment, lifecycle persistence, role boundaries, additive prompt composition, unmanaged fallback, aggregate footer behavior, documentation/version synchronization, and package-boundary verification.
+
+### Command aliases and issue forms
+
+The compatibility `/orchestrator <action>` command remains available. Its discoverable aliases are `/orchestrator:coordinator`, `:assign`, `:attach`, `:start`, `:handoff`, `:accept`, `:return`, `:decision`, `:block`, `:abandon`, and `:status`.
+
+Use the repository's [bug report](https://github.com/davidjadczyk/pi-session-orchestrator/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) or [feature request](https://github.com/davidjadczyk/pi-session-orchestrator/blob/main/.github/ISSUE_TEMPLATE/feature_request.yml) form for public reports. Sanitize credentials, private paths, and session transcripts.
+
+## Operational recovery and ledger
+
+Coordinator footers count current children rather than only working sessions: `working` means active execution, `ready` means attached and able to begin, `pending` means an invitation awaits attachment, and `attention` means a handoff or blocker needs action. A pending target sees `⏳ Pending focused assignment` and an additive attachment notice; it is never auto-attached or promoted.
+
+Session presence is separate from assignment role. Reloaded, suspended, and stale observations help a coordinator decide whether to retain, restore, release, or abandon work, but shutdown never detaches, deletes, or promotes a session. Presence becomes `stale` only when no observation has occurred for 30 minutes; this is derived at read time and starts no background timer. Restore a known session with `pi --session <id>`; use `/resume` or `pi -r` to browse the picker.
+
+`orchestrator_ledger` is a bounded, read-only per-root view derived from typed assignments, lifecycle events, handoffs, and presence. Every returned collection is capped by the requested limit and includes `total`, `returned`, and `truncated` metadata. It keeps structured objectives, decisions, and handoff evidence, not Pi or `pi-intercom` transcripts. Future analysis may join a stored transport reference with the original message only when explicitly requested and authorized.

package/docs/README.md

@@ -0,0 +1,18 @@
+# Documentation index
+
+This index separates stable, current behavior from exploratory material and local release preparation.
+
+## Stable documentation
+
+- [Coordination model](reference/coordination-model.md) — explicit durable roles, assignments, and bounded hierarchy.
+- [Operational boundaries](reference/operational-boundaries.md) — local state, authority limits, and what the extension never performs.
+- [Prompt injection and context](prompt-injection.md) — additive context, precedence, and explicit delegation guidance.
+- [Contributor guide](../CONTRIBUTING.md) — local development and validation.
+- [Optional pi-intercom companion](pi-intercom.md) — transport relationship; `pi-intercom` is not a package dependency.
+- [Release and version preparation](release-version-preparation.md) — local SemVer decisions and validation only.
+
+## Exploratory documentation
+
+- [Fast decision model](reference/fast-decision-model.md) — **Exploratory**; not a runtime contract or delivery promise.
+
+See the [reference index](reference/README.md) for the stable/exploratory reference split.

package/docs/pi-intercom.md

@@ -0,0 +1,7 @@
+# Optional pi-intercom companion
+
+**Status: Stable integration boundary.**
+
+`pi-intercom` may provide live message transport between independently running sessions. `pi-session-orchestrator` records explicit assignments, lifecycle events, handoffs, and optional transport references; it does not deliver messages or retain message transcripts.
+
+`pi-intercom` is optional and is not a dependency of this package. Install and configure it independently when live transport is wanted. Its availability never creates a coordinator role, a managed assignment, operational authority, or delivery authority.

package/docs/prompt-injection.md

@@ -0,0 +1,52 @@
+# Prompt injection contract
+
+When `pi-session-orchestrator` is active, it injects a concise universal coordination baseline before each model run. When a session has explicit durable managed state, it also injects a concise role-specific section. Neither section is a second workflow policy or a source of authority.
+
+## What users should configure
+
+Users do **not** need to copy role or session context into `APPEND_SYSTEM.md`, `AGENTS.md`, or a custom system prompt when the extension is active. Keep durable, always-applicable policy in those normal locations. The extension supplies the changing root-coordinator, domain-coordinator, or focused-session facts from its managed assignment state.
+
+## Prompt composition and precedence
+
+A prompt has four complementary inputs:
+
+1. **Always-on baseline policy** supplies stable safety, authority, and general operating rules.
+2. **Extension-injected universal baseline** advertises explicit managed coordination and its narrow control-plane tools.
+3. **Extension-injected role context** supplies current managed role and assignment facts only after an explicit durable transition.
+4. **Repository/project instructions** supply repository-local conventions, commands, and delivery constraints.
+
+The extension sections are factual and additive. They cannot override higher-authority system policy or repository/project instructions. An assignment may narrow the work a focused session performs, but it does not authorize actions that the governing policy or project instructions prohibit. If instructions conflict, follow the normal instruction hierarchy and the more restrictive applicable constraint.
+
+Prompt composition is additive: this extension injects only its own named structured section and never replaces the whole system prompt. Later sections and sections owned by other extensions must remain intact.
+
+## Universal coordination baseline
+
+Every active extension session receives a named baseline that says small, known work may remain inline; managed multi-session coordination is available only through an explicit durable assignment; and roles are never inferred from conversation, repository, or session creation. `orchestrator_status` reads state and `orchestrator_update` records explicit state transitions. When work outgrows its bounded scope, record an assignment and use fast focused delegation rather than widening a session's context. Keep overarching coordination topics with coordinators and implementation detail with focused sessions; do not dump either across that boundary. Session creation and `pi-intercom` messaging remain separate concerns, and the extension transfers neither authority nor delivery authority.
+
+This resolves the bootstrap problem: an unmanaged session knows how to enter explicit coordination without being falsely treated as a coordinator or focused session.
+
+## Role-specific facts
+
+For a root coordinator, the extension injects its canonical session identity, direct active assignments and lifecycle states, and its cross-boundary coordination and handoff obligations.
+
+For a domain coordinator, it injects the same concise local coordination facts for its delegated boundary. It may coordinate focused sessions only.
+
+For a focused session, it injects the parent/coordinator session ID, objective, allowed scope, canonical repository/worktree binding, escalation rules, and compact handoff format. It cannot create managed children. It retains implementation detail locally and escalates oversized work rather than absorbing broader coordination concerns.
+
+The extension injects only the facts needed for that role and turn. A root footer may aggregate active focused descendants for display, but coordinator prompt context remains limited to direct assignments. The extension does not inject a full orchestration philosophy, unrelated assignment details, repository instructions, conversation history, secrets, or unsupported workflow state. Unknown or unavailable assignment data is omitted rather than invented.
+
+## Pending assignments and operational recovery
+
+A created assignment does not confer a managed role. When a target session ID has a pending assignment, the extension may inject a concise named attachment notice and show a pending footer so the target can validate its own binding and attach explicitly. Coordinators see operational child buckets: working, ready, pending, and attention. Session presence is recorded separately from assignment role; it becomes `stale` only after 30 minutes without an observation, and shutdown or stale presence never auto-detaches, promotes, or deletes a session. Recovery guidance is contextual: `pi --session <id>` restores a known session, while `/resume` or `pi -r` opens the picker.
+
+`orchestrator_ledger` exposes a bounded read-only view derived from typed orchestration state. Its assignments, events, handoffs, and presence collections are each capped by the requested limit and report `total`, `returned`, and `truncated` metadata. It retains structured goals, decisions, handoffs, timestamps, and optional transport references, but never copies Pi or `pi-intercom` transcripts into the ledger or prompt.
+
+## Unmanaged fallback
+
+A session is unmanaged unless it explicitly attaches to a matching managed assignment. While the extension is active, an unmanaged session receives the universal baseline but no role/session section and no footer. If the extension is inactive or unavailable, it injects nothing. The extension makes no role inference from conversation text, working directory, or a session tree; the session otherwise continues with its normal Pi, project, and user-provided prompt configuration.
+
+## Tool-driven bootstrap and adoption
+
+`orchestrator_status` returns the current role, footer, pending attachment, direct assignments, and next prompt-context state. `orchestrator_update` records explicit `register-root`, `assign-existing`, `attach`, lifecycle, handoff, settlement, and terminal transitions.
+
+A root may atomically adopt existing known sessions in an `assign-existing` batch. Both `orchestrator_update({ operation: "assign-existing" })` and `/orchestrator assign` require full canonical Pi session UUIDs; abbreviated display IDs are rejected. Assignment creation never creates a session or worktree. Each target remains unmanaged until it explicitly attaches from its own matching canonical Git worktree. A successful transition reports the new state immediately; role-specific injection begins on the next model run.

package/docs/reference/README.md

@@ -0,0 +1,14 @@
+# Reference
+
+Reference pages separate stable, current behavior from exploration.
+
+## Stable
+
+- [Coordination model](coordination-model.md) — **Stable current behavior**.
+- [Operational boundaries](operational-boundaries.md) — **Stable current behavior**.
+
+## Exploratory
+
+- [Fast decision model](fast-decision-model.md) — **Exploratory**, not a runtime contract.
+
+For prompt composition, contributor guidance, optional transport, and release preparation, use the [documentation index](../README.md).

package/docs/reference/coordination-model.md

@@ -0,0 +1,9 @@
+# Coordination model
+
+**Status: Current behavior.**
+
+The extension records explicit coordinator and focused-session roles, assignments, canonical repository/worktree bindings, lifecycle transitions, handoffs, and typed decisions. Relationships are not inferred from conversation, session topology, repository location, or worktree location.
+
+Managed depth is limited to root coordinator → domain coordinator → focused session. Unmanaged sessions retain normal Pi behavior. Agent-callable `orchestrator_*` tools are the normal automated control plane; human `/orchestrator` commands provide direct operation and recovery.
+
+Each assignment carries a durable scope revision (legacy state hydrates revision `1`). A focused session can use `propose-scope-change` with its current revision, a narrow requested scope, a reason, and evidence. Only the explicitly assigned coordinator can approve that current proposal; approval updates the assignment and increments the revision. A focused session may also record `approve-scope-change-human`, which updates the scope and revision immediately and creates a pending coordinator reconciliation obligation. Reconciliation acknowledges the change and does not approve it a second time. Stale proposals or revisions fail closed before state is written. These controls do not grant filesystem, worktree, session-management, delivery, or Git authority.

package/docs/reference/fast-decision-model.md

@@ -0,0 +1,23 @@
+# Fast decision model
+
+**Status: Exploratory.** This brief is a Jev/fast-decision-model exploration, not a runtime commitment or delivery promise.
+
+## Intent
+
+Explore a compact way to frame routine decisions while preserving explicit ownership, evidence, and human authority for consequential choices.
+
+## Candidate decision flow
+
+1. State the decision and bounded scope.
+2. Gather local evidence and list constraints.
+3. Record options, recommendation, and reversible next step.
+4. Escalate product, security, cost, destructive, or remote-state choices.
+5. Record the outcome and evidence for later review.
+
+## Open questions
+
+- Which decision classes benefit from a shorter template?
+- How should uncertainty and expiry be represented?
+- What evidence threshold is useful without creating a new runtime contract?
+
+This page is exploratory only. It is not a runtime commitment, API specification, authorization mechanism, or promise of delivery.

package/docs/reference/operational-boundaries.md

@@ -0,0 +1,7 @@
+# Operational boundaries
+
+**Status: Current behavior.**
+
+The extension records coordination state and provides additive prompt context and display-only status. It does not create sessions, branches, worktrees, processes, releases, commits, pushes, merges, deployments, or publication actions. A handoff is evidence and never delivery authorization.
+
+Human product, security, cost, destructive, credential, and remote-state decisions remain outside the extension. State is local and explicit; the compatibility `/orchestrator <action>` command and namespaced aliases use the same command implementation.

package/docs/release-version-preparation.md

@@ -0,0 +1,55 @@
+# Release and version preparation
+
+Use this guide to prepare a local candidate. It does not authorize delivery or run npm publishing locally.
+
+## Choose the version
+
+Follow SemVer:
+
+- **Major:** incompatible public API, documented behavior, or packaging-contract change.
+- **Minor:** backward-compatible user-visible capability or additive documented contract.
+- **Patch:** backward-compatible bug fix or documentation correction with no new capability.
+- **Before 1.0:** treat incompatible public-contract changes as minor; use patch for compatible fixes. State the compatibility impact explicitly.
+
+Version `0.2.0` is a minor release because it adds user-visible explicit delegation guidance and packaged documentation while preserving existing APIs and dependencies.
+
+## Pi installation and discovery
+
+- Keep `pi-package` in `package.json` keywords so the package gallery can discover the package.
+- Keep `pi.extensions` as the resource manifest for the extension entry point.
+- Keep the gallery image on the public `main` URL so the registry metadata remains stable:
+  `https://raw.githubusercontent.com/davidjadczyk/pi-session-orchestrator/main/assets/pi-session-orchestrator-thumbnail-pi-sessions.png`.
+- After publication, users install the package with `pi install npm:pi-session-orchestrator`.
+
+## Prepare locally
+
+1. Update `package.json` and the root `package-lock.json` to the same valid SemVer version.
+2. Keep Pi runtime packages, including `typebox`, in `peerDependencies` with `"*"`; retain development pins only for local type-checking and tests.
+3. Update package-facing documentation and its distribution allowlist.
+4. Run:
+
+   ```sh
+   npm test
+   npm run build
+   npm run verify-pack
+   npm pack --dry-run --json --ignore-scripts
+   ruby -e 'require "yaml"; ARGV.each { |path| YAML.safe_load_file(path) }' .github/workflows/ci.yml .github/ISSUE_TEMPLATE/bug_report.yml .github/ISSUE_TEMPLATE/feature_request.yml
+   git diff --check
+   git diff --cached --name-only
+   ```
+
+4. Inspect the dry-run package list and verify every README-linked package document is included.
+
+## Protected-branch release procedure
+
+1. Configure the repository externally with protected `main` as the default branch. Require pull requests and the repository's normal required checks before merging.
+2. Configure npm trusted publishing externally for `davidjadczyk/pi-session-orchestrator` using GitHub Actions, workflow file `.github/workflows/publish.yml`, and the public npm registry. The npm package settings, not this repository, store that trusted-publisher relationship.
+3. Merge the reviewed release to protected `main`, create an exact annotated tag such as `v0.2.0`, and push the tag through the normal authorized repository process.
+4. Manually dispatch **Publish package** from `main` with the exact tag. The workflow rejects non-`vSemVer` input, lightweight tags, tag/main divergence, version mismatches, and any run that is not based on remote `main`.
+5. The workflow runs `npm ci`, tests, build, package verification, and `npm pack --dry-run` before `npm publish --provenance` with GitHub OIDC. No npm token is stored in the repository or used for this release path.
+
+The external prerequisites are: protected `main` and its required checks, the annotated-tag push permission, and npm trusted-publisher configuration for this exact repository/workflow. Verify them in their respective systems before attempting a dispatch.
+
+## Delivery boundary
+
+Commits, pushes, tags, GitHub releases, remote Actions observation, and npm publishing each require separate authorization. Local preparation must never publish to npm, create a tag or release, dispatch the workflow, or change GitHub settings.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "pi-session-orchestrator",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Explicit, durable coordinator and focused-session state for Pi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidjadczyk/pi-session-orchestrator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/davidjadczyk/pi-session-orchestrator/issues"
+  },
+  "homepage": "https://github.com/davidjadczyk/pi-session-orchestrator",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "orchestration",
+    "session-coordination"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "assets/pi-session-orchestrator-thumbnail-pi-sessions.png",
+    "docs/"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/davidjadczyk/pi-session-orchestrator/main/assets/pi-session-orchestrator-thumbnail-pi-sessions.png"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "test": "node --test --import tsx test/*.test.ts",
+    "verify-pack": "node scripts/verify-pack.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@types/node": "22.10.10",
+    "tsx": "4.19.2",
+    "typebox": "1.3.7",
+    "typescript": "5.7.3"
+  }
+}

package/src/binding.ts

@@ -0,0 +1,50 @@
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+import type { CanonicalBinding } from "./model";
+
+function gitDirectory(worktree: string): string {
+  const dotGit = join(worktree, ".git");
+  const metadata = lstatSync(dotGit);
+  if (metadata.isDirectory()) return dotGit;
+  if (!metadata.isFile()) throw new Error("Git metadata is not a file or directory");
+
+  const match = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotGit, "utf8"));
+  if (!match) throw new Error("Git metadata file has no gitdir");
+  return isAbsolute(match[1]) ? match[1] : resolve(worktree, match[1]);
+}
+
+function worktreeFor(cwd: string): string {
+  let directory = realpathSync(cwd);
+  while (true) {
+    try {
+      gitDirectory(directory);
+      return directory;
+    } catch {
+      const parent = dirname(directory);
+      if (parent === directory) throw new Error("No Git worktree found");
+      directory = parent;
+    }
+  }
+}
+
+function commonGitDirectory(gitDir: string): string {
+  try {
+    return resolve(gitDir, readFileSync(join(gitDir, "commondir"), "utf8").trim());
+  } catch {
+    return gitDir;
+  }
+}
+
+/** Resolves canonical Git metadata from filesystem worktree metadata without spawning Git. */
+export function activeCanonicalBinding(cwd: string): CanonicalBinding {
+  try {
+    const worktree = worktreeFor(cwd);
+    return {
+      repository: realpathSync(commonGitDirectory(gitDirectory(worktree))),
+      worktree,
+    };
+  } catch {
+    throw new Error("A managed assignment requires an active Git repository/worktree binding");
+  }
+}