@jmfederico/pi-web 1.202609.0 → 1.202610.0

package/dist/pi-packages/captains-log/dist/roundtrip.js

@@ -0,0 +1,62 @@
+// Generated from pi-packages/captains-log/src/roundtrip.ts. Do not edit directly.
+import { MAX_FINDINGS, CAPTAIN_REPLY, CAPTAIN_REQUEST, SOURCE_REPLY, SOURCE_REQUEST } from "./browser/protocol.js";
+export function collectReply(connection, requestId, text, lifetime, progress) {
+    return collect(connection, requestId, { requestId, text }, CAPTAIN_REQUEST, CAPTAIN_REPLY, lifetime, progress);
+}
+export function collectSourceReply(connection, requestId, lifetime, progress) {
+    return collect(connection, requestId, { requestId }, SOURCE_REQUEST, SOURCE_REPLY, lifetime, progress);
+}
+/** Subscribe before sending. Never retry an ambiguous send or cancel Pi on timeout. */
+async function collect(connection, requestId, payload, requestEvent, replyEvent, lifetime, progress) {
+    const signal = AbortSignal.any([lifetime, connection.signal]);
+    signal.throwIfAborted();
+    let unsubscribe;
+    let onAbort;
+    let receiptTimer;
+    let completionTimer;
+    try {
+        return await new Promise((resolve, reject) => {
+            onAbort = () => { reject(new Error("Captain connection interrupted; agent work may continue in Sessions")); };
+            signal.addEventListener("abort", onAbort, { once: true });
+            receiptTimer = setTimeout(() => { reject(new Error("No companion receipt within 5 seconds. Check package enablement/trust; inspect Sessions before retrying.")); }, 5_000);
+            completionTimer = setTimeout(() => { reject(new Error("Captain request exceeded 10 minutes; agent work may continue in Sessions. No translation saved.")); }, 600_000);
+            unsubscribe = connection.on(replyEvent, (data) => {
+                if (typeof data !== "object" || data === null || !("requestId" in data) || data.requestId !== requestId)
+                    return;
+                if (!("status" in data))
+                    return;
+                if (data.status === "accepted") {
+                    clearTimeout(receiptTimer);
+                    progress("Native companion received request");
+                    return;
+                }
+                if (data.status === "running") {
+                    progress("Native Pi agent running");
+                    return;
+                }
+                if (data.status === "failed") {
+                    reject(new Error("error" in data && typeof data.error === "string" ? data.error.slice(0, 4000) : "Captain request failed"));
+                }
+                else if (data.status === "completed") {
+                    if (!("text" in data) || typeof data.text !== "string" || !data.text.trim() || data.text.length > MAX_FINDINGS) {
+                        reject(new Error("Invalid companion reply"));
+                    }
+                    else {
+                        progress("Backend received correlated final reply");
+                        resolve(data.text);
+                    }
+                }
+            });
+            // Native listeners can reply synchronously.
+            progress("Backend sent request to native companion");
+            connection.emit(requestEvent, payload);
+        });
+    }
+    finally {
+        clearTimeout(receiptTimer);
+        clearTimeout(completionTimer);
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+        unsubscribe?.();
+    }
+}

package/dist/pi-packages/captains-log/dist/server.js

@@ -0,0 +1,210 @@
+// Generated from pi-packages/captains-log/src/server.ts. Do not edit directly.
+import { randomUUID } from "node:crypto";
+import { PI_WEB_HOST_PI_SESSIONS_CAPABILITY, PI_WEB_HOST_PI_SESSION_EVENTS_CAPABILITY } from "@jmfederico/pi-web/server-plugin-api";
+import {} from "./browser/protocol.js";
+import { LOG_CHANNEL, entryFrames, isCaptainClientFrame } from "./browser/channelProtocol.js";
+import { collectReply, collectSourceReply } from "./roundtrip.js";
+import { LogStore, logScope } from "./store.js";
+const plugin = {
+    apiVersion: 3,
+    name: "Captain's Log",
+    requires: [PI_WEB_HOST_PI_SESSIONS_CAPABILITY, PI_WEB_HOST_PI_SESSION_EVENTS_CAPABILITY],
+    activate(host) {
+        const store = new LogStore(host.dataDirectory);
+        const active = new Map();
+        const unsaved = new Map();
+        const currentSessions = new Map();
+        const subscribers = new Map();
+        const channelCleanups = new Set();
+        function publish(scope, entry, saved) {
+            for (const frame of entryFrames(entry, saved))
+                for (const send of subscribers.get(scope) ?? [])
+                    send(frame);
+        }
+        const tasks = new Set();
+        let sessions;
+        let events;
+        function visible(scope, entry) {
+            const live = active.get(scope);
+            if (live?.id === entry.id)
+                return live;
+            return unsaved.get(entry.id) ?? (entry.status === "running"
+                ? { ...entry, status: "interrupted", failureCode: "interrupted", text: "Captain's Log stopped before recording completion. Inspect the previous session before retrying. Nothing was resent automatically." }
+                : entry);
+        }
+        return {
+            start({ capabilities }) {
+                sessions = capabilities.resolve(PI_WEB_HOST_PI_SESSIONS_CAPABILITY);
+                events = capabilities.resolve(PI_WEB_HOST_PI_SESSION_EVENTS_CAPABILITY);
+            },
+            peer: {
+                async request(context) {
+                    context.signal.throwIfAborted();
+                    host.lifetimeSignal.throwIfAborted();
+                    const selection = { projectId: context.project.id, workspaceId: context.workspace.id };
+                    const scope = logScope(selection.projectId, selection.workspaceId);
+                    if (context.operation === "list") {
+                        const entries = (await store.list(scope)).map((entry) => visible(scope, entry));
+                        const live = active.get(scope);
+                        if (live && !entries.some((entry) => entry.id === live.id))
+                            entries.unshift(live);
+                        return entries.map((entry) => ({ ...entry, text: "" }));
+                    }
+                    if (context.operation === "read") {
+                        const live = active.get(scope);
+                        return { ...(live?.id === context.input ? live : visible(scope, await store.read(scope, context.input))) };
+                    }
+                    throw new Error("Unknown Captain operation (translations require the log channel)");
+                },
+                openChannel(context) {
+                    context.signal.throwIfAborted();
+                    host.lifetimeSignal.throwIfAborted();
+                    if (context.operation !== LOG_CHANNEL || context.input !== null)
+                        throw new Error("Invalid Captain channel open");
+                    const selection = { projectId: context.project.id, workspaceId: context.workspace.id };
+                    const scope = logScope(selection.projectId, selection.workspaceId);
+                    let listening = true;
+                    const send = (frame) => {
+                        if (!listening)
+                            return;
+                        try {
+                            context.send(frame.type === "entry" ? { ...frame, entry: { ...frame.entry } } : frame);
+                        }
+                        catch (error) {
+                            cleanup();
+                            host.logger.warn(`Captain subscriber disconnected: ${String(error)}`);
+                        }
+                    };
+                    const cleanup = () => {
+                        listening = false;
+                        subscribers.get(scope)?.delete(send);
+                        if ((subscribers.get(scope)?.size ?? 0) === 0)
+                            subscribers.delete(scope);
+                        context.signal.removeEventListener("abort", cleanup);
+                        host.lifetimeSignal.removeEventListener("abort", cleanup);
+                        channelCleanups.delete(cleanup);
+                    };
+                    if (!subscribers.has(scope))
+                        subscribers.set(scope, new Set());
+                    subscribers.get(scope)?.add(send);
+                    context.signal.addEventListener("abort", cleanup, { once: true });
+                    host.lifetimeSignal.addEventListener("abort", cleanup, { once: true });
+                    channelCleanups.add(cleanup);
+                    return {
+                        close: cleanup,
+                        async receive(data, signal) {
+                            signal.throwIfAborted();
+                            host.lifetimeSignal.throwIfAborted();
+                            if (!isCaptainClientFrame(data))
+                                throw new Error("Invalid Captain translation frame");
+                            const reject = (message) => { send({ type: "rejected", requestId: data.requestId, message: message.slice(0, 2000) }); };
+                            if (active.has(scope)) {
+                                reject("Captain is already working.");
+                                return;
+                            }
+                            const entry = { id: randomUUID(), createdAt: new Date().toISOString(), sessionId: "", question: "Translate last reply", sourceSessionId: data.sourceSessionId, status: "running", stages: ["Backend admitted translation"], text: "Preparing Captain's Log…" };
+                            // Lock before any I/O so concurrent tabs cannot create two dedicated sessions.
+                            active.set(scope, entry);
+                            try {
+                                const previous = await store.list(scope);
+                                // Strictly increasing admission times make persisted session selection independent of UUID ties.
+                                const latestTime = Math.max(0, ...previous.map((record) => Date.parse(record.createdAt)).filter(Number.isFinite));
+                                entry.createdAt = new Date(Math.max(Date.now(), latestTime + 1)).toISOString();
+                                entry.sessionId = currentSessions.get(scope) ?? previous.find((record) => record.sessionId)?.sessionId ?? "";
+                                if (entry.sessionId === data.sourceSessionId || previous.some((record) => record.sessionId === data.sourceSessionId))
+                                    throw new Error("Select a source session other than the pirate conversation.");
+                                await store.save(scope, entry);
+                            }
+                            catch (error) {
+                                active.delete(scope);
+                                reject(String(error));
+                                return;
+                            }
+                            send({ type: "admitted", requestId: data.requestId, id: entry.id });
+                            publish(scope, entry, true);
+                            const progress = (stage) => {
+                                if (!entry.stages.includes(stage) && entry.stages.length < 16)
+                                    entry.stages.push(stage);
+                                publish(scope, entry, false);
+                            };
+                            const task = (async () => {
+                                try {
+                                    host.lifetimeSignal.throwIfAborted();
+                                    const source = await events.connect({ ...selection, sessionId: data.sourceSessionId });
+                                    let sourceText;
+                                    try {
+                                        sourceText = await collectSourceReply(source, entry.id, host.lifetimeSignal, progress);
+                                    }
+                                    finally {
+                                        source.close();
+                                    }
+                                    progress("Source reply read without changing source");
+                                    const createPirate = async () => {
+                                        ({ sessionId: entry.sessionId } = await sessions.create(selection));
+                                        currentSessions.set(scope, entry.sessionId);
+                                        // Persist identity before any potentially ambiguous send.
+                                        await store.save(scope, entry);
+                                        return events.connect({ ...selection, sessionId: entry.sessionId });
+                                    };
+                                    const previousSessionId = entry.sessionId;
+                                    const connection = previousSessionId
+                                        ? await events.connect({ ...selection, sessionId: previousSessionId }).catch((error) => {
+                                            // Only a definitive rejection before sending permits automatic replacement.
+                                            if (error instanceof Error && error.message === "Selected session is not hosted in this workspace on this machine")
+                                                return createPirate();
+                                            throw error;
+                                        })
+                                        : await createPirate();
+                                    progress("Pirate conversation selected");
+                                    try {
+                                        entry.text = await collectReply(connection, entry.id, sourceText, host.lifetimeSignal, progress);
+                                    }
+                                    finally {
+                                        connection.close();
+                                    }
+                                    entry.status = "completed";
+                                }
+                                catch (error) {
+                                    entry.status = "failed";
+                                    entry.failureCode ??= "request-failed";
+                                    entry.text = `Captain could not finish this request. Inspect the session before retrying; nothing was resent automatically.\n${error instanceof Error ? error.message : String(error)}`.slice(0, 4000);
+                                    progress("Backend recorded failure (not success)");
+                                }
+                                let saved = false;
+                                try {
+                                    if (entry.status === "completed")
+                                        entry.stages.push("Backend saved completed roundtrip");
+                                    await store.save(scope, entry);
+                                    saved = true;
+                                }
+                                catch (error) {
+                                    entry.status = "failed";
+                                    entry.failureCode = "request-failed";
+                                    entry.stages = entry.stages.filter((stage) => stage !== "Backend saved completed roundtrip");
+                                    entry.text = `Could not save Captain's Log: ${String(error)}. Inspect session ${entry.sessionId}.`.slice(0, 4000);
+                                    unsaved.set(entry.id, { ...entry });
+                                    host.logger.error(entry.text);
+                                }
+                                finally {
+                                    active.delete(scope);
+                                    publish(scope, entry, saved);
+                                }
+                            })();
+                            tasks.add(task);
+                            void task.finally(() => { tasks.delete(task); });
+                        },
+                    };
+                },
+            },
+            async dispose() {
+                await Promise.all(tasks);
+                for (const cleanup of channelCleanups)
+                    cleanup();
+                active.clear();
+                unsaved.clear();
+                currentSessions.clear();
+            },
+        };
+    },
+};
+export default plugin;

package/dist/pi-packages/captains-log/dist/store.js

@@ -0,0 +1,75 @@
+// Generated from pi-packages/captains-log/src/store.ts. Do not edit directly.
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readdir, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { isLogEntry } from "./browser/protocol.js";
+/** Only host-resolved ids enter the scope hash; peer input is never a filesystem path. */
+export function logScope(projectId, workspaceId) {
+    return createHash("sha256").update(JSON.stringify([projectId, workspaceId])).digest("hex");
+}
+export class LogStore {
+    dataDirectory;
+    constructor(dataDirectory) {
+        this.dataDirectory = dataDirectory;
+    }
+    async directory(scope) {
+        if (!/^[a-f0-9]{64}$/.test(scope))
+            throw new Error("Invalid captain scope");
+        const directory = join(this.dataDirectory, scope);
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        if (!(await lstat(directory)).isDirectory())
+            throw new Error("LogEntry directory must not be a symlink");
+        return directory;
+    }
+    async save(scope, captain) {
+        if (!isLogEntry(captain))
+            throw new Error("Invalid captain record");
+        const directory = await this.directory(scope);
+        const temporary = join(directory, `.${randomUUID()}.tmp`);
+        try {
+            const file = await open(temporary, "wx", 0o600);
+            try {
+                await file.writeFile(JSON.stringify(captain));
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await rename(temporary, join(directory, `${captain.id}.json`));
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    async read(scope, id) {
+        if (typeof id !== "string" || !/^[a-f0-9-]{36}$/.test(id))
+            throw new Error("Invalid captain id");
+        const path = join(await this.directory(scope), `${id}.json`);
+        // O_NOFOLLOW is not enforced on Windows; reject existing links there too.
+        if (!(await lstat(path)).isFile())
+            throw new Error("Invalid captain file");
+        const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.size > 300_000)
+                throw new Error("Invalid captain file");
+            const value = JSON.parse(await file.readFile("utf8"));
+            if (!isLogEntry(value) || value.id !== id)
+                throw new Error("Invalid saved captain");
+            return value;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async list(scope) {
+        const names = await readdir(await this.directory(scope));
+        const captains = [];
+        for (const name of names) {
+            if (/^[a-f0-9-]{36}\.json$/.test(name))
+                captains.push(await this.read(scope, name.slice(0, -5)));
+        }
+        return captains.sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+    }
+}

package/dist/pi-packages/captains-log/docs/usage.md

@@ -0,0 +1,32 @@
+# Using Captain's Log
+
+Select a conversation in the current workspace, open **Captain's Log**, and click **Let the Captain tell it**. The companion reads that session's latest completed assistant reply without sending it a prompt or changing its transcript. A separate pirate conversation retells the text using your configured model. The prompt asks for a fresh, theatrical crew briefing with nautical metaphors and humor—not just a few pirate words. It asks the model to preserve important facts, warnings, and next steps, and keep code and commands exact.
+
+The pirate gets a short introduction on its first prompt and keeps speaking pirate. Further translations use the same conversation while it is loaded in the session daemon. If it is no longer loaded, the next translation automatically creates a new pirate conversation. There are no confirmation dialogs, workspace reviews, or plain-English mode.
+
+To keep the previous pirate's context after a daemon restart, open the most recent **Captain's Log** conversation in Sessions before translating. Once loading finishes, the plugin can reuse it; it need not remain selected. Then select the conversation whose reply you want translated. The plugin does not automatically reopen saved sessions or stop/delete old sessions.
+
+## Results and connections
+
+Use **Open source session** beneath a translation to return to its original conversation in chat, even when another conversation is selected. This action uses the record's machine/project/workspace scope and source session ID. If the source is no longer available, PI WEB shows its normal unavailable-destination message; it does not create a replacement conversation.
+
+- The translation is rendered as Markdown, including headings, lists, emphasis, links, tables, and code blocks. Embedded HTML stays literal, unsafe links are inert, and images are not loaded automatically. **Previous translations** holds earlier results; **Diagnostics** holds session/request IDs and the message trail. Both start collapsed. Existing review-era logs remain on disk but are not shown as translations.
+- The panel inherits PI WEB's workspace styles and themes. The action-palette **Open pirate translator** opens it without spending model tokens.
+- Browser requests and backend progress use a bidirectional peer channel, with no polling. Opening or reconnecting loads a snapshot. Progress is not token-by-token model streaming; the completed translation arrives when the pirate finishes.
+- Closing the panel or browser does not cancel admitted work. Reconnect to recover the result. Requests with uncertain delivery are never automatically resent. Automatic pirate creation happens only before sending a translation, when the previous pirate is confirmed unhosted—not after a timeout or arbitrary connection failure.
+
+## When a translation cannot run
+
+Select an ordinary, unarchived conversation in the same workspace and machine, not the pirate itself. Wait for it to finish responding. It needs a completed assistant reply with text; partial, aborted, failed, and tool-call-only replies are not translations. If the native companion is missing from an existing session, use `/reload` in that session and try again.
+
+Only one panel translation per workspace runs at a time. Busy pirates, direct user messages during a translation, provider errors, aborted or truncated replies, and runtime replacement are reported as failures rather than successful translations. A receipt timeout or completion timeout detaches listeners but does not stop Pi. Inspect the pirate conversation before retrying an uncertain request. Very large source replies or results are rejected rather than silently truncated; see Diagnostics for the reason.
+
+Translations and metadata are stored under the host-provided plugin data directory, scoped to the project/workspace. Pi owns the conversation transcripts. Interrupted records remain visible; there is no durable job resumption or automatic retention policy. The source text is sent to the pirate's model provider. This is trusted agent code, not a tool sandbox.
+
+## Installation and activation
+
+Install from **Settings → Pi packages → Available packages** on the target machine, then explicitly enable **Captain's Log** in **Settings → PI WEB plugins**. The package ships compiled. Manual installation can use `pi install /absolute/path/to/dist/pi-packages/captains-log` with the target machine's Pi profile.
+
+Restart the target session daemon manually when safe, **from outside its hosted sessions**, then reload the browser. A web/API restart alone cannot activate the backend. Existing sessions need `/reload` to load an updated native companion. Project-scoped packages require normal project trust.
+
+Disabling the PI WEB plugin controls its panel/backend, not its native extension. Remove the Pi package to remove both resource declarations; saved conversations and plugin data are retained. The older Workspace Reviews example has a separate plugin ID and must be disabled or removed separately.

package/dist/pi-packages/captains-log/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@jmfederico/pi-captains-log",
+  "version": "0.1.0",
+  "description": "Opt-in Captain's Log: translate the selected session's last reply into pirate through a native Pi companion and PI WEB panel",
+  "private": true,
+  "type": "module",
+  "keywords": ["pi-package"],
+  "files": ["dist", "src", "docs", "test", "tsconfig.json", "vite.config.mjs"],
+  "scripts": { "build": "tsc -p tsconfig.json && vite build", "test": "node --test test/*.test.mjs" },
+  "dependencies": {
+    "marked": "^18.0.6"
+  },
+  "devDependencies": {
+    "@jmfederico/pi-web": "^1.202609.1",
+    "@earendil-works/pi-coding-agent": "^0.87.0",
+    "@types/node": "^24.13.3",
+    "typescript": "^6.0.3",
+    "vite": "^8.1.4"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@jmfederico/pi-web": "^1.202609.1"
+  },
+  "pi": { "extensions": ["./dist/companion.js"] },
+  "piWeb": {
+    "plugins": [{
+      "id": "captains-log",
+      "defaultEnabled": false,
+      "browserRoot": "dist/browser",
+      "module": "dist/browser/index.js",
+      "serverModule": "dist/server.js",
+      "machineSpecific": true
+    }]
+  }
+}

package/dist/pi-packages/captains-log/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": true,
+    "noEmitOnError": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/dist/pi-packages/captains-log/vite.config.mjs

@@ -0,0 +1,28 @@
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vite";
+
+const packageDir = fileURLToPath(new URL(".", import.meta.url));
+
+export default defineConfig({
+  root: packageDir,
+  base: "./",
+  publicDir: false,
+  build: {
+    outDir: "dist/browser",
+    // Retain the transpiled filenames for existing package/install consumers.
+    emptyOutDir: false,
+    copyPublicDir: false,
+    target: "es2022",
+    sourcemap: false,
+    rollupOptions: {
+      input: fileURLToPath(new URL("src/browser/index.ts", import.meta.url)),
+      preserveEntrySignatures: "strict",
+      output: {
+        format: "es",
+        entryFileNames: "index.js",
+        chunkFileNames: "assets/[name]-[hash].js",
+        assetFileNames: "assets/[name]-[hash][extname]",
+      },
+    },
+  },
+});

package/dist/pi-packages/relays/pi-web-plugin.js

@@ -2,7 +2,7 @@
 import { RELAYS_ROOT } from "./relayDiscovery.js";
 import { defineRelaysPanelElement } from "./relaysPanelElement.js";
 const plugin = {
-    apiVersion: 2,
+    apiVersion: 4,
     name: "Relays",
     activate: ({ runtimePluginId, html, svg }) => {
         defineRelaysPanelElement();

package/dist/pi-packages/relays/prompts/relay.md

@@ -19,7 +19,7 @@ The quality of the Relay depends on a clear shared understanding of its destinat
 1. **Start a reviewable draft packet.** Choose a clear Relay name and create `.pi-web/relays/<name>/` in the current drafting checkout. Seed draft `charter.md`, `operations.md`, `status.md`, and `log.md`; mark status **Draft — awaiting approval; not dispatched**. Update these documents as understanding improves so the human can review them through the Relays UI. Draft creation is not dispatch authorization.
 2. **Understand the request and baseline.** Read the repository's canonical agent/contributor instructions and task-relevant project material. Inspect enough current behavior, repository state, and delivery context to distinguish the user's intended outcome from an assumed solution. Keep this bounded to facts that affect the goal, scope edges, feasibility, working location, or first leg; leave implementation archaeology to the Relay.
 3. **Capture understanding without making a roadmap.** Keep `charter.md` to the plain-language goal and observable finish line, minimum outcome acceptance, in-scope edges, explicit non-goals, directly affected behavior to preserve, and material assumptions or human decisions. Put packet/profile identity, proposed operating mode/base, canonical project-guidance pointers, verification/delivery mechanics, and packet isolation in `operations.md`. Put only the proposed first bounded leg and current approval state in `status.md`.
-4. **Do not pre-plan the chain.** Do not create a fixed leg count, work-package hierarchy, exhaustive stage list, expected file/layer map, `plan.md`, or technical design merely to make the Relay look prepared. The route is adaptive. If implementation uncertainty does not change the destination or edges, make the first leg a bounded discovery slice or let its runner resolve it.
+4. **Do not pre-plan the chain.** Do not create a fixed leg count, work-package hierarchy, exhaustive stage list, expected file/layer map, `plan.md`, or technical design merely to make the Relay look prepared. The route is adaptive. Select an implementation-first leg under the runner profile. Reserve research-only work for a concrete unanswered question blocking implementation; routine investigation belongs inside the implementation leg.
 5. **Discuss and refine.** Point the user at the draft packet, summarize the current understanding, ask related material questions together with `ask_user`, and incorporate the answers into the drafts. Do not hide assumptions or settle product, destructive-data, target, base, or delivery choices by guesswork.
 6. **Request approval against the final drafts.** After the user has had a chance to review the final document purposes and content, provide the packet path plus a concise goal/edges, operating-setup, and first-leg summary. Use `ask_user` to offer **Approve and dispatch**, **Revise**, or **Do not dispatch**. The initial request, a clear task, prior general enthusiasm, silence, or permission to create drafts is not dispatch approval. If goal, edges, operating target, or first leg changes materially after approval, update the drafts and obtain fresh approval.
 

package/dist/pi-packages/relays/skills/relay-runner/SKILL.md

@@ -15,6 +15,7 @@ For a Relay using this profile:
 
 - Have the preparation prompt select `relay-runner` before drafting the packet. Record it immediately in draft `operations.md` and retain it as required for every active leg, including implementation, review, remediation, and delivery.
 - Name both `relay` and `relay-runner` in every handoff prompt. Fresh sessions cannot inherit a prior runner's loaded skills.
+- Keep every Relay handoff on the current runner's model by omitting the `model` argument, unless instructed to use a specific model or to choose an appropriate one. Record any Relay-wide model instruction in `operations.md` so it remains available to later runners.
 - Treat the charter as destination and scope edges, `operations.md` as this profile's repository and execution bindings, `status.md` as current position and next work, and repository instructions as the quality and implementation authority.
 - Follow canonical repository policy when it conflicts with a profile default. Record a material operational adaptation in `operations.md`, not the charter. Stop for human intervention when reconciling the conflict would change the finish line or an edge, weaken a protected invariant, or require a product or business decision.
 
@@ -53,19 +54,26 @@ Relay intentionally does not predict the chain. Before dispatch, establish the d
 
 Expected files, subsystems, dependencies, architecture, and sequencing are route assumptions. Keep only what the current or next leg needs in status or a targeted temporary artifact; do not turn route assumptions into stable agreement.
 
-A leg is one context-contained, reviewable slice that leaves coherent durable progress toward the finish line. Prefer a functional, locally verifiable checkpoint. Keep directly coupled implementation, tests or manual checks, contracts, generated outputs, documentation, and integration glue together. Split independent responsibilities rather than splitting mechanically by file or repository layer.
+A leg is one context-contained, reviewable slice that advances the finish line. Development legs implement and verify by default: optimize for the smallest useful behaviour, not the smallest independently testable artifact. A functional checkpoint makes an observable charter outcome available and verifies it through the relevant application boundary. A tested but unused module is a prerequisite, not a functional outcome. Setup, required verification, review and delivery remain legitimate lifecycle legs.
+
+Slice by supported cases across the necessary layers. When a journey is too large, choose a narrower case or a safe partial capability with explicit limitations, keeping the full charter outstanding. Keep directly coupled implementation, checks, contracts, generated outputs, documentation and integration together.
 
 Before substantial work, state the leg's:
 
-- bounded outcome;
-- primary responsibility and expected change surface;
-- coupled verification;
-- deferred dependencies; and
-- checkpoint type: functional or profile-authorized transitional.
+- observable outcome and application boundary;
+- bounded change surface and coupled verification;
+- remaining connection to usable behaviour, if any; and
+- checkpoint type: functional, necessary prerequisite or profile-authorized transitional.
+
+An unconnected prerequisite must name the behaviour it enables and why a connected slice cannot reasonably fit. Its successor prioritizes that connection. Before adding another prerequisite-only leg, reassess the slice and simplify the route; continue only when a concrete dependency still prevents connection.
+
+Routine reading, design, sizing and test investigation belong inside implementation. A research-only leg requires a specific unanswered question blocking responsible implementation: record the blocked behaviour, why available evidence is insufficient and the result needed to proceed. Answer that question and hand off to implementation; intervene if it remains unresolved. Size or complexity alone calls for a smaller implementation slice.
+
+Choose the simplest design satisfying the charter, canonical project rules and concrete risks introduced by the change. Justify additional safeguards against those obligations; keep speculative recovery systems and future-use abstractions outside the slice. Preserve safety when narrowing behaviour.
 
-Persist only conclusions useful to the next runner. If uncertainty prevents responsible sizing, run a bounded discovery leg with a concrete question and durable result instead of mixing broad archaeology with implementation.
+Persist only conclusions useful to the next runner. Keep leg history in the packet log and project documentation focused on current behaviour and contracts.
 
-If a leg grows beyond its context-contained slice, stop broadening before context exhaustion. Finish or revert to a functional checkpoint, or use an already authorized transition. Record the next bounded slice. Do not promise a fixed total leg count.
+If a leg grows beyond its context-contained slice, stop broadening before context exhaustion. Finish or revert to a coherent functional or justified prerequisite checkpoint, or use an already authorized transition. Record the next bounded slice. Do not promise a fixed total leg count.
 
 When status does not name the next task, choose the smallest coherent slice that advances the critical path or unblocks an agreed outcome. Do not invent cleanup or speculative follow-up merely to fill a leg.
 
@@ -130,7 +138,7 @@ Do **not** put a quality bar, technical design, expected files or subsystems, ve
 Write the profile's mechanics to `operations.md` instead:
 
 - packet identity and `relay-runner` as the profile required in every leg and handoff;
-- adaptive leg sizing and critical-path task selection, with route assumptions provisional and no fixed leg count;
+- implementation-first leg sizing and outcome-led task selection under this profile, with route assumptions provisional and no fixed leg count;
 - pointers to canonical repository instructions and applicable project skills;
 - checkpoint and transition policy;
 - packet root, working location, branch, immutable base commit, initial HEAD, pre-existing state, packet isolation, and exact review range;
@@ -158,11 +166,11 @@ Use this loop:
 
 1. Read `charter.md`, `operations.md`, `status.md`, and only targeted context they reference. Then load canonical project skills applicable to this leg.
 2. Confirm that the prompt's leg identifier, status baton, working location, branch, and blockers are consistent. Resolve small baton defects with targeted inspection; intervene instead of broad archaeology or guessing about intent.
-3. Choose the explicit next task from status when it fits the charter and leg size. Otherwise apply the operations record's critical-path task-selection policy. If the task remains ambiguous or falls outside the finish line, intervene.
+3. Use status's next outcome as the starting point. Revise inherited sequencing or design when a simpler connected slice better advances it. Safe implementation splits within the charter are runner decisions, not approval requests. If the intended outcome remains ambiguous or falls outside the finish line, intervene.
 4. Re-anchor to the finish line and perform the containment check. Do exactly one bounded slice. Do not audit unrelated code, execute the next nominal leg too, or expand scope under the guise of quality.
 5. Run every focused check meaningful for the slice and report exact results. Before whole review, run the full verification named by `operations.md`. Never describe failed, skipped, or incomplete verification as passing.
 6. Make delivery changes durable under the operations record's commit policy without absorbing unrelated state. Keep packet-only writes out of delivery commits.
-7. Update status with the new position, completed and next leg identifiers, next task or selection pointer, targeted context, verification state, blockers, and active transition/review pointers. Append the concise leg entry to the log before stopping or handing off.
+7. Update status with the observable progress, completed and next leg identifiers, next outcome, existing seam to connect, concrete constraints, remaining unconnected work, targeted context, verification state, blockers and active transition/review pointers. Keep route choices provisional. Append the concise leg entry to the log before stopping or handing off.
 8. Stop without spawning when Relay completion is recorded, the leg is blocked, or an intervention trigger fires. When the chartered outcome is implemented but required review, approval, or delivery remains, name that lifecycle work as the next leg instead of stopping. Surface the intervention signal clearly. Otherwise hand off exactly once at the end with `spawn_session`.
 
 Use this handoff shape, substituting the actual paths and next identifier:
@@ -177,7 +185,7 @@ Load the `relay` and `relay-runner` skills, then read:
 - .pi-web/relays/<name>/status.md
 
 Do not read log.md end-to-end. Use only targeted entries referenced by charter.md, operations.md, or status.md.
-Run exactly one leg, make its work and packet updates durable, then either hand off once or stop with the recorded intervention signal.
+Run exactly one outcome-led leg under the profile's implementation-first rules. Use status's next outcome and connection priority; adapt the route within the charter. Make work and packet updates durable, then either hand off once or stop with the recorded intervention signal.
 ```
 
 ## Whole-work review and remediation
@@ -200,7 +208,7 @@ For each attempt:
 - When attempt 2 has a blocking finding, do not automatically consume attempt 3. Invoke the remediation contingency only when concrete evidence shows that an attempted remediation reasonably expected to resolve a blocker did not, remediation introduced an in-scope regression, or materially new evidence reveals a blocker that could not reasonably have been assessed earlier—and one bounded remediation is likely to resolve it. Record that justification, mark the contingency invoked, and dispatch one coherent remediation leg followed by attempt 3. Expanded scrutiny, a changed standard, deferred already-available evidence, or speculative possibility does not qualify. If a genuine blocker remains but the contingency is not justified or bounded, intervene.
 - When exceptional attempt 3 still has any blocking finding, stop the automatic loop. Record the unresolved findings and exact decision needed, raise the human intervention signal, and do **not** dispatch remediation or a fourth review. A human may accept an authorized risk, change the agreement, stop the Relay, or explicitly grant a bounded additional remediation/review attempt.
 
-The reviewer chooses proportionate independent review and records that decision. Independent subreviews are optional; use them only when a specific changed surface benefits from focused expertise, not to create review theater or increase the chance of finding something. The reviewer may use `spawn_subsession` for report-only focused reviews, then `yield_to_subsessions` and consolidate. Subreview prompts must identify repository, base and exact diff, the charter's goal and edges, canonical quality instructions, and the prohibition on all writes including packet changes. The consolidating reviewer is the sole packet writer. Do not assume a particular model is available. The Relay handoff still uses one `spawn_session` only at the end of the leg.
+The reviewer chooses proportionate independent review and records that decision. Independent subreviews are optional; use them only when a specific changed surface benefits from focused expertise, not to create review theater or increase the chance of finding something. The reviewer may use `spawn_subsession` for report-only focused reviews, then `yield_to_subsessions` and consolidate. Subreview prompts must identify repository, base and exact diff, the charter's goal and edges, canonical quality instructions, and the prohibition on all writes including packet changes. The consolidating reviewer is the sole packet writer. The Relay handoff still uses one `spawn_session` only at the end of the leg.
 
 A blocking finding needs concrete evidence of an in-scope defect: for example a reproduced failure, a failing relevant check, a specific execution path that violates the approved outcome, or a clear breach of a material contract, invariant, security, authorization, or data-integrity boundary. Mere possibility, stylistic preference, optional hardening, hypothetical future requirements, or “there could be an edge case” is not blocking. If proportionate targeted inspection cannot establish applicability and impact, classify the concern as non-blocking or omit it rather than forcing remediation.
 

package/dist/pi-web-plugins/files/browser/assets/files-icon-DZObYhxb.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M3 6.5A2.5 2.5 0 0 1 5.5 4H10l2 2h6.5A2.5 2.5 0 0 1 21 8.5v8A2.5 2.5 0 0 1 18.5 19h-13A2.5 2.5 0 0 1 3 16.5z"/>
+</svg>