pi-session-orchestrator 0.2.0

package/src/index.ts

@@ -0,0 +1,311 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { activeCanonicalBinding } from "./binding";
+import type { OrchestrationEvent, PresenceStatus } from "./model";
+import { appendBaselineContext, appendPendingContext, appendRoleContext, footerStatus, pendingAssignmentContext, roleContext } from "./prompt";
+import { LocalStateStore } from "./state";
+import { isCanonicalSessionId, registerOrchestratorTools } from "./tools";
+
+const STATUS_KEY = "pi-session-orchestrator";
+const EVENT_ENTRY_TYPE = "pi-session-orchestrator-event";
+const EVENT_WIDGET_KEY = "pi-session-orchestrator-events";
+const MAX_RENDERED_EVENTS = 8;
+
+export function eventIndicatorLines(events: readonly OrchestrationEvent[]): string[] {
+  const lines = events.slice(0, MAX_RENDERED_EVENTS).map((event) => {
+    const action = event.action?.replaceAll("_", " ") ?? event.type.replaceAll("_", " ");
+    const summary = event.summary.replace(/[\r\n]+/g, " ").trim().slice(0, 120);
+    return `↳ orchestration · ${action}: ${summary}`;
+  });
+  if (events.length > MAX_RENDERED_EVENTS) lines.push(`↳ orchestration · ${events.length - MAX_RENDERED_EVENTS} more updates`);
+  return lines;
+}
+
+type EventPresentationContext = Pick<ExtensionContext, "ui" | "mode" | "hasUI" | "sessionManager">;
+type RenderComponent = { render(width: number): string[]; invalidate(): void };
+type EntryRendererRegistrar = (customType: string, renderer: (entry: { data?: unknown }, options: { expanded: boolean }, theme: { fg(color: string, text: string): string }) => RenderComponent | undefined) => void;
+type EntryAppender = (customType: string, data?: unknown) => void;
+
+function isEntryRendererRegistrar(value: unknown): value is EntryRendererRegistrar {
+  return typeof value === "function";
+}
+
+function isEntryAppender(value: unknown): value is EntryAppender {
+  return typeof value === "function";
+}
+
+function registerEventEntryRenderer(pi: ExtensionAPI): boolean {
+  const registrar = pi.registerEntryRenderer;
+  if (!isEntryRendererRegistrar(registrar)) return false;
+  registrar.call(pi, EVENT_ENTRY_TYPE, (entry, _options, theme) => {
+    const data = entry.data as { events?: unknown } | undefined;
+    const events = Array.isArray(data?.events) ? data.events.filter((event): event is OrchestrationEvent => (
+      typeof event === "object" && event !== null && typeof (event as OrchestrationEvent).summary === "string"
+    )) : [];
+    const lines = eventIndicatorLines(events);
+    return {
+      render: (width) => lines.map((line) => theme.fg("dim", line.slice(0, width))),
+      invalidate: () => undefined,
+    };
+  });
+  return true;
+}
+
+export function presentUnseenEvents(store: LocalStateStore, ctx: EventPresentationContext, pi?: ExtensionAPI): void {
+  // Test doubles and legacy callers may not expose Pi's run mode; do not consume a cursor without a render path.
+  if (ctx.mode === undefined && !ctx.hasUI) return;
+  let events: OrchestrationEvent[];
+  try {
+    events = store.consumeRelevantEvents(ctx.sessionManager.getSessionId(), MAX_RENDERED_EVENTS);
+  } catch {
+    return;
+  }
+  if (!events.length) return;
+
+  const lines = eventIndicatorLines(events);
+  const appender = pi?.appendEntry;
+  if (ctx.mode === "tui" && isEntryAppender(appender)) {
+    try {
+      appender.call(pi, EVENT_ENTRY_TYPE, { version: 1, events });
+      return;
+    } catch {
+      // Fall through to the supported widget/notification path.
+    }
+  }
+  if (ctx.mode === "tui") ctx.ui.setWidget(EVENT_WIDGET_KEY, lines, { placement: "aboveEditor" });
+  if (ctx.hasUI) ctx.ui.notify(`Orchestration: ${events.length} new update${events.length === 1 ? "" : "s"}.`, "info");
+}
+const COMMAND_HELP = `Usage:
+/orchestrator coordinator
+/orchestrator assign {"focusedSessionId":"...","role":"domain-coordinator|focused-session","objective":"...","allowedScope":"...","worktree":"optional target path"}
+/orchestrator attach <assignment-id>
+/orchestrator start
+/orchestrator handoff {"outcome":"...","changedSurfaces":[],"checks":[],"risks":[]}
+/orchestrator accept <assignment-id> [reason]
+/orchestrator return <assignment-id> <reason>
+/orchestrator decision {"summary":"...","options":["..."],"recommendation":"..."}
+/orchestrator propose-scope-change {"requestedScope":"...","scopeRevision":1,"reason":"...","evidence":["..."]}
+/orchestrator approve-scope-change {"assignmentId":"...","proposalId":"...","scopeRevision":1}
+/orchestrator approve-scope-change-human {"proposalId":"...","scopeRevision":1}
+/orchestrator reconcile-scope-change {"reconciliationId":"...","scopeRevision":2}
+/orchestrator block <reason>
+/orchestrator abandon <reason>
+/orchestrator status`;
+
+function sessionId(ctx: ExtensionCommandContext): string {
+  return ctx.sessionManager.getSessionId();
+}
+
+function objectArgument(args: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(args);
+  } catch {
+    throw new Error("Expected a valid JSON object");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("Expected a JSON object");
+  return parsed as Record<string, unknown>;
+}
+
+function text(value: unknown, field: string): string {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${field} must be a non-empty string`);
+  return value.trim();
+}
+
+function strings(value: unknown, field: string): string[] {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new Error(`${field} must be an array of strings`);
+  return value;
+}
+
+function integer(value: unknown, field: string): number {
+  if (!Number.isInteger(value) || (value as number) < 1) throw new Error(`${field} must be a positive integer`);
+  return value as number;
+}
+
+function assignmentRole(value: unknown): "domain-coordinator" | "focused-session" | undefined {
+  if (value === undefined) return undefined;
+  if (value === "domain-coordinator" || value === "focused-session") return value;
+  throw new Error("role must be domain-coordinator or focused-session");
+}
+
+export function presenceForSessionStart(reason: "startup" | "reload" | "new" | "resume" | "fork"): PresenceStatus {
+  return reason === "reload" ? "reloading" : "live";
+}
+
+export function presenceForSessionShutdown(reason: "quit" | "reload" | "new" | "resume" | "fork"): PresenceStatus {
+  return reason === "reload" ? "reloading" : "suspended";
+}
+
+function refreshStatus(store: LocalStateStore, ctx: { ui: { setStatus(key: string, text: string | undefined): void }; sessionManager: { getSessionId(): string } }): void {
+  try {
+    ctx.ui.setStatus(STATUS_KEY, footerStatus(store.read(), ctx.sessionManager.getSessionId()));
+  } catch {
+    // Corrupt or unavailable local state is deliberately unmanaged, never inferred.
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+  }
+}
+
+export async function runCommand(store: LocalStateStore, args: string, ctx: ExtensionCommandContext,
+  present: (ctx: EventPresentationContext) => void = (current) => presentUnseenEvents(store, current)): Promise<void> {
+  const [action = "", ...rest] = args.trim().split(/\s+/);
+  const remainder = rest.join(" ").trim();
+  const currentSessionId = sessionId(ctx);
+
+  try {
+    switch (action) {
+      case "coordinator":
+        store.registerCoordinator(currentSessionId);
+        ctx.ui.notify("Coordinator role recorded locally.", "info");
+        break;
+      case "assign": {
+        const input = objectArgument(remainder);
+        const focusedSessionId = text(input.focusedSessionId, "focusedSessionId");
+        if (!isCanonicalSessionId(focusedSessionId)) throw new Error("assign requires a full canonical Pi session ID");
+        const assignment = store.createAssignment({
+          coordinatorSessionId: currentSessionId,
+          focusedSessionId,
+          targetRole: assignmentRole(input.role),
+          binding: activeCanonicalBinding(typeof input.worktree === "string" ? text(input.worktree, "worktree") : ctx.cwd),
+          objective: text(input.objective, "objective"),
+          allowedScope: text(input.allowedScope, "allowedScope"),
+        });
+        ctx.ui.notify(`Assignment ${assignment.id} created; the ${assignment.targetRole} must attach explicitly.`, "info");
+        break;
+      }
+      case "attach": {
+        const assignment = store.attach(text(remainder, "assignment ID"), currentSessionId, activeCanonicalBinding(ctx.cwd));
+        ctx.ui.notify(`Attached to assignment ${assignment.id}.`, "info");
+        break;
+      }
+      case "start": {
+        const assignment = store.activate(currentSessionId);
+        ctx.ui.notify(`Assignment ${assignment.id} is active.`, "info");
+        break;
+      }
+      case "handoff": {
+        const input = objectArgument(remainder);
+        const handoff = store.submitHandoff(currentSessionId, {
+          outcome: text(input.outcome, "outcome"),
+          artifactIdentity: typeof input.artifactIdentity === "string" ? input.artifactIdentity : undefined,
+          changedSurfaces: strings(input.changedSurfaces, "changedSurfaces"),
+          checks: strings(input.checks, "checks"),
+          risks: strings(input.risks, "risks"),
+        });
+        ctx.ui.notify(`Handoff ${handoff.id} recorded locally; it does not authorize delivery.`, "info");
+        break;
+      }
+      case "accept":
+      case "return": {
+        const [assignmentId = "", ...reasonParts] = remainder.split(/\s+/);
+        const reason = reasonParts.join(" ").trim();
+        if (action === "return" && !reason) throw new Error("A return reason is required");
+        store.acceptOrReturn(currentSessionId, text(assignmentId, "assignment ID"), action === "accept" ? "accepted" : "returned", reason || undefined);
+        ctx.ui.notify(`Handoff ${action === "accept" ? "accepted" : "returned"}.`, "info");
+        break;
+      }
+      case "decision": {
+        const input = objectArgument(remainder);
+        store.decide(currentSessionId, text(input.summary, "summary"), input);
+        ctx.ui.notify("Decision request recorded locally; delivery remains a pi-intercom concern.", "info");
+        break;
+      }
+      case "propose-scope-change": {
+        const input = objectArgument(remainder);
+        const proposal = store.proposeScopeChange(currentSessionId, {
+          baseScopeRevision: integer(input.scopeRevision, "scopeRevision"),
+          requestedScope: text(input.requestedScope, "requestedScope"),
+          reason: text(input.reason, "reason"),
+          evidence: strings(input.evidence, "evidence"),
+        });
+        ctx.ui.notify(`Scope-change proposal ${proposal.id} recorded at revision ${proposal.baseScopeRevision}.`, "info");
+        break;
+      }
+      case "approve-scope-change": {
+        const input = objectArgument(remainder);
+        const assignment = store.approveScopeChange(currentSessionId, text(input.assignmentId, "assignmentId"), text(input.proposalId, "proposalId"), integer(input.scopeRevision, "scopeRevision"));
+        ctx.ui.notify(`Scope change approved; assignment is now at revision ${assignment.scopeRevision ?? 1}.`, "info");
+        break;
+      }
+      case "approve-scope-change-human": {
+        const input = objectArgument(remainder);
+        const assignment = store.approveScopeChangeAsHuman(currentSessionId, text(input.proposalId, "proposalId"), integer(input.scopeRevision, "scopeRevision"));
+        ctx.ui.notify(`Direct human scope approval recorded at revision ${assignment.scopeRevision ?? 1}; coordinator reconciliation is required.`, "info");
+        break;
+      }
+      case "reconcile-scope-change": {
+        const input = objectArgument(remainder);
+        store.reconcileScopeChange(currentSessionId, text(input.reconciliationId, "reconciliationId"), integer(input.scopeRevision, "scopeRevision"));
+        ctx.ui.notify("Direct-human scope change reconciled without a second approval.", "info");
+        break;
+      }
+      case "block":
+      case "abandon":
+        store.markTerminal(currentSessionId, action === "block" ? "blocked" : "abandoned", text(remainder, "reason"));
+        ctx.ui.notify(`Assignment marked ${action === "block" ? "blocked" : "abandoned"}.`, "info");
+        break;
+      case "status": {
+        const role = store.getRole(currentSessionId);
+        ctx.ui.notify(role.kind === "unmanaged" ? "Unmanaged session." : `${role.kind} session: ${currentSessionId}`, "info");
+        break;
+      }
+      default:
+        ctx.ui.notify(COMMAND_HELP, "info");
+        return;
+    }
+    present(ctx);
+    refreshStatus(store, ctx);
+  } catch (error: unknown) {
+    ctx.ui.notify(error instanceof Error ? error.message : "Orchestration command failed", "error");
+    refreshStatus(store, ctx);
+  }
+}
+
+const DISCOVERABLE_ACTIONS = [
+  "coordinator", "assign", "attach", "start", "handoff", "accept", "return", "decision", "propose-scope-change", "approve-scope-change", "approve-scope-change-human", "reconcile-scope-change", "block", "abandon", "status",
+] as const;
+
+function registerDiscoverableAliases(pi: ExtensionAPI, store: LocalStateStore,
+  present: (ctx: EventPresentationContext) => void): void {
+  for (const action of DISCOVERABLE_ACTIONS) {
+    pi.registerCommand(`orchestrator:${action}`, {
+      description: `Run /orchestrator ${action}`,
+      handler: (args, ctx) => runCommand(store, `${action} ${args}`.trim(), ctx, present),
+    });
+  }
+}
+
+export default function sessionOrchestratorExtension(pi: ExtensionAPI, store = new LocalStateStore()): void {
+  const entryRendererAvailable = registerEventEntryRenderer(pi);
+  const present = (ctx: EventPresentationContext) => presentUnseenEvents(store, ctx, entryRendererAvailable ? pi : undefined);
+
+  pi.registerCommand("orchestrator", {
+    description: "Explicit durable coordinator/focused assignment commands",
+    handler: (args, ctx) => runCommand(store, args, ctx, present),
+  });
+  registerDiscoverableAliases(pi, store, present);
+  registerOrchestratorTools(pi, store, present);
+
+  pi.on("session_start", (event, ctx) => {
+    store.observePresence(ctx.sessionManager.getSessionId(), presenceForSessionStart(event.reason));
+    present(ctx);
+    refreshStatus(store, ctx);
+  });
+  pi.on("session_shutdown", (event, ctx) => {
+    store.observePresence(ctx.sessionManager.getSessionId(), presenceForSessionShutdown(event.reason), event.reason);
+    present(ctx);
+  });
+  pi.on("before_agent_start", (_event, ctx) => {
+    store.observePresence(ctx.sessionManager.getSessionId(), "live");
+    present(ctx);
+    refreshStatus(store, ctx);
+    try {
+      const state = store.read();
+      const section = roleContext(state, ctx.sessionManager.getSessionId());
+      const pending = pendingAssignmentContext(state, ctx.sessionManager.getSessionId());
+      const systemPrompt = appendRoleContext(appendPendingContext(appendBaselineContext(ctx.getSystemPrompt()), pending), section);
+      return systemPrompt === ctx.getSystemPrompt() ? undefined : { systemPrompt };
+    } catch {
+      return undefined;
+    }
+  });
+}

package/src/model.ts

@@ -0,0 +1,164 @@
+export const ASSIGNMENT_STATUSES = [
+  "created",
+  "attached",
+  "active",
+  "handoff-submitted",
+  "accepted",
+  "returned",
+  "blocked",
+  "abandoned",
+] as const;
+
+export type AssignmentStatus = (typeof ASSIGNMENT_STATUSES)[number];
+export type EventType = "progress" | "blocker" | "decision_request" | "handoff" | "review_result";
+export type OrchestrationEventAction =
+  | "coordinator_registered"
+  | "assignment_created"
+  | "assignment_attached"
+  | "assignment_started"
+  | "handoff_submitted"
+  | "handoff_accepted"
+  | "handoff_returned"
+  | "assignment_blocked"
+  | "assignment_abandoned"
+  | "decision_requested"
+  | "scope_change_proposed"
+  | "scope_change_approved"
+  | "scope_change_human_approved"
+  | "scope_change_reconciled"
+  | "presence_changed";
+export type AssignmentRole = "domain-coordinator" | "focused-session";
+
+export interface CanonicalBinding {
+  repository: string;
+  worktree: string;
+}
+
+export interface Assignment {
+  id: string;
+  coordinatorSessionId: string;
+  focusedSessionId: string;
+  binding: CanonicalBinding;
+  objective: string;
+  allowedScope: string;
+  /** Revision of the durable allowed scope; legacy assignments hydrate as revision 1. */
+  scopeRevision?: number;
+  targetRole?: AssignmentRole;
+  status: AssignmentStatus;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface HandoffRecord {
+  id: string;
+  assignmentId: string;
+  submittedAt: string;
+  outcome: string;
+  artifactIdentity?: string;
+  changedSurfaces: string[];
+  checks: string[];
+  risks: string[];
+}
+
+export interface OrchestrationEvent {
+  id: string;
+  /** Empty for coordinator registration or an unassigned presence observation. */
+  assignmentId: string;
+  /** Set for session-scoped events such as registration and presence. */
+  sessionId?: string;
+  type: EventType;
+  /** Explicit mutation represented by this event; absent on legacy state entries. */
+  action?: OrchestrationEventAction;
+  /** Monotonic local ordering; absent on legacy state entries. */
+  sequence?: number;
+  createdAt: string;
+  summary: string;
+  nextAction?: string;
+  details?: Record<string, unknown>;
+}
+
+export interface EventCursor {
+  lastSequence: number;
+  eventIds: string[];
+}
+
+export type ScopeChangeProposalStatus = "pending" | "approved";
+export type ScopeChangeApprovalKind = "coordinator" | "direct-human";
+
+export interface ScopeChangeProposal {
+  id: string;
+  assignmentId: string;
+  requesterSessionId: string;
+  baseScopeRevision: number;
+  requestedScope: string;
+  reason: string;
+  evidence: string[];
+  status: ScopeChangeProposalStatus;
+  createdAt: string;
+  updatedAt: string;
+  approvalKind?: ScopeChangeApprovalKind;
+  approvedBy?: string;
+}
+
+export interface ScopeReconciliation {
+  id: string;
+  assignmentId: string;
+  scopeRevision: number;
+  requestedScope: string;
+  reason: string;
+  evidence: string[];
+  status: "pending" | "reconciled";
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Versioned extension state; the containing field remains optional for legacy files. */
+export interface ScopeChangeState {
+  version: 1;
+  proposals: ScopeChangeProposal[];
+  reconciliations: ScopeReconciliation[];
+}
+
+export type PresenceStatus = "live" | "reloading" | "suspended";
+
+export interface SessionPresence {
+  sessionId: string;
+  status: PresenceStatus;
+  lastSeenAt: string;
+  lastShutdownReason?: string;
+}
+
+export interface DurableState {
+  version: 1;
+  coordinators: string[];
+  assignments: Assignment[];
+  handoffs: HandoffRecord[];
+  events: OrchestrationEvent[];
+  presence?: SessionPresence[];
+  /** Optional fields keep state files written before event indicators readable. */
+  nextEventSequence?: number;
+  eventCursors?: Record<string, EventCursor>;
+  /** Hydrated on read for legacy state files and written after scope changes are used. */
+  scopeChanges?: ScopeChangeState;
+}
+
+export type SessionRole =
+  | { kind: "root-coordinator" }
+  | { kind: "domain-coordinator"; assignment: Assignment }
+  | { kind: "focused-session"; assignment: Assignment }
+  | { kind: "unmanaged" };
+
+export const EMPTY_STATE: DurableState = {
+  version: 1,
+  coordinators: [],
+  assignments: [],
+  handoffs: [],
+  events: [],
+  presence: [],
+  eventCursors: {},
+  scopeChanges: { version: 1, proposals: [], reconciliations: [] },
+};
+
+export function isTerminal(status: AssignmentStatus): boolean {
+  return ["accepted", "returned", "blocked", "abandoned"].includes(status);
+}

package/src/prompt.ts

@@ -0,0 +1,118 @@
+import type { Assignment, DurableState, SessionRole } from "./model";
+
+export const BASELINE_CONTEXT_MARKER = "## pi-session-orchestrator baseline";
+export const ROLE_CONTEXT_MARKER = "## pi-session-orchestrator role context";
+export const PENDING_CONTEXT_MARKER = "## pi-session-orchestrator pending assignment";
+
+export function baselineContext(): string {
+  return `${BASELINE_CONTEXT_MARKER}
+This extension supports explicit, durable coordination among existing Pi sessions. Small, known work may remain inline. Use orchestrator_status to inspect state and orchestrator_update to record transitions. Do not infer roles from conversation, repository topology, or session creation: orchestration or delegation requires an explicit durable assignment. When work becomes larger than its bounded scope, use fast focused delegation after recording that assignment. Keep coordinator topics with coordinators and focused implementation detail with focused sessions; do not dump either across that boundary. Session creation and pi-intercom messaging remain separate concerns; this extension neither creates sessions nor transfers authority or delivery authority.`;
+}
+
+export function appendBaselineContext(systemPrompt: string): string {
+  if (systemPrompt.includes(BASELINE_CONTEXT_MARKER)) return systemPrompt;
+  return `${systemPrompt}\n\n${baselineContext()}`;
+}
+
+function activeAssignments(state: DurableState, coordinatorSessionId: string): Assignment[] {
+  return state.assignments.filter((assignment) => assignment.coordinatorSessionId === coordinatorSessionId
+    && ["created", "attached", "active", "handoff-submitted"].includes(assignment.status));
+}
+
+function scopeRevision(assignment: Assignment): number {
+  return assignment.scopeRevision ?? 1;
+}
+
+function scopeObligations(state: DurableState, assignmentIds: Set<string>): string {
+  const scopeChanges = state.scopeChanges ?? { version: 1 as const, proposals: [], reconciliations: [] };
+  const proposals = scopeChanges.proposals.filter((proposal) => assignmentIds.has(proposal.assignmentId) && proposal.status === "pending");
+  const reconciliations = scopeChanges.reconciliations.filter((reconciliation) => assignmentIds.has(reconciliation.assignmentId) && reconciliation.status === "pending");
+  const parts: string[] = [];
+  if (proposals.length) parts.push(`pending proposals: ${proposals.map((proposal) => `${proposal.id} (revision ${proposal.baseScopeRevision})`).join(", ")}`);
+  if (reconciliations.length) parts.push(`reconciliation required: ${reconciliations.map((item) => `${item.id} (revision ${item.scopeRevision})`).join(", ")}`);
+  return parts.join("; ") || "none";
+}
+
+export function roleForState(state: DurableState, sessionId: string): SessionRole {
+  const assignment = [...state.assignments].reverse().find((item) => item.focusedSessionId === sessionId
+    && item.status !== "created");
+  if (assignment?.targetRole === "domain-coordinator") return { kind: "domain-coordinator", assignment };
+  if (assignment) return { kind: "focused-session", assignment };
+  return state.coordinators.includes(sessionId) ? { kind: "root-coordinator" } : { kind: "unmanaged" };
+}
+
+function childBuckets(state: DurableState, coordinatorSessionId: string): Record<string, number> {
+  const buckets: Record<string, number> = { children: 0, working: 0, ready: 0, pending: 0, attention: 0 };
+  for (const assignment of state.assignments.filter((item) => item.coordinatorSessionId === coordinatorSessionId)) {
+    if (assignment.targetRole === "domain-coordinator") {
+      const nested = childBuckets(state, assignment.focusedSessionId);
+      for (const [key, value] of Object.entries(nested)) buckets[key] += value;
+      continue;
+    }
+    if (["accepted", "returned", "abandoned"].includes(assignment.status)) continue;
+    buckets.children += 1;
+    if (assignment.status === "active") buckets.working += 1;
+    else if (assignment.status === "attached") buckets.ready += 1;
+    else if (assignment.status === "created") buckets.pending += 1;
+    else buckets.attention += 1;
+  }
+  return buckets;
+}
+
+export function pendingAssignmentContext(state: DurableState, sessionId: string): string | undefined {
+  const assignment = state.assignments.find((item) => item.focusedSessionId === sessionId && item.status === "created");
+  return assignment ? `${PENDING_CONTEXT_MARKER}
+A pending ${assignment.targetRole ?? "focused-session"} assignment awaits your explicit attachment. Coordinator ID: ${assignment.coordinatorSessionId}. Objective: ${assignment.objective}. Validate your binding, then use orchestrator_update with operation attach and assignmentId ${assignment.id}.` : undefined;
+}
+
+export function appendPendingContext(systemPrompt: string, section: string | undefined): string {
+  if (!section || systemPrompt.includes(PENDING_CONTEXT_MARKER)) return systemPrompt;
+  return `${systemPrompt}\n\n${section}`;
+}
+
+export function roleContext(state: DurableState, sessionId: string): string | undefined {
+  const role = roleForState(state, sessionId);
+  if (role.kind === "unmanaged") return undefined;
+
+  if (role.kind === "root-coordinator" || role.kind === "domain-coordinator") {
+    const assignments = activeAssignments(state, sessionId)
+      .map((assignment) => `- ${assignment.id}: ${assignment.targetRole ?? "focused-session"} ${assignment.focusedSessionId}; ${assignment.status}; revision ${scopeRevision(assignment)}; ${assignment.objective}`)
+      .join("\n") || "- none";
+    const assignmentIds = new Set(activeAssignments(state, sessionId).map((assignment) => assignment.id));
+    const obligations = scopeObligations(state, assignmentIds);
+    const roleName = role.kind === "root-coordinator" ? "root coordinator" : "domain coordinator";
+    return `${ROLE_CONTEXT_MARKER}
+Role: ${roleName}. Session ID: ${sessionId}.
+Active assignment summaries:
+${assignments}
+Route cross-session decisions, preserve ownership boundaries, and explicitly accept or return handoffs. Scope-change obligations: ${obligations}. Approve only current proposals within the assigned boundary; reconcile direct-human changes without a second approval.
+Keep overarching coordination topics here; do not push them into focused-session context or pull focused implementation detail into this context. This does not replace the governing orchestration framework or transfer authority.`;
+  }
+
+  const { assignment } = role;
+  const obligations = scopeObligations(state, new Set([assignment.id]));
+  return `${ROLE_CONTEXT_MARKER}
+Role: focused session. Coordinator ID: ${assignment.coordinatorSessionId}. Assignment: ${assignment.id} (${assignment.status}).
+Objective: ${assignment.objective}
+Allowed scope: ${assignment.allowedScope}
+Scope revision: ${scopeRevision(assignment)}
+Scope-change obligations: ${obligations}
+Binding: repository ${assignment.binding.repository}; worktree ${assignment.binding.worktree}.
+Stay within scope; independently report blockers, dependencies, scope changes, and decisions. If the issue grows beyond this bounded scope, promptly ask the coordinator for explicit re-scoping or delegation; use orchestrator_update operation propose-scope-change with the current scopeRevision, a narrow requestedScope, reason, and evidence; do not absorb the change silently. Keep focused implementation detail here; do not take on overarching coordinator topics. Handoff format: outcome, artifact identity, changed surfaces, checks, risks. A handoff never authorizes delivery.`;
+}
+
+export function appendRoleContext(systemPrompt: string, section: string | undefined): string {
+  if (!section || systemPrompt.includes(ROLE_CONTEXT_MARKER)) return systemPrompt;
+  return `${systemPrompt}\n\n${section}`;
+}
+
+export function footerStatus(state: DurableState, sessionId: string): string | undefined {
+  const role = roleForState(state, sessionId);
+  if (role.kind === "unmanaged") return pendingAssignmentContext(state, sessionId) ? "⏳ Pending focused assignment" : undefined;
+  if (role.kind === "focused-session") return "🎯 Focused session";
+  const buckets = childBuckets(state, sessionId);
+  const label = role.kind === "root-coordinator" ? "Root" : "Domain";
+  const parts = [`🧭 ${label} · ${buckets.children} children`];
+  for (const key of ["working", "ready", "pending", "attention"] as const) if (buckets[key]) parts.push(`${buckets[key]} ${key}`);
+  return parts.join(" · ");
+}