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

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';
@@ -53,8 +53,8 @@ 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');
+  const body = stripFrontmatter(readFileSync(mode.path, 'utf8')).trim();
+  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, '</skill>'].join('\n');
 }
 
 // A mode's badge shows the skill's `icon` (default: lightning) and `color`. Icon names map to terminal glyphs and

package/src/paths.ts

@@ -23,6 +23,19 @@ export function routinesDir(): string {
   return join(stateDir(), 'routines');
 }
 
+/** 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];
+}

package/src/rule.ts

@@ -1,7 +1,7 @@
 import { existsSync, linkSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
-import { parseFrontmatter } from '@earendil-works/pi-coding-agent';
+import { stripFrontmatter } from '@earendil-works/pi-coding-agent';
 
 const RULE_SECTION_LIMIT = 8_000;
 const LEGACY_RULE_NAME = 'pstack-models.mdc';
@@ -26,9 +26,9 @@ export function migrateLegacyRule(path: string): void {
     if (errno(error) === 'ENOENT') return;
     throw error;
   }
-  const { body } = parseFrontmatter(text);
+  const body = stripFrontmatter(text).trim();
   try {
-    writeFileSync(path, `${body.trim()}\n`, { flag: 'wx' });
+    writeFileSync(path, `${body}\n`, { flag: 'wx' });
   } catch (error) {
     if (errno(error) === 'EEXIST') return;
     throw error;
@@ -50,7 +50,7 @@ export function migrateLegacyRule(path: string): void {
 /** The rule inline and bounded. A stray frontmatter block is not part of the rule. */
 export function modelsSection(ruleText: string | undefined, path: string): string {
   if (ruleText === undefined) return `No pstack model rule exists at ${path}. Every role uses its skill default until /setup-pstack writes one.`;
-  const body = parseFrontmatter(ruleText).body.trim();
+  const body = stripFrontmatter(ruleText).trim();
   if (body.length <= RULE_SECTION_LIMIT) return `Path: ${path}\n${body}`;
   return `Path: ${path}\n${body.slice(0, RULE_SECTION_LIMIT)}\n[truncated: the rule is ${body.length} characters; read ${path} for the rest]`;
 }

package/src/sections.ts

@@ -83,13 +83,14 @@ export function hostSection(facts: HostFacts): string {
     '- The user keeps a skill on every turn with `/mode <skill>` (exit `/mode off`) and plans without edits with `/plan` (exit `/plan off`).',
     '- PR operations use the forge command the step gives, such as `gh pr create`. Bugbot comments on a GitHub PR are ordinary review threads; skip a step that starts, waits for, or configures Bugbot when the PR has no Bugbot check or comment.',
     '- MCP tools are named mcp__<server>__<tool>; `pi mcp list` shows the servers.',
-    "- Media in a reply: Pi's chat renders no image or video inside a reply. To show the user a screenshot or a frame, read the image file with the read tool, which displays it inline in terminals that support images, and name its path. A video cannot play in Pi, so give the video's path and read one frame from each slide.",
+    "- Media in a reply: Pi's chat renders no image or video inside a reply. To show a screenshot or a frame, read the image file with the read tool, which displays it inline in terminals that support images, and name its path. For a watchable catch-up video, open the local file with the system player (`open` on macOS, `xdg-open` on Linux), read one frame from each slide, and name the video path. Pi chat still does not play the video inline.",
     `- pi-pstack's README (${join(facts.packageRoot, 'README.md')}) and guide (${join(facts.packageRoot, 'docs/guide')}) describe installing and using it.`,
     ...(facts.activeTools.includes('Task')
       ? [
           "- Isolated workers (Task environment \"cloud\") run on this machine in their own git worktree on branch pstack/<agent id>, created from cloud_base_branch or this checkout's HEAD commit, so uncommitted changes do not reach them. They share this workspace's Projects, stores, and subagent records. The Task result names the worktree and branch; merge that branch to take the subagent's work. Pi never deletes these worktrees or branches; the worktree-cleanup playbook prunes them.",
         ]
       : []),
+    '- Always-applied engineering rules (also `/no-inline-imports` and `/typescript-exhaustive-switch`): place imports at the top of a module, never inline in bodies or type positions unless a circular dependency forces it and is documented; in switches over discriminated unions or enums, use a `never` check in the default case so new variants fail at compile time until handled.',
   ].join('\n');
 }
 

package/src/subscriptions/durable-store.ts

@@ -0,0 +1,482 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+import { durableRegistryPath, durableRuntimeDir } from '../paths.ts';
+import { parseCron } from './cron.ts';
+import type { ArmStatus, DurableRegistry, DurableSubscription, PendingEvent, StoredSubscription, SupervisorLock } from './durable-types.ts';
+import { routineSlug } from './webhook.ts';
+
+export function canonicalPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    const absolute = resolve(path);
+    return absolute === dirname(absolute) ? absolute : join(canonicalPath(dirname(absolute)), absolute.slice(dirname(absolute).length + 1));
+  }
+}
+
+export function alive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+function writeAtomic(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    renameSync(temporary, path);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+const runtime = (cwd: string) => durableRuntimeDir(canonicalPath(cwd));
+export const supervisorLockPath = (cwd: string) => join(runtime(cwd), 'supervisor.lock');
+const registryLockPath = (cwd: string) => join(runtime(cwd), 'registry.lock');
+export const ownerLockPath = (cwd: string, id: string) => join(runtime(cwd), `owner-${createHash('sha256').update(id).digest('hex')}.lock`);
+
+export type Lease = { token: string; release: () => void };
+
+/** Publish a nonempty directory atomically. Recovery removes only the dead holder's token. */
+export function acquireLease(path: string): Lease | undefined {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const token = `${process.pid}-${randomUUID()}`;
+  const temporary = `${path}.${token}.tmp`;
+  mkdirSync(temporary, { mode: 0o700 });
+  try {
+    writeFileSync(join(temporary, token), '', { mode: 0o600 });
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      try {
+        renameSync(temporary, path);
+        return {
+          token,
+          release: () => {
+            rmSync(join(path, token), { force: true });
+            try {
+              rmdirSync(path);
+            } catch (error) {
+              if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+            }
+          },
+        };
+      } catch (error) {
+        if (!['ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+      }
+      let holders: string[];
+      try {
+        holders = readdirSync(path);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw error;
+      }
+      for (const holder of holders) {
+        const pid = Number(/^(\d+)-[a-f0-9-]+$/.exec(holder)?.[1]);
+        if (!Number.isInteger(pid)) throw new Error(`Invalid subscription lock ${path}. Retain it for diagnosis.`);
+        if (alive(pid)) return undefined;
+        rmSync(join(path, holder), { force: true });
+      }
+      try {
+        rmdirSync(path);
+      } catch (error) {
+        if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+      }
+    }
+    return undefined;
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+export function ownerIsLive(cwd: string, sessionId: string): boolean {
+  const path = ownerLockPath(cwd, sessionId);
+  try {
+    const holders = readdirSync(path);
+    for (const holder of holders) {
+      const pid = Number(/^(\d+)-[a-f0-9-]+$/.exec(holder)?.[1]);
+      if (Number.isInteger(pid) && alive(pid)) return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+function withRegistryLock<T>(cwd: string, work: () => T): T {
+  const deadline = performance.now() + 5_000;
+  do {
+    const lease = acquireLease(registryLockPath(cwd));
+    if (lease !== undefined) {
+      try {
+        return work();
+      } finally {
+        lease.release();
+      }
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+  } while (performance.now() < deadline);
+  throw new Error(`Subscription registry is busy in ${cwd}. Retry when the live writer finishes.`);
+}
+
+function validSubscription(value: unknown): value is DurableSubscription {
+  if (typeof value !== 'object' || value === null) return false;
+  const sub = value as DurableSubscription;
+  if (typeof sub.id !== 'string' || !/^sub-[a-zA-Z0-9-]+$/.test(sub.id) || typeof sub.name !== 'string' || !sub.name.trim() || !Number.isFinite(sub.createdAt) || !Number.isFinite(sub.expiresAt)) return false;
+  if ((sub.ownerSessionId !== undefined && (typeof sub.ownerSessionId !== 'string' || !sub.ownerSessionId)) || (sub.ownerSessionFile !== undefined && typeof sub.ownerSessionFile !== 'string')) return false;
+  const c = sub.config;
+  if (typeof c !== 'object' || c === null) return false;
+  if (c.kind === 'github') {
+    const t = c.target;
+    return (
+      typeof t === 'object' &&
+      t !== null &&
+      (t.scope === 'pr'
+        ? typeof t.prUrl === 'string' && /^https:\/\/[^\s/]+\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/pull\/\d+\/?$/.test(t.prUrl)
+        : (t.scope === 'repo' || t.scope === 'author') &&
+          typeof t.repo === 'string' &&
+          /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(t.repo) &&
+          (t.scope !== 'author' || (typeof t.author === 'string' && /^(?:@me|[A-Za-z0-9](?:[A-Za-z0-9-]|\[bot\]|\/)*)$/.test(t.author))))
+    );
+  }
+  if (typeof c.prompt !== 'string') return false;
+  if (c.kind === 'webhook') {
+    try {
+      return typeof c.slug === 'string' && routineSlug(sub.name) === c.slug;
+    } catch {
+      return false;
+    }
+  }
+  if (c.kind !== 'timer' || typeof c.once !== 'boolean' || !['wake_self', 'new_session'].includes(c.strategy)) return false;
+  if ((c.cron === undefined) === (c.delaySeconds === undefined)) return false;
+  if (c.cron !== undefined) {
+    try {
+      parseCron(c.cron);
+    } catch {
+      return false;
+    }
+  }
+  return c.delaySeconds === undefined || (Number.isInteger(c.delaySeconds) && c.delaySeconds >= 1);
+}
+
+function emptyRegistry(cwd: string): DurableRegistry {
+  return { version: 2, workspaceCwd: canonicalPath(cwd), revision: 0, subscriptions: [], pending: [] };
+}
+
+function migratedOwner(sub: DurableSubscription): string | undefined {
+  if (sub.ownerSessionId !== undefined) return sub.ownerSessionId;
+  if (sub.ownerSessionFile === undefined) return undefined;
+  try {
+    const header = JSON.parse(readFileSync(sub.ownerSessionFile, 'utf8').split('\n')[0] ?? '');
+    return header.type === 'session' && typeof header.id === 'string' && header.id ? header.id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function loadRegistry(cwd: string): DurableRegistry {
+  const path = durableRegistryPath(canonicalPath(cwd));
+  if (!existsSync(path)) return emptyRegistry(cwd);
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (typeof raw !== 'object' || raw === null || ![1, 2].includes(raw.version) || !Array.isArray(raw.subscriptions) || !raw.subscriptions.every(validSubscription)) throw new Error('invalid subscriptions');
+    if (typeof raw.workspaceCwd !== 'string' || canonicalPath(raw.workspaceCwd) !== canonicalPath(cwd)) throw new Error('Registry belongs to a different workspace.');
+    if (raw.version === 1) {
+      return {
+        ...emptyRegistry(cwd),
+        revision: 1,
+        subscriptions: raw.subscriptions.map((sub: DurableSubscription) => {
+          const { detachedDelivery: _legacy, ...config } = sub;
+          const ownerSessionId = migratedOwner(sub);
+          return { ...config, ...(ownerSessionId === undefined ? { lastError: { at: Date.now(), text: 'Owner session ID unavailable. Recreate this subscription.' } } : { ownerSessionId }), revision: 1, lifecycle: 'active' };
+        }),
+      };
+    }
+    if (!Number.isInteger(raw.revision) || raw.revision < 0 || !Array.isArray(raw.pending)) throw new Error('invalid registry revision or pending events');
+    const ids = new Set<string>();
+    for (const sub of raw.subscriptions) {
+      if (ids.has(sub.id) || !Number.isInteger(sub.revision) || !['active', 'completed', 'cancelled', 'expired'].includes(sub.lifecycle)) throw new Error('invalid subscription lifecycle');
+      ids.add(sub.id);
+      if (sub.lastOccurrence !== undefined && typeof sub.lastOccurrence !== 'string') throw new Error('invalid occurrence');
+      for (const note of [sub.lastEvent, sub.lastError, sub.lastOutcome]) if (note !== undefined && (typeof note.text !== 'string' || !Number.isFinite(note.at))) throw new Error('invalid subscription status');
+    }
+    const eventIds = new Set<string>();
+    for (const event of raw.pending) {
+      if (
+        typeof event.id !== 'string' ||
+        eventIds.has(event.id) ||
+        !ids.has(event.subscriptionId) ||
+        !Number.isFinite(event.acceptedAt) ||
+        typeof event.content !== 'string' ||
+        (event.claim !== undefined && (!Number.isInteger(event.claim.pid) || event.claim.pid <= 0 || typeof event.claim.token !== 'string' || !['live', 'detached'].includes(event.claim.mode))) ||
+        (event.attempts !== undefined && (!Number.isInteger(event.attempts) || event.attempts < 0)) ||
+        (event.retryAt !== undefined && !Number.isFinite(event.retryAt))
+      )
+        throw new Error('invalid pending event');
+      eventIds.add(event.id);
+    }
+    return { version: 2, workspaceCwd: canonicalPath(cwd), revision: raw.revision, subscriptions: raw.subscriptions, pending: raw.pending };
+  } catch (error) {
+    throw new Error(`Cannot read authoritative subscription registry ${path}. Retain the file for diagnosis. ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export function readRegistry(cwd: string): DurableRegistry {
+  const path = durableRegistryPath(canonicalPath(cwd));
+  const registry = loadRegistry(cwd);
+  if (existsSync(path) && JSON.parse(readFileSync(path, 'utf8')).version === 1) {
+    return withRegistryLock(cwd, () => {
+      const current = loadRegistry(cwd);
+      writeAtomic(path, current);
+      return current;
+    });
+  }
+  return registry;
+}
+
+function transaction<T>(cwd: string, change: (registry: DurableRegistry) => T): T {
+  return withRegistryLock(cwd, () => {
+    const registry = loadRegistry(cwd);
+    const before = JSON.stringify(registry);
+    const result = change(registry);
+    if (JSON.stringify(registry) !== before) {
+      registry.revision += 1;
+      writeAtomic(durableRegistryPath(canonicalPath(cwd)), registry);
+    }
+    return result;
+  });
+}
+
+export const isDesired = (sub: StoredSubscription, now = Date.now()) => sub.lifecycle === 'active' && sub.expiresAt > now;
+export function visibleSubscriptions(registry: DurableRegistry, now = Date.now()): StoredSubscription[] {
+  return registry.subscriptions.filter((sub) => sub.lifecycle !== 'cancelled' && (isDesired(sub, now) || registry.pending.some((event) => event.subscriptionId === sub.id) || sub.lastOutcome !== undefined));
+}
+
+export function createDesired(cwd: string, sub: DurableSubscription): { created: boolean; subscription: StoredSubscription } {
+  if (!validSubscription(sub)) throw new Error('Invalid subscription configuration.');
+  return transaction(cwd, (registry) => {
+    const existing = registry.subscriptions.find((entry) => isDesired(entry) && entry.name === sub.name);
+    if (existing !== undefined) return { created: false, subscription: existing };
+    if (registry.subscriptions.some((entry) => entry.id === sub.id)) throw new Error(`Subscription identity ${sub.id} already exists.`);
+    const config = sub.config;
+    if (config.kind === 'webhook') {
+      const clash = registry.subscriptions.find((entry) => isDesired(entry) && entry.config.kind === 'webhook' && entry.config.slug === config.slug);
+      if (clash !== undefined) throw new Error(`Routine "${clash.name}" already uses the slug ${config.slug}.`);
+    }
+    const { detachedDelivery: _legacy, ...input } = sub;
+    const stored: StoredSubscription = { ...input, revision: registry.revision + 1, lifecycle: 'active' };
+    registry.subscriptions.push(stored);
+    return { created: true, subscription: stored };
+  });
+}
+
+export function cancelDesired(cwd: string, key: string): StoredSubscription | undefined {
+  return transaction(cwd, (registry) => {
+    const candidates = visibleSubscriptions(registry);
+    const sub = candidates.find((entry) => entry.id === key) ?? candidates.find((entry) => entry.name === key && isDesired(entry)) ?? candidates.find((entry) => entry.name === key);
+    if (sub === undefined) return undefined;
+    sub.lifecycle = 'cancelled';
+    delete sub.lastOutcome;
+    registry.pending = registry.pending.filter((event) => event.subscriptionId !== sub.id);
+    return sub;
+  });
+}
+
+export function expireDesired(cwd: string, at = Date.now()): void {
+  transaction(cwd, (registry) => {
+    for (const sub of registry.subscriptions) if (sub.lifecycle === 'active' && sub.expiresAt <= at) sub.lifecycle = 'expired';
+  });
+}
+
+export const MAX_PENDING_PER_SUBSCRIPTION = 20;
+
+export function acceptEvent(cwd: string, subscriptionId: string, occurrence: string, content: string, at = Date.now()): 'accepted' | 'duplicate' | 'inactive' {
+  return transaction(cwd, (registry) => {
+    const sub = registry.subscriptions.find((entry) => entry.id === subscriptionId);
+    if (sub === undefined || !isDesired(sub, at)) return 'inactive';
+    if (sub.lastOccurrence === occurrence || registry.pending.some((event) => event.id === occurrence)) return 'duplicate';
+    const forSub = registry.pending.filter((event) => event.subscriptionId === subscriptionId);
+    if (forSub.length >= MAX_PENDING_PER_SUBSCRIPTION) {
+      const oldest = forSub[0];
+      if (oldest !== undefined) {
+        registry.pending = registry.pending.filter((event) => event.id !== oldest.id);
+      }
+    }
+    registry.pending.push({ id: occurrence, subscriptionId, acceptedAt: at, content });
+    sub.lastOccurrence = occurrence;
+    sub.lastEvent = { at, text: 'accepted' };
+    delete sub.lastError;
+    if (sub.config.kind === 'timer' && sub.config.once) sub.lifecycle = 'completed';
+    return 'accepted';
+  });
+}
+
+export function deliverOwner(cwd: string, ownerSessionId: string, eligible: () => boolean, send: (sub: StoredSubscription, event: PendingEvent) => void): void {
+  transaction(cwd, (registry) => {
+    for (const event of [...registry.pending]) {
+      const sub = registry.subscriptions.find((entry) => entry.id === event.subscriptionId);
+      if (sub === undefined || sub.ownerSessionId !== ownerSessionId || sub.lifecycle === 'cancelled' || (sub.config.kind === 'timer' && sub.config.strategy === 'new_session')) continue;
+      if (!eligible()) return;
+      // Pi enqueue and disk acknowledgement cannot commit atomically. A crash can replay this event.
+      send(sub, event);
+      registry.pending = registry.pending.filter((entry) => entry.id !== event.id);
+    }
+  });
+}
+
+export function startFresh(
+  cwd: string,
+  eventId: string,
+  ownerSessionId: string | undefined,
+  eligible: () => boolean,
+  run: (sub: StoredSubscription, event: PendingEvent) => Promise<void> | void,
+): { token: string; result: Promise<void> } | undefined {
+  const claim = transaction(cwd, (registry) => {
+    const event = registry.pending.find((entry) => entry.id === eventId);
+    const sub = registry.subscriptions.find((entry) => entry.id === event?.subscriptionId);
+    if (
+      event === undefined ||
+      sub === undefined ||
+      sub.lifecycle === 'cancelled' ||
+      sub.config.kind !== 'timer' ||
+      sub.config.strategy !== 'new_session' ||
+      sub.ownerSessionId === undefined ||
+      (event.claim !== undefined && alive(event.claim.pid)) ||
+      (event.retryAt !== undefined && Date.now() < event.retryAt) ||
+      Date.now() >= sub.expiresAt ||
+      !eligible()
+    )
+      return undefined;
+    if (ownerSessionId === undefined ? sub.ownerSessionId !== undefined && ownerIsLive(cwd, sub.ownerSessionId) : sub.ownerSessionId !== ownerSessionId) return undefined;
+    const token = randomUUID();
+    event.claim = { pid: process.pid, token, mode: ownerSessionId === undefined ? 'detached' : 'live' };
+    return { token, sub, event };
+  });
+  if (claim === undefined) return undefined;
+  let result: Promise<void>;
+  try {
+    result = Promise.resolve(run(claim.sub, claim.event));
+  } catch (error) {
+    result = Promise.reject(error);
+  }
+  return { token: claim.token, result };
+}
+
+export function finishFresh(cwd: string, eventId: string, token: string, error?: unknown): void {
+  transaction(cwd, (registry) => {
+    const event = registry.pending.find((entry) => entry.id === eventId && entry.claim?.token === token);
+    if (event === undefined) return;
+    const sub = registry.subscriptions.find((entry) => entry.id === event.subscriptionId);
+    if (sub === undefined) return;
+    if (error !== undefined) {
+      const attempts = (event.attempts ?? 0) + 1;
+      const MAX_ATTEMPTS = 5;
+      sub.lastError = { at: Date.now(), text: error instanceof Error ? error.message : String(error) };
+      delete event.claim;
+      event.attempts = attempts;
+      if (attempts >= MAX_ATTEMPTS || Date.now() >= sub.expiresAt) {
+        registry.pending = registry.pending.filter((entry) => entry.id !== eventId);
+      } else {
+        const backoffMs = Math.min(60_000, 250 * 2 ** (attempts - 1));
+        event.retryAt = Date.now() + backoffMs;
+      }
+    } else {
+      sub.lastOutcome = { at: Date.now(), text: event.claim?.mode === 'live' ? 'live Task callback accepted' : 'detached run completed' };
+      delete sub.lastError;
+      registry.pending = registry.pending.filter((entry) => entry.id !== eventId);
+    }
+  });
+}
+
+export function clearError(cwd: string, id: string): void {
+  transaction(cwd, (registry) => {
+    const sub = registry.subscriptions.find((entry) => entry.id === id);
+    if (sub !== undefined) delete sub.lastError;
+  });
+}
+
+export function recordError(cwd: string, id: string, error: unknown): void {
+  const text = error instanceof Error ? error.message : String(error);
+  transaction(cwd, (registry) => {
+    const sub = registry.subscriptions.find((entry) => entry.id === id);
+    if (sub !== undefined && sub.lastError?.text !== text) {
+      sub.lastError = { at: Date.now(), text };
+    }
+  });
+}
+
+export function readLock(cwd: string): SupervisorLock | undefined {
+  try {
+    const value = JSON.parse(readFileSync(supervisorLockPath(cwd), 'utf8'));
+    return Number.isInteger(value.pid) && value.pid > 0 && Number.isFinite(value.startedAt) && typeof value.epoch === 'string' && value.epoch !== '' ? { pid: value.pid, startedAt: value.startedAt, epoch: value.epoch } : undefined;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw new Error(`Cannot read supervisor lock ${supervisorLockPath(cwd)}. ${String(error)}`);
+  }
+}
+export function isSupervisorLive(cwd: string): boolean {
+  const lock = readLock(cwd);
+  return lock !== undefined && alive(lock.pid);
+}
+export function acquireSupervisorLock(cwd: string, pid = process.pid, startedAt = Date.now()): { acquired: true } | { acquired: false; alreadyRunning: true; pid: number } {
+  return withRegistryLock(cwd, () => {
+    try {
+      const raw = JSON.parse(readFileSync(supervisorLockPath(cwd), 'utf8'));
+      if (Number.isInteger(raw.pid) && raw.pid > 0 && alive(raw.pid)) {
+        if (typeof raw.epoch === 'string' && raw.epoch !== '') {
+          return { acquired: false, alreadyRunning: true, pid: raw.pid };
+        }
+        try {
+          process.kill(raw.pid, 'SIGTERM');
+        } catch {}
+        const deadline = Date.now() + 1_000;
+        while (Date.now() < deadline && alive(raw.pid)) {
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+        }
+        if (alive(raw.pid)) {
+          return { acquired: false, alreadyRunning: true, pid: raw.pid };
+        }
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        // Corrupted lock file: overwrite with clean lock
+      }
+    }
+    writeAtomic(supervisorLockPath(cwd), { pid, startedAt, epoch: randomUUID() });
+    return { acquired: true };
+  });
+}
+export function releaseSupervisorLock(cwd: string, pid = process.pid, epoch?: string): void {
+  withRegistryLock(cwd, () => {
+    const lock = readLock(cwd);
+    if (lock?.pid === pid && (epoch === undefined || epoch === lock.epoch)) rmSync(supervisorLockPath(cwd), { force: true });
+  });
+}
+
+const armPath = (cwd: string, id: string) => join(runtime(cwd), 'arms', `${createHash('sha256').update(id).digest('hex')}.json`);
+export function writeArm(cwd: string, status: ArmStatus): void {
+  writeAtomic(armPath(cwd, status.subscriptionId), status);
+}
+export function readArm(cwd: string, sub: StoredSubscription): ArmStatus | undefined {
+  const lock = readLock(cwd);
+  if (lock === undefined || !alive(lock.pid)) return undefined;
+  try {
+    const status = JSON.parse(readFileSync(armPath(cwd, sub.id), 'utf8')) as ArmStatus;
+    return status.subscriptionId === sub.id &&
+      status.revision === sub.revision &&
+      status.epoch === lock.epoch &&
+      ((status.state === 'error' && typeof status.message === 'string') || (status.state === 'ready' && (status.url === undefined || typeof status.url === 'string')))
+      ? status
+      : undefined;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}

package/src/subscriptions/durable-types.ts

@@ -0,0 +1,41 @@
+export type Target = { scope: 'pr'; prUrl: string } | { scope: 'repo'; repo: string } | { scope: 'author'; author: string; repo: string };
+export type Config = { kind: 'github'; target: Target } | { kind: 'timer'; prompt: string; cron?: string; delaySeconds?: number; once: boolean; strategy: 'wake_self' | 'new_session' } | { kind: 'webhook'; prompt: string; slug: string };
+
+export type Subscription = { id: string; name: string; createdAt: number; expiresAt: number; config: Config };
+export type DurableSubscription = Subscription & {
+  ownerSessionId?: string;
+  ownerSessionFile?: string;
+  /** Read only during v1 migration. Delivery is determined by config, never this flag. */
+  detachedDelivery?: 'spawn' | 'park';
+};
+export type Note = { at: number; text: string };
+export type StoredSubscription = DurableSubscription & {
+  revision: number;
+  lifecycle: 'active' | 'completed' | 'cancelled' | 'expired';
+  lastOccurrence?: string;
+  lastEvent?: Note;
+  lastError?: Note;
+  lastOutcome?: Note;
+};
+export type PendingEvent = {
+  id: string;
+  subscriptionId: string;
+  acceptedAt: number;
+  content: string;
+  claim?: { pid: number; token: string; mode: 'live' | 'detached' };
+  attempts?: number;
+  retryAt?: number;
+};
+export type DurableRegistry = {
+  version: 2;
+  workspaceCwd: string;
+  revision: number;
+  subscriptions: StoredSubscription[];
+  pending: PendingEvent[];
+};
+export type SupervisorLock = { pid: number; startedAt: number; epoch: string };
+export type ArmStatus = {
+  subscriptionId: string;
+  revision: number;
+  epoch: string;
+} & ({ state: 'ready'; url?: string } | { state: 'error'; message: string });