@chainingintention/pi-web-cn 2.0.0 → 2.202610.0

package/examples/workspace-provider-plugin/src/browser/index.ts

@@ -0,0 +1,69 @@
+import type { JsonObject, PiWebPlugin, WorkspacePanelContext } from "@chainingintention/pi-web-cn/plugin-api";
+
+const summaries = new Map<string, string>();
+
+const plugin = {
+  apiVersion: 4,
+  name: "工作区提供器示例",
+  activate: ({ pluginId, runtimePluginId, html }) => ({
+    contributions: {
+      actions: [
+        {
+          id: "workspace.open",
+          title: "打开工作区提供器示例",
+          enabled: ({ state }) => state.selectedWorkspace?.provider?.pluginId === pluginId,
+          run: ({ selectWorkspaceTool }) => {
+            selectWorkspaceTool(`${runtimePluginId}:workspace.example-provider`);
+          },
+        },
+      ],
+      workspacePanels: [
+        {
+          id: "workspace.example-provider",
+          title: "提供器示例",
+          visible: ({ workspace }) => workspace.provider?.pluginId === pluginId,
+          render: (context) => {
+            const marker = stringMetadata(context.workspace.provider?.metadata, "marker") ?? "未知";
+            const summary = summaries.get(workspaceKey(context)) ?? "请从此包的服务端插件获取摘要。";
+            return html`
+              <section class="toolbar"><strong>工作区提供器示例</strong></section>
+              <section class="viewer">
+                <p>此工作区由 <code>${pluginId}</code> 提供。</p>
+                <p class="muted">接管标记：<code>${marker}</code></p>
+                <button
+                  ?disabled=${context.peer?.request === undefined}
+                  @click=${() => { void refreshSummary(context); }}
+                >获取包摘要</button>
+                <p aria-live="polite">${summary}</p>
+              </section>
+            `;
+          },
+        },
+      ],
+    },
+  }),
+} satisfies PiWebPlugin;
+
+export default plugin;
+
+async function refreshSummary(context: WorkspacePanelContext): Promise<void> {
+  const key = workspaceKey(context);
+  try {
+    if (context.peer?.request === undefined) throw new Error("插件后端不可用");
+    const result = await context.peer.request("summary", null);
+    if (typeof result !== "string") throw new Error("插件后端返回的摘要无效");
+    summaries.set(key, result);
+  } catch (error) {
+    summaries.set(key, error instanceof Error ? error.message : String(error));
+  }
+  context.host.requestRender();
+}
+
+function workspaceKey(context: WorkspacePanelContext): string {
+  return `${context.machine.id}:${context.workspace.id}`;
+}
+
+function stringMetadata(metadata: JsonObject | undefined, key: string): string | undefined {
+  const value = metadata?.[key];
+  return typeof value === "string" ? value : undefined;
+}

package/examples/workspace-provider-plugin/src/server.ts

@@ -0,0 +1,68 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import type {
+  PiWebServerPlugin,
+  ProjectInput,
+  ProviderClaim,
+  ProviderWorkspace,
+  ServerPluginPeerRequestContext,
+  WorkspaceProvider,
+} from "@chainingintention/pi-web-cn/server-plugin-api";
+
+const markerPath = ".pi-web/example-workspace-provider";
+
+const plugin: PiWebServerPlugin = {
+  apiVersion: 3,
+  name: "工作区提供器示例",
+  activate({ pluginId, logger }) {
+    logger.info("激活工作区提供器示例", { pluginId });
+    return {
+      workspaceProvider: createWorkspaceProvider(),
+      peer: { request: (context) => requestSummary(pluginId, context) },
+    };
+  },
+};
+
+export default plugin;
+
+function createWorkspaceProvider(): WorkspaceProvider {
+  return {
+    async probe(project: ProjectInput, signal: AbortSignal): Promise<ProviderClaim> {
+      signal.throwIfAborted();
+      try {
+        await access(join(project.path, markerPath));
+        signal.throwIfAborted();
+        return "claim";
+      } catch (error) {
+        if (isMissingFile(error)) return "pass";
+        throw error;
+      }
+    },
+    async list(project: ProjectInput, signal: AbortSignal): Promise<ProviderWorkspace[]> {
+      signal.throwIfAborted();
+      return [{
+        key: "main",
+        path: project.path,
+        label: project.name,
+        isMain: true,
+        // This object is visible to every browser script and API consumer.
+        publicMetadata: { kind: "example", marker: markerPath },
+      }];
+    },
+  };
+}
+
+function requestSummary(pluginId: string, context: ServerPluginPeerRequestContext): string {
+  context.signal.throwIfAborted();
+  if (context.operation !== "summary") {
+    throw new Error(`不支持的示例工作区操作：${context.operation}`);
+  }
+  return `${pluginId} 提供工作区 ${context.workspace.label}，路径：${context.workspace.path}`;
+}
+
+function isMissingFile(error: unknown): boolean {
+  return typeof error === "object"
+    && error !== null
+    && "code" in error
+    && Reflect.get(error, "code") === "ENOENT";
+}

package/examples/workspace-provider-plugin/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "types": ["node"],
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": false,
+    "noEmitOnError": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/extensions/pi-web.ts

@@ -3,7 +3,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getPackageDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const cliPath = join(packageRoot, "dist", "cli.js");
@@ -63,6 +63,8 @@ function run(command: string, args: string[], env: NodeJS.ProcessEnv = {}): Prom
 }
 
 async function runPiWeb(args: string[], env: NodeJS.ProcessEnv = {}): Promise<{ code: number; output: string }> {
+  // Pi resolves this import against its own installation, outside PI WEB's dependency tree.
+  env = { ...env, PI_WEB_PI_PACKAGE_DIR: getPackageDir() };
   if (existsSync(cliPath)) {
     return run(process.execPath, [cliPath, ...args], env);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chainingintention/pi-web-cn",
-  "version": "2.0.0",
-  "description": "Remote web UI and browser control plane for persistent Pi Coding Agent sessions.",
+  "version": "2.202610.0",
+  "description": "Web UI for persistent Pi Coding Agent sessions in real workspaces.",
   "license": "MIT",
   "author": "Federico Jaramillo Martinez",
   "type": "module",
@@ -10,7 +10,8 @@
       "types": "./dist/plugin-api.d.ts"
     },
     "./server-plugin-api": {
-      "types": "./dist/server-plugin-api.d.ts"
+      "types": "./dist/server-plugin-api.d.ts",
+      "import": "./dist/server-plugin-api.js"
     }
   },
   "typesVersions": {
@@ -35,7 +36,12 @@
     "README.md",
     "LICENSE",
     "skills/relay/SKILL.md",
+    "skills/relay-runner/SKILL.md",
     "extensions",
+    "examples/workspace-provider-plugin",
+    "examples/session-bridge-plugin",
+    "!examples/**/node_modules",
+    "!examples/**/dist",
     "docs/plugins.md",
     "docs/config.md",
     "docs/assets",
@@ -44,8 +50,8 @@
   ],
   "scripts": {
     "dev": "bash -c 'trap \"kill 0\" EXIT; npm run dev:sessiond & npm run dev:web & npm run dev:client & wait'",
-    "dev:sessiond": "tsx watch src/server/sessiond.ts",
-    "dev:web": "bash -c 'set -e; npm run build:plugins; trap \"kill 0\" EXIT; npm run dev:plugins & tsx watch src/server/index.ts & wait'",
+    "dev:sessiond": "node scripts/dev-sessiond.mjs --watch",
+    "dev:web": "tsc -p tsconfig.plugins.json && node scripts/dev-web.mjs",
     "dev:server": "npm run dev:web",
     "dev:client": "vite --host 0.0.0.0",
     "dev:plugins": "node scripts/build-plugins.mjs --watch",
@@ -53,15 +59,18 @@
     "build:plugin-api": "tsc -p tsconfig.plugin-api.json",
     "build:plugins": "tsc -p tsconfig.plugins.json && node scripts/build-plugins.mjs",
     "capture:screenshots": "node scripts/capture-screenshots.mjs",
+    "perf:load": "node scripts/perf-load.mjs",
     "typecheck": "tsc --noEmit",
     "typecheck:cached": "tsc --noEmit --incremental --tsBuildInfoFile node_modules/.cache/pi-web/typecheck.tsbuildinfo",
     "knip": "knip",
-    "lint": "eslint \"src/**/*.ts\" \"extensions/**/*.ts\" \"pi-web-plugins/**/*.ts\" vite.config.ts vitest.config.ts",
+    "lint": "eslint \"src/**/*.ts\" \"extensions/**/*.ts\" \"pi-web-plugins/**/*.ts\" \"pi-packages/**/*.ts\" \"test-fixtures/browser/**/*.ts\" vite.config.ts vitest.config.ts vitest.artifacts.config.ts playwright.config.ts",
     "test": "vitest run --config vitest.config.ts",
+    "test:browser": "playwright test",
+    "check:artifacts": "vitest run --config vitest.artifacts.config.ts",
     "verify": "npm run typecheck && npm run lint && npm run knip && npm test",
     "verify:staged": "node scripts/verify-staged.mjs",
     "start": "tsx src/server/index.ts",
-    "start:sessiond": "tsx src/server/sessiond.ts",
+    "start:sessiond": "node scripts/dev-sessiond.mjs",
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "prepack": "npm run build",
     "pack:dry": "npm pack --dry-run",
@@ -74,52 +83,61 @@
     "changelog:status": "changeset status"
   },
   "dependencies": {
-    "@codemirror/commands": "^6.10.4",
+    "@codemirror/commands": "^6.11.1",
     "@codemirror/lang-css": "^6.3.1",
     "@codemirror/lang-go": "^6.0.1",
     "@codemirror/lang-html": "^6.4.11",
     "@codemirror/lang-javascript": "^6.2.5",
     "@codemirror/lang-json": "^6.0.2",
-    "@codemirror/lang-markdown": "^6.5.0",
+    "@codemirror/lang-markdown": "^6.5.2",
     "@codemirror/lang-python": "^6.2.1",
     "@codemirror/lang-rust": "^6.0.2",
-    "@codemirror/language": "^6.12.4",
+    "@codemirror/language": "^6.13.1",
     "@codemirror/legacy-modes": "^6.5.3",
-    "@codemirror/state": "^6.7.1",
-    "@codemirror/view": "^6.43.6",
-    "@fastify/compress": "^9.0.0",
-    "@fastify/static": "^9.3.0",
-    "@fastify/websocket": "^11.3.0",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/view": "6.43.13",
+    "@fastify/compress": "^9.2.2",
+    "@fastify/static": "^10.1.6",
+    "@fastify/websocket": "^11.3.4",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
+    "css-tree": "^3.2.1",
     "diff": "^9.0.0",
-    "fastify": "^5.10.0",
+    "fastify": "^5.12.7",
+    "highlight.js": "^11.12.0",
+    "image-size": "^2.0.4",
+    "import-meta-resolve": "^4.2.0",
     "lit": "^3.3.3",
-    "marked": "^18.0.6",
+    "marked": "^18.1.1",
     "node-pty": "^1.1.0",
-    "typebox": "1.3.6",
-    "ws": "^8.21.0",
+    "pi-web-typebox": "npm:typebox@1.3.37",
+    "undici": "^8.11.2",
+    "ws": "^8.22.0",
     "yauzl": "^3.4.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.31.0",
-    "@earendil-works/pi-agent-core": "^0.84.1",
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@changesets/cli": "^3.0.3",
+    "@earendil-works/pi-agent-core": "1.3.0",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
     "@eslint/js": "^10.0.1",
-    "@types/node": "^24.13.3",
-    "@types/ws": "^8.18.1",
+    "@playwright/test": "^1.64.1",
+    "@types/css-tree": "^3.2.0",
+    "@types/node": "^26.6.5",
+    "@types/ws": "^8.18.2",
     "@types/yauzl": "^2.10.3",
     "@types/yazl": "^2.4.6",
-    "eslint": "^10.6.0",
-    "globals": "^17.7.0",
-    "happy-dom": "^20.11.1",
-    "knip": "^6.25.0",
-    "tsx": "^4.23.0",
+    "dompurify": "^3.4.17",
+    "eslint": "^10.12.0",
+    "globals": "^17.13.0",
+    "happy-dom": "^20.14.6",
+    "knip": "^6.41.0",
+    "mermaid": "^12.2.0",
+    "tsx": "^4.23.15",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.63.0",
-    "vite": "^8.1.4",
-    "vitest": "^4.1.10",
+    "typescript-eslint": "^8.71.2",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.4",
     "yazl": "^3.3.1"
   },
   "publishConfig": {
@@ -138,9 +156,14 @@
   "homepage": "https://github.com/nayuto-wakusei/pi-web-ChineseTranslation#readme",
   "packageManager": "npm@11.11.0",
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.84.0",
-    "@earendil-works/pi-ai": ">=0.84.0",
-    "@earendil-works/pi-coding-agent": ">=0.84.0"
+    "@earendil-works/pi-agent-core": "0.86.1 || 0.87.0 || 1.3.0",
+    "@earendil-works/pi-ai": "0.86.1 || 0.87.0 || 1.3.0",
+    "@earendil-works/pi-coding-agent": "0.86.1 || 0.87.0 || 1.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-agent-core": { "optional": true },
+    "@earendil-works/pi-ai": { "optional": true },
+    "@earendil-works/pi-coding-agent": { "optional": true }
   },
   "keywords": [
     "pi-package",

package/skills/README.md

@@ -4,9 +4,35 @@ Distributable agent skills developed alongside pi-web.
 
 ## relay
 
-Execute a long or complex plan as a chain of independent sessions, each running
-one well-sized leg and handing off to the next via `spawn_session`.
+A tool-agnostic foundation for the [Relay Principle](https://relayprinciple.ai/):
+carry long work through a chain of fresh agent contexts, one bounded leg and one
+durable handoff at a time, without a standing coordinator or role hierarchy.
+It centers the agreed finish line, relay-specific scope, compact baton, durable
+history, and visible completion or need for help.
 
 ```bash
 npx skills add jmfederico/pi-web --skill relay -a pi -g
 ```
+
+## relay-runner
+
+The Pi session and record mechanics used by `/relay` and `/relay-worktree`.
+Preparation clarifies the goal and boundaries with the human and requires explicit
+approval before dispatch. Each fresh runner chooses its next useful slice, keeps
+`charter.md`, `status.md`, and `log.md` durable, and hands off once or stops.
+An optional `decisions.md` keeps consequential reasoning out of the baton.
+The runner requires a fresh-context final review, with at most three attempts,
+without scripting the development route. Project instructions and applicable
+skills govern the work. Dispatch and handoff prompts select both Relay skills.
+
+```bash
+npx skills add jmfederico/pi-web --skill relay-runner -a pi -g
+```
+
+`relay-runner` is not standalone; install the base `relay` skill as well when
+using these commands directly. The `relays` Pi package ships and installs both
+skills atomically. Its files under
+`pi-packages/relays/skills/` are symlinks to the canonical `SKILL.md` files in
+this directory; the package build (`npm run build:plugins`, or the dev watch)
+materializes them as real packaged files. Edit the canonical copies here, not
+the package links.

package/skills/relay/SKILL.md

@@ -1,115 +1,50 @@
 ---
 name: relay
-description: "How the Relay method works: executing a plan as a chain of independent sessions that each do one slice and hand off to the next via spawn_session. Load this skill only when you already know you are in a relay: a prompt states you are working under the Relay framework (or relay/chain), points you at a relay charter/status/log, or the user invokes this skill directly. Do not load it for generic multi-step plans or ordinary spawn_session use."
+description: "Carry work across a chain of fresh agent contexts using a shared goal, compact baton, and durable record. Use when a user invokes Relay, discusses the Relay method, prepares a Relay, or continues an active Relay. Do not load for generic multi-step work or ordinary delegation."
 ---
 
 # Relay
 
-Relay is a way to execute a long or complex plan as a chain of independent sessions. Each session runs **one leg** — a single well-sized slice of the work — then hands the work off to a fresh session that runs the next leg. The chain continues until the goal is reached.
+A Relay carries work across fresh agent contexts until the agreed goal is reached or an agent needs human help. Each context owns one useful slice, called a **leg**. There is no standing coordinator or fixed set of agent roles.
 
-There is no coordinator and no referee. Each runner is the coordinator for their own leg: smart enough to do the work, adapt to what they discover, and hand off cleanly. Trust is distributed to every agent, not held by a god-agent above them.
+Follow the [Relay Principle](https://relayprinciple.ai/): give agents a destination and enough continuity to act, rather than recreating a management structure around them.
 
-Relay works because it does not try to recreate human management structures. The point is fewer boundaries, less hierarchy, and more fluid execution. The thing that makes that safe is **context containment**: every leg starts with a fresh, small context, and the accumulated knowledge lives in compact documents on disk rather than in any one session's memory.
+## Finish line over plan
 
-## The hard constraint that shapes everything
+Help the human express what they want built and how they will recognize it is done. Resolve material ambiguity before dispatch. An existing requirements document can supply the goal; reference it rather than rewriting it into a larger specification.
 
-`spawn_session` is fire-and-forget. When you spawn the next leg, **you do not see its output and you cannot correct it.** The only thing that travels down the chain is what you wrote to disk. A human may be watching in the UI, but they intervene by reading your documents, not by relaying messages between sessions.
+Keep the goal stable and the route adaptable. Each runner checks the finish line against the current work and chooses the next useful slice. Changing the goal requires human agreement; changing implementation or sequencing within scope does not.
 
-Two consequences follow, and they govern the whole method:
+## Scope over script
 
-- **Make your work durable before you hand off.** Update the status, append the log, save/commit the artifacts (commit if the relay says to), and only then spawn the next leg. Anything not on disk is lost.
-- **Hand off exactly once, at the end.** Do not spawn early, do not spawn several runners "to parallelize," and never spawn while you still have work in flight. One leg, one handoff.
+Record the relay-specific boundaries, limitations, conditions, and clarifications needed to understand the request. Preserve technical requirements and any other details the human explicitly asks to include.
 
-## The relay packet
+Do not invent an implementation roadmap, speculative requirements, or a new software process. Project instructions, skills, and harness conventions remain where they belong; each runner discovers and follows what applies to its work. A Relay does not replace or weaken those rules.
 
-A relay is carried by a small packet of documents. By default they live in `.pi-web/relays/<name>/` unless the user or the dispatching prompt says otherwise — always follow an explicit location if given.
+## Handoff over handhold
 
-Every relay has these three core files:
+A baton says **where we are**, not **how you must work**. Avoid suggesting or assigning the next slice: even a provisional suggestion can anchor the successor. Record remaining gaps and concrete dependencies instead, and trust the successor to inspect reality and choose its slice.
 
-**Charter** (`charter.md`) — the stable agreement, written when the relay is planned. It must contain, at minimum:
+Choose a meaningful increment that fits one context, not the tiniest possible task. Investigation and related work can stay together. Leg boundaries protect context quality, not organizational ownership.
 
-- **Relay identity.** The relay name and root path, so runners know exactly which relay they are on.
-- **Goal / finish line.** A concrete, achievable end state. Without this the relay runs forever — this is non-negotiable.
-- **Sizing.** How much is *one leg*? This is project- and plan-specific; the charter defines it (a task, a slice, a time/scope budget — whatever fits). The skill does not decide this for you.
-- **Task selection policy.** How a runner chooses the next task when `status.md` does not name one explicitly.
-- **Handover.** How a runner hands off: what the spawn prompt should say and what the next runner must read. A normal handoff starts with a natural header containing the relay name and next leg number, then points at `charter.md` and `status.md`, not the full log.
-- **Intervention signal.** When and how a runner must stop and get the human, and how that is made visible. The charter must define this; the skill does not define it for you.
-- **Reading discipline.** The files a runner should read to orient, and any files that should not be read defensively.
+Finish ongoing work and preserve the state before starting at most one fresh successor. Handoff is the final operational action; only a user-facing summary follows. Do not watch or steer the successor.
 
-The charter *can* be edited, but it should rarely *need* to be. If it is changing every leg, that is a smell — the design wasn't settled, or the goal is drifting. Treat frequent charter edits as a reason to stop and involve the human.
+## Record over memory
 
-**Status** (`status.md`) — the compact baton/current state. This is the file every runner reads after the charter, and every runner updates before handoff or stop. Keep it short enough that a fresh runner can load it cheaply. It should answer:
+Keep three kinds of durable information:
 
-- **Current position.** Where the relay is now.
-- **Current or next task.** The next leg if known; otherwise enough information to apply the charter's task selection policy.
-- **Leg tracking.** The last completed leg and the next leg to run. Keep this explicit so runners do not have to infer whether “current leg” means the leg just finished or the leg being handed off, and so new PI-WEB sessions can distinguish relay legs from the first line of their prompt without naming instructions.
-- **Relevant context.** Only the files, sections, commands, artifacts, or specific log entries needed for the next leg.
-- **Progress documentation.** Where this runner must write progress: update `status.md`, append `log.md`, update artifacts, commit, etc.
-- **Blockers / intervention state.** Current risks, open decisions, or active reasons to stop.
+- **Goal:** the agreed finish line and relay-specific scope. Current status cannot override it.
+- **Baton:** current position, completed work, what remains, relevant evidence and decisions, useful pointers, and any blocker.
+- **History:** concise entries recording each leg's result, decisions, artifacts, checks, and handoff or stop.
 
-Think of `status.md` as the thing passed from runner to runner. If it grows into a history dump, compress it back into current state plus pointers. If an older relay lacks leg tracking, repair it when you update status; prefer the leg number from the prompt or status, and do not read `log.md` end-to-end just to count prior legs.
+Keep the baton compact. Use history for targeted lookup, not mandatory reconstruction. Inspect the actual work as needed; the record saves rediscovering prior decisions, not reading the project.
 
-**Log** (`log.md`) — append-only history. Each leg appends a concise entry recording what it did, decisions made and why, durable artifacts changed, status updates made, and blockers. The log preserves auditability, but it is **not** orientation memory.
+## Signal over spin
 
-Do not read `log.md` end-to-end by default. Read targeted log entries only when `status.md` points to them, when the charter requires a specific lookup, or when there is an inconsistency you must resolve before continuing.
+Stop when the finish line is met, with evidence. Completion does not require finding another improvement.
 
-Optional files such as `plan.md`, `backlog.md`, or artifact notes are fine, but runners should read them only when the charter/status points to the relevant part.
+Stop visibly when progress needs human input: record the blocker, what was tried, and the specific decision or help needed. If successive legs keep revisiting the same issue without new evidence or meaningful progress, surface that stall instead of spawning another attempt.
 
-## Context containment rule
+Optional cleanup, hypothetical risks, and a desire for perfection are not reasons to prolong the chain. Revisit a settled decision when facts change or concrete evidence shows it was wrong, not merely because a fresh agent has arrived.
 
-A runner normally reads:
-
-1. `charter.md`
-2. `status.md`
-3. Only the specific files or log entries referenced for the current leg
-
-Do not defensively rebuild the relay's full history. Do not read the full log, the full backlog, or a large artifact tree just because they exist. The relay stays scalable because each runner pays only for the context needed now.
-
-If `status.md` is insufficient, fix the baton rather than compensating by reading everything. Use targeted inspection to clarify the current state, update `status.md` so the next runner has a clean start, and continue only if the task is still clear. If reconstructing the state would require broad archaeology or judgment about past intent, stop and raise the intervention signal.
-
-## Running one leg
-
-This is the loop you run when you are dispatched into a relay.
-
-1. **Orient from the packet.** Read `charter.md` and `status.md`. Confirm the relay name/root, goal, sizing, handoff protocol, last completed leg, next leg to run, intervention signal, and current/next task. If you are not sure you are in a relay, the prompt or `.pi-web/relays/` is your clue — and reading this skill means you are.
-2. **Choose the leg.** Prefer the explicit current/next task in `status.md`. If none is named, apply the charter's task selection policy. If that still requires context, inspect only the referenced plan/backlog/artifact sections. If the next task is still ambiguous or would materially change direction, stop and involve the human.
-3. **Re-anchor to the goal.** Does the goal still make sense given the status and what you now see? If reality has diverged from the charter, that is often an intervention moment — don't quietly redefine the task.
-4. **Run one leg.** Do exactly one well-sized slice, per the charter's sizing. Resist doing "just a bit more" — extra scope bloats context and breaks the containment that makes Relay work.
-5. **Document progress.** Make all work durable. Update `status.md` with the new current state, last completed leg, next leg to run (if any), next task or task-selection pointer, relevant context for the next runner, and blockers. Append a concise `log.md` entry with what you did, why, decisions made, artifacts changed, and whether you are handing off or stopping.
-6. **Decide: hand off, or stop.**
-   - **Hand off** if there is a clear next leg and you are on track. Use `spawn_session` once, with a prompt whose first line is a natural task header containing the relay name and next leg number (for example, `Relay "<name>" leg <N> begins now.`), followed by the Relay method and pointers to `charter.md` and `status.md` (so this skill loads and they can orient cheaply). Then you are done. Handoff is deliberately fire-and-forget: `spawn_session` starts an independent session you will not see and cannot steer — do not reach for a tracked subsession to keep an eye on it. Letting go is the point. The next runner is trusted to run their own leg, and the relay packet is the only thread between you; if you feel the need to watch downstream work, that usually means the leg wasn't sized or handed off cleanly, or an intervention signal should have fired.
-   - **Stop — do not spawn —** if the goal is reached, or you are blocked, or the charter's intervention signal fires. Update `status.md`, append a clear note in `log.md`, and raise the intervention signal so the watching human sees exactly what happened and what they need to decide. A stalled relay that stopped cleanly with a clear blocker is a success; a relay that spawned a confused next runner is a failure.
-
-A good handoff prompt is short and explicit. Put the relay identity and leg number at the very beginning so PI-WEB's session title generator sees useful distinguishing context without any naming instruction:
-
-```text
-Relay "<name>" leg <N> begins now.
-
-You are the next runner in this Relay method chain.
-
-Read:
-- .pi-web/relays/<name>/charter.md
-- .pi-web/relays/<name>/status.md
-
-Do not read log.md end-to-end. Use it only for targeted lookup if status.md or charter.md points you there.
-
-Run one leg according to the charter. Before handing off, update status.md, append log.md, make work durable, then either spawn the next leg once or stop with a clear intervention note.
-```
-
-## Planning a relay
-
-When the user asks to set up a relay, your job is to produce the relay packet: `charter.md`, `status.md`, and `log.md`. The charter must have the required slots filled: relay identity, goal, sizing, task selection policy, handover, intervention signal, and reading discipline. The initial status must give the first runner a compact baton: current position, leg tracking (usually last completed leg 0 and next leg to run 1 for a new relay), first task or task selection pointer, relevant context, documentation expectations, and known blockers. The log may start empty or with a short seed entry explaining that the relay was created.
-
-Draw the required choices out from the user rather than inventing them: ask what the finish line is, how much should be one leg, how runners pick tasks, how runners hand off, what they should read, and when they must stop and get the human. Sizing, task selection, and the intervention signal especially are the user's to decide — propose options if it helps them think, but do not quietly settle them yourself.
-
-Do **not** impose what a "good" plan, leg size, or cadence looks like — those are deeply project-, plan-, and human-specific, and getting them wrong by being prescriptive is worse than leaving them to the user. Your value in planning is making sure the relay is *runnable*: the finish line exists, sizing is stated, task selection is stated, handover is stated, reading discipline is stated, and the intervention signal is stated. Once the packet is agreed, you can dispatch the first leg with `spawn_session`.
-
-## Smells to watch for
-
-- **No finish line** → infinite relay. Refuse to run a relay without a defined goal.
-- **Goal drift** → each leg quietly restates the task. Re-anchor every leg.
-- **Charter churn** → the charter changes every leg. The design isn't settled; involve the human.
-- **Status bloat** → `status.md` turns into a history dump. Compress it to current state plus targeted pointers.
-- **Defensive reading** → reading the full log/backlog/artifact tree to feel safe. Use the packet and targeted lookups; stop if the baton is not enough.
-- **Eager spawning** → spawning early, spawning several runners, or spawning before work is durable. One leg, one handoff, at the end.
-- **Silent stall** → getting stuck and stopping with no note, or spawning anyway. Always update status, log the blocker, and surface it.
+Tools, storage, and session creation belong to the environment-specific runner skill, not the definition of Relay.

package/skills/relay-runner/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: relay-runner
+description: "Prepare and run Relay legs in Pi: keep the goal, baton, and log durable, then hand off to one fresh session or stop visibly. Use with relay for /relay, /relay-worktree, or a handoff naming relay-runner. Supplies continuity and a bounded fresh-context final review without prescribing the development route."
+---
+
+# Relay runner
+
+This skill binds the `relay` method to Pi sessions and a small file packet. It supplies continuity and one completion gate: a fresh-context final review. The development route remains adaptive. Each agent discovers applicable project instructions and skills through the repository and harness; do not copy them into the packet or preselect them for future legs.
+
+## Packet
+
+Use `.pi-web/relays/<name>/` in the working checkout unless the user selects another location inside the target workspace. Start with three files:
+
+- **`charter.md` — goal.** The agreed outcome and recognizable finish line, relay-specific scope boundaries and clarifications, and any explicit human requirements. Reference an existing specification when useful. Do not add project rules, implementation plans, or generic quality or delivery procedures; include such details only when the human explicitly asks.
+- **`status.md` — baton.** State (`Draft — awaiting approval; not dispatched`, `Active`, `Complete`, or `Needs help`), last completed leg and next leg number, working location, current progress, remaining gaps to the goal, relevant checks, current review state, targeted pointers, and blockers. Include only what is useful now. Avoid suggesting the next slice; record remaining gaps and concrete dependencies instead.
+- **`log.md` — history.** Append a short entry per leg: what changed or was learned, important decisions and why, artifact or commit references, checks and actual results, and the next leg or stop. Record human approval and scope changes here too.
+
+Charter = agreement; status = position; decisions = durable reasoning; log = history. Keep revisions in the log, not a separate revisions document; no decision template is required. Status, decisions, and the log cannot silently change the agreement. Keep relay-specific decisions durable without adding documents merely to satisfy a template. The packet is not a second home for project policy or this skill's instructions.
+
+Add **`decisions.md` only when useful**: a compact, living record of consequential decisions and their reasons, including rejected approaches or review concerns worth remembering. Keep current conclusions there and record revisions in the log. Link it from status and consult relevant entries rather than duplicating the reasoning in the baton. It is not a plan, task list, or another home for project rules. Human changes to the goal or scope still belong in the charter. Do not create an empty register or impose a decision template.
+
+## Preparation and dispatch
+
+The preparation prompt owns discussion and approval. Drafting is allowed before approval; `dispatch_relay` is not. After the human reviews the goal and boundaries, require an explicit **Approve and dispatch** response. If the approved goal, scope, or working target changes materially, obtain fresh approval.
+
+Use the current checkout for `/relay` unless the user chooses another. For `/relay-worktree`, create a fresh branch and worktree after approval, following project conventions; use current HEAD as the starting point unless another base is agreed. Ask about a material target ambiguity rather than guessing. Move the draft packet into the target checkout before dispatch, update its location, and remove the stale drafting copy.
+
+Record the actual checkout and, in Git, branch and starting commit in status. Keep packet files out of delivery commits using an existing ignore rule or a local Git exclusion. Leave unrelated existing work untouched. Bootstrap the target as needed under project conventions; setup does not automatically require a separate leg.
+
+Record approval in status/log, mark status `Active`, and seed leg 1. The first runner chooses its own slice; preparation need not prescribe one. Dispatch with the same handoff mechanics used by later legs.
+
+## Run a leg
+
+1. Read the charter and status, then inspect relevant project guidance and work. Consult only the history or supporting material needed to understand the current state. Repair small record gaps with targeted inspection; ask for help if the goal or ownership is unclear.
+2. Compare reality with the finish line and completion requirements, including the final review below. If all are satisfied, record completion and stop. Otherwise choose one useful, context-sized slice that closes a remaining gap. Briefly state in the session which slice you chose and how it advances the goal.
+3. Do the work and the checks appropriate to it under project conventions. Record failed, skipped, or incomplete checks honestly.
+4. Make the result durable before handoff. In Git, commit the leg's changes when project policy and human instructions permit, without including unrelated changes or the packet. Otherwise record the exact saved work and why it is uncommitted. Finish any helpers before handing off.
+5. Refresh the compact status and append the log entry. Record progress against the goal, important evidence and decisions, remaining gaps, and any limitations the successor needs to know. Then complete, ask for help, or hand off once.
+
+Other reviews, delivery steps, and gates apply only when the human or project requires them. Keep this skill's review procedure here, not copied into the packet.
+
+## Final review
+
+When a leg finishes substantive work and believes implementation is done, record that final review is pending and hand off to a fresh leg. A fresh runner finding implementation complete with review pending performs the review instead of passing it on again. Leave substantive corrections to another leg so the review stays independent.
+
+Review the whole relay result, not just the last slice, against the charter and applicable project guidance. Approve when no concrete, evidence-backed in-scope blocker remains. Optional improvements, speculative concerns, and unrelated pre-existing shortcomings do not block completion. Record consequential finding dispositions in `decisions.md` when useful.
+
+Allow **at most three review attempts total**: the initial review and up to two post-correction reviews, not three mandatory passes. Keep the attempt count, latest result, and reviewed work reference in status; put evidence and findings in the log or link to decisions. Subsequent attempts happen only after concrete corrections and focus on those corrections and changed evidence, carrying supported prior decisions forward rather than restarting an expanding audit.
+
+If the third attempt still has blockers, or a required further review would exceed the budget, mark `Needs help`, record what remains, and stop without dispatching another review or correction leg. A valid approval satisfies the gate; a new context or packet-only update does not reopen it. Material changes to the reviewed result require re-review within the same budget.
+
+## Stop or hand off
+
+Mark `Complete` and report the result and evidence when no required work remains and final review has passed for the current result. Do not spawn a successor to search for extra work.
+
+Mark `Needs help` when a decision, permission, environment problem, or lack of progress prevents responsible continuation. Record the concrete blocker, attempts and evidence, and the smallest question or action needed from the human. Surface it clearly in the user-facing response; use `ask_user` when an answer is needed. Do not hand a human-dependent blocker to another context hoping it will disappear.
+
+Before continuing, check that concrete required work remains, including any pending final review; leave slice selection to the successor.
+
+For handoff, finish work and all packet writes first. The charter supplies the goal and saved `status.md` is the actual baton: save progress, remaining gaps, decisions, checks and blockers there, with targeted pointers to supporting records as needed. Do not put missing continuity into a separate handover prompt.
+
+Call the dedicated `dispatch_relay` tool at most once with the saved directory as `packet`, the next leg identity as `leg`, and the target checkout as `cwd`. A relative `packet` resolves inside that `cwd`; custom packet locations must also stay inside the target workspace. Pass `leg` as a string: the next leg number written as `"2"`, or an explicitly chosen identifier of 1–32 letters, digits, dots, underscores or hyphens, starting with a letter or digit. Non-string values are rejected rather than converted. For example, substitute the actual paths and next leg:
+
+```json
+{
+  "packet": ".pi-web/relays/<name>",
+  "leg": "2",
+  "cwd": "/absolute/path/to/checkout"
+}
+```
+
+The tool validates the saved packet, generates the handover instructions, and records explicit Relay identity and a predictable session name. It accepts no free-form prompt and starts an independent session; do not substitute a generic session tool or tracked subsession. Omit `model` and `thinkingLevel` to inherit them unless the human instructed otherwise; keep any relay-wide instruction in the packet.
+
+`dispatch_relay` is the final operational action. After it returns, give only a brief handoff summary: no further tool use, packet writes, work, or downstream supervision. If the tool is unavailable or dispatch fails, report the failure rather than claiming the next leg started.