pi-extended-teams 2.1.16

package/extensions/runtime/pending-child-controller.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it, vi } from "vitest";
+import { createPendingChildController, type ParentRunIdentity } from "./pending-child-controller.js";
+
+function parent(overrides: Partial<ParentRunIdentity> = {}): ParentRunIdentity {
+  return {
+    teamName: "team",
+    parentName: "writer",
+    parentRunId: "parent-run",
+    ...overrides,
+  };
+}
+
+describe("pending child controller", () => {
+  it("registers acceptance before exact-run binding and settles a fast child without losing the empty event", async () => {
+    const controller = createPendingChildController();
+    const identity = parent();
+    const accepted = controller.acceptChild(identity, "fast-child");
+    const waiting = controller.waitForEmptyOrCancelled(identity);
+
+    expect(controller.pendingCount(identity)).toBe(1);
+    const run = controller.bindAcceptedChild(accepted, "fast-child", "fast-run");
+    expect(run).toEqual(expect.objectContaining({ childName: "fast-child", childRunId: "fast-run" }));
+    expect(controller.settleChildRun(run!)).toBe(true);
+
+    await expect(waiting).resolves.toBe("empty");
+    expect(controller.hasPendingChildren(identity)).toBe(false);
+    expect(controller.trackedParentCount()).toBe(1);
+    expect(controller.forgetParent(identity)).toBe(true);
+    expect(controller.trackedParentCount()).toBe(0);
+  });
+
+  it("keeps a queued token pending while transferring it atomically to the assigned lifecycle run", async () => {
+    const controller = createPendingChildController();
+    const identity = parent();
+    const queued = controller.acceptChild(identity, "queued-child");
+    const waiting = controller.waitForEmptyOrCancelled(identity);
+    let latchSettled = false;
+    void waiting.then(() => { latchSettled = true; });
+
+    const promoted = controller.bindAcceptedChild(queued, "queued-child", "promoted-run");
+    await Promise.resolve();
+    expect(latchSettled).toBe(false);
+    expect(controller.pendingCount(identity)).toBe(1);
+
+    expect(controller.settleChildRun(promoted!)).toBe(true);
+    await expect(waiting).resolves.toBe("empty");
+    expect(controller.forgetParent(identity)).toBe(true);
+  });
+
+  it("requires exact child-run settlement so stale run A cannot clear same-name run B", async () => {
+    const controller = createPendingChildController();
+    const identity = parent();
+    const acceptedA = controller.acceptChild(identity, "same-name");
+    const runA = controller.bindAcceptedChild(acceptedA, "same-name", "run-a")!;
+    expect(controller.settleChildRun(runA)).toBe(true);
+
+    const acceptedB = controller.acceptChild(identity, "same-name");
+    const runB = controller.bindAcceptedChild(acceptedB, "same-name", "run-b")!;
+    const waitingForB = controller.waitForEmptyOrCancelled(identity);
+
+    expect(controller.settleChildRun(runA)).toBe(false);
+    expect(controller.pendingCount(identity)).toBe(1);
+    expect(controller.settleChildRun(runB)).toBe(true);
+    await expect(waitingForB).resolves.toBe("empty");
+    expect(controller.forgetParent(identity)).toBe(true);
+  });
+
+  it("cancels waiters immediately, notifies once, and leaves duplicate cleanup idempotent", async () => {
+    const controller = createPendingChildController();
+    const identity = parent();
+    const cancelled = vi.fn();
+    controller.onParentCancelled(cancelled);
+    const accepted = controller.acceptChild(identity, "queued-child");
+    const waiting = controller.waitForEmptyOrCancelled(identity);
+
+    expect(controller.cancelParent(identity)).toBe(true);
+    expect(controller.cancelParent(identity)).toBe(false);
+    expect(controller.settleAcceptance(accepted)).toBe(false);
+    await expect(waiting).resolves.toBe("cancelled");
+    expect(cancelled).toHaveBeenCalledOnce();
+    expect(controller.pendingCount(identity)).toBe(0);
+
+    expect(controller.forgetParent(identity)).toBe(true);
+    expect(controller.trackedParentCount()).toBe(0);
+  });
+
+  it("creates a durable unseen cancellation sentinel, notifies once, and isolates a newer same-name run", async () => {
+    const controller = createPendingChildController();
+    const exactRun = parent();
+    const newerRun = parent({ parentRunId: "parent-run-newer" });
+    const cancelled = vi.fn();
+    controller.onParentCancelled(cancelled);
+
+    expect(controller.cancelParent(exactRun)).toBe(true);
+    expect(controller.cancelParent(exactRun)).toBe(false);
+    expect(controller.trackedParentCount()).toBe(1);
+    expect(controller.observeParent(exactRun)).toMatchObject({ cancelled: true, pendingCount: 0 });
+    expect(() => controller.acceptChild(exactRun, "late-child")).toThrow("is closing");
+    expect(cancelled).toHaveBeenCalledOnce();
+    expect(cancelled).toHaveBeenCalledWith(exactRun);
+
+    const newerAcceptance = controller.acceptChild(newerRun, "newer-child");
+    const newerChild = controller.bindAcceptedChild(newerAcceptance, "newer-child", "newer-child-run");
+    expect(newerChild).toBeDefined();
+    expect(controller.pendingCount(newerRun)).toBe(1);
+    expect(controller.observeParent(newerRun).cancelled).toBe(false);
+    expect(controller.observeParent(exactRun).cancelled).toBe(true);
+
+    expect(controller.settleChildRun(newerChild!)).toBe(true);
+    expect(controller.trackedParentCount()).toBe(2);
+    expect(controller.forgetParent(newerRun)).toBe(true);
+    expect(controller.trackedParentCount()).toBe(1);
+    expect(controller.observeParent(exactRun).cancelled).toBe(true);
+    expect(controller.forgetParent(exactRun)).toBe(true);
+    expect(controller.trackedParentCount()).toBe(0);
+  });
+
+  it("wakes and rearms exact-parent generation waiters for accept, bind, settle, signal, and cancel", async () => {
+    const controller = createPendingChildController();
+    const identity = parent();
+    let snapshot = controller.observeParent(identity);
+
+    let changed = controller.waitForChangeOrCancelled(identity, snapshot.generation);
+    const acceptance = controller.acceptChild(identity, "child");
+    await expect(changed).resolves.toMatchObject({ status: "changed" });
+
+    snapshot = controller.observeParent(identity);
+    changed = controller.waitForChangeOrCancelled(identity, snapshot.generation);
+    const child = controller.bindAcceptedChild(acceptance, "child", "child-run")!;
+    await expect(changed).resolves.toMatchObject({ status: "changed" });
+
+    snapshot = controller.observeParent(identity);
+    changed = controller.waitForChangeOrCancelled(identity, snapshot.generation);
+    expect(controller.settleChildRun(child)).toBe(true);
+    await expect(changed).resolves.toMatchObject({ status: "changed" });
+
+    snapshot = controller.observeParent(identity);
+    changed = controller.waitForChangeOrCancelled(identity, snapshot.generation);
+    expect(controller.signalParentChange(identity)).toBe(true);
+    await expect(changed).resolves.toMatchObject({ status: "changed" });
+
+    snapshot = controller.observeParent(identity);
+    changed = controller.waitForChangeOrCancelled(identity, snapshot.generation);
+    expect(controller.cancelParent(identity)).toBe(true);
+    await expect(changed).resolves.toMatchObject({ status: "cancelled" });
+    expect(controller.trackedParentCount()).toBe(1);
+    expect(controller.forgetParent(identity)).toBe(true);
+  });
+
+  it("reclaims only an exact zero-child state and retains cancelled quarantine until successful forget", () => {
+    const controller = createPendingChildController();
+    const quarantined = parent({ parentRunId: "quarantined-run" });
+    const active = parent({ parentRunId: "active-run" });
+    const acceptance = controller.acceptChild(active, "child");
+
+    expect(controller.cancelParent(quarantined)).toBe(true);
+    expect(controller.forgetParent(active)).toBe(false);
+    expect(controller.trackedParentCount()).toBe(2);
+    expect(controller.settleAcceptance(acceptance)).toBe(true);
+    expect(controller.trackedParentCount()).toBe(2);
+    expect(controller.observeParent(quarantined).cancelled).toBe(true);
+
+    expect(controller.forgetParent(active)).toBe(true);
+    expect(controller.trackedParentCount()).toBe(1);
+    expect(controller.observeParent(quarantined).cancelled).toBe(true);
+    expect(controller.forgetParent(quarantined)).toBe(true);
+    expect(controller.trackedParentCount()).toBe(0);
+  });
+});

package/extensions/runtime/pending-child-controller.ts

@@ -0,0 +1,280 @@
+import crypto from "node:crypto";
+
+export interface ParentRunIdentity {
+  teamName: string;
+  parentName: string;
+  parentRunId: string;
+}
+
+export interface PendingChildAcceptance extends ParentRunIdentity {
+  token: string;
+  childName: string;
+}
+
+export interface PendingChildRun extends ParentRunIdentity {
+  childName: string;
+  childRunId: string;
+}
+
+export type PendingChildrenLatchResult = "empty" | "cancelled";
+
+export interface PendingParentSnapshot {
+  generation: number;
+  pendingCount: number;
+  cancelled: boolean;
+}
+
+export type PendingParentChangeResult =
+  | { status: "changed"; generation: number }
+  | { status: "cancelled"; generation: number };
+
+type PendingChildEntry =
+  | { phase: "accepted"; acceptance: PendingChildAcceptance }
+  | { phase: "running"; acceptance: PendingChildAcceptance; run: PendingChildRun };
+
+interface ParentRunState {
+  identity: ParentRunIdentity;
+  cancelled: boolean;
+  generation: number;
+  childrenByToken: Map<string, PendingChildEntry>;
+  emptyWaiters: Set<(result: PendingChildrenLatchResult) => void>;
+  changeWaiters: Set<(result: PendingParentChangeResult) => void>;
+}
+
+export interface PendingChildController {
+  acceptChild(parent: ParentRunIdentity, childName: string): PendingChildAcceptance;
+  bindAcceptedChild(
+    acceptance: PendingChildAcceptance,
+    childName: string,
+    childRunId: string
+  ): PendingChildRun | undefined;
+  settleAcceptance(acceptance: PendingChildAcceptance): boolean;
+  settleChildRun(child: PendingChildRun): boolean;
+  hasPendingChildren(parent: ParentRunIdentity): boolean;
+  pendingCount(parent: ParentRunIdentity): number;
+  observeParent(parent: ParentRunIdentity): PendingParentSnapshot;
+  signalParentChange(parent: ParentRunIdentity): boolean;
+  waitForChangeOrCancelled(
+    parent: ParentRunIdentity,
+    afterGeneration: number
+  ): Promise<PendingParentChangeResult>;
+  waitForEmptyOrCancelled(parent: ParentRunIdentity): Promise<PendingChildrenLatchResult>;
+  cancelParent(parent: ParentRunIdentity): boolean;
+  forgetParent(parent: ParentRunIdentity): boolean;
+  onParentCancelled(listener: (parent: ParentRunIdentity) => void): () => void;
+  trackedParentCount(): number;
+}
+
+function parentKey(parent: ParentRunIdentity): string {
+  return `${parent.teamName}\u0000${parent.parentName}\u0000${parent.parentRunId}`;
+}
+
+function sameParent(left: ParentRunIdentity, right: ParentRunIdentity): boolean {
+  return left.teamName === right.teamName
+    && left.parentName === right.parentName
+    && left.parentRunId === right.parentRunId;
+}
+
+function immutableParent(parent: ParentRunIdentity): ParentRunIdentity {
+  return Object.freeze({
+    teamName: parent.teamName,
+    parentName: parent.parentName,
+    parentRunId: parent.parentRunId,
+  });
+}
+
+export function createPendingChildController(): PendingChildController {
+  const parents = new Map<string, ParentRunState>();
+  const cancellationListeners = new Set<(parent: ParentRunIdentity) => void>();
+
+  const createParentState = (parent: ParentRunIdentity): ParentRunState => ({
+    identity: immutableParent(parent),
+    cancelled: false,
+    generation: 0,
+    childrenByToken: new Map(),
+    emptyWaiters: new Set(),
+    changeWaiters: new Set(),
+  });
+
+  const ensureParentState = (parent: ParentRunIdentity): ParentRunState => {
+    const key = parentKey(parent);
+    let state = parents.get(key);
+    if (!state) {
+      state = createParentState(parent);
+      parents.set(key, state);
+    }
+    return state;
+  };
+
+  const resolveEmptyWaiters = (state: ParentRunState, result: PendingChildrenLatchResult): void => {
+    const waiters = Array.from(state.emptyWaiters);
+    state.emptyWaiters.clear();
+    for (const resolve of waiters) resolve(result);
+  };
+
+  const signalChange = (state: ParentRunState): void => {
+    state.generation += 1;
+    const result: PendingParentChangeResult = state.cancelled
+      ? { status: "cancelled", generation: state.generation }
+      : { status: "changed", generation: state.generation };
+    const waiters = Array.from(state.changeWaiters);
+    state.changeWaiters.clear();
+    for (const resolve of waiters) resolve(result);
+  };
+
+  const settleToken = (acceptance: PendingChildAcceptance): boolean => {
+    const key = parentKey(acceptance);
+    const state = parents.get(key);
+    const entry = state?.childrenByToken.get(acceptance.token);
+    if (!state || !entry || entry.acceptance !== acceptance) return false;
+
+    state.childrenByToken.delete(acceptance.token);
+    signalChange(state);
+    if (state.childrenByToken.size === 0) resolveEmptyWaiters(state, "empty");
+    return true;
+  };
+
+  return {
+    acceptChild(parent, childName) {
+      const key = parentKey(parent);
+      let state = parents.get(key);
+      if (state?.cancelled) {
+        throw new Error(`Cannot accept child ${childName}: parent ${parent.parentName} run ${parent.parentRunId} is closing.`);
+      }
+      if (!state) state = ensureParentState(parent);
+
+      const acceptance = Object.freeze({
+        ...state.identity,
+        token: crypto.randomUUID(),
+        childName,
+      });
+      state.childrenByToken.set(acceptance.token, { phase: "accepted", acceptance });
+      signalChange(state);
+      return acceptance;
+    },
+
+    bindAcceptedChild(acceptance, childName, childRunId) {
+      const state = parents.get(parentKey(acceptance));
+      const entry = state?.childrenByToken.get(acceptance.token);
+      if (!state || state.cancelled || !entry || entry.phase !== "accepted" || entry.acceptance !== acceptance) {
+        return undefined;
+      }
+      if (acceptance.childName !== childName) return undefined;
+
+      const run = Object.freeze({
+        teamName: acceptance.teamName,
+        parentName: acceptance.parentName,
+        parentRunId: acceptance.parentRunId,
+        childName,
+        childRunId,
+      });
+      state.childrenByToken.set(acceptance.token, { phase: "running", acceptance, run });
+      signalChange(state);
+      return run;
+    },
+
+    settleAcceptance(acceptance) {
+      return settleToken(acceptance);
+    },
+
+    settleChildRun(child) {
+      const state = parents.get(parentKey(child));
+      if (!state || state.cancelled) return false;
+      for (const entry of state.childrenByToken.values()) {
+        if (entry.phase !== "running") continue;
+        if (entry.run.childName !== child.childName || entry.run.childRunId !== child.childRunId) continue;
+        if (!sameParent(entry.run, child)) continue;
+        return settleToken(entry.acceptance);
+      }
+      return false;
+    },
+
+    hasPendingChildren(parent) {
+      return (parents.get(parentKey(parent))?.childrenByToken.size ?? 0) > 0;
+    },
+
+    pendingCount(parent) {
+      return parents.get(parentKey(parent))?.childrenByToken.size ?? 0;
+    },
+
+    observeParent(parent) {
+      const state = ensureParentState(parent);
+      return {
+        generation: state.generation,
+        pendingCount: state.childrenByToken.size,
+        cancelled: state.cancelled,
+      };
+    },
+
+    signalParentChange(parent) {
+      const state = ensureParentState(parent);
+      if (state.cancelled) return false;
+      signalChange(state);
+      return true;
+    },
+
+    waitForChangeOrCancelled(parent, afterGeneration) {
+      const state = ensureParentState(parent);
+      if (state.cancelled) {
+        return Promise.resolve({ status: "cancelled", generation: state.generation });
+      }
+      if (state.generation !== afterGeneration) {
+        return Promise.resolve({ status: "changed", generation: state.generation });
+      }
+      return new Promise<PendingParentChangeResult>((resolve) => {
+        state.changeWaiters.add(resolve);
+      });
+    },
+
+    waitForEmptyOrCancelled(parent) {
+      const state = parents.get(parentKey(parent));
+      if (!state) return Promise.resolve("empty");
+      if (state.cancelled) return Promise.resolve("cancelled");
+      if (state.childrenByToken.size === 0) return Promise.resolve("empty");
+      return new Promise<PendingChildrenLatchResult>((resolve) => {
+        state.emptyWaiters.add(resolve);
+      });
+    },
+
+    cancelParent(parent) {
+      const state = ensureParentState(parent);
+      if (state.cancelled) return false;
+      state.cancelled = true;
+      state.childrenByToken.clear();
+      signalChange(state);
+      resolveEmptyWaiters(state, "cancelled");
+      for (const listener of cancellationListeners) {
+        try {
+          listener(state.identity);
+        } catch {
+          // Cancellation is authoritative even if an in-memory observer fails.
+        }
+      }
+      return true;
+    },
+
+    forgetParent(parent) {
+      const key = parentKey(parent);
+      const state = parents.get(key);
+      if (!state || state.childrenByToken.size > 0) return false;
+      parents.delete(key);
+      resolveEmptyWaiters(state, state.cancelled ? "cancelled" : "empty");
+      const changeResult: PendingParentChangeResult = state.cancelled
+        ? { status: "cancelled", generation: state.generation }
+        : { status: "changed", generation: state.generation };
+      const changeWaiters = Array.from(state.changeWaiters);
+      state.changeWaiters.clear();
+      for (const resolve of changeWaiters) resolve(changeResult);
+      return true;
+    },
+
+    onParentCancelled(listener) {
+      cancellationListeners.add(listener);
+      return () => { cancellationListeners.delete(listener); };
+    },
+
+    trackedParentCount() {
+      return parents.size;
+    },
+  };
+}

package/extensions/runtime/types.ts

@@ -0,0 +1,68 @@
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import type { ContextUsageSnapshot, RuntimeError } from "../../src/utils/runtime";
+import type { ManagedReadAgentLifecycleState } from "../agents/read-agent-session-lifecycle";
+
+export interface RunningReadAgent extends ManagedReadAgentLifecycleState {
+  runId: string;
+  name: string;
+  teamName: string;
+  startedAt: number;
+  tokensUsed: number;
+  contextUsage?: ContextUsageSnapshot;
+  status: "starting" | "thinking" | "working" | "finishing";
+  recentEvents: string[];
+  lastActivityAt: number;
+  activeToolName?: string;
+  lastError?: RuntimeError;
+  idleNudgeLevel?: "soft" | "hard";
+  role?: string;
+  model?: string;
+  thinking?: string;
+  modelSlot?: string;
+  latestAssistantSnippet?: string;
+  assistantProgressNormalizedTail?: string;
+  assistantProgressTailTruncated?: boolean;
+  assistantProgressContentIndex?: number;
+  assistantProgressNeedsSeparator?: boolean;
+  assistantProgressIncrementalUnsafe?: boolean;
+  latestProgress?: string;
+  progressUpdatedAt?: number;
+  /** Remove the private child transcript only after durable successful reporting and session disposal. */
+  cleanupPrivateSessionOnFinalize?: boolean;
+  /** Fail finalization closed so runtime, member, fence, and transcript remain recoverable. */
+  finalizationBlockedReason?: string;
+  session?: AgentSession;
+  finished?: Promise<void>;
+}
+
+export type AgentReportSource =
+  | "report_and_exit"
+  | "persisted-report_and_exit"
+  | "assistant-text"
+  | "persisted-assistant-text"
+  | "irrecoverable-empty"
+  | "runtime-failure";
+
+export interface CompletedAgentReport {
+  name: string;
+  role: string;
+  status: "completed" | "failed";
+  report: string;
+  summary?: string;
+  completedAt: number;
+  startedAt?: number;
+  elapsedMs?: number;
+  tokensUsed?: number;
+  costUsd?: number;
+  model?: string;
+  thinking?: string;
+  modelSlot?: string;
+  color?: string;
+  requestedBy?: string;
+  initialPrompt?: string;
+  reportSource?: AgentReportSource;
+  recoveryAttempted?: boolean;
+  recoverySessionId?: string;
+  recoverySessionFile?: string;
+  source: "read-agent" | "lead-inbox" | "report-event";
+}

package/extensions/team/contracts.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+
+const contractPath = path.resolve(process.cwd(), "extensions/team/team-contracts.json");
+
+describe("persisted team behavior contracts", () => {
+  it("saves Leo's required team lifecycle/UI contracts locally", () => {
+    expect(fs.existsSync(contractPath)).toBe(true);
+    const contract = JSON.parse(fs.readFileSync(contractPath, "utf-8"));
+
+    expect(contract.version).toBe(1);
+    expect(contract.contracts).toEqual(expect.arrayContaining([
+      expect.objectContaining({ id: "ui.team-activity-card" }),
+      expect.objectContaining({ id: "ui.active-reader-writer-info" }),
+      expect.objectContaining({ id: "ui.agent-follow-navigation" }),
+      expect.objectContaining({ id: "helpers.requested-by-writer" }),
+      expect.objectContaining({ id: "writers.request-only-lead-spawns" }),
+      expect.objectContaining({ id: "messaging.push-on-completion" }),
+      expect.objectContaining({ id: "completion.remove-from-active-keep-history" }),
+      expect.objectContaining({ id: "runtime.reload-disposes-background-handles" }),
+      expect.objectContaining({ id: "writers.tmux-closes-when-done" }),
+    ]));
+
+    const byId = Object.fromEntries(contract.contracts.map((entry: any) => [entry.id, entry.description]));
+    expect(byId["ui.team-activity-card"]).not.toContain("writers are tmux agents and are not mirrored");
+    expect(byId["ui.team-activity-card"]).not.toContain("lead inbox reports");
+    expect(byId["ui.team-activity-card"]).toContain("reports arrive as messages");
+    expect(byId["ui.team-activity-card"]).toContain("stable below-editor pi-emote-style card");
+    expect(byId["ui.team-activity-card"]).toContain("updates progress, elapsed time, and token counts in place without flicker");
+    expect(byId["ui.team-activity-card"]).toContain("revealing the new phrase left-to-right");
+    expect(byId["ui.team-activity-card"]).toContain("Each active writer row shows +N");
+    expect(byId["ui.team-activity-card"]).toContain("without changing global active/read/write counts");
+    expect(byId["ui.active-reader-writer-info"]).toContain("team activity card");
+    expect(byId["ui.active-reader-writer-info"]).toContain("Active reader and writer information");
+    expect(byId["ui.agent-follow-navigation"]).toContain("full-window interactive live-follow view");
+    expect(byId["ui.agent-follow-navigation"]).toContain("Up moves to the previous agent");
+    expect(byId["ui.agent-follow-navigation"]).toContain("pairs tool calls with their results in readable blocks");
+    expect(byId["ui.agent-follow-navigation"]).toContain("provides an input for direct messages");
+    expect(byId["ui.agent-follow-navigation"]).toContain("Pressing x stops the selected subagent");
+    expect(byId["writers.request-only-lead-spawns"]).toContain("explicitly opted-in depth-0 write-feature/write-critical");
+    expect(byId["writers.request-only-lead-spawns"]).toContain("any canonical read tier and any count subject to global capacity");
+    expect(byId["writers.request-only-lead-spawns"]).toContain("Read agents, depth-1 children, write-patch, and write-system remain denied");
+    expect(byId["writers.request-only-lead-spawns"]).toContain("requesting writer and cannot delegate");
+    expect(byId["messaging.push-on-completion"]).toContain("classified completion notice to the lead");
+    expect(byId["runtime.reload-disposes-background-handles"]).toContain("title/initial-trigger timers");
+    expect(byId["runtime.reload-disposes-background-handles"]).toContain("active in-process agent sessions/heartbeats");
+  });
+
+  it("requires context-rich missions for isolated agent sessions", () => {
+    const skill = fs.readFileSync(path.resolve(process.cwd(), "skills/teams.md"), "utf-8");
+
+    expect(skill).toContain("they do not inherit the lead or parent conversation");
+    expect(skill).toContain("## Context handoff contract");
+    expect(skill).toContain("make a context-selection pass");
+    expect(skill).toContain("### Lazy session reference");
+    expect(skill).toContain("session_context: \"lazy\"");
+    expect(skill).toContain("Do not enable it by default or use it as an excuse for a weak mission");
+    expect(skill).toContain("The child should not open it by default");
+    expect(skill).toContain("excludes thinking, images, raw tool arguments, and raw tool-result bodies");
+    expect(skill).toContain("**Augment/reuse (default):**");
+    expect(skill).toContain("**Corroborate:**");
+    expect(skill).toContain("**Blind re-derive (exception):**");
+    for (const field of [
+      "**Question:**",
+      "**Expected delta:**",
+      "**Known:**",
+      "**Inspected:**",
+      "**Do not rediscover:**",
+      "**Dependencies consumed:**",
+    ]) {
+      expect(skill).toContain(field);
+    }
+    for (const label of ["`[verified]`", "`[reported]`", "`[hypothesis]`", "`[open]`", "`[conflict]`", "`[decision]`"]) {
+      expect(skill).toContain(label);
+    }
+    expect(skill).toContain("an **Evidence delta**");
+    expect(skill).toContain("what the next lane must not repeat plus its next bounded question");
+    expect(skill).toContain("Give each child the same Context handoff contract");
+
+    const exampleSlice = (name: string, endMarker: string) => {
+      const start = skill.indexOf(`name: "${name}"`);
+      const end = skill.indexOf(endMarker, start);
+      expect(start, `${name} example start`).toBeGreaterThan(-1);
+      expect(end, `${name} example end`).toBeGreaterThan(start);
+      return skill.slice(start, end);
+    };
+    const writerExamples = [
+      exampleSlice("docs-fix", "For a bounded feature or critical writer"),
+      exampleSlice("parser-feature", "## Hot-word trigger"),
+    ];
+    for (const example of writerExamples) {
+      expect(example).toContain("Mode: EDIT-ALLOWED");
+      for (const field of ["Question:", "Expected delta:", "Known:", "Inspected:", "Do not rediscover:", "Dependencies consumed:"]) {
+        expect(example).toContain(field);
+      }
+    }
+    expect(writerExamples[1]).toContain("same Context handoff contract");
+
+    const knownExampleLines = skill.split("\n").filter((line) => line.startsWith("Known:"));
+    expect(knownExampleLines.length).toBeGreaterThanOrEqual(5);
+    for (const line of knownExampleLines) {
+      const claims = line.match(/\[(?:verified|reported|decision)\]/g) ?? [];
+      const sources = line.match(/source:/g) ?? [];
+      expect(claims.length, line).toBeGreaterThan(0);
+      expect(sources.length, line).toBe(claims.length);
+    }
+    expect(skill).toMatch(/Prior result: \[verified\] source:/);
+    expect(skill).toContain("replace illustrative placeholders with real evidence before using the `docs-fix` template");
+  });
+});