@justjoshn/pi-pstack 0.15.36-pi.1 → 0.15.36-pi.12

package/src/index.ts

@@ -1,9 +1,12 @@
+import { basename } from 'node:path';
+
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { aliasInputResult, aliasTable, packageSkillNames } from './aliases.ts';
 import { registerAskQuestion } from './ask.ts';
 import { aliasAutocomplete } from './autocomplete.ts';
 import { childIdentity } from './child-env.ts';
+import { registerGenerateImage } from './generate-image.ts';
 import { registerLoop } from './loop.ts';
 import { registerMode } from './mode.ts';
 import { canAsk, isOneShot } from './modes.ts';
@@ -11,7 +14,7 @@ import { artifactsDir, PACKAGE_ROOT, projectsDir, rootStoreDir, rulePath, SKILLS
 import { registerPlanMode } from './plan.ts';
 import { registerReadonlyShell } from './readonly-shell.ts';
 import { migrateLegacyRule, modelsSection, readRule } from './rule.ts';
-import { hostSection, subagentsSection } from './sections.ts';
+import { alwaysAppliedRules, hostSection, subagentsSection } from './sections.ts';
 import { registerSubscriptions } from './subscriptions/index.ts';
 import { type AgentDefinition, loadAgentDefinitions } from './task/agents.ts';
 import { registerAgentStatus } from './task/status.ts';
@@ -22,10 +25,14 @@ import { registerVisualize } from './visualize.ts';
 const WATCHDOG_MS = 1_000;
 const ORPHAN_EXIT_MS = 5_000;
 
-/** In a subagent, the agent definition body joins the system prompt as the agent's own instructions. */
+// What Cursor tells every subagent in a system reminder, minus its sentence about Cursor Canvas files.
+const SUBAGENT_REMINDER = 'You are running as a subagent under a parent agent. Do not spawn additional subagents unless requested by the user or by your instructions.';
+
+/** In a subagent, Cursor's subagent reminder, and the agent definition body as the agent's own instructions. */
 function agentSection(agents: readonly AgentDefinition[]): Record<string, string> {
+  if (childIdentity.depth === 0) return {};
   const prompt = agents.find((agent) => agent.type === childIdentity.agentType)?.prompt ?? '';
-  return prompt === '' ? {} : { pstack_agent: prompt };
+  return { pstack_subagent: SUBAGENT_REMINDER, ...(prompt === '' ? {} : { pstack_agent: prompt }) };
 }
 
 function hostSections(pi: ExtensionAPI, ctx: ExtensionContext, agents: readonly AgentDefinition[]): Record<string, string> {
@@ -47,6 +54,7 @@ function hostSections(pi: ExtensionAPI, ctx: ExtensionContext, agents: readonly
       loopAvailable: !isOneShot(ctx.mode),
       questionsAvailable: canAsk(ctx),
       activeTools,
+      rules: alwaysAppliedRules(SKILLS_DIR),
     }),
     ...(activeTools.includes('Task') ? { pstack_subagents: subagentsSection(agents, availableModels(ctx), parentModel(ctx)) } : {}),
     pstack_models: modelsSection(readRule(rulePath()), rulePath()),
@@ -95,27 +103,38 @@ export default function piPstack(pi: ExtensionAPI): void {
   });
 
   const mode = registerMode(pi);
-  const plan = registerPlanMode(pi);
+  const plan = registerPlanMode(pi, { buildInWorker: (planFile, request) => task.startBackground(`Build ${basename(planFile)}`, request, { environment: 'cloud' }) });
   registerVisualize(pi, { artifactsDir: (ctx) => artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()) });
-  const task = registerTask(pi, { agents, depth: childIdentity.depth, planMode: plan.enabled });
+  registerGenerateImage(pi, { artifactsDir: (ctx) => artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()), mayOffer: () => !childIdentity.readonly && !plan.enabled() });
+  const ownType = agents.find((agent) => agent.type === childIdentity.agentType);
+  const task = registerTask(pi, { agents, depth: childIdentity.depth, canSpawn: childIdentity.depth < 2 && ownType?.spawns !== false, planMode: plan.enabled });
   registerAgentStatus(pi);
-  registerSubscriptions(pi, { runFresh: async (prompt, name) => void (await task.startBackground(`timer ${name}`, prompt)) });
+  registerSubscriptions(pi, {
+    runFresh: async (prompt, name, meta) => {
+      await task.startBackground(`timer ${name}`, prompt, {
+        ...(meta.model === undefined ? {} : { model: `${meta.model.provider}/${meta.model.id}${meta.model.thinking === undefined ? '' : `:${meta.model.thinking}`}` }),
+        ...(meta.trusted === undefined ? {} : { trusted: meta.trusted }),
+      });
+      return undefined;
+    },
+  });
   const loop = registerLoop(pi, { hasPendingWork: task.hasBackgroundWork });
-  registerTodoWrite(pi);
+  const todos = registerTodoWrite(pi);
   registerAskQuestion(pi);
   if (childIdentity.parentPid !== undefined) watchParent(pi, childIdentity.parentPid);
   if (childIdentity.readonly) registerReadonlyShell(pi);
 
   pi.on('before_agent_start', (event, ctx) => {
-    const modeText = mode.section();
     const loopText = loop.section();
     const planText = plan.section();
+    const todoText = todos.section();
     Object.assign(
       event.systemPromptOptions.sections,
       hostSections(pi, ctx, agents),
-      modeText === undefined ? {} : { pstack_mode: modeText },
+      mode.sections(),
       loopText === undefined ? {} : { pstack_loop: loopText },
       planText === undefined ? {} : { pstack_plan: planText },
+      todoText === undefined ? {} : { pstack_todos: todoText },
     );
   });
 

package/src/loop.ts

@@ -5,14 +5,21 @@ import { isOneShot } from './modes.ts';
 const DAY_MS = 86_400_000;
 const UNIT_MS: Record<string, number> = { s: 1_000, m: 60_000, h: 3_600_000, d: DAY_MS };
 const DURATION = /^(?:\d+[smhd])+$/;
+const WORD_UNITS: Record<string, string> = { second: 's', seconds: 's', sec: 's', secs: 's', minute: 'm', minutes: 'm', min: 'm', mins: 'm', hour: 'h', hours: 'h', hr: 'h', hrs: 'h', day: 'd', days: 'd' };
 // setTimeout fires at once for delays past 2^31-1 ms (about 24.8 days), which would turn a long loop into a runaway.
 const MAX_DELAY_MS = 24 * DAY_MS;
 const TOO_LONG = 'Loop intervals can be at most 24d.';
 
-/** Milliseconds for a duration such as 30s, 5m, 1h30m; undefined when the text is not a duration. */
+/** Milliseconds for a duration such as 30s, 5m, 1h30m, 10 minutes, or 1 hour 30 minutes; undefined when the text is not a duration. */
 export function parseDuration(text: string): number | undefined {
-  if (!DURATION.test(text)) return undefined;
-  const total = [...text.matchAll(/(\d+)([smhd])/g)].reduce((sum, [, count, unit]) => sum + Number(count) * (UNIT_MS[unit ?? 's'] ?? 0), 0);
+  const compact = text
+    .trim()
+    .toLowerCase()
+    .replace(/^every\s+/, '')
+    .replace(/(\d+)\s*(seconds?|secs?|minutes?|mins?|hours?|hrs?|days?)\b/g, (_match, count: string, word: string) => `${count}${WORD_UNITS[word] ?? ''}`)
+    .replace(/\s+/g, '');
+  if (!DURATION.test(compact)) return undefined;
+  const total = [...compact.matchAll(/(\d+)([smhd])/g)].reduce((sum, [, count, unit]) => sum + Number(count) * (UNIT_MS[unit ?? 's'] ?? 0), 0);
   return total > 0 ? total : undefined;
 }
 
@@ -25,15 +32,41 @@ function delayOf(text: string): number {
 
 export type LoopCommand = { kind: 'status' } | { kind: 'stop' } | { kind: 'start'; prompt: string; intervalMs?: number } | { kind: 'error'; message: string };
 
+/** The longest trailing phrase that parses as a duration, such as `5m`, `every 10 minutes`, or `1 hour 30 minutes`. */
+function trailingInterval(text: string): { prompt: string; intervalMs: number } | undefined {
+  const tokens = text.split(/\s+/);
+  for (let take = Math.min(6, tokens.length); take >= 1; take -= 1) {
+    const intervalMs = parseDuration(tokens.slice(-take).join(' '));
+    if (intervalMs === undefined) continue;
+    const prompt = tokens
+      .slice(0, -take)
+      .join(' ')
+      .replace(/\s+every$/i, '')
+      .trim();
+    return { prompt, intervalMs };
+  }
+  return undefined;
+}
+
 export function parseLoopArgs(args: string): LoopCommand {
   const trimmed = args.trim();
   if (trimmed === '') return { kind: 'status' };
   if (trimmed === 'stop' || trimmed === 'off') return { kind: 'stop' };
   const [, first = '', rest = ''] = /^(\S+)\s*([\s\S]*)$/.exec(trimmed) ?? [];
-  const intervalMs = parseDuration(first);
-  if (intervalMs === undefined) return { kind: 'start', prompt: trimmed };
-  if (intervalMs > MAX_DELAY_MS) return { kind: 'error', message: TOO_LONG };
-  return rest.trim() === '' ? { kind: 'error', message: '/loop needs a prompt: /loop [interval] <prompt>' } : { kind: 'start', prompt: rest.trim(), intervalMs };
+  const leadMs = parseDuration(first) ?? (first.toLowerCase() === 'every' ? parseDuration(rest.split(/\s+/)[0] ?? '') : undefined);
+  if (leadMs !== undefined) {
+    if (leadMs > MAX_DELAY_MS) return { kind: 'error', message: TOO_LONG };
+    const after = first.toLowerCase() === 'every' ? rest.split(/\s+/).slice(1).join(' ') : rest;
+    return after.trim() === '' ? { kind: 'error', message: '/loop needs a prompt: /loop [interval] <prompt>' } : { kind: 'start', prompt: after.trim(), intervalMs: leadMs };
+  }
+  // Cursor accepts the interval at either end, including `every 10 minutes`, so both ends are tried before treating it as a prompt.
+  const trailing = trailingInterval(trimmed);
+  if (trailing !== undefined) {
+    if (trailing.intervalMs > MAX_DELAY_MS) return { kind: 'error', message: TOO_LONG };
+    if (trailing.prompt === '') return { kind: 'error', message: '/loop needs a prompt: /loop [interval] <prompt>' };
+    return { kind: 'start', prompt: trailing.prompt, intervalMs: trailing.intervalMs };
+  }
+  return { kind: 'start', prompt: trimmed };
 }
 
 interface Loop {
@@ -42,6 +75,8 @@ interface Loop {
   iteration: number;
   nextWakeMs?: number;
   timer?: ReturnType<typeof setTimeout>;
+  /** A wake came due while a run was going; it fires once when that run settles. */
+  due?: boolean;
 }
 
 const formatMs = (ms: number) => (ms % 86_400_000 === 0 ? `${ms / 86_400_000}d` : ms % 3_600_000 === 0 ? `${ms / 3_600_000}h` : ms % 60_000 === 0 ? `${ms / 60_000}m` : `${Math.round(ms / 1_000)}s`);
@@ -74,33 +109,55 @@ function createLoopController(pi: ExtensionAPI, options: LoopOptions) {
     clear();
     notify(ctx, `Loop stopped: ${reason}`);
   };
-  const fire = () => {
+  const run = () => {
     if (loop === undefined) return;
-    const { timer: _timer, nextWakeMs: _wake, ...rest } = loop;
-    loop = { ...rest, iteration: rest.iteration + 1 };
+    loop = { ...loop, iteration: loop.iteration + 1, due: false };
     // Expansion lets a loop run a skill or template each time.
-    pi.sendUserMessage(loop.prompt, { expandPromptTemplates: true, ...(lastCtx === undefined || lastCtx.isIdle() ? {} : { deliverAs: 'followUp' as const }) });
+    pi.sendUserMessage(loop.prompt, { expandPromptTemplates: true });
+  };
+  /**
+   * A timer fired. A fixed loop keeps its wall-clock cadence, like Cursor's sleep-and-echo shell loop, so a long run
+   * does not push the next tick out. A wake that lands while a run is going is delivered once that run settles, as
+   * Cursor's monitored shell output notifies after the turn, and several such wakes fire once, not once each.
+   */
+  const tick = () => {
+    if (loop === undefined) return;
+    const { timer: _spent, nextWakeMs: _wake, ...rest } = loop;
+    loop = rest.intervalMs === undefined ? rest : { ...rest, timer: setTimeout(tick, rest.intervalMs) };
+    if (lastCtx !== undefined && !lastCtx.isIdle()) loop = { ...loop, due: true };
+    else run();
   };
   const settled = (ctx: ExtensionContext, aborted: boolean) => {
     lastCtx = ctx;
-    if (loop === undefined || loop.timer !== undefined) return;
+    if (loop === undefined) return;
     if (aborted) return stop(ctx, 'the run was aborted.');
-    const delay = loop.intervalMs ?? loop.nextWakeMs;
-    if (delay !== undefined) loop = { ...loop, timer: setTimeout(fire, delay) };
+    if (loop.due === true) return run();
+    if (loop.timer !== undefined) return;
+    if (loop.intervalMs !== undefined) {
+      // An armed fixed loop has no timer yet; its first tick waits for this turn to end.
+      loop = { ...loop, timer: setTimeout(tick, loop.intervalMs) };
+      return;
+    }
+    const delay = loop.nextWakeMs;
+    if (delay !== undefined) loop = { ...loop, timer: setTimeout(tick, delay) };
     else if (!options.hasPendingWork()) stop(ctx, 'the agent scheduled no next wake.');
   };
   const start = (ctx: ExtensionContext, prompt: string, intervalMs: number | undefined) => {
     if (loop !== undefined) stop(ctx, 'replaced by a new /loop.');
     lastCtx = ctx;
     loop = { prompt, iteration: 0, ...(intervalMs === undefined ? {} : { intervalMs }) };
-    fire();
+    run();
+    if (loop.intervalMs !== undefined) loop = { ...loop, timer: setTimeout(tick, loop.intervalMs) };
   };
   /** An agent arms a loop mid-turn, so its first run waits for this turn to settle and then for the first delay. */
   const arm = (ctx: ExtensionContext, prompt: string, schedule: { intervalMs: number } | { firstWakeMs: number }) => {
     if (loop !== undefined) stop(ctx, 'replaced by a new loop.');
     loop = 'intervalMs' in schedule ? { prompt, iteration: 0, intervalMs: schedule.intervalMs } : { prompt, iteration: 0, nextWakeMs: schedule.firstWakeMs };
   };
-  const status = () => (loop === undefined ? 'No loop is running.' : `Loop: "${loop.prompt}" (iteration ${loop.iteration}${loop.intervalMs === undefined ? ', agent-paced' : `, every ${formatMs(loop.intervalMs)}`})`);
+  const status = () =>
+    loop === undefined
+      ? 'No loop is running. Usage: /loop [interval] <prompt>, with the interval at either end; /loop stop ends one.'
+      : `Loop: "${loop.prompt}" (iteration ${loop.iteration}${loop.intervalMs === undefined ? ', agent-paced' : `, every ${formatMs(loop.intervalMs)}`})`;
   const wake = (delayMs: number) => {
     if (loop === undefined) throw new Error('No loop is running. Start one with prompt plus interval or wake_in, or ask the user to run /loop.');
     if (loop.intervalMs !== undefined) throw new Error(`This loop runs every ${formatMs(loop.intervalMs)}; only the user can change its interval. Pass stop: true to end it.`);
@@ -181,7 +238,7 @@ export function registerLoop(pi: ExtensionAPI, options: LoopOptions): { section:
   pi.on('agent_settled', (event, ctx) => controller.settled(ctx, event.aborted));
   pi.on('session_shutdown', () => controller.clear());
   pi.registerCommand('loop', {
-    description: 'Run a prompt repeatedly: /loop [interval] <prompt> (interval like 30s, 5m, 1h, at most 24d); /loop stop',
+    description: 'Run a prompt repeatedly: /loop [interval] <prompt>, interval either end and like 30s, 5m, 1h, every 10 minutes (at most 24d); /loop stop',
     handler: async (args, ctx) => handleLoopCommand(controller, args, ctx),
   });
   registerLoopTool(pi, controller);

package/src/mode.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, ThemeColor } from '@earendil-works/pi-coding-agent';
-import { parseFrontmatter } from '@earendil-works/pi-coding-agent';
+import { parseFrontmatter, stripFrontmatter } from '@earendil-works/pi-coding-agent';
 
 export const MODE_ENTRY = 'pstack/mode';
 const STATUS_KEY = 'pstack-mode';
@@ -13,6 +13,32 @@ export interface ActiveMode {
   path?: string;
 }
 
+/**
+ * Cursor's custom-mode lifecycle: a mode is `entered` until a request carries it, then `active`. Leaving or switching
+ * away from an `active` mode leaves it `exited` until the next request says so once.
+ */
+export interface ModeState {
+  active?: ActiveMode & { lifecycle: 'entered' | 'active' };
+  exited?: string;
+}
+
+const left = (state: ModeState): string | undefined => (state.active?.lifecycle === 'active' ? state.active.skill : state.exited);
+
+export function enterMode(state: ModeState, mode: ActiveMode): ModeState {
+  const exited = left(state);
+  return { active: { ...mode, lifecycle: 'entered' }, ...(exited === undefined ? {} : { exited }) };
+}
+
+export function exitMode(state: ModeState): ModeState {
+  const exited = left(state);
+  return exited === undefined ? {} : { exited };
+}
+
+/** What a request leaves behind: the mode it carried is now active, and its exit notice has been sent. */
+export function afterRequest(state: ModeState): ModeState {
+  return state.active === undefined ? {} : { active: { ...state.active, lifecycle: 'active' } };
+}
+
 export type ModeCommand = { kind: 'status' } | { kind: 'off' } | { kind: 'set'; skill: string; task: string };
 
 export function parseModeArgs(args: string): ModeCommand {
@@ -31,30 +57,53 @@ interface BranchEntry {
 
 const SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
 
+/** A stored mode as a skill name only: a session file can come from elsewhere, so a stored path is ignored and a value that is not a plausible skill name (it would reach the system prompt) counts as no mode. */
+function storedSkill(data: unknown): string | undefined {
+  const skill = (data as { skill?: unknown } | null)?.skill;
+  return typeof skill === 'string' && SKILL_NAME.test(skill) ? skill : undefined;
+}
+
 /**
- * The last mode entry on the branch, as a skill name only: a session file can come from elsewhere, so a stored path
- * is ignored and a value that is not a plausible skill name (it would reach the system prompt) counts as no mode.
+ * Replays the branch into the mode state: each mode entry enters or leaves a mode, and an assistant message after it
+ * shows a request carried the mode. Skills are resolved by name, never by a stored path.
  */
-export function modeFromBranch(entries: readonly BranchEntry[]): ActiveMode | undefined {
-  for (let index = entries.length - 1; index >= 0; index -= 1) {
-    const entry = entries[index];
-    if (entry?.type !== 'custom' || entry.customType !== MODE_ENTRY) continue;
-    const skill = (entry.data as { skill?: unknown } | null)?.skill;
-    return typeof skill === 'string' && SKILL_NAME.test(skill) ? { skill } : undefined;
+export function modeFromBranch(entries: readonly BranchEntry[], resolve: (skill: string) => ActiveMode = (skill) => ({ skill })): ModeState {
+  let state: ModeState = {};
+  for (const entry of entries) {
+    if (entry.type === 'custom' && entry.customType === MODE_ENTRY) {
+      const skill = storedSkill(entry.data);
+      state = skill === undefined ? exitMode(state) : enterMode(state, resolve(skill));
+    } else if (entry.type === 'message' && (entry as { message?: { role?: string } }).message?.role === 'assistant') state = afterRequest(state);
   }
-  return undefined;
+  return state;
+}
+
+/** Cursor's custom-mode notices for the next request (CLI `custom-modes` module). */
+export function modeNotice(state: ModeState): string | undefined {
+  const lines: string[] = [];
+  const { active, exited } = state;
+  if (exited !== undefined && exited !== active?.skill) lines.push(`The user has exited ${exited} custom mode. Stop following that mode's skill. Continue without those constraints.`);
+  if (active?.path === undefined && active !== undefined) lines.push(`Mode ${active.skill} is on, but no loaded skill has that name. Tell the user to run /mode off or /mode <skill>.`);
+  else if (active?.path !== undefined && !existsSync(active.path)) lines.push(`Mode ${active.skill} is on, but its skill file ${active.path} no longer exists. Tell the user to run /mode off or /mode <skill>.`);
+  else if (active?.lifecycle === 'entered')
+    lines.push(`The user has entered ${active.skill} custom mode. Follow the skill instructions in ${JSON.stringify(active.path)} until the user exits or switches modes. Do not drift back to default agent behavior.`);
+  else if (active !== undefined)
+    lines.push(
+      `Reminder: you are still in ${active.skill} mode. Follow that mode's skill on this turn. Do not drop it because the request looks small or you already have context. Do not drift back to default agent behavior. If you cannot state the mode's hard rules, read ${JSON.stringify(active.path)} before acting.`,
+    );
+  return lines.length === 0 ? undefined : lines.join('\n\n');
 }
 
 /**
- * The mode text for every request: the skill block in the same shape as Pi's own
- * `/skill:name` expansion (agent-session.js `_expandSkillCommand`), which Pi does not export as a function.
+ * The skill a mode keeps in context on every request until the user leaves it, in the block Pi's own /skill:name
+ * expansion builds. Cursor keeps the attached skill durable in the conversation; a section keeps it in every request,
+ * through compaction and restarts, and Pi re-sends a section only when it changes.
  */
-export function modeSection(mode: ActiveMode): string {
-  if (mode.path === undefined) return `Mode ${mode.skill} is on, but no loaded skill has that name. Tell the user to run /mode off or /mode <skill>.`;
-  if (!existsSync(mode.path)) return `Mode ${mode.skill} is on, but its skill file ${mode.path} no longer exists. Tell the user to run /mode off or /mode <skill>.`;
-  // The frontmatter, including `reminder`, stays out of the model's context in a mode (MODE-004).
-  const { body } = parseFrontmatter(readFileSync(mode.path, 'utf8'));
-  return [`Mode ${mode.skill} is on for every turn until the user runs /mode off.`, `<skill name="${mode.skill}" location="${mode.path}">`, `References are relative to ${dirname(mode.path)}.`, '', body.trim(), '</skill>'].join('\n');
+export function modeSkill(mode: ActiveMode): string | undefined {
+  if (mode.path === undefined || !existsSync(mode.path)) return undefined;
+  // The frontmatter stays out of the model's context in a mode (MODE-004).
+  const body = stripFrontmatter(readFileSync(mode.path, 'utf8')).trim();
+  return [`<skill name="${mode.skill}" location="${mode.path}">`, `References are relative to ${dirname(mode.path)}.`, '', body, '</skill>'].join('\n');
 }
 
 // A mode's badge shows the skill's `icon` (default: lightning) and `color`. Icon names map to terminal glyphs and
@@ -97,17 +146,22 @@ function loadedSkills(pi: ExtensionAPI): Map<string, string> {
   return skills;
 }
 
-export function registerMode(pi: ExtensionAPI): { section: () => string | undefined } {
-  let active: ActiveMode | undefined;
+/** The mode sections of one request: Cursor's notice, and the skill the mode keeps in context. */
+export interface ModeSections {
+  pstack_mode?: string;
+  pstack_mode_skill?: string;
+}
+
+export function registerMode(pi: ExtensionAPI): { sections: () => ModeSections } {
+  let state: ModeState = {};
   const show = (ctx: ExtensionContext) => {
     if (!ctx.hasUI) return;
-    const badge = active === undefined ? undefined : modeBadge(active);
+    const badge = state.active === undefined ? undefined : modeBadge(state.active);
     ctx.ui.setStatus(STATUS_KEY, badge === undefined ? undefined : badge.color === undefined ? badge.text : ctx.ui.theme.fg(badge.color, badge.text));
   };
   // The skill is looked up by name among loaded skills; a stored path is never read, since it can be stale or crafted.
   const restore = (ctx: ExtensionContext) => {
-    const stored = modeFromBranch(ctx.sessionManager.getBranch());
-    active = stored === undefined ? undefined : (tryResolve(stored.skill) ?? { skill: stored.skill });
+    state = modeFromBranch(ctx.sessionManager.getBranch(), (skill) => tryResolve(skill) ?? { skill });
     show(ctx);
   };
   pi.on('session_start', (_event, ctx) => restore(ctx));
@@ -131,11 +185,12 @@ export function registerMode(pi: ExtensionAPI): { section: () => string | undefi
 
   const handle = (args: string, ctx: ExtensionCommandContext) => {
     const command = parseModeArgs(args);
+    const { active } = state;
     if (command.kind === 'status') return ctx.ui.notify(active === undefined ? 'No mode is on.' : `Mode on: ${active.skill} (${active.path ?? 'no loaded skill has that name'}).`, 'info');
-    active = command.kind === 'off' ? undefined : resolveSkill(command.skill);
-    pi.appendEntry(MODE_ENTRY, active === undefined ? null : { skill: active.skill });
+    state = command.kind === 'off' ? exitMode(state) : enterMode(state, resolveSkill(command.skill));
+    pi.appendEntry(MODE_ENTRY, state.active === undefined ? null : { skill: state.active.skill });
     show(ctx);
-    ctx.ui.notify(active === undefined ? 'Mode off.' : `Mode on: ${active.skill}. /mode off exits.`, 'info');
+    ctx.ui.notify(state.active === undefined ? 'Mode off.' : `Mode on: ${state.active.skill}. /mode off exits.`, 'info');
     if (command.kind === 'set' && command.task !== '') pi.sendUserMessage(command.task, { expandPromptTemplates: true, ...(ctx.isIdle() ? {} : { deliverAs: 'followUp' as const }) });
     return undefined;
   };
@@ -152,5 +207,12 @@ export function registerMode(pi: ExtensionAPI): { section: () => string | undefi
     },
   });
 
-  return { section: () => (active === undefined ? undefined : modeSection(active)) };
+  return {
+    sections: () => {
+      const notice = modeNotice(state);
+      const skill = state.active === undefined ? undefined : modeSkill(state.active);
+      state = afterRequest(state);
+      return { ...(notice === undefined ? {} : { pstack_mode: notice }), ...(skill === undefined ? {} : { pstack_mode_skill: skill }) };
+    },
+  };
 }

package/src/paths.ts

@@ -23,6 +23,24 @@ export function routinesDir(): string {
   return join(stateDir(), 'routines');
 }
 
+/** Plan-mode artifacts, the way Cursor keeps a plan file under `~/.cursor/plans`. */
+export function plansDir(): string {
+  return join(stateDir(), 'plans');
+}
+
+/** Desired-state registry and supervisor runtime for one workspace. */
+export function durableDir(cwd: string): string {
+  return join(stateDir(), 'durable', workspaceSlug(cwd));
+}
+
+export function durableRegistryPath(cwd: string): string {
+  return join(durableDir(cwd), 'subscriptions.json');
+}
+
+export function durableRuntimeDir(cwd: string): string {
+  return join(durableDir(cwd), 'runtime');
+}
+
 /**
  * Pi's rule for a session folder name, so per-workspace state lines up with `<agentDir>/sessions/<slug>`. The live
  * `sessionManager.getSessionDir()` needs a session and names the current one, which is `<workspace>/subagents` in a

package/src/pi-command.ts

@@ -0,0 +1,12 @@
+import { existsSync } from 'node:fs';
+import { basename } from 'node:path';
+
+/**
+ * Argv prefix for spawning Pi: the running script when available so children match
+ * the parent's Pi version, else `pi` on PATH. Same rule as task/tool.ts historically.
+ */
+export function piCommand(): string[] {
+  const script = process.argv[1];
+  if (script !== undefined && !script.startsWith('/$bunfs/') && existsSync(script)) return [process.execPath, script];
+  return /^(node|bun)(\.exe)?$/.test(basename(process.execPath).toLowerCase()) ? ['pi'] : [process.execPath];
+}