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

package/src/child-env.ts

@@ -7,6 +7,7 @@ export const READONLY_ENV = 'PI_PSTACK_READONLY';
 export const ROOT_STORE_ENV = 'PI_PSTACK_ROOT_STORE';
 export const WORKSPACE_ENV = 'PI_PSTACK_WORKSPACE_STATE';
 export const ROOT_WORKSPACE_ENV = 'PI_PSTACK_ROOT_WORKSPACE';
+export const BUILD_PLAN_ENV = 'PI_PSTACK_BUILD_PLAN';
 
 export interface ChildIdentity {
   depth: number;
@@ -18,6 +19,7 @@ export interface ChildIdentity {
   workspaceState: string | undefined;
   /** The main chat's working directory, which authorizes every record stored in its shared workspace. */
   rootWorkspace: string | undefined;
+  buildPlan: string | undefined;
 }
 
 function read(): ChildIdentity {
@@ -31,6 +33,7 @@ function read(): ChildIdentity {
     rootStore: process.env[ROOT_STORE_ENV] || undefined,
     workspaceState: process.env[WORKSPACE_ENV] || undefined,
     rootWorkspace: process.env[ROOT_WORKSPACE_ENV] || undefined,
+    buildPlan: process.env[BUILD_PLAN_ENV] || undefined,
   };
 }
 
@@ -42,6 +45,7 @@ delete process.env[READONLY_ENV];
 delete process.env[ROOT_STORE_ENV];
 delete process.env[WORKSPACE_ENV];
 delete process.env[ROOT_WORKSPACE_ENV];
+delete process.env[BUILD_PLAN_ENV];
 
 /** Variables for a child of this process at `depth` (an agent keeps the depth it was created at). */
 export function childVariables(agentType: string, depth: number, readonly: boolean, rootStore: string, workspaceState: string, rootWorkspace: string): Record<string, string> {

package/src/index.ts

@@ -5,16 +5,17 @@ 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 { registerBackgroundShell } from './background-shell.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';
-import { artifactsDir, PACKAGE_ROOT, projectsDir, rootStoreDir, rulePath, SKILLS_DIR, storeDir, subagentDir } from './paths.ts';
+import { artifactsDir, PACKAGE_ROOT, projectsDir, rootStoreDir, rulePath, SKILLS_DIR, storeDir, subagentDir, terminalsDir } from './paths.ts';
 import { registerPlanMode } from './plan.ts';
 import { registerReadonlyShell } from './readonly-shell.ts';
 import { migrateLegacyRule, modelsSection, readRule } from './rule.ts';
-import { alwaysAppliedRules, hostSection, subagentsSection } from './sections.ts';
+import { alwaysAppliedRules, hostSection, subagentsSection, todayText } from './sections.ts';
 import { registerSubscriptions } from './subscriptions/index.ts';
 import { type AgentDefinition, loadAgentDefinitions } from './task/agents.ts';
 import { registerAgentStatus } from './task/status.ts';
@@ -39,6 +40,7 @@ function hostSections(pi: ExtensionAPI, ctx: ExtensionContext, agents: readonly
   const activeTools = pi.getActiveTools();
   return {
     pstack_host: hostSection({
+      today: todayText(new Date()),
       packageRoot: PACKAGE_ROOT,
       skillsDir: SKILLS_DIR,
       skillNames: packageSkillNames(pi.getCommands()),
@@ -51,6 +53,7 @@ function hostSections(pi: ExtensionAPI, ctx: ExtensionContext, agents: readonly
       rootStoreDir: rootStoreDir(ctx.cwd, ctx.sessionManager.getSessionId(), childIdentity.rootStore),
       projectsDir: projectsDir(ctx.cwd),
       artifactsDir: artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()),
+      terminalsDir: terminalsDir(ctx.cwd),
       loopAvailable: !isOneShot(ctx.mode),
       questionsAvailable: canAsk(ctx),
       activeTools,
@@ -103,7 +106,11 @@ export default function piPstack(pi: ExtensionAPI): void {
   });
 
   const mode = registerMode(pi);
-  const plan = registerPlanMode(pi, { buildInWorker: (planFile, request) => task.startBackground(`Build ${basename(planFile)}`, request, { environment: 'cloud' }) });
+  const plan = registerPlanMode(pi, {
+    ...(childIdentity.buildPlan === undefined ? {} : { buildPlan: childIdentity.buildPlan }),
+    setTodos: (items, ctx) => todos.replace(items, ctx),
+    buildInWorker: (planFile, request) => task.startBackground(`Build ${basename(planFile)}`, request, { environment: 'cloud', buildPlan: planFile }),
+  });
   registerVisualize(pi, { artifactsDir: (ctx) => artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()) });
   registerGenerateImage(pi, { artifactsDir: (ctx) => artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()), mayOffer: () => !childIdentity.readonly && !plan.enabled() });
   const ownType = agents.find((agent) => agent.type === childIdentity.agentType);
@@ -118,8 +125,16 @@ export default function piPstack(pi: ExtensionAPI): void {
       return undefined;
     },
   });
-  const loop = registerLoop(pi, { hasPendingWork: task.hasBackgroundWork });
-  const todos = registerTodoWrite(pi);
+  // A readonly agent's shell is the sandboxed one, and a background job would run outside that sandbox.
+  const shells = childIdentity.readonly
+    ? undefined
+    : registerBackgroundShell(pi, {
+        terminalsDir: (ctx) => terminalsDir(ctx.cwd),
+        waitsForJobs: (ctx) => childIdentity.depth === 0 && (ctx.mode === 'print' || ctx.mode === 'json'),
+        endsWithTurn: childIdentity.depth > 0,
+      });
+  const loop = registerLoop(pi, { hasPendingWork: () => task.hasBackgroundWork() || shells?.hasRunningJobs() === true });
+  const todos = registerTodoWrite(pi, childIdentity.readonly ? {} : { onWrite: plan.syncTodos });
   registerAskQuestion(pi);
   if (childIdentity.parentPid !== undefined) watchParent(pi, childIdentity.parentPid);
   if (childIdentity.readonly) registerReadonlyShell(pi);

package/src/linux-readonly-sandbox.ts

@@ -0,0 +1,121 @@
+// The Linux read-only sandbox: bubblewrap with every namespace unshared, the whole filesystem bound read-only, and a
+// seccomp filter that refuses Unix sockets. bubblewrap installs the filter itself, so this needs no nested user
+// namespace, which hosts with kernel.apparmor_restrict_unprivileged_userns=1 (Ubuntu 24.04 and later) refuse.
+import { spawnSync } from 'node:child_process';
+import { accessSync, closeSync, constants, existsSync, mkdtempSync, openSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+
+const LD_ABS_W = 0x20;
+const JEQ_K = 0x15;
+const JGE_K = 0x35;
+const RET_K = 0x06;
+const SECCOMP_RET_ALLOW = 0x7fff_0000;
+const SECCOMP_RET_ERRNO_EPERM = 0x0005_0001;
+const SECCOMP_RET_KILL_PROCESS = 0x8000_0000;
+const X32_SYSCALL_BIT = 0x4000_0000;
+const AF_UNIX = 1;
+
+const ARCHES: Record<string, { audit: number; socket: number; ioUringSetup: number }> = {
+  x64: { audit: 0xc000_003e, socket: 41, ioUringSetup: 425 },
+  arm64: { audit: 0xc000_00b7, socket: 198, ioUringSetup: 425 },
+};
+
+const instruction = (code: number, jt: number, jf: number, k: number): Buffer => {
+  const bytes = Buffer.alloc(8);
+  bytes.writeUInt16LE(code, 0);
+  bytes.writeUInt8(jt, 2);
+  bytes.writeUInt8(jf, 3);
+  bytes.writeUInt32LE(k >>> 0, 4);
+  return bytes;
+};
+
+/**
+ * A classic BPF seccomp program: socket(AF_UNIX, ...) and io_uring_setup fail with EPERM, any other architecture or
+ * the x32 ABI kills the process, and everything else is allowed. Jumps are relative to the next instruction.
+ */
+export function seccompFilter(arch: string): Buffer {
+  const target = ARCHES[arch];
+  if (target === undefined) throw new Error(`the read-only shell has no seccomp filter for ${arch}`);
+  return Buffer.concat([
+    instruction(LD_ABS_W, 0, 0, 4), // 0: architecture
+    instruction(JEQ_K, 0, 8, target.audit), // 1: native → 2, otherwise → 10
+    instruction(LD_ABS_W, 0, 0, 0), // 2: syscall number
+    instruction(JGE_K, 6, 0, X32_SYSCALL_BIT), // 3: x32 → 10
+    instruction(JEQ_K, 0, 2, target.socket), // 4: socket → 5, otherwise → 7
+    instruction(LD_ABS_W, 0, 0, 16), // 5: low word of the first argument, the domain
+    instruction(JEQ_K, 2, 1, AF_UNIX), // 6: AF_UNIX → 9, otherwise → 8
+    instruction(JEQ_K, 1, 0, target.ioUringSetup), // 7: io_uring_setup → 9, otherwise → 8
+    instruction(RET_K, 0, 0, SECCOMP_RET_ALLOW), // 8
+    instruction(RET_K, 0, 0, SECCOMP_RET_ERRNO_EPERM), // 9
+    instruction(RET_K, 0, 0, SECCOMP_RET_KILL_PROCESS), // 10
+  ]);
+}
+
+const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
+
+/** bubblewrap's arguments before the command: nothing is writable and nothing outside is reachable. */
+export function bwrapArgs(cwd: string): string[] {
+  return ['--new-session', '--die-with-parent', '--unshare-all', '--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--cap-drop', 'ALL', '--chdir', cwd, '--seccomp', '3'];
+}
+
+interface Sandbox {
+  bwrap: string;
+  filterPath: string;
+  shell: string;
+}
+
+/** The first executable `name` on PATH, so every command runs the bubblewrap the check ran. */
+function onPath(name: string): string | undefined {
+  for (const dir of (process.env['PATH'] ?? '').split(delimiter).filter((entry) => entry !== '')) {
+    const candidate = join(dir, name);
+    try {
+      accessSync(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      // Not here; keep looking.
+    }
+  }
+  return undefined;
+}
+
+let verified: { sandbox: Sandbox } | { error: Error } | undefined;
+
+/** The checked sandbox, or the error that stopped it; either is kept, so a failed host never retries into a weaker state. */
+function verifiedSandbox(): Sandbox {
+  verified ??= (() => {
+    try {
+      return { sandbox: checkSandbox() };
+    } catch (error) {
+      return { error: error instanceof Error ? error : new Error(String(error)) };
+    }
+  })();
+  if ('error' in verified) throw verified.error;
+  return verified.sandbox;
+}
+
+/** Writes the filter into a private directory and checks that bubblewrap can load it here. */
+function checkSandbox(): Sandbox {
+  const filter = seccompFilter(process.arch);
+  const bwrap = onPath('bwrap');
+  if (bwrap === undefined) throw new Error('bubblewrap (bwrap) is not available: no bwrap on PATH');
+  const dir = mkdtempSync(join(tmpdir(), 'pi-pstack-ro-'));
+  const filterPath = join(dir, 'unix-block.bpf');
+  writeFileSync(filterPath, filter, { mode: 0o400 });
+  const shell = existsSync('/bin/bash') ? '/bin/bash' : '/bin/sh';
+  const fd = openSync(filterPath, 'r');
+  try {
+    const probe = spawnSync(bwrap, [...bwrapArgs('/'), '--', shell, '-c', 'exit 0'], { stdio: ['ignore', 'ignore', 'pipe', fd], encoding: 'utf8', timeout: 15_000 });
+    if (probe.error !== undefined) throw new Error(`bubblewrap (bwrap) could not run: ${probe.error.message}`);
+    if (probe.status !== 0) throw new Error(`bubblewrap could not start the read-only sandbox: ${probe.stderr.trim() || `exit ${probe.status}`}`);
+  } finally {
+    closeSync(fd);
+  }
+  return { bwrap, filterPath, shell };
+}
+
+/** The shell command that runs `command` inside the read-only sandbox, or an error when no sandbox can start. */
+export function linuxReadonlyCommand(command: string, cwd: string): string {
+  const { bwrap, filterPath, shell } = verifiedSandbox();
+  return `exec ${quote(bwrap)} ${bwrapArgs(cwd).map(quote).join(' ')} -- ${quote(shell)} -c ${quote(command)} 3< ${quote(filterPath)}`;
+}

package/src/loop.ts

@@ -1,5 +1,7 @@
+import { randomUUID } from 'node:crypto';
+
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent';
-import { Type } from 'typebox';
+import { type Static, Type } from 'typebox';
 import { isOneShot } from './modes.ts';
 
 const DAY_MS = 86_400_000;
@@ -30,19 +32,16 @@ function delayOf(text: string): number {
   return ms;
 }
 
-export type LoopCommand = { kind: 'status' } | { kind: 'stop' } | { kind: 'start'; prompt: string; intervalMs?: number } | { kind: 'error'; message: string };
+export type LoopCommand = { kind: 'status' } | { kind: 'stop'; loopId?: string } | { 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(' '));
+function edgeInterval(text: string, edge: 'leading' | 'trailing'): { prompt: string; intervalMs: number } | undefined {
+  const tokens = [...text.matchAll(/\S+/g)];
+  for (let take = tokens.length; take >= 1; take -= 1) {
+    const start = edge === 'leading' ? 0 : (tokens[tokens.length - take]?.index ?? 0);
+    const end = edge === 'trailing' ? text.length : (tokens[take - 1]?.index ?? 0) + (tokens[take - 1]?.[0].length ?? 0);
+    const intervalMs = parseDuration(text.slice(start, end));
     if (intervalMs === undefined) continue;
-    const prompt = tokens
-      .slice(0, -take)
-      .join(' ')
-      .replace(/\s+every$/i, '')
-      .trim();
+    const prompt = (edge === 'leading' ? text.slice(end) : text.slice(0, start).replace(/\s+every\s*$/i, '')).trim();
     return { prompt, intervalMs };
   }
   return undefined;
@@ -51,20 +50,13 @@ function trailingInterval(text: string): { prompt: string; intervalMs: number }
 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 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 };
+  const stop = /^(?:stop|off)(?:\s+(\S+))?$/.exec(trimmed);
+  if (stop !== null) return { kind: 'stop', ...(stop[1] === undefined ? {} : { loopId: stop[1] }) };
+  const interval = edgeInterval(trimmed, 'leading') ?? edgeInterval(trimmed, 'trailing');
+  if (interval !== undefined) {
+    if (interval.intervalMs > MAX_DELAY_MS) return { kind: 'error', message: TOO_LONG };
+    if (interval.prompt === '') return { kind: 'error', message: '/loop needs a prompt: /loop [interval] <prompt>' };
+    return { kind: 'start', ...interval };
   }
   return { kind: 'start', prompt: trimmed };
 }
@@ -113,7 +105,7 @@ function createLoopController(pi: ExtensionAPI, options: LoopOptions) {
     if (loop === undefined) return;
     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 });
+    pi.sendUserMessage(loop.prompt, { expandPromptTemplates: true, deliverAs: 'followUp' });
   };
   /**
    * A timer fired. A fixed loop keeps its wall-clock cadence, like Cursor's sleep-and-echo shell loop, so a long run
@@ -167,31 +159,77 @@ function createLoopController(pi: ExtensionAPI, options: LoopOptions) {
     loop = { ...rest, nextWakeMs: delayMs };
   };
   const section = () => (loop === undefined ? undefined : loopSection(loop));
-  return { notify, stop, settled, start, arm, status, wake, clear, section, active: () => loop !== undefined };
+  return { stop, settled, start, arm, status, wake, clear, section, prompt: () => loop?.prompt, active: () => loop !== undefined };
+}
+
+function createLoopRegistry(pi: ExtensionAPI, options: LoopOptions) {
+  const controllers = new Map<string, ReturnType<typeof createLoopController>>();
+  const entries = () => {
+    for (const [id, controller] of controllers) if (!controller.active()) controllers.delete(id);
+    return [...controllers];
+  };
+  const choose = (loopId?: string, prompt?: string) => {
+    const active = entries();
+    const existing = active.find(([id, controller]) => (loopId !== undefined ? id === loopId : prompt !== undefined ? controller.prompt() === prompt : active.length === 1));
+    if (existing !== undefined) return { loopId: existing[0], controller: existing[1] };
+    if (loopId !== undefined) throw new Error(`No running loop has id "${loopId}". /loop lists running loops.`);
+    if (prompt !== undefined) {
+      const id = randomUUID();
+      const controller = createLoopController(pi, options);
+      controllers.set(id, controller);
+      return { loopId: id, controller };
+    }
+    if (active.length === 0) throw new Error('No loop is running.');
+    throw new Error(`Several loops are running. Pass loop_id to choose one, or use /loop stop <id>. Running loops:\n${active.map(([id, controller]) => `${id} ${controller.status()}`).join('\n')}`);
+  };
+  const status = () => {
+    const active = entries();
+    if (active.length === 0) return 'No loop is running. Usage: /loop [interval] <prompt>, with the interval at either end; /loop stop ends one.';
+    return active.map(([id, controller]) => (active.length === 1 ? controller.status() : `${id} ${controller.status()}`)).join('\n');
+  };
+  const section = () => {
+    const active = entries();
+    if (active.length === 0) return undefined;
+    if (active.length === 1) return active[0]?.[1].section();
+    return [...active.map(([id, controller]) => `Loop ${id} runs ${JSON.stringify(controller.prompt())}.\n${controller.section()}`), 'Several loops are running. Pass loop_id with wake_in or stop so only the intended loop changes.'].join(
+      '\n\n',
+    );
+  };
+  return { choose, entries, status, section };
 }
 
 type LoopController = ReturnType<typeof createLoopController>;
+type LoopRegistry = ReturnType<typeof createLoopRegistry>;
 
 const ONE_SHOT = '/loop needs an interactive or RPC session; print and JSON runs exit when the agent settles.';
 
-function handleLoopCommand(controller: LoopController, args: string, ctx: ExtensionCommandContext): void {
+function handleLoopCommand(registry: LoopRegistry, args: string, ctx: ExtensionCommandContext): void {
   const command = parseLoopArgs(args);
-  if (command.kind === 'status') controller.notify(ctx, controller.status());
-  else if (command.kind === 'stop') controller.stop(ctx, 'stopped by /loop stop.');
-  else if (command.kind === 'error') controller.notify(ctx, command.message);
-  else if (isOneShot(ctx.mode)) process.stderr.write(`${ONE_SHOT}\n`);
-  else controller.start(ctx, command.prompt, command.intervalMs);
+  try {
+    if (command.kind === 'status') ctx.ui.notify(registry.status(), 'info');
+    else if (command.kind === 'stop') registry.choose(command.loopId).controller.stop(ctx, 'stopped by /loop stop.');
+    else if (command.kind === 'error') ctx.ui.notify(command.message, 'error');
+    else if (isOneShot(ctx.mode)) process.stderr.write(`${ONE_SHOT}\n`);
+    else registry.choose(undefined, command.prompt).controller.start(ctx, command.prompt, command.intervalMs);
+  } catch (error) {
+    ctx.ui.notify(error instanceof Error ? error.message : String(error), 'error');
+  }
 }
 
 const LoopParams = Type.Object({
-  prompt: Type.Optional(Type.String({ description: 'Start (or replace) a loop that sends this prompt each run. It may be a skill or template command such as /poteto-mode <task>.' })),
+  loop_id: Type.Optional(Type.String({ description: 'Loop ID from an earlier Loop result. Required to wake, stop, or replace one loop when several are running. Omit with a new prompt to start an independent loop.' })),
+  prompt: Type.Optional(
+    Type.String({
+      description:
+        'Start a loop that sends this prompt each run. A different prompt starts an independent loop; the same prompt or an explicit loop_id replaces its earlier schedule. It may be a skill or template command such as /poteto-mode <task>.',
+    }),
+  ),
   interval: Type.Optional(Type.String({ description: 'With prompt: a fixed cadence such as 30m or 1h; the first run starts that long after this turn ends.' })),
   wake_in: Type.Optional(Type.String({ description: 'With prompt: the first run of an agent-paced loop. Alone: the next run of the running agent-paced loop. A duration such as 10m, at most 24d.' })),
   stop: Type.Optional(Type.Boolean({ description: 'End the loop once its goal is met.' })),
 });
 
-function loopToolText(controller: LoopController, params: { prompt?: string; interval?: string; wake_in?: string; stop?: boolean }, ctx: ExtensionContext): string {
-  if (isOneShot(ctx.mode)) throw new Error(`${ONE_SHOT} Do the work now instead of scheduling it.`);
+function loopToolText(controller: LoopController, params: Static<typeof LoopParams>, ctx: ExtensionContext): string {
   if (params.stop === true) {
     if (!controller.active()) throw new Error('No loop is running.');
     controller.stop(ctx, 'the agent ended it.');
@@ -215,32 +253,39 @@ function loopToolText(controller: LoopController, params: { prompt?: string; int
   return `Next loop run in ${formatMs(delay)}, after this turn ends.`;
 }
 
-function registerLoopTool(pi: ExtensionAPI, controller: LoopController): void {
+function registerLoopTool(pi: ExtensionAPI, registry: LoopRegistry): void {
   pi.registerTool({
     name: 'Loop',
     label: 'Loop',
-    description: '/loop for you: start a loop that re-sends a prompt at a fixed interval or at wakes you pick, schedule the next wake of an agent-paced loop, or stop the loop once its goal is met. Use it when a playbook says to arm /loop.',
+    description:
+      '/loop for you: start an independent loop that re-sends a prompt at a fixed interval or at wakes you pick, schedule its next wake, or stop it once its goal is met. Use it when a playbook says to arm /loop. Run the prompt once yourself in the turn that arms the loop; the first scheduled run comes after the interval or wake_in. Then confirm the interval, that the prompt already ran once, and when the first run comes. Each result names the loop ID. With several loops running, pass loop_id to wake or stop the intended loop.',
     promptSnippet: 'Start a /loop, schedule its next wake, or stop it',
     parameters: LoopParams,
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      return { content: [{ type: 'text', text: loopToolText(controller, params, ctx) }], details: undefined };
+      if (isOneShot(ctx.mode)) throw new Error(`${ONE_SHOT} Do the work now instead of scheduling it.`);
+      const { loopId, controller } = registry.choose(params.loop_id, params.prompt);
+      return { content: [{ type: 'text', text: `${loopToolText(controller, params, ctx)}\nLoop ID: ${loopId}` }], details: { loopId } };
     },
   });
 }
 
 /** /loop: run a prompt at a fixed interval, or at wakes the agent picks, until stopped. */
 export function registerLoop(pi: ExtensionAPI, options: LoopOptions): { section: () => string | undefined } {
-  const controller = createLoopController(pi, options);
+  const registry = createLoopRegistry(pi, options);
   pi.on('session_start', (_event, ctx) => {
     if (isOneShot(ctx.mode)) pi.setActiveTools(pi.getActiveTools().filter((name) => name !== 'Loop'));
   });
-  pi.on('agent_settled', (event, ctx) => controller.settled(ctx, event.aborted));
-  pi.on('session_shutdown', () => controller.clear());
+  pi.on('agent_settled', (event, ctx) => {
+    for (const [, controller] of registry.entries()) controller.settled(ctx, event.aborted);
+  });
+  pi.on('session_shutdown', () => {
+    for (const [, controller] of registry.entries()) controller.clear();
+  });
   pi.registerCommand('loop', {
-    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),
+    description: 'Run independent prompts repeatedly: /loop [interval] <prompt>, interval either end and like 30s, 5m, 1h, every 10 minutes (at most 24d); /loop lists them; /loop stop [id] stops one',
+    handler: async (args, ctx) => handleLoopCommand(registry, args, ctx),
   });
-  registerLoopTool(pi, controller);
-  return { section: controller.section };
+  registerLoopTool(pi, registry);
+  return { section: registry.section };
 }

package/src/paths.ts

@@ -75,6 +75,11 @@ export function artifactsDir(cwd: string, sessionId: string): string {
   return join(workspaceStateDir(cwd), 'artifacts', sessionId);
 }
 
+/** Background shell jobs' output files, `<shell id>.txt`, as Cursor keeps them in a workspace's terminals folder. */
+export function terminalsDir(cwd: string): string {
+  return join(workspaceStateDir(cwd), 'terminals');
+}
+
 export function worktreesDir(cwd: string): string {
   return join(workspaceStateDir(cwd), 'worktrees');
 }