pstack-claude-mirror 0.0.0-stage → 0.9.133

package/plugins/pstack/pi/one-shot.ts

@@ -0,0 +1,90 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { AgentRunner } from "./agents.ts";
+import type { Settings } from "./config.ts";
+
+const PENDING_POLL_MS = 50;
+
+export interface OneShot {
+  exits(ctx: Pick<ExtensionContext, "mode">): boolean;
+  untilSettled(): Promise<void>;
+  assertStartsRun(prompt: string, ctx: ExtensionContext): Promise<void>;
+  dispose(): void;
+}
+
+// Why Pi would start no run for a prompt this extension sends, by the checks
+// its prompt() makes first: an extension command runs in place, and a prompt
+// without a model or credentials is refused. No settle follows either, and Pi
+// reports a refusal only to its own error listeners, so a one-shot /loop
+// waiting on the settle would never return. It cannot see an input handler
+// that consumes the prompt.
+async function noRunReason(pi: ExtensionAPI, prompt: string, ctx: ExtensionContext): Promise<string | undefined> {
+  if (prompt.startsWith("/")) {
+    const space = prompt.indexOf(" ");
+    const name = prompt.slice(1, space === -1 ? undefined : space);
+    if (pi.getCommands().some((command) => command.source === "extension" && command.name === name)) {
+      return `/${name} is an extension command, not a prompt`;
+    }
+  }
+  const model = ctx.model;
+  if (!model) return "no model is selected";
+  if (ctx.modelRegistry.hasConfiguredAuth(model)) return undefined;
+  const available = await ctx.modelRegistry.getAvailableOfType("chat", model.provider);
+  return available.length ? undefined : "the selected model has no credentials";
+}
+
+// Resolves once Pi has a queued message, which is the same condition Pi checks
+// after agent_before_settle returns to decide whether the run continues.
+function pendingMessage(ctx: ExtensionContext, signal: { done: boolean }): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setInterval(() => {
+      if (!signal.done && !ctx.hasPendingMessages()) return;
+      clearInterval(timer);
+      resolve();
+    }, PENDING_POLL_MS);
+    timer.unref();
+  });
+}
+
+// Everything that follows from "this process ends when the run settles":
+// a background agent's notice would be lost, so the settle is held until one
+// exits or a message arrives; /loop must wait for the run it started; a wakeup
+// could never fire; Ctrl-C must take the children along, since pi's one SIGINT
+// listener outside interactive mode is signal-exit's, which re-raises the signal
+// and so skips the exit hook.
+export function registerOneShot(pi: ExtensionAPI, settings: Settings, runner: Pick<AgentRunner, "nextExit">): OneShot {
+  // Print and json runs exit once the agent settles. A pstack child is an rpc
+  // process whose parent closes its stdin at the same moment, so it is one-shot too.
+  const exits = (ctx: Pick<ExtensionContext, "mode">) => ctx.mode === "print" || ctx.mode === "json" || settings.depth > 0;
+  const settleWaiters: (() => void)[] = [];
+  const settle = () => {
+    for (const resolve of settleWaiters.splice(0)) resolve();
+  };
+  // The exit hook in index.ts signals the children.
+  const onSigint = () => process.exit(130);
+  pi.on("session_start", (_event, ctx) => {
+    if (exits(ctx) && !process.listeners("SIGINT").includes(onSigint)) process.on("SIGINT", onSigint);
+  });
+  pi.on("agent_before_settle", async (_event, ctx) => {
+    if (!exits(ctx) || ctx.hasPendingMessages()) return;
+    const signal = { done: false };
+    await Promise.race([runner.nextExit(), pendingMessage(ctx, signal)]);
+    signal.done = true;
+  });
+  pi.on("agent_settled", settle);
+  return {
+    exits,
+    untilSettled: () => new Promise<void>((resolve) => settleWaiters.push(resolve)),
+    assertStartsRun: async (prompt, ctx) => {
+      const reason = await noRunReason(pi, prompt, ctx);
+      if (reason === undefined) return;
+      // Pi prints a command handler's throw and still exits 0.
+      process.exitCode = 1;
+      throw new Error(`No run would start: ${reason}`);
+    },
+    dispose: () => {
+      process.off("SIGINT", onSigint);
+      settle();
+    },
+  };
+}

package/plugins/pstack/pi/path-skills.ts

@@ -0,0 +1,54 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { isAbsolute, join, matchesGlob, relative, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { frontmatter } from "./agent-files.ts";
+import type { Settings } from "./config.ts";
+
+const FILE_TOOLS = new Set(["read", "edit", "write"]);
+
+interface PathSkill {
+  name: string;
+  file: string;
+  globs: string[];
+}
+
+function parsePaths(file: string, globs: unknown): string[] {
+  if (Array.isArray(globs) && globs.every((g): g is string => typeof g === "string")) return globs;
+  throw new Error(`${file}: paths must be a JSON array of globs`);
+}
+
+// Skills whose frontmatter names `paths:` globs, the files that should load them.
+function pathSkills(pluginRoot: string): PathSkill[] {
+  const dir = join(pluginRoot, "skills");
+  if (!existsSync(dir)) return [];
+  const skills: PathSkill[] = [];
+  for (const name of readdirSync(dir).sort()) {
+    const file = join(dir, name, "SKILL.md");
+    if (!existsSync(file)) continue;
+    const globs = frontmatter(readFileSync(file, "utf8")).fields.paths;
+    if (globs != null) skills.push({ name, file, globs: parsePaths(file, globs) });
+  }
+  return skills;
+}
+
+// Claude Code loads a skill with `paths:` when a matching file is touched; Pi
+// has no such hook, so the first matching tool result carries a note instead.
+export function registerPathSkills(pi: ExtensionAPI, settings: Settings): void {
+  const skills = pathSkills(settings.pluginRoot);
+  const noted = new Set<string>();
+  pi.on("tool_result", (event, ctx) => {
+    if (!FILE_TOOLS.has(event.toolName) || event.isError) return;
+    const raw = event.input.path;
+    if (typeof raw !== "string") return;
+    const rel = relative(ctx.cwd, isAbsolute(raw) ? raw : resolve(ctx.cwd, raw)).split("\\").join("/");
+    const skill = skills.find((s) => !noted.has(s.name) && s.globs.some((g) => matchesGlob(rel, g)));
+    if (!skill) return;
+    noted.add(skill.name);
+    const note = `pstack: ${rel} matches the ${skill.name} skill's paths. Load that skill now (read ${skill.file}) and follow it while you work on this file.`;
+    return {
+      content: [...event.content, { type: "text", text: note }],
+      structuredContent: event.structuredContent,
+    };
+  });
+}

package/plugins/pstack/pi/prompt.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { readSheet, type Settings } from "./config.ts";
+
+const MANDATE_SECTION = "pstack-session-start";
+const SHEET_SECTION = "pstack-models";
+const PARALLEL_SECTION = "pstack-parallel-calls";
+const TOOLS_SECTION = "pstack-pi-tools";
+
+// pstack skills name Claude Code tools and models. A session with the hook off,
+// a child agent, or a skill invoked directly may never see the pointer in
+// poteto-mode/SKILL.md, so every session gets it here.
+function piToolsNote(pluginRoot: string): string {
+  const file = join(pluginRoot, "skills", "poteto-mode", "references", "pi-tools.md");
+  return `pstack skills are written for Claude Code. When one names a Claude Code tool (Agent, Skill, AskUserQuestion, Bash), a bundled skill, or a Claude model, read ${file} for the Pi equivalent before following it.`;
+}
+// Claude Code's system prompt, word for word but for its function_calls block.
+// pstack skills that say "one message, N Agent calls" rely on it.
+const PARALLEL_CALLS =
+  "If you intend to call multiple tools and there are no dependencies between the calls, make all of the independent calls in the same response, otherwise you MUST wait for previous calls to finish first to determine the dependent values.";
+
+// Claude Code runs the session hook and loads the sheet through a CLAUDE.md
+// include; Pi has neither, so both ride as system prompt sections, set again
+// on every agent start so compaction cannot drop them.
+// A child gets the sheet, as a Claude Code subagent sees CLAUDE.md, but not
+// the mandate: SessionStart does not run for subagents.
+export function registerPromptSections(pi: ExtensionAPI, settings: Settings): void {
+  const mandateFile = join(settings.pluginRoot, "hooks", "session-start-context.md");
+  pi.on("before_agent_start", (event) => {
+    const sheet = readSheet(settings.agentDir);
+    const sections = event.systemPromptOptions.sections;
+    sections[PARALLEL_SECTION] = PARALLEL_CALLS;
+    sections[TOOLS_SECTION] = piToolsNote(settings.pluginRoot);
+    if (settings.depth === 0 && !sheet?.hookOff) sections[MANDATE_SECTION] = readFileSync(mandateFile, "utf8");
+    if (sheet) sections[SHEET_SECTION] = sheet.text;
+  });
+}

package/plugins/pstack/pi/schedule.ts

@@ -0,0 +1,254 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import type { OneShot } from "./one-shot.ts";
+import { expandSlash } from "./slash.ts";
+
+const MIN_DELAY_S = 60;
+const MAX_DELAY_S = 3600;
+// setInterval treats a delay above 2^31-1 ms as 1 ms.
+const MAX_LOOP_S = 24 * 86400;
+const IDLE_RETRY_MS = 1000;
+// Text the agent chose (a schedule_wakeup prompt, and what a loop it re-arms sends) goes in as a custom
+// message, not a user message. The permission classifier reads user-role messages as what the user asked
+// for, so a user message here would let the agent write its own permission.
+const AGENT_PROMPT_TYPE = "pstack-wakeup";
+const LOOP_COMMAND = /^\/loop(?:\s+([\s\S]*))?$/;
+type Send = (prompt: string) => void;
+
+const errorText = (e: unknown) => (e instanceof Error ? e.message : String(e));
+
+const wakeupParams = Type.Object({
+  delaySeconds: Type.Optional(Type.Number({ description: `Seconds until the wakeup (${MIN_DELAY_S}-${MAX_DELAY_S})` })),
+  prompt: Type.Optional(Type.String({ description: "The prompt to run when the wakeup fires" })),
+  reason: Type.Optional(Type.String({ description: "Why this delay, in one short sentence" })),
+  noop: Type.Optional(Type.Boolean({ description: "Mark this wakeup as a routine check; it is scheduled all the same" })),
+  stop: Type.Optional(Type.Boolean({ description: "Cancel the pending wakeup; no other field is needed" })),
+});
+
+// One pending wakeup, one fixed-interval loop, and one live self-paced loop per
+// session. A due wakeup or loop tick runs the delivery its caller chose, at
+// once when the agent is idle.
+export class Scheduler {
+  private wakeup?: NodeJS.Timeout;
+  private loop?: NodeJS.Timeout;
+  // A self-paced loop has no timer of its own while its iteration runs, so
+  // this is what /loop stop finds then.
+  private selfPaced = false;
+  // Set by a /loop command that ends or replaces the loop while a run is in
+  // flight, until that run settles. A schedule_wakeup call names no loop, so
+  // nothing tells that run's re-arm of the old loop from any other wakeup. It
+  // is refused them all, or the loop the user just ended would come back.
+  sealed = false;
+  // A run is in flight: set by agent_start, cleared by agent_settled. Not
+  // ctx.isIdle(), which is also false during a manual compaction.
+  running = false;
+
+  scheduleWakeup(seconds: number, deliver: () => void, ctx: ExtensionContext): void {
+    this.cancelWakeup();
+    const due = () => {
+      // Pi rejects prompts during manual compaction. Keep the wakeup pending
+      // until idle, including while a run or compaction is still finishing.
+      if (!ctx.isIdle()) {
+        this.wakeup = setTimeout(due, IDLE_RETRY_MS).unref();
+        return;
+      }
+      this.wakeup = undefined;
+      deliver();
+    };
+    this.wakeup = setTimeout(due, seconds * 1000);
+    this.wakeup.unref();
+  }
+
+  cancelWakeup(): boolean {
+    const had = this.wakeup !== undefined;
+    clearTimeout(this.wakeup);
+    this.wakeup = undefined;
+    return had;
+  }
+
+  startLoop(seconds: number, tick: () => void, ctx: ExtensionContext): void {
+    // A tick that lands mid-run is dropped, so a slow iteration cannot pile up a backlog.
+    this.loop = setInterval(() => ctx.isIdle() && tick(), seconds * 1000);
+    this.loop.unref();
+  }
+
+  private stopLoop(): boolean {
+    const had = this.loop !== undefined;
+    clearInterval(this.loop);
+    this.loop = undefined;
+    return had;
+  }
+
+  startSelfPaced(): void {
+    this.selfPaced = true;
+  }
+
+  // Ends the loop and the pending wakeup. midRun says a run is in flight,
+  // which seals the wakeup slot against it.
+  stopAll(midRun = false): boolean {
+    const wakeup = this.cancelWakeup();
+    const selfPaced = this.selfPaced;
+    this.selfPaced = false;
+    if (midRun) this.sealed = true;
+    return this.stopLoop() || wakeup || selfPaced;
+  }
+}
+
+function clampDelay(seconds: number): number {
+  return Math.min(MAX_DELAY_S, Math.max(MIN_DELAY_S, Math.round(seconds)));
+}
+
+const UNIT_SECONDS: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400 };
+
+type LoopCommand =
+  | { kind: "stop" }
+  | { kind: "usage"; reason?: string }
+  | { kind: "fixed"; seconds: number; prompt: string }
+  | { kind: "dynamic"; prompt: string };
+
+function parseLoop(args: string): LoopCommand {
+  const text = args.trim();
+  if (!text) return { kind: "usage" };
+  if (text === "stop") return { kind: "stop" };
+  const m = /^(\d+)([smhd])(?:\s+([\s\S]+))?$/.exec(text);
+  if (m) {
+    const seconds = Number(m[1]) * UNIT_SECONDS[m[2]];
+    if (!m[3]) return { kind: "usage" };
+    if (seconds > MAX_LOOP_S) return { kind: "usage", reason: "Intervals over 24 days are not supported." };
+    return { kind: "fixed", seconds, prompt: m[3].trim() };
+  }
+  return { kind: "dynamic", prompt: text };
+}
+
+function dynamicPrompt(prompt: string): string {
+  return (
+    `${prompt}\n\n` +
+    `[/loop, self-paced] When this iteration is done, call schedule_wakeup with prompt "/loop ${prompt}" ` +
+    `and a delay that fits what you are waiting for (${MIN_DELAY_S} to ${MAX_DELAY_S} seconds) to run it again. ` +
+    `Skip the call to end the loop.`
+  );
+}
+
+// model-only exposure keeps the tool declared under codemode.mode "only".
+export function registerSchedule(pi: ExtensionAPI, scheduler: Scheduler, oneShot: OneShot): void {
+  // The prompt's author picks the role: the user's /loop sends user messages, and text the agent chose
+  // goes in as a custom message, which the permission classifier does not read as the user's ask. Pi
+  // expands slash text only in a user message, so the agent's is expanded before it is sent.
+  const sendAsUser: Send = (prompt) => pi.sendUserMessage(prompt, { deliverAs: "followUp", expandPromptTemplates: true });
+  const sendAsAgent =
+    (ctx: ExtensionContext): Send =>
+    (prompt) => {
+      let content = prompt;
+      try {
+        content = expandSlash(pi.getCommands(), prompt);
+      } catch (e) {
+        ctx.ui.notify(`A wakeup's command could not be expanded and was sent as written: ${errorText(e)}`, "error");
+      }
+      pi.sendMessage({ customType: AGENT_PROMPT_TYPE, content, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+    };
+
+  pi.registerTool({
+    name: "schedule_wakeup",
+    label: "Schedule wakeup",
+    exposure: "model-only",
+    description: `Schedule this session to be re-invoked with a prompt after delaySeconds (clamped to ${MIN_DELAY_S}-${MAX_DELAY_S}), once the session is idle. One wakeup is pending at a time: a new call replaces it, and stop: true cancels it. Used by /loop's self-paced mode.`,
+    parameters: wakeupParams,
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      if (params.stop) {
+        // What is pending in a sealed slot is a loop start the user asked for, not this run's.
+        const had = !scheduler.sealed && scheduler.cancelWakeup();
+        const text = had ? "Pending wakeup cancelled." : "No wakeup was pending.";
+        return { content: [{ type: "text", text }], details: { cancelled: had } };
+      }
+      if (params.delaySeconds === undefined || !params.prompt) {
+        throw new Error("schedule_wakeup needs delaySeconds and prompt unless stop is true.");
+      }
+      if (scheduler.sealed) {
+        ctx.ui.notify("A wakeup this run asked for was not scheduled: /loop ended or replaced the loop while it ran.", "warning");
+        return {
+          content: [{ type: "text", text: "Not scheduled: the user ended or replaced the loop with a /loop command during this run. Do not schedule another wakeup in this run." }],
+          details: { refused: true },
+        };
+      }
+      if (oneShot.exits(ctx)) {
+        throw new Error(`schedule_wakeup cannot fire in a ${ctx.mode} run: pi exits when this run ends. Finish the work in this run instead.`);
+      }
+      const seconds = clampDelay(params.delaySeconds);
+      // A custom message runs no command, so the agent's "/loop ..." re-arm runs the loop here.
+      const prompt = params.prompt;
+      const send = sendAsAgent(ctx);
+      const loop = LOOP_COMMAND.exec(prompt);
+      const deliver = loop
+        ? () => void runLoop(loop[1] ?? "", ctx, send).catch((e) => ctx.ui.notify(`/loop from a wakeup failed: ${errorText(e)}`, "error"))
+        : () => send(prompt);
+      scheduler.scheduleWakeup(seconds, deliver, ctx);
+      const fireAt = new Date(Date.now() + seconds * 1000).toISOString();
+      const clamped = seconds !== params.delaySeconds ? ` (clamped from ${params.delaySeconds})` : "";
+      return {
+        content: [{ type: "text", text: `Wakeup scheduled in ${seconds}s${clamped}, at ${fireAt}. It replaces any earlier pending wakeup.` }],
+        details: { delaySeconds: seconds, fireAt, noop: params.noop === true },
+      };
+    },
+  });
+
+  pi.on("agent_start", () => {
+    scheduler.running = true;
+  });
+  pi.on("agent_settled", () => {
+    scheduler.running = false;
+    scheduler.sealed = false;
+  });
+
+  async function runLoop(args: string, ctx: ExtensionContext, send: Send): Promise<void> {
+    const cmd = parseLoop(args);
+    // Also true during a manual compaction, which no run is behind: the first
+    // prompt then waits for idle, but only a run in flight seals the slot.
+    const midRun = !ctx.isIdle();
+    // sendUserMessage only starts the run, and a one-shot run disposes the
+    // session as soon as the command returns, so there the command waits it out.
+    const fire = async (prompt: string) => {
+      // The slot is sealed against the run in flight, so the loop's first
+      // prompt takes the slot and runs once that run has settled. Its own
+      // re-arm then comes from a later run and is not refused.
+      if (midRun) {
+        scheduler.scheduleWakeup(0, () => send(prompt), ctx);
+        ctx.ui.notify("The loop starts once the session is idle.", "info");
+        return;
+      }
+      if (!oneShot.exits(ctx)) {
+        send(prompt);
+        return;
+      }
+      await oneShot.assertStartsRun(prompt, ctx);
+      const settled = oneShot.untilSettled();
+      send(prompt);
+      await settled;
+    };
+    switch (cmd.kind) {
+      case "usage":
+        ctx.ui.notify(`${cmd.reason ? `${cmd.reason} ` : ""}Usage: /loop [interval like 5m or 1h] <prompt>, or /loop stop`, "info");
+        return;
+      case "stop":
+        ctx.ui.notify(scheduler.stopAll(scheduler.running) ? "Loop stopped." : "No loop was running.", "info");
+        return;
+      case "fixed": {
+        const seconds = Math.max(MIN_DELAY_S, cmd.seconds);
+        scheduler.stopAll(scheduler.running);
+        scheduler.startLoop(seconds, () => send(cmd.prompt), ctx);
+        ctx.ui.notify(`Looping every ${seconds}s. /loop stop ends it.`, "info");
+        await fire(cmd.prompt);
+        return;
+      }
+      case "dynamic":
+        scheduler.stopAll(scheduler.running);
+        scheduler.startSelfPaced();
+        await fire(dynamicPrompt(cmd.prompt));
+    }
+  }
+
+  pi.registerCommand("loop", {
+    description: "Run a prompt on an interval (/loop 5m <prompt>), self-paced (/loop <prompt>), or stop (/loop stop)",
+    handler: (args, ctx) => runLoop(args, ctx, sendAsUser),
+  });
+}

package/plugins/pstack/pi/slash.ts

@@ -0,0 +1,92 @@
+import type { SlashCommandInfo } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+
+// Pi expands "/skill:name args" and "/template args" only inside sendUserMessage, and its package exports
+// none of the code that does it. This is that code from pi 1.4.0 (AgentSession._expandSkillCommand,
+// dist/core/prompt-templates.js, and dist/utils/frontmatter.js), reading the files pi.getCommands() names,
+// for text the extension sends as a custom message. tests/pi/slash.test.mjs checks it against the installed pi.
+
+export function stripFrontmatter(content: string): string {
+  const normalized = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (!normalized.startsWith("---")) return normalized;
+  const endIndex = normalized.indexOf("\n---", 3);
+  return endIndex === -1 ? normalized : normalized.slice(endIndex + 4).trim();
+}
+
+// Splits on whitespace outside quotes; a quote ends at the next quote of the same kind, and "" is an argument.
+export function parseCommandArgs(argsString: string): string[] {
+  const args: string[] = [];
+  let current = "";
+  let hasToken = false;
+  let inQuote: string | null = null;
+  for (const char of argsString) {
+    if (inQuote) {
+      if (char === inQuote) inQuote = null;
+      else current += char;
+    } else if (char === '"' || char === "'") {
+      inQuote = char;
+      hasToken = true;
+    } else if (/\s/.test(char)) {
+      if (hasToken) {
+        args.push(current);
+        current = "";
+        hasToken = false;
+      }
+    } else {
+      current += char;
+      hasToken = true;
+    }
+  }
+  if (hasToken) args.push(current);
+  return args;
+}
+
+// $1, $@, $ARGUMENTS, ${N:-default}, ${@:-default}, ${@:N} and ${@:N:L}. A value is not substituted again.
+export function substituteArgs(content: string, args: string[]): string {
+  const allArgs = args.join(" ");
+  return content.replace(
+    /\$\{(\d+|ARGUMENTS|@):-([^}]*)\}|\$\{@:(\d+)(?::(\d+))?\}|\$(ARGUMENTS|@|\d+)/g,
+    (_match, defaultTarget, defaultValue, sliceStart, sliceLength, simple) => {
+      if (defaultTarget) {
+        const value = defaultTarget === "@" || defaultTarget === "ARGUMENTS" ? allArgs : args[parseInt(defaultTarget, 10) - 1];
+        return value ? value : defaultValue;
+      }
+      if (sliceStart) {
+        const start = Math.max(0, parseInt(sliceStart, 10) - 1);
+        return (sliceLength ? args.slice(start, start + parseInt(sliceLength, 10)) : args.slice(start)).join(" ");
+      }
+      if (simple === "ARGUMENTS" || simple === "@") return allArgs;
+      return args[parseInt(simple, 10) - 1] ?? "";
+    },
+  );
+}
+
+function expandSkillCommand(commands: readonly SlashCommandInfo[], text: string): string {
+  if (!text.startsWith("/skill:")) return text;
+  const spaceIndex = text.indexOf(" ");
+  const name = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+  const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
+  const skill = commands.find((c) => c.source === "skill" && c.name === name);
+  if (!skill) return text;
+  const { path, baseDir } = skill.sourceInfo;
+  const body = stripFrontmatter(readFileSync(path, "utf8")).trim();
+  const block = `<skill name="${name.slice("skill:".length)}" location="${path}">\nReferences are relative to ${baseDir}.\n\n${body}\n</skill>`;
+  return args ? `${block}\n\n${args}` : block;
+}
+
+function expandPromptTemplate(commands: readonly SlashCommandInfo[], text: string): string {
+  const match = /^\/([^\s]+)(?:\s+([\s\S]*))?$/.exec(text);
+  const template = match && commands.find((c) => c.source === "prompt" && c.name === match[1]);
+  if (!template) return text;
+  return substituteArgs(stripFrontmatter(readFileSync(template.sourceInfo.path, "utf8")), parseCommandArgs(match[2] ?? ""));
+}
+
+// The text a user message with this text would carry. A name pi has no skill or template for stays as written,
+// and so does an extension command: pi runs one only from a user message, and the agent must not run one as the
+// user. Throws when a command's file cannot be read, where pi reports the error and sends the text as written.
+export function expandSlash(commands: readonly SlashCommandInfo[], text: string): string {
+  const spaceIndex = text.indexOf(" ");
+  const name = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+  if (text.startsWith("/") && commands.some((c) => c.source === "extension" && c.name === name)) return text;
+  return expandPromptTemplate(commands, expandSkillCommand(commands, text));
+}

package/plugins/pstack/pi/sleep-wait.ts

@@ -0,0 +1,76 @@
+// Whether a bash command line waits on a foreground `sleep`, the way a model
+// polls for a background agent it should leave alone.
+//
+// A token rule, not a shell parser. After heredoc bodies, quoted strings, and
+// comments are removed, the word `sleep` followed by a literal duration of
+// MIN_WAIT_S or more blocks, anywhere in the line, unless that sleep itself is
+// directly backgrounded (`sleep 30 &`, never `&&` or `&>`). It errs toward
+// blocking: a wrongly blocked command costs one rephrased turn, a missed poll
+// loop costs minutes. Known misses: a sleep inside a quoted script such as
+// `bash -c 'sleep 30'`, a quoted duration (`sleep "30"`), a variable duration
+// (`sleep $N`), and a poll loop of sleeps under two seconds. Known over-blocks:
+// a sleep inside a backgrounded group (`(sleep 30; echo done) &`), a
+// backgrounded sleep with a redirection before the `&`, and
+// `timeout 5 sleep 30`. tests/pi/sleep-wait.test.mjs lists each, so changing
+// one is a visible decision.
+const MIN_WAIT_S = 2;
+const SLEEP_UNITS: Record<string, number> = { "": 1, s: 1, m: 60, h: 3600, d: 86400 };
+
+// Seconds a literal sleep argument asks for (30, 2.5, 1m, 1m30s, infinity);
+// 0 when it is not a literal.
+function sleepSeconds(arg: string): number {
+  if (/^inf(inity)?$/.test(arg)) return Infinity;
+  const parts = arg.match(/\d*\.?\d+[smhd]?/g);
+  if (!parts || parts.join("") !== arg) return 0;
+  return parts.reduce((sum, part) => {
+    const unit = /[smhd]$/.exec(part)?.[0] ?? "";
+    return sum + Number(part.slice(0, part.length - unit.length)) * SLEEP_UNITS[unit];
+  }, 0);
+}
+
+// One line with its quoted strings replaced by "" and a comment cut off, in a
+// single left-to-right pass. An unterminated quote drops the rest of the line.
+function stripQuotesAndComment(line: string): string {
+  let out = "";
+  let quote: string | undefined;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === "\\" && quote === '"') i++;
+      else if (c === quote) {
+        quote = undefined;
+        out += '""';
+      }
+    } else if (c === "\\") {
+      out += c + (line[i + 1] ?? "");
+      i++;
+    } else if (c === '"' || c === "'") quote = c;
+    else if (c === "#" && (i === 0 || /\s/.test(line[i - 1]))) break;
+    else out += c;
+  }
+  return out;
+}
+
+// The command text the shell would run: heredoc bodies, quoted strings, and
+// comments removed, one pass over the lines so the cost stays linear. The
+// line that opens a heredoc is kept, since commands can follow the `<<`.
+function shellText(command: string): string {
+  const kept: string[] = [];
+  let terminator: string | undefined;
+  for (const line of command.split("\n")) {
+    if (terminator !== undefined) {
+      if (line.trim() === terminator) terminator = undefined;
+      continue;
+    }
+    kept.push(stripQuotesAndComment(line));
+    terminator = /<<-?\s*(["']?)(\w+)\1/.exec(line)?.[2];
+  }
+  return kept.join("\n");
+}
+
+export function isForegroundWait(command: string): boolean {
+  for (const m of shellText(command).matchAll(/\bsleep\s+([^\s;|&()<>]+)\s*(&(?![&>]))?/g)) {
+    if (m[2] === undefined && sleepSeconds(m[1]) >= MIN_WAIT_S) return true;
+  }
+  return false;
+}