@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.33

package/plugins/triggers/run.mjs

@@ -0,0 +1,157 @@
+// The run decision: everything that must be true before an event may start a
+// session, and the record left afterwards. This is the safety half of the
+// mechanism, so it is deliberately small and entirely testable: an unattended
+// run must never overlap its own previous run, must never fire twice for one
+// event, and must never exceed the limits its definition declares.
+//
+// It does NOT run an agent: executing the session (Host plugin, `dscode trigger
+// run`, the goal service) is separate work. `planTriggerRun` answers "may this
+// run start, and with what identity", `finishTriggerRun` records how it ended.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { appendRun, readRuns } from './log.mjs';
+
+/** Grace added to a run's timeout before its lock is treated as abandoned. */
+export const LOCK_STALE_GRACE_MS = 60000;
+
+/** One trigger's single-flight lock. */
+export const lockPath = (home, triggerId) => join(home, 'triggers', 'locks', `${triggerId}.json`);
+
+/** True when a process id exists; EPERM means it exists but belongs to someone else. */
+export function alivePid(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function readLock(home, triggerId) {
+  try {
+    const lock = JSON.parse(readFileSync(lockPath(home, triggerId), 'utf8'));
+    return typeof lock?.runId === 'string' ? lock : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeLock(home, handle) {
+  const path = lockPath(home, handle.triggerId);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, JSON.stringify(handle) + '\n', { mode: 0o600 });
+}
+
+/**
+ * Decide whether one event may start a run, and take the lock when it may.
+ *
+ * Order matters: a disabled trigger never runs; a repeated event is recognised
+ * before any lock is touched; the rolling day and the minimum interval are
+ * checked against recorded runs; and only then does a live lock stop the run.
+ * An identity is REQUIRED: without one the duplicate check is inert, so a
+ * re-drained event would start a second session. A scheduled source passes the
+ * planned instant, an external producer passes its own event id.
+ * @param definition - a normalized definition (plugins/triggers/config.mjs).
+ * @param options - `{ home, now, eventId, isAlive, runId }`; `eventId` is required.
+ * @returns `{ action: 'run', handle }` or `{ action: 'skip', reason }`.
+ * @throws {Error} when `eventId` is missing or empty.
+ */
+export function planTriggerRun(definition, { home, now = Date.now(), eventId, isAlive = alivePid, runId = randomUUID() } = {}) {
+  if (typeof eventId !== 'string' || eventId.trim() === '') throw new Error('planTriggerRun needs an eventId: it is how a repeated firing is recognised');
+  if (!definition.enabled) return { action: 'skip', reason: 'disabled' };
+  if (!existsSync(definition.workspace)) return { action: 'skip', reason: 'workspace_missing' };
+  const recorded = readRuns(home, { triggerId: definition.id, limit: 0 }).filter(entry => entry.outcome !== 'skipped');
+  if (recorded.some(entry => entry.eventId === eventId)) return { action: 'skip', reason: 'duplicate' };
+  const lastDay = recorded.filter(entry => now - entry.startedAt < 24 * 60 * 60 * 1000);
+  if (lastDay.length >= definition.limits.maxRunsPerDay) return { action: 'skip', reason: 'over_daily_limit' };
+  const newest = recorded[0];
+  if (newest !== undefined && now - newest.startedAt < definition.limits.minIntervalSeconds * 1000) return { action: 'skip', reason: 'too_soon' };
+
+  const lock = readLock(home, definition.id);
+  if (lock !== undefined) {
+    // A dead holder is reclaimed at once. A live pid is normally the run itself,
+    // but a recycled pid would look alive forever, so a lock older than the run's
+    // own timeout (plus a grace) is abandoned regardless.
+    const abandoned = now - lock.startedAt > definition.limits.timeoutSeconds * 1000 + LOCK_STALE_GRACE_MS;
+    if (isAlive(lock.pid) && !abandoned) return { action: 'skip', reason: 'already_running' };
+  }
+  const handle = { triggerId: definition.id, runId, startedAt: now, pid: process.pid, eventId };
+  writeLock(home, handle);
+  return { action: 'run', handle };
+}
+
+/**
+ * Drop a lock this run owns, without recording anything.
+ * A lock whose contents cannot be read is left in place rather than deleted: an
+ * unreadable lock may belong to another run, and deleting it would let two
+ * sessions run for one trigger. It ages out on its own.
+ */
+export function releaseTriggerRun(home, handle) {
+  const lock = readLock(home, handle.triggerId);
+  if (lock === undefined || lock.runId !== handle.runId) return false;
+  try {
+    rmSync(lockPath(home, handle.triggerId));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Decide whether a run in flight should stop, and how it ended. Called after
+ * every turn and by the timeout, so it only reads durable goal state plus the
+ * spend the metrics ledger reports.
+ *
+ * Completion wins over a rejected approval: the goal was reached, and the
+ * rejection is recorded in the run tail. When a cap or the timeout stops a run
+ * that needed a human, `approval_required` is the reason — that is the failure an
+ * operator has to fix.
+ * @param state - `{ goal, costUsd, limits, approvalsRejected }`.
+ * @returns `{ stop: false }` or `{ stop: true, outcome, reason, exitCode }`.
+ */
+export function decideStop({ goal, costUsd, limits, approvalsRejected = false } = {}) {
+  const capped = approvalsRejected ? 'approval_required' : undefined;
+  // A goal that is gone was cleared: nothing left to continue for.
+  if (goal === undefined || goal === null) return { stop: true, outcome: 'completed', reason: null, exitCode: 0 };
+  if (goal.phase === 'complete') return { stop: true, outcome: 'completed', reason: null, exitCode: 0 };
+  if (goal.phase === 'blocked') return { stop: true, outcome: 'blocked', reason: 'goal_blocked', exitCode: 3 };
+  if (goal.phase === 'paused') return { stop: true, outcome: 'failed', reason: 'goal_paused', exitCode: 3 };
+  if (Number.isFinite(limits?.maxCostUsd) && Number.isFinite(costUsd) && costUsd >= limits.maxCostUsd) {
+    return { stop: true, outcome: 'overrun', reason: capped ?? 'cost_cap', exitCode: 2 };
+  }
+  if (Number.isFinite(goal.maxGoalRounds) && goal.roundsStarted >= goal.maxGoalRounds) {
+    return { stop: true, outcome: 'overrun', reason: capped ?? 'round_cap', exitCode: 2 };
+  }
+  return { stop: false };
+}
+
+/**
+ * Record how a run ended and release its lock.
+ * @param home - the state directory.
+ * @param handle - the handle `planTriggerRun` returned.
+ * @param result - `{ outcome, reason?, exitCode, sessionId?, cost?, rounds?, cwd?, endedAt?, eventId? }`.
+ * @returns the appended record.
+ */
+export function finishTriggerRun(home, handle, result) {
+  const record = appendRun(home, {
+    triggerId: handle.triggerId,
+    runId: handle.runId,
+    startedAt: handle.startedAt,
+    endedAt: result.endedAt ?? Date.now(),
+    eventId: result.eventId ?? handle.eventId,
+    ...(result.jobId ? { jobId: result.jobId } : {}),
+    source: result.source ?? null,
+    outcome: result.outcome,
+    reason: result.reason ?? null,
+    exitCode: result.exitCode,
+    sessionId: result.sessionId ?? null,
+    cost: result.cost ?? null,
+    rounds: result.rounds ?? null,
+    cwd: result.cwd ?? handle.cwd ?? null,
+  });
+  releaseTriggerRun(home, handle);
+  return record;
+}

package/plugins/triggers/schedule.mjs

@@ -0,0 +1,40 @@
+import { CronExpressionParser } from 'cron-parser';
+
+export function validateCalendar(cron, timezone) {
+  if (cron.trim().split(/\s+/u).length !== 5) throw new Error('source.cron must have five fields (minute hour day month weekday)');
+  if (!/^[\d*/,\-\s]+$/u.test(cron)) throw new Error('source.cron supports numeric fields, *, ranges, lists and steps');
+  new Intl.DateTimeFormat('en', { timeZone: timezone }).format(0);
+  CronExpressionParser.parse(cron, { tz: timezone }).next();
+}
+
+export function nextFiring(source, after) {
+  if (source.kind === 'calendar') return CronExpressionParser.parse(source.cron, { tz: source.timezone, currentDate: after }).next().getTime();
+  return after + (source.seconds ?? source.everySeconds) * 1000;
+}
+
+/** Coalesce all overdue occurrences to the latest one, without iterating years. */
+export function dueFiring(source, nextAt, now) {
+  if (now < nextAt) return undefined;
+  const scheduledAt = source.kind === 'calendar'
+    ? CronExpressionParser.parse(source.cron, { tz: source.timezone, currentDate: now + 1 }).prev().getTime()
+    : nextAt + Math.floor((now - nextAt) / ((source.seconds ?? source.everySeconds) * 1000)) * (source.seconds ?? source.everySeconds) * 1000;
+  return { scheduledAt, nextAt: nextFiring(source, now), skipped: source.misfire === 'skip' && now - scheduledAt >= 60000 };
+}
+
+export function dueTime({ after, at }, now = Date.now()) {
+  if ((after === undefined) === (at === undefined)) throw new Error('schedule needs exactly one of --after or --at');
+  let due;
+  if (after !== undefined) {
+    const match = /^(\d+(?:\.\d+)?)(s|m|h|d)$/u.exec(after);
+    if (!match) throw new Error('--after expects a duration such as 30s, 10m, 2h or 1d');
+    due = now + Number(match[1]) * { s: 1000, m: 60000, h: 3600000, d: 86400000 }[match[2]];
+  } else {
+    const match = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.\d{1,3})?(Z|[+-]\d{2}:\d{2})$/u.exec(at);
+    if (!match) throw new Error('--at needs an ISO timestamp with Z or an explicit UTC offset');
+    due = Date.parse(at);
+    const offset = match[2] === 'Z' ? 0 : (match[2][0] === '-' ? -1 : 1) * (Number(match[2].slice(1, 3)) * 60 + Number(match[2].slice(4))) * 60000;
+    if (!Number.isFinite(due) || new Date(due + offset).toISOString().slice(0, 19) !== match[1]) throw new Error('--at is not a valid calendar timestamp');
+  }
+  if (!Number.isSafeInteger(due) || due <= now || due > 8640000000000000) throw new Error('the scheduled time must be in the future');
+  return due;
+}

package/plugins/triggers/scheduler-service.mjs

@@ -0,0 +1,46 @@
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+
+const xml = value => String(value).replace(/[<>&"']/gu, char => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;' }[char]));
+export const schedulerLabel = home => `ai.dscode.scheduler.${createHash('sha256').update(home).digest('hex').slice(0, 12)}`;
+export const schedulerPath = (home, directory = join(homedir(), 'Library', 'LaunchAgents')) => join(directory, `${schedulerLabel(home)}.plist`);
+
+export function schedulerPlist(home, dscodePath) {
+  const args = [process.execPath, dscodePath, 'trigger', 'scheduler', 'start'];
+  const log = join(home, 'triggers', 'scheduler.log');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${xml(schedulerLabel(home))}</string>
+<key>ProgramArguments</key><array>${args.map(arg => `<string>${xml(arg)}</string>`).join('')}</array>
+<key>WorkingDirectory</key><string>${xml(home)}</string>
+<key>EnvironmentVariables</key><dict><key>DSH_HOME</key><string>${xml(home)}</string><key>DSCODE_HOME</key><string>${xml(home)}</string><key>PATH</key><string>${xml(`${dirname(process.execPath)}:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin`)}</string></dict>
+<key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
+<key>ThrottleInterval</key><integer>5</integer>
+<key>StandardOutPath</key><string>${xml(log)}</string>
+<key>StandardErrorPath</key><string>${xml(log)}</string>
+</dict></plist>
+`;
+}
+
+export async function schedulerService(action, { home, dscodePath, platform, launchctl, agentsDirectory, out }) {
+  if (platform !== 'darwin' || !launchctl) {
+    out(`Manage the scheduler with your service manager: ${JSON.stringify(process.execPath)} ${JSON.stringify(dscodePath)} trigger scheduler start (DSH_HOME=${JSON.stringify(home)}, DSCODE_HOME=${JSON.stringify(home)})`);
+    return;
+  }
+  const path = schedulerPath(home, agentsDirectory);
+  const label = `gui/${process.getuid()}/${schedulerLabel(home)}`;
+  if (action === 'uninstall') {
+    await launchctl(['bootout', label], { ignoreFailure: true });
+    rmSync(path, { force: true });
+    out(`removed scheduler service ${path}; pending jobs remain on disk`);
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  mkdirSync(join(home, 'triggers'), { recursive: true, mode: 0o700 });
+  writeFileSync(path, schedulerPlist(home, dscodePath), { mode: 0o600 });
+  if (await launchctl(['print', label], { ignoreFailure: true }) !== 0) await launchctl(['bootstrap', `gui/${process.getuid()}`, path]);
+  out(`scheduler installed: ${path}`);
+}

package/plugins/triggers/scheduler.mjs

@@ -0,0 +1,92 @@
+import { SourceSupervisor } from './sources.mjs';
+import { spawn } from 'node:child_process';
+import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { JobStore } from './jobs.mjs';
+import { loadTriggerDefinitions } from './config.mjs';
+import { acquireTriggerLease } from './lease.mjs';
+import { alivePid } from './run.mjs';
+import { readRuns } from './log.mjs';
+
+export function launchJobWorker({ home, dscodePath, job }) {
+  const directory = join(home, 'triggers', 'jobs');
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const fd = openSync(join(directory, `${job.id}.log`), 'a', 0o600);
+  let child;
+  try {
+    child = spawn(process.execPath, [dscodePath, 'trigger', 'run-job', job.id], {
+      cwd: home, env: { ...process.env, DSH_HOME: home, DSCODE_HOME: home },
+      stdio: ['ignore', fd, fd],
+    });
+  } finally { closeSync(fd); }
+  // Workers may finish after the scheduler exits. Their trigger leases and
+  // durable claims still exclude a replacement scheduler from double-running.
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', code => resolve(code ?? 130));
+  });
+}
+
+/** One scan; active promises are tracked separately so model latency cannot stop the clock. */
+export async function schedulerTick({ home, store, active, dscodePath, now = Date.now(), spawnWorker = launchJobWorker, report = console.error }) {
+  const definitions = new Map();
+  const resolve = saved => {
+    if (!definitions.has(saved.project)) {
+      const found = loadTriggerDefinitions({ home, workspace: saved.project });
+      for (const problem of found.problems) report(`${problem.path}: ${problem.message}`);
+      definitions.set(saved.project, found.definitions);
+    }
+    return definitions.get(saved.project).find(d => d.id === saved.triggerId);
+  };
+  store.materialize(resolve, now);
+  for (const job of store.running()) {
+    if (alivePid(job.pid)) continue;
+    const lease = await acquireTriggerLease(home, job.triggerId);
+    if (!lease) continue; // its orphaned Host still owns the descriptor
+    try {
+      const result = readRuns(home, { triggerId: job.triggerId, limit: 0 }).find(run => run.runId === job.runId);
+      store.finish(job.id, result ?? { exitCode: 130, reason: 'interrupted' }, now);
+    } finally { lease.release(); }
+  }
+  const busy = new Set([...active.values()].map(entry => entry.triggerId));
+  for (const job of store.pending(now)) {
+    if (active.size >= 4) break;
+    if (busy.has(job.triggerId)) continue;
+    busy.add(job.triggerId);
+    const promise = Promise.resolve().then(() => spawnWorker({ home, dscodePath, job })).then(code => {
+      if (code && store.get(job.id)?.state === 'pending') store.defer(job.id, 'worker_start_failed', Date.now() + 30000);
+    }).catch(error => {
+      report(`scheduler ${job.id}: ${error.message}`);
+      store.defer(job.id, 'worker_start_failed', Date.now() + 30000);
+    }).finally(() => { active.delete(job.id); });
+    active.set(job.id, { triggerId: job.triggerId, promise });
+  }
+}
+
+export async function runScheduler({ home, dscodePath, once = false, signal, spawnWorker, onReady, report = console.error }) {
+  const lease = await acquireTriggerLease(home, '_scheduler');
+  if (!lease) throw new Error('the scheduler is already running for this state directory');
+  let store, sources;
+  const active = new Map();
+  try {
+    store = new JobStore(home);
+    sources = new SourceSupervisor({ home, store, report });
+    await onReady?.();
+    do {
+      if (signal?.aborted) break;
+      if (!once) sources.tick();
+      await schedulerTick({ home, store, active, dscodePath, spawnWorker, report });
+      if (once) break;
+      await sleep(1000, undefined, { signal }).catch(error => { if (error.name !== 'AbortError') throw error; });
+    } while (!signal?.aborted);
+    await sources.close();
+    await Promise.allSettled([...active.values()].map(entry => entry.promise));
+    return 0;
+  } finally {
+    await sources?.close();
+    await Promise.allSettled([...active.values()].map(entry => entry.promise));
+    store?.close();
+    lease.release();
+  }
+}

package/plugins/triggers/session-run.mjs

@@ -0,0 +1,125 @@
+// One owned unattended run, independent of the process that hosts it. The caller
+// owns admission/leases and persists the final run record; this module owns only
+// its Agent, goal, listeners and deadline.
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { openTriggerSession } from './session.mjs';
+import { decideStop } from './run.mjs';
+import { writeRunTail } from './log.mjs';
+import { sessionSpend } from '../session-metrics/view.mjs';
+import { markUnattended } from './unattended.mjs';
+
+function splitRoute(value) {
+  const at = value.indexOf('/');
+  if (at <= 0 || at === value.length - 1) throw Error(`model expects provider/model, got ${value}`);
+  return [value.slice(0, at), value.slice(at + 1)];
+}
+
+/** Starts input after setup; done settles only after the owned Agent is drained. */
+export async function startTriggerSession(ctx, { spec, home, spend = sessionSpend, signal, prepare }) {
+  signal?.throwIfAborted();
+  const selection = ctx.agentDefaultModel.currentSelection();
+  const [provider, model] = spec.model ? splitRoute(spec.model) : [selection.provider, selection.model];
+  const effort = spec.effort ?? selection.reasoningEffort;
+  const agentOptions = { provider, model, ...(effort ? { reasoningEffort: effort } : {}) };
+  const setup = async (scope, agent) => {
+    await ctx.agentPresets.mount(scope, spec.preset ?? 'dscode');
+    await prepare?.(scope, agent);
+  };
+  const handle = await openTriggerSession(ctx, spec, { home, agentOptions, setup, signal });
+  const agent = handle.agent, session = agent.session;
+  const unmark = markUnattended(agent);
+  const disposers = [];
+  let timer, finished = false, approvalsRejected = false, lastText = '';
+  const cleanup = () => { clearTimeout(timer); for (const dispose of disposers.splice(0)) dispose(); };
+  try {
+    signal?.throwIfAborted();
+    if (spec.permission) {
+      ctx.permissionPresets.resolve(spec.permission);
+      ctx.permissionPresets.set(session, spec.permission);
+    }
+    const previous = ctx.goals.get(agent);
+    if (previous) ctx.goals.clear(agent, { id: previous.id, revision: previous.revision });
+    const initialCost = spend(session.id).cost;
+    const runCost = () => {
+      try {
+        const total = spend(session.id).cost;
+        return Number.isFinite(initialCost) && Number.isFinite(total) ? Math.max(0, total - initialCost) : undefined;
+      } catch { return undefined; }
+    };
+    ctx.goals.create(agent, { objective: spec.goal.objective, maxGoalRounds: spec.goal.maxRounds });
+    const completion = Promise.withResolvers();
+    // Callers receive the promise after setup; avoid a premature rejection warning.
+    void completion.promise.catch(() => {});
+    const finish = result => {
+      if (finished) return completion.promise;
+      finished = true;
+      cleanup();
+      void (async () => {
+        try {
+          // Cancelling only this Agent stops queued goal continuations too.
+          agent.cancel({ kind: 'user' });
+          await agent.whenIdle();
+          if (lastText.trim()) {
+            try { writeRunTail(home, spec.triggerId, spec.runId, lastText); } catch { /* the caller still receives the result */ }
+          }
+          await ctx.sessions.flush(session);
+          await handle.dispose();
+          completion.resolve({ ...result, sessionId: session.id });
+        } catch (error) {
+          await handle.dispose().catch(() => {});
+          completion.reject(error);
+        } finally { unmark(); }
+      })();
+      return completion.promise;
+    };
+    const currentGoal = () => { try { return ctx.goals.get(agent); } catch { return undefined; } };
+    const numbers = () => ({ cost: runCost() ?? null, rounds: currentGoal()?.roundsStarted ?? null });
+    const observe = (event, callback) => disposers.push(ctx.on(event, callback));
+    observe('session/event', (subject, event) => {
+      if (subject.id !== session.id || finished) return;
+      if (event.type === 'assistant/message') {
+        const text = (event.data.message?.content ?? []).filter(block => block.type === 'text').map(block => block.text).join('');
+        if (text) lastText = text;
+      } else if (event.type === 'turn/end') {
+        const decision = decideStop({ goal: currentGoal(), costUsd: runCost(), limits: spec.limits, approvalsRejected });
+        if (decision.stop) void finish({ outcome: decision.outcome, reason: decision.reason ?? null, exitCode: decision.exitCode, ...numbers() });
+      }
+    });
+    observe('session/disposed', subject => {
+      if (subject.id === session.id) void finish({ outcome: 'failed', reason: 'model_error', exitCode: 1, ...numbers() });
+    });
+    const owns = candidate => {
+      const seen = new Set();
+      while (candidate && !seen.has(candidate.id)) {
+        if (candidate.id === agent.id) return true;
+        seen.add(candidate.id);
+        const parent = candidate.session?.header.parentSession;
+        candidate = parent ? ctx.agents.get(parent) : undefined;
+      }
+      return false;
+    };
+    observe('approval/request', (request, next) => {
+      if (!owns(request.agent)) return next();
+      approvalsRejected = true;
+      return 'rejected';
+    });
+    const cancel = () => finish({ outcome: 'failed', reason: 'interrupted', exitCode: 130, ...numbers() });
+    if (signal) {
+      const abort = () => { void cancel(); };
+      signal.addEventListener('abort', abort, { once: true });
+      disposers.push(() => signal.removeEventListener('abort', abort));
+      if (signal.aborted) abort();
+    }
+    const seconds = spec.limits?.timeoutSeconds;
+    if (!finished && Number.isFinite(seconds) && seconds > 0) {
+      timer = setTimeout(() => { void finish({ outcome: 'timedout', reason: approvalsRejected ? 'approval_required' : 'timeout', exitCode: 124, ...numbers() }); }, seconds * 1000);
+      timer.unref();
+    }
+    if (!finished) agent.followup(createUserMessage({ content: [{ type: 'text', text: spec.prompt }], source: { kind: 'user' } }));
+    return { agent, done: completion.promise, cancel };
+  } catch (error) {
+    cleanup();
+    try { await handle.dispose(); } finally { unmark(); }
+    throw error;
+  }
+}

package/plugins/triggers/session.mjs

@@ -0,0 +1,48 @@
+// A trigger owns this binding, independently of any one run's outcome. Publish
+// it only after the new session has been flushed, before delivering its input.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const bindingPath = (home, id) => join(home, 'triggers', 'sessions', `${id}.json`);
+
+export function readSessionBinding(home, spec) {
+  let binding;
+  try { binding = JSON.parse(readFileSync(bindingPath(home, spec.triggerId), 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+  if (!binding || typeof binding.sessionId !== 'string' || !binding.sessionId || binding.triggerId !== spec.triggerId) {
+    throw new Error(`invalid session binding for ${spec.triggerId}`);
+  }
+  if (binding.workspace !== spec.workspace || binding.preset !== (spec.preset ?? 'dscode')) {
+    throw new Error(`persistent trigger ${spec.triggerId} is bound to another workspace or preset; use a new trigger id`);
+  }
+  return binding;
+}
+
+export function writeSessionBinding(home, spec, sessionId) {
+  const path = bindingPath(home, spec.triggerId);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const scratch = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(scratch, JSON.stringify({ triggerId: spec.triggerId, sessionId, workspace: spec.workspace, preset: spec.preset ?? 'dscode' }) + '\n', { mode: 0o600 });
+  renameSync(scratch, path);
+}
+
+/** Called under the CLI's trigger lease. A failed resume never erases history. */
+export async function openTriggerSession(ctx, spec, { home, agentOptions, setup, signal }) {
+  const persistent = spec.session?.mode === 'persistent';
+  const binding = persistent ? readSessionBinding(home, spec) : undefined;
+  const handle = binding
+    ? await ctx.agents.resume({ resumeSessionId: binding.sessionId, agentOptions, setup, signal })
+    : await ctx.agents.create({ sessionId: randomUUID(), meta: { cwd: spec.workspace, agentPreset: spec.preset ?? 'dscode' }, agentOptions, setup, signal });
+  try {
+    if (handle.agent.session.header.cwd !== spec.workspace) throw new Error('trigger session workspace does not match its definition');
+    if (persistent && !binding) {
+      await ctx.sessions.flush(handle.agent.session);
+      writeSessionBinding(home, spec, handle.agent.session.id);
+    }
+    return handle;
+  } catch (error) {
+    await handle.dispose();
+    throw error;
+  }
+}

package/plugins/triggers/source-emit.mjs

@@ -0,0 +1,19 @@
+// Private command exposed to sandboxed producers; it grants only emit access.
+import { readFileSync } from 'node:fs';
+import { emitToSource } from './source-ingress.mjs';
+
+try {
+  const [group, command, triggerId, ...args] = process.argv.slice(2);
+  if (group !== 'trigger' || command !== 'emit' || !triggerId) throw new Error('source scripts may use: dscode trigger emit ID --event-id ID --text TEXT (or --event FILE)');
+  let eventId, payload = {}, bodySet = false;
+  for (let i = 0; i < args.length; i += 2) {
+    const flag = args[i], value = args[i + 1];
+    if (value === undefined) throw new Error(`${flag} requires a value`);
+    if (flag === '--event-id') eventId = value;
+    else if (['--text', '--event'].includes(flag) && !bodySet) {
+      payload = flag === '--text' ? { source: 'cli', text: value } : JSON.parse(readFileSync(value === '-' ? 0 : value, 'utf8'));
+      bodySet = true;
+    } else throw new Error(`unsupported or repeated option ${flag}`);
+  }
+  console.log(JSON.stringify(await emitToSource({ triggerId, eventId, payload })));
+} catch (error) { console.error(error.message); process.exitCode = 1; }

package/plugins/triggers/source-host.mjs

@@ -0,0 +1,78 @@
+// One guarded script attempt. The scheduler owns this guardian over IPC; losing
+// that channel terminates the script process group, including ordinary children.
+import { spawn } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, realpathSync, lstatSync } from 'node:fs';
+import { join, delimiter } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { JobStore } from './jobs.mjs';
+import { acquireTriggerLease } from './lease.mjs';
+import { sandboxCommand, signalGroup } from './source-sandbox.mjs';
+import { openSourceIngress } from './source-ingress.mjs';
+
+export async function runSourceAttempt({ home, project, definition, sourceId }) {
+  const store = new JobStore(home);
+  const lease = await acquireTriggerLease(home, `source-${sourceId}`);
+  if (!lease) { store.close(); throw new Error('source lease is held by another process; inspect the previous source before restarting'); }
+  let child, ingress, scratch, timer, flush, stopped = false, timedOut = false, log = '', failure;
+  const stop = () => { stopped = true; if (child) signalGroup(child, 'SIGTERM'); };
+  process.once('disconnect', stop);
+  process.on('message', stop);
+  for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.once(signal, stop);
+  const persistLog = () => store.run('UPDATE sources SET log=? WHERE id=?', log, sourceId);
+  const collect = chunk => { log = (log + String(chunk)).slice(-32768); };
+  try {
+    const data = join(home, 'triggers', 'source-data', sourceId);
+    mkdirSync(data, { recursive: true, mode: 0o700 });
+    if (lstatSync(data).isSymbolicLink() || realpathSync(data) !== join(realpathSync(home), 'triggers', 'source-data', sourceId)) throw new Error('source state directory must not be redirected through symlinks');
+    scratch = mkdtempSync('/tmp/dscode-script-');
+    ingress = await openSourceIngress({ home, project, definition, store });
+    const bin = join(scratch, 'bin');
+    mkdirSync(bin);
+    // A tiny private CLI avoids launcher provisioning and writes to global state.
+    const client = fileURLToPath(new URL('./source-emit.mjs', import.meta.url));
+    const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+    writeFileSync(join(bin, 'dscode'), `#!/bin/sh\nexec ${quote(process.execPath)} ${quote(client)} "$@"\n`, { mode: 0o700 });
+    const launch = sandboxCommand(definition.source.command, { workspace: definition.workspace, home, writable: [data, scratch], permission: definition.source.permission });
+    if (stopped || (process.send && !process.connected)) return;
+    const env = { ...process.env };
+    delete env.NODE_CHANNEL_FD; delete env.NODE_CHANNEL_SERIALIZATION_MODE;
+    child = spawn(launch.command, launch.args, {
+      cwd: definition.workspace, detached: true,
+      env: { ...env, PATH: bin + delimiter + (process.env.PATH ?? ''), TMPDIR: scratch, TMP: scratch, TEMP: scratch,
+        DSCODE_SOURCE_SOCKET: ingress.path, DSCODE_SOURCE_TOKEN: ingress.token, DSCODE_SOURCE_STATE: data, DSCODE_TRIGGER_ID: definition.id },
+      stdio: ['ignore', 'pipe', 'pipe', lease.fd],
+    });
+    child.stdout.on('data', collect); child.stderr.on('data', collect);
+    store.run("UPDATE sources SET status='running',pid=?,error=NULL WHERE id=?", child.pid ?? null, sourceId);
+    flush = setInterval(persistLog, 1000);
+    if (definition.source.mode === 'poll') timer = setTimeout(() => { timedOut = true; stop(); }, definition.source.timeoutSeconds * 1000);
+    // A bounded grace period also handles children ignoring SIGTERM.
+    const reap = setInterval(() => { if (stopped) signalGroup(child, 'SIGKILL'); }, 1000);
+    try {
+      const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', (code, signal) => resolve(code ?? signal)); });
+      if (timedOut) throw new Error('script poll timed out');
+      if (!stopped && (code !== 0 || definition.source.mode === 'daemon')) throw new Error(`script exited (${code})`);
+    } finally { clearInterval(reap); }
+  } catch (error) { failure = error.message; collect(`\n${failure}\n`); }
+  finally {
+    clearTimeout(timer); clearInterval(flush);
+    if (child) { signalGroup(child, 'SIGTERM'); await sleep(100); signalGroup(child, 'SIGKILL'); }
+    await ingress?.close();
+    if (scratch) rmSync(scratch, { recursive: true, force: true });
+    const saved = store.one('SELECT * FROM sources WHERE id=?', sourceId);
+    const failures = failure ? (saved?.failures ?? 0) + 1 : 0;
+    const delay = failure ? Math.min(300000, 1000 * 2 ** Math.min(failures, 8)) : (definition.source.everySeconds ?? 1) * 1000;
+    persistLog();
+    store.run('UPDATE sources SET status=?,pid=NULL,error=?,failures=?,nextAt=? WHERE id=?', failure ? 'backoff' : 'stopped', failure ?? null, failures, Date.now() + delay, sourceId);
+    store.close(); lease.release();
+    process.off('disconnect', stop); process.off('message', stop);
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.off(signal, stop);
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try { await runSourceAttempt(JSON.parse(process.argv[2])); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+  if (process.connected) process.disconnect();
+}