@toddzheng024/dscode-bundle 0.7.24 → 0.7.26

package/plugins/triggers/jobs.mjs

@@ -0,0 +1,156 @@
+// The schedule cursor and generated job commit together. Claim/cancel are SQL
+// compare-and-swap transitions; a running job is never automatically retried.
+import { DatabaseSync } from 'node:sqlite';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { normalizeEvent } from './spool.mjs';
+import { nextFiring, dueFiring } from './schedule.mjs';
+
+const key = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export class JobStore {
+  constructor(home) {
+    const directory = join(home, 'triggers');
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const path = join(directory, 'jobs.sqlite');
+    this.db = new DatabaseSync(path);
+    chmodSync(path, 0o600);
+    this.db.exec(`PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
+      CREATE TABLE IF NOT EXISTS schedules (id TEXT PRIMARY KEY, triggerId TEXT NOT NULL, project TEXT NOT NULL, workspace TEXT NOT NULL, source TEXT NOT NULL, nextAt INTEGER NOT NULL, enabled INTEGER NOT NULL DEFAULT 1);
+      CREATE TABLE IF NOT EXISTS sources (id TEXT PRIMARY KEY, triggerId TEXT NOT NULL, project TEXT NOT NULL, desired TEXT NOT NULL DEFAULT 'running', revision INTEGER NOT NULL DEFAULT 0, nextAt INTEGER NOT NULL DEFAULT 0, failures INTEGER NOT NULL DEFAULT 0, status TEXT NOT NULL DEFAULT 'waiting', pid INTEGER, error TEXT, log TEXT NOT NULL DEFAULT '');
+      CREATE TABLE IF NOT EXISTS event_receipts (id TEXT PRIMARY KEY, eventId TEXT NOT NULL, request TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS job_requests (id TEXT PRIMARY KEY, request TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS jobs (seq INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT UNIQUE NOT NULL, triggerId TEXT NOT NULL, project TEXT NOT NULL, workspace TEXT NOT NULL, kind TEXT NOT NULL, scheduleId TEXT, dueAt INTEGER NOT NULL, availableAt INTEGER NOT NULL, createdAt INTEGER NOT NULL, payload TEXT NOT NULL, state TEXT NOT NULL DEFAULT 'pending', reason TEXT, runId TEXT, sessionId TEXT, pid INTEGER, startedAt INTEGER, endedAt INTEGER, exitCode INTEGER);
+      CREATE INDEX IF NOT EXISTS jobs_due ON jobs(state,availableAt,dueAt,seq);`);
+  }
+  close() { this.db.close(); }
+  all(sql, ...args) { return this.db.prepare(sql).all(...args); }
+  one(sql, ...args) { return this.db.prepare(sql).get(...args); }
+  run(sql, ...args) { return this.db.prepare(sql).run(...args); }
+  transaction(fn) {
+    this.db.exec('BEGIN IMMEDIATE');
+    try { const result = fn(); this.db.exec('COMMIT'); return result; }
+    catch (error) { this.db.exec('ROLLBACK'); throw error; }
+  }
+  get(id) { return this.one('SELECT * FROM jobs WHERE id=?', id); }
+  list(triggerId) { return this.all(`SELECT * FROM jobs ${triggerId ? 'WHERE triggerId=?' : ''} ORDER BY dueAt DESC,seq DESC`, ...(triggerId ? [triggerId] : [])); }
+  pending(now) { return this.all(`SELECT j.* FROM jobs j WHERE j.state='pending' AND j.availableAt<=?
+    AND NOT EXISTS (SELECT 1 FROM jobs older WHERE older.triggerId=j.triggerId AND older.state='pending' AND older.dueAt<=?
+      AND (older.dueAt<j.dueAt OR (older.dueAt=j.dueAt AND older.seq<j.seq))) ORDER BY j.dueAt,j.seq`, now, now); }
+  running() { return this.all("SELECT * FROM jobs WHERE state='running'"); }
+  create({ triggerId, project, workspace, payload = {}, dueAt, kind = 'delay', scheduleId = null, id = `job-${randomUUID()}`, now = Date.now() }) {
+    this.run('INSERT OR IGNORE INTO jobs(id,triggerId,project,workspace,kind,scheduleId,dueAt,availableAt,createdAt,payload) VALUES(?,?,?,?,?,?,?,?,?,?)', id, triggerId, project, workspace, kind, scheduleId, dueAt, dueAt, now, JSON.stringify(payload));
+    return this.get(id);
+  }
+  acceptEvent({ definition, project, payload, eventId, now = Date.now(), maxPending = 100 }) {
+    const event = normalizeEvent(definition.id, payload, { eventId, now });
+    const { triggerId, receivedAt: _received, eventId: identity, ...body } = event;
+    const request = JSON.stringify(body, (_k, v) => v && typeof v === 'object' && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b))) : v);
+    if (Buffer.byteLength(request) > 131072) throw new Error('event body exceeds 128 KiB');
+    const id = `event-${key([project, triggerId, identity])}`;
+    return this.transaction(() => {
+      const receipt = this.one('SELECT * FROM event_receipts WHERE id=?', id);
+      if (receipt) {
+        if (receipt.request !== request) throw new Error('eventId was already used for a different payload');
+        return this.get(id);
+      }
+      const count = this.one("SELECT COUNT(*) AS n FROM jobs WHERE project=? AND triggerId=? AND state IN ('pending','running')", project, triggerId).n;
+      if (count >= maxPending) throw new Error('QUEUE_FULL: retry this event later with the same eventId');
+      this.run('INSERT INTO event_receipts(id,eventId,request) VALUES(?,?,?)', id, identity, request);
+      return this.create({ id, triggerId, project, workspace: definition.workspace, payload: body, kind: 'event', dueAt: now, now });
+    });
+  }
+  eventIdentity(id) { return this.one('SELECT eventId FROM event_receipts WHERE id=?', id)?.eventId; }
+  sources() { return this.all('SELECT * FROM sources'); }
+  source(triggerId, project) { return this.one('SELECT * FROM sources WHERE id=?', key([project, triggerId])); }
+  registerSource(definition, project) {
+    if (definition.source.kind !== 'script') throw new Error('source management requires a script source');
+    const id = key([project, definition.id]);
+    this.run('INSERT OR IGNORE INTO sources(id,triggerId,project) VALUES(?,?,?)', id, definition.id, project);
+    return this.source(definition.id, project);
+  }
+  controlSource(definition, project, action) {
+    if (!['start', 'stop', 'restart'].includes(action)) throw new Error('source expects status, start, stop, restart or logs');
+    const saved = this.registerSource(definition, project);
+    this.run("UPDATE sources SET desired=?,revision=revision+?,nextAt=0,failures=0 WHERE id=?", action === 'stop' ? 'stopped' : 'running', Number(action === 'restart'), saved.id);
+    return this.source(definition.id, project);
+  }
+  cancel(id, now = Date.now()) {
+    if (!this.get(id)) throw new Error(`no job "${id}"`);
+    if (!this.run("UPDATE jobs SET state='cancelled',reason='cancelled',endedAt=? WHERE id=? AND state='pending'", now, id).changes) {
+      throw new Error(`job ${id} is ${this.get(id).state}; only pending jobs can be cancelled`);
+    }
+  }
+  /** Tool retries reuse the first due time; a changed request cannot reuse its key. */
+  createOnce({ requestKey, request, ...options }) {
+    const id = `job-${key([options.project, requestKey])}`;
+    return this.transaction(() => {
+      const saved = this.one('SELECT request FROM job_requests WHERE id=?', id);
+      if (saved) {
+        if (saved.request !== request) throw new Error('idempotency_key was already used for a different job request');
+        return this.get(id);
+      }
+      this.run('INSERT INTO job_requests(id,request) VALUES(?,?)', id, request);
+      return this.create({ ...options, dueAt: typeof options.dueAt === 'function' ? options.dueAt() : options.dueAt, id });
+    });
+  }
+  defer(id, reason, availableAt) { this.run("UPDATE jobs SET reason=?,availableAt=? WHERE id=? AND state='pending'", reason, availableAt, id); }
+  claim(id, runId, now) { return this.run("UPDATE jobs SET state='running',reason=NULL,runId=?,pid=?,startedAt=? WHERE id=? AND state='pending' AND availableAt<=?", runId, process.pid, now, id, now).changes === 1; }
+  finish(id, result, now = Date.now()) {
+    const state = result.exitCode === 0 ? 'completed' : 'failed';
+    this.run("UPDATE jobs SET state=?,reason=?,sessionId=?,endedAt=?,exitCode=? WHERE id=? AND state='running'", state, result.reason ?? null, result.sessionId ?? null, now, result.exitCode, id);
+  }
+  schedules() { return this.all('SELECT * FROM schedules'); }
+  register(definition, project, now = Date.now()) {
+    if (definition.source.kind === 'script') {
+      this.run('DELETE FROM schedules WHERE id=?', key([project, definition.id]));
+      return this.registerSource(definition, project);
+    }
+    this.run('DELETE FROM sources WHERE id=?', key([project, definition.id]));
+    if (!['calendar', 'interval', 'poll'].includes(definition.source.kind)) throw new Error('only calendar, interval and poll sources have recurring jobs');
+    const id = key([project, definition.id]);
+    const source = JSON.stringify(definition.source);
+    const old = this.one('SELECT * FROM schedules WHERE id=?', id);
+    if (old?.workspace === definition.workspace && old.source === source) return old;
+    const nextAt = nextFiring(definition.source, now);
+    this.run('INSERT INTO schedules(id,triggerId,project,workspace,source,nextAt,enabled) VALUES(?,?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET workspace=excluded.workspace,source=excluded.source,nextAt=excluded.nextAt,enabled=excluded.enabled', id, definition.id, project, definition.workspace, source, nextAt, Number(definition.enabled));
+    return this.one('SELECT * FROM schedules WHERE id=?', id);
+  }
+  unregister(triggerId, project, now = Date.now()) {
+    const id = key([project, triggerId]);
+    this.transaction(() => {
+      this.run('DELETE FROM schedules WHERE id=?', id);
+      this.run('DELETE FROM sources WHERE id=?', id);
+      this.run("UPDATE jobs SET state='cancelled',reason='uninstalled',endedAt=? WHERE scheduleId=? AND state='pending'", now, id);
+    });
+  }
+  /** Reloaded definitions drive enable/disable and source edits; absent definitions stop producing jobs. */
+  materialize(resolveDefinition, now = Date.now()) {
+    return this.transaction(() => {
+      const created = [];
+      for (const saved of this.schedules()) {
+        const definition = resolveDefinition(saved);
+        if (!definition || !['calendar', 'interval', 'poll'].includes(definition.source.kind)) continue;
+        const source = JSON.stringify(definition.source);
+        if (saved.source !== source || saved.workspace !== definition.workspace || Boolean(saved.enabled) !== definition.enabled) {
+          this.run('UPDATE schedules SET source=?,workspace=?,enabled=?,nextAt=? WHERE id=?', source, definition.workspace, Number(definition.enabled), nextFiring(definition.source, now), saved.id);
+          continue;
+        }
+        if (!definition.enabled) continue;
+        const firing = dueFiring(definition.source, saved.nextAt, now);
+        if (!firing) continue;
+        if (!firing.skipped) created.push(this.create({
+          id: `cron-${key([saved.id, source, firing.scheduledAt])}`, kind: 'cron', scheduleId: saved.id,
+          triggerId: saved.triggerId, project: saved.project, workspace: saved.workspace,
+          dueAt: firing.scheduledAt, now, payload: { source: definition.source.kind, fields: { scheduledAt: new Date(firing.scheduledAt).toISOString() } },
+        }));
+        this.run('UPDATE schedules SET nextAt=? WHERE id=?', firing.nextAt, saved.id);
+      }
+      return created;
+    });
+  }
+}
+
+export function formatJob(job) {
+  return `${job.id} ${job.triggerId} ${job.state}${job.reason ? ` (${job.reason})` : ''} · due ${new Date(job.dueAt).toISOString()}${job.runId ? ` · run ${job.runId}` : ''}${job.sessionId ? ` · session ${job.sessionId}` : ''}`;
+}

package/plugins/triggers/lease.mjs

@@ -0,0 +1,24 @@
+// A permanent inode and a kernel lock serialize CLI processes. The Host inherits
+// the descriptor so a killed parent cannot leave a still-running session unowned.
+import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+import { tryLockExclusive } from '@deepseek-ai/node-addon-system/flock';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+export async function acquireTriggerLease(home, id, { wait = false, delay = sleep } = {}) {
+  const directory = join(home, 'triggers', 'locks');
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const fd = openSync(join(directory, `${id}.guard`), 'a', 0o600);
+  try {
+    for (;;) {
+      try { await tryLockExclusive(fd); break; }
+      catch (error) {
+        if (!['EAGAIN', 'EWOULDBLOCK'].includes(error.code)) throw error;
+        if (!wait) { closeSync(fd); return undefined; }
+        await delay(100);
+      }
+    }
+    let released = false;
+    return { fd, release() { if (!released) { released = true; closeSync(fd); } } };
+  } catch (error) { closeSync(fd); throw error; }
+}

package/plugins/triggers/management.mjs

@@ -0,0 +1,181 @@
+// Agent-facing management uses the same definitions, jobs and scheduler as the CLI.
+import { existsSync, lstatSync, mkdirSync, renameSync, rmSync, writeFileSync, linkSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { stringify } from 'yaml';
+import { loadTriggerDefinitions, normalizeTrigger } from './config.mjs';
+import { JobStore } from './jobs.mjs';
+import { normalizeEvent } from './spool.mjs';
+import { dueTime } from './schedule.mjs';
+import { acquireTriggerLease } from './lease.mjs';
+import { schedulerService } from './scheduler-service.mjs';
+
+const stable = value => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+  ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item);
+const required = (value, label) => { if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} is required`); return value; };
+const clean = definition => Object.fromEntries(Object.entries(definition).filter(([key]) => !['origin', 'path', 'overrides'].includes(key)));
+
+/** No shell, inherited input or unbounded launchctl wait. */
+function launchctl(args, { ignoreFailure = false } = {}) {
+  return new Promise((resolveRun, reject) => {
+    const child = spawn('/bin/launchctl', args, { stdio: 'ignore' });
+    const timer = setTimeout(() => child.kill('SIGKILL'), 10000);
+    child.once('error', error => { clearTimeout(timer); if (ignoreFailure) resolveRun(1); else reject(error); });
+    child.once('exit', code => { clearTimeout(timer); if (code === 0 || ignoreFailure) resolveRun(code ?? 1); else reject(new Error(`launchctl failed (${code})`)); });
+  });
+}
+
+export class TriggerManagement {
+  constructor({ home, dscodePath, platform = process.platform, now = Date.now, service = schedulerService, runLaunchctl = launchctl }) {
+    Object.assign(this, { home, dscodePath, platform, now, service, runLaunchctl });
+  }
+  workspace(agent) {
+    const cwd = agent?.session?.header?.cwd;
+    if (!cwd || !isAbsolute(cwd)) throw new Error('A session bound to a workspace is required');
+    return resolve(cwd);
+  }
+  definitions(project) { return loadTriggerDefinitions({ home: this.home, workspace: project }); }
+  definition(project, id) {
+    required(id, 'trigger_id');
+    const definition = this.definitions(project).definitions.find(item => item.id === id);
+    if (!definition) throw new Error(`No trigger "${id}"`);
+    if (resolve(definition.workspace) !== project) throw new Error('The trigger belongs to another workspace');
+    return definition;
+  }
+  runnable(definition) {
+    if (!['read-only', 'workspace-write'].includes(definition.permission) || definition.preset !== 'dscode') {
+      throw new Error('Agent-managed scheduling requires the dscode preset and read-only or workspace-write permission');
+    }
+  }
+  withStore(fn) {
+    const store = new JobStore(this.home);
+    try { return fn(store); } finally { store.close(); }
+  }
+  async status() {
+    const lease = await acquireTriggerLease(this.home, '_scheduler');
+    const running = !lease;
+    lease?.release();
+    return { running, ...(!running ? { next_step: 'Use trigger_scheduler(action="install") on macOS, or run dscode trigger scheduler start under a service manager.' } : {}) };
+  }
+  write(project, definition, existing) {
+    const directory = join(project, '.dsh', 'triggers');
+    // Do not turn a project-local tool into an arbitrary-file writer via symlinks.
+    for (const path of [join(project, '.dsh'), directory]) {
+      if (existsSync(path) && lstatSync(path).isSymbolicLink()) throw new Error('Trigger configuration directories must not be symlinks');
+    }
+    mkdirSync(directory, { recursive: true });
+    const path = existing?.path ?? join(directory, `${definition.id}.yml`);
+    if (relative(directory, dirname(path)) !== '' || (existsSync(path) && lstatSync(path).isSymbolicLink())) throw new Error('Only regular project-local definitions can be changed');
+    const body = path.endsWith('.json') ? JSON.stringify(clean(definition), null, 2) + '\n' : stringify(clean(definition));
+    const temp = join(directory, `.${randomUUID()}.tmp`);
+    try {
+      writeFileSync(temp, body, { flag: 'wx', mode: 0o600 });
+      if (existing) renameSync(temp, path);
+      else linkSync(temp, path); // Never overwrite a concurrently created definition.
+    } finally { rmSync(temp, { force: true }); }
+    return path;
+  }
+  async manage(args, agent) {
+    const project = this.workspace(agent);
+    const { action, trigger_id: id } = args;
+    if (action === 'list') {
+      const found = this.definitions(project);
+      return { definitions: found.definitions.filter(d => resolve(d.workspace) === project), problems: found.problems, schedules: this.withStore(s => s.schedules().filter(row => row.project === project)), sources: this.withStore(s => s.sources().filter(row => row.project === project)), scheduler: await this.status() };
+    }
+    if (action === 'get') return { definition: this.definition(project, id) };
+    if (!['create', 'update', 'enable', 'disable', 'register', 'unregister'].includes(action)) throw new Error('Unknown trigger action');
+    let definition;
+    if (action === 'create' || action === 'update') {
+      required(id, 'trigger_id');
+      const found = this.definitions(project);
+      const existing = found.definitions.find(d => d.id === id);
+      if (action === 'create' && existing) throw new Error('Trigger already exists; use update');
+      if (action === 'update' && (!existing || existing.origin !== 'project')) throw new Error('Only existing project-local definitions can be updated');
+      if (existing && resolve(existing.workspace) !== project) throw new Error('The trigger belongs to another workspace');
+      // A broken JSON/YAML file must be repaired explicitly, never shadowed by a new extension.
+      if (found.problems.some(p => ['yml', 'yaml', 'json'].some(ext => p.path === join(project, '.dsh', 'triggers', `${id}.${ext}`)))) throw new Error('Repair the unreadable definition before editing it');
+      const patch = args.definition;
+      if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('definition is required for create/update');
+      const allowed = ['prompt', 'source', 'goal', 'limits', 'session', 'enabled', 'permission', 'model', 'effort'];
+      if (Object.keys(patch).some(key => !allowed.includes(key))) throw new Error(`definition accepts only ${allowed.join(', ')}`);
+      const base = existing ? clean(existing) : {};
+      if (patch.session) delete base.overlap;
+      definition = normalizeTrigger({ ...base, ...patch, id, workspace: project, preset: 'dscode' }, { origin: 'project' });
+      if (!['external', 'calendar', 'interval', 'script'].includes(definition.source.kind)) throw new Error('Agent-managed sources must be external, calendar, interval or script');
+      this.runnable(definition);
+      definition.path = this.write(project, definition, existing);
+      // Creating/editing a recurring source also registers it; external has no cadence.
+      this.withStore(s => definition.source.kind === 'external' ? s.unregister(id, project, this.now()) : s.register(definition, project, this.now()));
+    } else {
+      definition = this.definition(project, id);
+      if (action === 'register') {
+        this.runnable(definition);
+        this.withStore(s => s.register(definition, project, this.now()));
+      } else if (action === 'unregister') this.withStore(s => s.unregister(id, project, this.now()));
+      else {
+        if (definition.origin !== 'project') throw new Error('Only project-local definitions can be enabled or disabled');
+        definition.enabled = action === 'enable';
+        if (definition.enabled) this.runnable(definition);
+        this.write(project, definition, definition);
+      }
+    }
+    return { definition, action, scheduler: await this.status() };
+  }
+  async source(args, agent) {
+    const project = this.workspace(agent);
+    const definition = this.definition(project, args.trigger_id);
+    if (definition.source.kind !== 'script') throw new Error('source management requires a script source');
+    const source = this.withStore(s => {
+      if (['status', 'logs'].includes(args.action)) return s.source(definition.id, project);
+      this.runnable(definition);
+      return s.controlSource(definition, project, args.action);
+    });
+    if (args.action === 'logs') return { log: source?.log ?? '' };
+    return { source: source ?? { status: 'unregistered' }, scheduler: await this.status() };
+  }
+  async emit(args, agent) {
+    const project = this.workspace(agent);
+    const definition = this.definition(project, args.trigger_id);
+    this.runnable(definition);
+    const job = this.withStore(s => s.acceptEvent({ definition, project, payload: args.event ?? {}, eventId: args.eventId, now: this.now() }));
+    return { job, scheduler: await this.status() };
+  }
+  async jobs(args, agent) {
+    const project = this.workspace(agent);
+    const now = this.now();
+    if (args.action === 'list') {
+      const limit = args.limit ?? 50;
+      if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error('limit must be 1..100');
+      return { jobs: this.withStore(s => s.list(args.trigger_id).filter(j => j.project === project && j.workspace === project).slice(0, limit)), scheduler: await this.status() };
+    }
+    if (args.action === 'cancel') {
+      required(args.job_id, 'job_id');
+      return this.withStore(s => {
+        const job = s.get(args.job_id);
+        if (!job || job.project !== project || job.workspace !== project) throw new Error('No job in this workspace');
+        if (job.state !== 'cancelled') s.cancel(job.id, now);
+        return { job: s.get(job.id) };
+      });
+    }
+    if (args.action !== 'schedule') throw new Error('Unknown job action');
+    const definition = this.definition(project, args.trigger_id);
+    this.runnable(definition);
+    const requestKey = required(args.idempotency_key, 'idempotency_key');
+    if (requestKey.length > 200) throw new Error('idempotency_key must be at most 200 characters');
+    const payload = args.event ?? {};
+    normalizeEvent(definition.id, payload, { eventId: 'validation', now });
+    // Lookup a retry before future-time validation: its original due time may have passed.
+    const request = stable({ triggerId: definition.id, after: args.after, at: args.at, payload });
+    const job = this.withStore(s => s.createOnce({ requestKey, request, triggerId: definition.id, project, workspace: project, payload, dueAt: () => dueTime(args, now), now }));
+    return { job, scheduler: await this.status() };
+  }
+  async scheduler(args) {
+    if (args.action === 'status') return this.status();
+    if (args.action !== 'install') throw new Error('Scheduler action must be status or install');
+    if (!this.dscodePath || !isAbsolute(this.dscodePath) || !existsSync(this.dscodePath)) throw new Error('Restart DSCODE to provide its launcher path, or install the scheduler through the CLI');
+    const messages = [];
+    await this.service('install', { home: this.home, dscodePath: this.dscodePath, platform: this.platform, launchctl: this.runLaunchctl, out: text => messages.push(text) });
+    return { messages, scheduler: await this.status() };
+  }
+}

package/plugins/triggers/options.mjs

@@ -75,6 +75,7 @@ export function writeRunSpec(path, spec) {
   }
   if (!isPlainObject(spec.goal) || typeof spec.goal.objective !== 'string' || spec.goal.objective.trim() === '') fail('a run spec needs goal.objective');
   if (!Number.isSafeInteger(spec.goal.maxRounds) || spec.goal.maxRounds <= 0) fail('a run spec needs a positive goal.maxRounds');
+  validateSessionMode(spec);
   return writeJson(path, spec);
 }
 
@@ -84,6 +85,7 @@ export function readRunSpec(path) {
   for (const field of ['triggerId', 'runId', 'workspace', 'prompt', 'goal']) {
     if (spec[field] === undefined) fail(`the run spec is missing ${field}`);
   }
+  validateSessionMode(spec);
   return spec;
 }
 
@@ -107,3 +109,9 @@ export function readRunResult(path) {
     return undefined;
   }
 }
+
+function validateSessionMode(spec) {
+  if (spec.session !== undefined && (!isPlainObject(spec.session) || !['new', 'persistent'].includes(spec.session.mode) || Object.keys(spec.session).some(key => key !== 'mode'))) {
+    fail('a run spec session must contain only mode: new or persistent');
+  }
+}

package/plugins/triggers/poll.mjs

@@ -6,6 +6,8 @@
 // A predicate that cannot run must not fire a run: a spawn failure or a timeout
 // is reported as not matched, never as a match.
 
+import { mkdtempSync, rmSync } from 'node:fs';
+import { sandboxCommand, signalGroup } from './source-sandbox.mjs';
 import { spawn as nodeSpawn } from 'node:child_process';
 
 /** Output cap for the check's own text, so a chatty check cannot flood a record. */
@@ -17,12 +19,16 @@ export const MAX_CHECK_OUTPUT_CHARS = 2000;
  * @param options - `{ cwd, timeoutMs, spawn }`; `spawn` is injectable for tests.
  * @returns `{ matched, code, output }`: `matched` is true only on exit 0.
  */
-export function evaluateCheck(check, { cwd, timeoutMs = 60000, spawn = nodeSpawn } = {}) {
+export function evaluateCheck(check, { cwd, timeoutMs = 60000, spawn = nodeSpawn, home, permission = 'read-only' } = {}) {
   return new Promise(resolveCheck => {
-    let child;
+    let child, scratch;
+    const cleanup = () => { if (child) signalGroup(child, 'SIGKILL'); if (scratch) rmSync(scratch, { recursive: true, force: true }); };
     try {
-      child = spawn('/bin/sh', ['-c', check], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+      scratch = mkdtempSync('/tmp/dscode-poll-');
+      const launch = sandboxCommand(['/bin/sh', '-c', check], { workspace: cwd, writable: [scratch], home, permission });
+      child = spawn(launch.command, launch.args, { cwd, detached: true, env: { ...process.env, TMPDIR: scratch, TMP: scratch, TEMP: scratch }, stdio: ['ignore', 'pipe', 'pipe'] });
     } catch (error) {
+      cleanup();
       resolveCheck({ matched: false, code: null, output: `could not start the check: ${error?.message ?? error}` });
       return;
     }
@@ -36,7 +42,7 @@ export function evaluateCheck(check, { cwd, timeoutMs = 60000, spawn = nodeSpawn
     const timer = setTimeout(() => {
       if (settled) return;
       settled = true;
-      try { child.kill('SIGKILL'); } catch { /* already gone */ }
+      cleanup();
       resolveCheck({ matched: false, code: null, output: `${output}\n(the check exceeded ${timeoutMs}ms and was stopped)`.trim().slice(0, MAX_CHECK_OUTPUT_CHARS) });
     }, timeoutMs);
     timer.unref?.();
@@ -44,12 +50,14 @@ export function evaluateCheck(check, { cwd, timeoutMs = 60000, spawn = nodeSpawn
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      cleanup();
       resolveCheck({ matched: code === 0, code, output: output.replace(/\s+/gu, ' ').trim().slice(0, MAX_CHECK_OUTPUT_CHARS) });
     };
     child.once('error', error => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      cleanup();
       resolveCheck({ matched: false, code: null, output: `the check failed to start: ${error?.message ?? error}` });
     });
     child.once('exit', code => finish(code));

package/plugins/triggers/run.mjs

@@ -142,6 +142,7 @@ export function finishTriggerRun(home, handle, result) {
     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,

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,90 @@
+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, 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 });
+    do {
+      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();
+  }
+}