@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.34

package/plugins/triggers/desktop-host.mjs

@@ -0,0 +1,88 @@
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { clientRequestSchema } from '@deepseek-ai/dsh-client-connection';
+import { DesktopTriggerControl, DesktopTriggerManagement } from './desktop-management.mjs';
+import { registerTriggerTools } from './tools.mjs';
+import { triggerCommand } from './commands.mjs';
+import { mutationProblem } from './unattended.mjs';
+
+export const inject = ['agents', 'commands', 'jobs', 'agentPresets', 'agentDefaultModel', 'sessions', 'goals', 'permissionPresets'];
+const isDscode = (ctx, agent) => agent && ctx.agentPresets.composedPreset(agent.ctx) === 'dscode';
+
+/** UI requests select a live session, never a client-supplied workspace path. */
+export async function triggerDesktopRequest(ctx, { control, management }, payload, signal) {
+  signal?.throwIfAborted();
+  if (!payload || typeof payload !== 'object') throw Error('Invalid scheduling request');
+  if (['status', 'start', 'stop'].includes(payload.action)) {
+    if (payload.action !== 'status') await control.setEnabled(payload.action === 'start');
+    return { scheduler: await control.status(), sessions: ctx.agents.roots().filter(agent => isDscode(ctx, agent)).map(agent => ({
+      id: agent.id, workspace: management.workspace(agent), writable: !mutationProblem(ctx, agent),
+    })) };
+  }
+  if (typeof payload.sessionId !== 'string') throw Error('Choose an open DSCODE session');
+  const agent = ctx.agents.get(payload.sessionId);
+  if (!isDscode(ctx, agent)) throw Error('The DSCODE session is no longer open');
+  if (payload.action === 'workspace') return { ...(await management.manage({ action: 'list' }, agent)),
+    ...(await management.jobs({ action: 'list', limit: 50 }, agent)), writable: !mutationProblem(ctx, agent) };
+  if (!['manage', 'jobs', 'source'].includes(payload.action)) throw Error('Unknown scheduling action');
+  const action = payload.args?.action;
+  const reading = payload.action === 'manage' ? ['list', 'get'].includes(action) : payload.action === 'jobs' ? action === 'list' : ['status', 'logs'].includes(action);
+  if (!reading) {
+    const problem = mutationProblem(ctx, agent);
+    if (problem) throw Error(problem);
+  }
+  return management[payload.action](payload.args ?? {}, agent);
+}
+
+export function apply(ctx) {
+  const home = resolveDshHome();
+  const control = new DesktopTriggerControl(ctx, { home });
+  const management = new DesktopTriggerManagement({ home, control });
+  const service = { control, management };
+  const toolScopes = new Set();
+  ctx.provide('dscodeTriggers', service);
+  ctx.effect(() => async () => {
+    await control.dispose();
+    await Promise.all([...toolScopes].map(fiber => fiber.dispose()));
+  }, 'dscode desktop scheduling drain');
+  void control.initialize(ctx.get('loader').await());
+
+  ctx.on('agent/created', async ({ agent }) => {
+    if (!isDscode(ctx, agent) || control.closed) return;
+    const fiber = agent.ctx.inject(['tools', 'systemPrompt', 'permissionPresets'], scope => {
+      if (!control.closed) registerTriggerTools(scope, { home, management });
+    });
+    toolScopes.add(fiber);
+    agent.ctx.effect(() => () => { toolScopes.delete(fiber); });
+    await fiber;
+    if (control.closed) await fiber.dispose();
+  });
+  const handler = triggerCommand({ management, mutationProblem: agent => mutationProblem(ctx, agent) });
+  for (const name of ['trigger', 'triggers']) ctx.commands.register({ name, description: 'Manage DSCODE schedules; /trigger help',
+    input: { hint: '[list|create|update|schedule|jobs|source|scheduler|help]' },
+    handler: args => isDscode(ctx, args.agent) ? handler(args) : { kind: 'error', text: 'Choose a DSCODE session to manage its schedules.' },
+  });
+  // An unattended run must not use generic job_kill to stop every other
+  // project's scheduler after its own trigger_scheduler mutation was denied.
+  ctx.on('tools/pre-execute', async (exec, next) => {
+    const decision = await next();
+    if (decision.kind !== 'allow' || exec.name !== 'job_kill' || exec.arguments?.job_id !== control.owner.status().job_id) return decision;
+    const problem = mutationProblem(ctx, exec.agent);
+    return problem ? { kind: 'deny', reason: problem } : { kind: 'ask', reason: 'Stopping the DSCODE scheduler interrupts scheduled work for every registered project.' };
+  }, { prepend: true });
+
+  ctx.inject(['connection'], scope => {
+    scope.effect(() => scope.connection.fetch.register({ path: '/api/dscode-triggers', methods: ['POST'], requestBody: 'buffered',
+      fetch: async request => {
+        let body;
+        try { body = await request.json(); } catch { return new Response('Invalid JSON', { status: 400 }); }
+        const parsed = clientRequestSchema.safeParse(body);
+        if (!parsed.success || parsed.data.method !== 'dscode-triggers') return new Response('Invalid scheduling request', { status: 400 });
+        const { rpcId, payload } = parsed.data;
+        let result;
+        try { result = { ok: true, value: await triggerDesktopRequest(ctx, service, payload, request.signal) }; }
+        catch (error) { result = { ok: false, error: { code: 'dscode-triggers', message: error.message, details: {} } }; }
+        return Response.json({ type: 'server-response', rpcId, result }, { headers: { 'Cache-Control': 'no-store' } });
+      },
+    }), 'dscode scheduling rpc');
+  }).then(undefined, error => { ctx.logger.error(`Scheduling transport failed: ${error.message}`); });
+}

package/plugins/triggers/desktop-management.mjs

@@ -0,0 +1,97 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { DesktopTriggerScheduler } from './desktop-scheduler.mjs';
+import { TriggerManagement } from './management.mjs';
+import { acquireTriggerLease } from './lease.mjs';
+
+export const desktopSchedulerDescription = 'Desktop scheduler start enables delivery for all registered projects and remembers that choice for future Desktop launches. stop disables that choice, interrupts active trigger runs and drains script sources; pending jobs remain queued. Desktop must stay open to deliver jobs. No OS service is installed.';
+
+/** Persistent user choice and serialized controls around one process-owned scheduler. */
+export class DesktopTriggerControl {
+  constructor(ctx, { home, owner = new DesktopTriggerScheduler(ctx, { home }) }) {
+    this.home = home; this.owner = owner; this.enabled = false; this.closed = false;
+    this.pending = Promise.resolve(); this.ready = Promise.resolve();
+    this.path = join(home, 'config', 'desktop-scheduler.json');
+    try {
+      const value = JSON.parse(readFileSync(this.path, 'utf8'));
+      if (value?.version !== 1 || typeof value.enabled !== 'boolean') throw Error('Invalid Desktop scheduler settings');
+      this.enabled = value.enabled;
+    } catch (error) { if (error.code !== 'ENOENT') this.error = error.message; }
+  }
+  enqueue(operation) {
+    const result = this.pending.then(() => {
+      if (this.closed) throw Error('Desktop scheduling is shutting down');
+      return operation();
+    });
+    this.pending = result.catch(() => {});
+    return result;
+  }
+  initialize(hostReady = Promise.resolve()) {
+    // Loading all providers/preset hooks precedes automatic delivery. Do not
+    // block the plugin apply callback on its own loader's readiness barrier.
+    this.ready = Promise.resolve(hostReady).then(() => this.enqueue(async () => {
+      if (this.enabled) await this.owner.start();
+    })).catch(error => { this.error = error.message; });
+    return this.ready;
+  }
+  save(enabled) {
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    const temp = `${this.path}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temp, JSON.stringify({ version: 1, enabled }) + '\n', { flag: 'wx', mode: 0o600 });
+      renameSync(temp, this.path); this.enabled = enabled;
+    } finally { rmSync(temp, { force: true }); }
+  }
+  async setEnabled(enabled) {
+    if (typeof enabled !== 'boolean') throw Error('enabled must be a boolean');
+    await this.ready;
+    await this.enqueue(async () => {
+      const previous = this.enabled;
+      this.save(enabled); // A failed save cannot start autonomous work.
+      this.error = undefined;
+      try { if (enabled) await this.owner.start(); else await this.owner.stop(); }
+      catch (error) {
+        if (enabled && !previous) this.save(false);
+        this.error = error.message; throw error;
+      }
+    });
+    return this.status();
+  }
+  async status() {
+    await this.ready;
+    const local = this.owner.status();
+    let external = false;
+    if (!local.running && !local.stopping) {
+      const lease = await acquireTriggerLease(this.home, '_scheduler');
+      external = !lease; lease?.release();
+    }
+    return { ...local, enabled: this.enabled, running: local.running || external,
+      owner: external ? 'external' : 'desktop', requires_open_application: !external,
+      next_step: external ? 'Another process owns the queue; control it from its terminal or service manager.' : 'Use /trigger scheduler start or Settings > DSCODE schedules to enable delivery.',
+      ...(this.error ? { error: this.error } : {}) };
+  }
+  async dispose() {
+    this.closed = true;
+    // Keep the user's saved choice; quit/unload only stops this process owner.
+    await this.owner.dispose();
+  }
+}
+
+export class DesktopTriggerManagement extends TriggerManagement {
+  constructor({ control, ...options }) {
+    super(options); this.control = control;
+    this.schedulerActions = ['status', 'start', 'stop'];
+    this.schedulerDescription = desktopSchedulerDescription;
+  }
+  workspace(agent) {
+    if (this.control.closed) throw Error('Desktop scheduling is shutting down');
+    return super.workspace(agent);
+  }
+  status() { return this.control.status(); }
+  async scheduler({ action }) {
+    if (action === 'status') return this.status();
+    if (!['start', 'stop'].includes(action)) throw Error('Desktop scheduler action must be status, start or stop');
+    return { scheduler: await this.control.setEnabled(action === 'start') };
+  }
+}

package/plugins/triggers/desktop-scheduler.mjs

@@ -0,0 +1,125 @@
+// Desktop queue owner. Management/UI chooses when to start it; merely loading
+// this module creates no jobs, timers, service registration or OS launch agent.
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { installModelSelection } from '@deepseek-ai/dsh-agent';
+import { runScheduler } from './scheduler.mjs';
+import { runTriggerCli } from './cli.mjs';
+import { loadTriggerDefinitions } from './config.mjs';
+import { startTriggerSession } from './session-run.mjs';
+
+export class DesktopTriggerScheduler {
+  constructor(ctx, { home, jobs = ctx.get?.('jobs'), report = message => ctx.logger.warn(message) }) {
+    this.ctx = ctx; this.home = home; this.report = report; this.jobs = jobs;
+    this.task = undefined; this.ready = undefined; this.controller = undefined;
+    this.stopping = false; this.error = undefined; this.disposed = false;
+  }
+  status() {
+    return { running: !!this.task && this.started === true && !this.stopping,
+      stopping: this.stopping, owner: 'desktop', requires_open_application: true,
+      ...(this.jobId ? { job_id: this.jobId } : {}),
+      ...(this.error ? { error: this.error } : {}) };
+  }
+  async start() {
+    if (this.disposed) throw Error('Desktop scheduler has been disposed.');
+    if (this.stopping) throw Error('Desktop scheduler is stopping; wait until it has drained before starting again.');
+    if (this.task) { await this.ready; return this.status(); }
+    const ready = Promise.withResolvers();
+    this.ready = ready.promise;
+    this.controller = new AbortController(); this.error = undefined; this.started = false;
+    const signal = this.controller.signal;
+    const launch = () => runScheduler({ home: this.home, signal,
+      onReady: () => { this.started = true; ready.resolve(); },
+      spawnWorker: request => this.execute(request.job, signal), report: this.report,
+    });
+    let task, detach;
+    try {
+      if (this.jobs) {
+        detach = this.jobs.attachController('DSCODE Desktop scheduler');
+        // Register before dispatching anything. Native quit/update inspection
+        // sees this global job even while the queue has no live Agent. Its
+        // cancellation hook drains both Agents and supervised script sources.
+        this.jobId = this.jobs.start({ kind: 'dscode-scheduler', label: 'DSCODE scheduler — requires the application to stay open',
+          run: handle => {
+            handle.updateProgress('Waiting for scheduled work');
+            task = launch();
+            return { cancel: reason => this.requestStop(reason), done: task.then(
+              () => ({ status: signal.aborted ? 'killed' : 'completed' }),
+              error => ({ status: 'failed', detail: error.message }),
+            ) };
+          },
+        });
+      } else task = launch();
+    } catch (error) {
+      detach?.(); this.controller = undefined; this.ready = undefined;
+      this.error = error.message;
+      throw error;
+    }
+    this.task = task;
+    // Completion is observed even when a UI no longer waits on its start request.
+    void task.catch(error => { this.error = error.message; ready.reject(error); this.report(error.message); }).finally(() => {
+      detach?.();
+      if (this.task === task) { this.task = undefined; this.controller = undefined; this.started = false; this.stopping = false; }
+    });
+    await this.ready;
+    return this.status();
+  }
+  async stop() {
+    const task = this.task;
+    if (!task) return this.status();
+    this.requestStop();
+    try { await task; } finally {
+      if (this.task === task) { this.task = undefined; this.controller = undefined; this.started = false; this.stopping = false; }
+    }
+    return this.status();
+  }
+  requestStop(reason = 'Desktop scheduler stopped') {
+    if (!this.controller) return;
+    this.stopping = true;
+    this.controller.abort(new Error(reason));
+  }
+  async dispose() {
+    this.disposed = true;
+    return this.stop();
+  }
+  async execute(job, signal) {
+    if (signal.aborted) return 0; // leave unclaimed work pending for the next owner
+    // Do not let manually edited files bypass the same bounds as agent-managed
+    // definitions. CLI-only presets and elevated unattended modes stay excluded.
+    const definition = loadTriggerDefinitions({ home: this.home, workspace: job.project }).definitions.find(row => row.id === job.triggerId);
+    if (definition && (definition.preset !== 'dscode' || !['read-only', 'workspace-write'].includes(definition.permission))) {
+      throw Error('Desktop scheduling requires the dscode preset and read-only or workspace-write permission');
+    }
+    const directory = join(this.home, 'triggers/jobs'); mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const log = { write: text => appendFileSync(join(directory, `${job.id}.log`), text, { mode: 0o600 }) };
+    return runTriggerCli(['run-job', job.id], { home: this.home, project: job.project, stdout: log, stderr: log,
+      spawnRun: async ({ spec }) => {
+        if (spec.preset !== 'dscode' || !['read-only', 'workspace-write'].includes(spec.permission)) throw Error('Unsupported Desktop trigger preset or permission');
+        const deadline = AbortSignal.timeout(spec.limits.timeoutSeconds * 1000);
+        const combined = AbortSignal.any([signal, deadline]);
+        const stopped = () => ({ outcome: deadline.aborted && !signal.aborted ? 'timedout' : 'failed',
+          reason: deadline.aborted && !signal.aborted ? 'timeout' : 'interrupted', exitCode: deadline.aborted && !signal.aborted ? 124 : 130,
+          sessionId: null, cost: null, rounds: null });
+        if (combined.aborted) { const result = stopped(); return { code: result.exitCode, result }; }
+        try {
+          const run = await startTriggerSession(this.ctx, { spec, home: this.home, signal: combined,
+            prepare: (scope, agent) => installModelSelection(scope, { get current() { return agent.session.requestHeader()?.config ?? agent.options; }, assembled: undefined }),
+          });
+          let result = await run.done;
+          if (result.reason === 'interrupted' && deadline.aborted && !signal.aborted) result = { ...result, outcome: 'timedout', reason: 'timeout', exitCode: 124 };
+          return { code: result.exitCode, result };
+        } catch (error) {
+          if (!combined.aborted) throw error;
+          const result = stopped(); return { code: result.exitCode, result };
+        }
+      },
+    });
+  }
+}
+
+/** Bind shutdown and plugin removal to the same drain as an explicit stop. */
+export function createDesktopTriggerScheduler(ctx, options) {
+  const scheduler = new DesktopTriggerScheduler(ctx, options);
+  ctx.effect(() => () => scheduler.dispose(), 'dscode scheduler drain');
+  return scheduler;
+}

package/plugins/triggers/host.mjs

@@ -0,0 +1,24 @@
+// Process-owned adapter for the CLI. Desktop can use startTriggerSession without
+// exiting its shared Host when a task completes or reaches its deadline.
+import { startTriggerSession } from './session-run.mjs';
+import { readRunSpec, writeRunResult } from './options.mjs';
+import { sessionSpend } from '../session-metrics/view.mjs';
+export { triggerOverlay } from './overlay.mjs';
+
+export const name = 'dscode-trigger-host';
+export const inject = ['agents', 'sessions', 'agentPresets', 'agentDefaultModel', 'permissionPresets', 'llm', 'goals', 'appExit'];
+export function apply(ctx) {
+  void runTriggerHost(ctx).catch(error => { process.stderr.write(`dscode trigger run: ${error.message}\n`); ctx.get('appExit')(1); });
+}
+export async function runTriggerHost(ctx, { optionsPath = process.env.DSCODE_TRIGGER_OPTIONS, home = process.env.DSH_HOME, spend = sessionSpend } = {}) {
+  await ctx.get('loader').await();
+  if (!optionsPath) throw Error('DSCODE_TRIGGER_OPTIONS is missing');
+  const run = await startTriggerSession(ctx, { spec: readRunSpec(optionsPath), home, spend });
+  void run.done.then(result => {
+    writeRunResult(`${optionsPath}.result.json`, result);
+    ctx.get('appExit')(result.exitCode);
+  }).catch(error => {
+    process.stderr.write(`dscode trigger run: ${error.message}\n`);
+    ctx.get('appExit')(1);
+  });
+}

package/plugins/triggers/index.mjs

@@ -0,0 +1,27 @@
+// TUI management and agent tools use one definitions/jobs/source service.
+import { registerTriggerTools, mutationProblem } from './tools.mjs';
+import { TriggerManagement } from './management.mjs';
+import { triggerCommand } from './commands.mjs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const name = 'dscode-triggers';
+export const inject = ['commands'];
+const stateHome = () => process.env.DSH_HOME ?? process.env.DSCODE_HOME ?? join(homedir(), '.local/share/dscode-hub');
+
+export function apply(ctx) {
+  const home = stateHome();
+  let managementContext;
+  ctx.inject(['tools', 'systemPrompt', 'permissionPresets'], toolCtx => {
+    managementContext = toolCtx;
+    registerTriggerTools(toolCtx, { home });
+  });
+  const management = new TriggerManagement({ home, dscodePath: process.env.DSCODE_CLI_PATH });
+  const handler = triggerCommand({ management, mutationProblem: agent => managementContext
+    ? mutationProblem(managementContext, agent) : 'Trigger management services are not available yet.' });
+  for (const name of ['trigger', 'triggers']) ctx.commands.register({
+    name, description: 'Manage triggers, jobs and script sources; /trigger help',
+    input: { hint: '[list|show|new|update|enable|disable|run|schedule|jobs|cancel|source|scheduler|help]' },
+    handler,
+  });
+}

package/plugins/triggers/job-cli.mjs

@@ -0,0 +1,110 @@
+import { existsSync } from 'node:fs';
+import { JobStore, formatJob } from './jobs.mjs';
+import { normalizeEvent } from './spool.mjs';
+import { dueTime } from './schedule.mjs';
+import { runScheduler } from './scheduler.mjs';
+import { schedulerService } from './scheduler-service.mjs';
+import { acquireTriggerLease } from './lease.mjs';
+import { appendRun, readRuns } from './log.mjs';
+
+export const JOB_COMMANDS = ['schedule', 'jobs', 'cancel', 'scheduler', 'run-job'];
+
+export async function handleJobCommand(options, context) {
+  const { home, project, now, platform, dscodePath, launchctl, out, err, deps, findDefinition, readEventBody } = context;
+  if (options.command === 'scheduler') {
+    if (!['start', 'tick', 'install', 'uninstall', 'status'].includes(options.id)) throw new Error('scheduler expects start, tick, install, uninstall or status');
+    if (options.id === 'status') {
+      const lease = await acquireTriggerLease(home, '_scheduler');
+      out(lease ? 'scheduler stopped' : 'scheduler running');
+      lease?.release();
+      return 0;
+    }
+    if (!dscodePath || !existsSync(dscodePath)) throw new Error('the scheduler needs a valid dscode program path');
+    if (['install', 'uninstall'].includes(options.id)) {
+      await schedulerService(options.id, { home, dscodePath, platform, launchctl, agentsDirectory: deps.agentsDirectory, out });
+      return 0;
+    }
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.once(signal, stop);
+    try {
+      out(`scheduler ${options.id}: ${home}`);
+      return await runScheduler({ home, dscodePath, once: options.id === 'tick', signal: controller.signal, spawnWorker: deps.spawnWorker, report: err });
+    } finally { for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.off(signal, stop); }
+  }
+  const store = new JobStore(home);
+  try {
+    if (options.command === 'jobs') {
+      const jobs = store.list(options.id || undefined);
+      out(jobs.length ? jobs.map(formatJob).join('\n') : 'No jobs scheduled.');
+      return 0;
+    }
+    if (options.command === 'cancel') {
+      store.cancel(options.id, now);
+      out(`cancelled ${options.id}`);
+      return 0;
+    }
+    if (options.command === 'schedule') {
+      const definition = findDefinition(home, project, options.id);
+      const dueAt = dueTime(options, now);
+      const payload = (await readEventBody(options, deps.stdin ?? process.stdin)) ?? {};
+      normalizeEvent(definition.id, payload, { eventId: 'validation', now });
+      if (options.eventId !== undefined) throw new Error('schedule assigns a jobId; --event-id is only for emit/fire/run');
+      const job = store.create({ triggerId: definition.id, project, workspace: definition.workspace, payload, dueAt, now });
+      out(formatJob(job));
+      out('The scheduler delivers this job: dscode trigger scheduler install (or scheduler start).');
+      return 0;
+    }
+    return await executeJob(store, options.id, context);
+  } finally { store.close(); }
+}
+
+export async function executeJob(store, id, context) {
+  const { home, now, deps, out, err, executeEvent, findDefinition } = context;
+  const job = store.get(id);
+  if (!job) throw new Error(`no job "${id}"`);
+  if (job.state !== 'pending' || job.availableAt > now) { out(formatJob(job)); return 0; }
+  const triggerLease = await acquireTriggerLease(home, job.triggerId);
+  if (!triggerLease) { store.defer(id, 'already_running', now + 1000); return 0; }
+  let handle;
+  try {
+    let definition;
+    try { definition = findDefinition(home, job.project, job.triggerId); }
+    catch (error) { store.defer(id, 'definition_missing', now + 30000); err(error.message); return 0; }
+    if (definition.workspace !== job.workspace) {
+      store.defer(id, 'workspace_changed', now + 30000);
+      err(`job ${id} belongs to ${job.workspace}; cancel it and schedule a new job for the changed workspace`);
+      return 0;
+    }
+    const eventId = store.eventIdentity(job.id) ?? `job:${job.id}`;
+    const chosen = normalizeEvent(job.triggerId, { source: job.kind, ...JSON.parse(job.payload) }, { eventId, now: job.createdAt });
+    const result = await executeEvent(definition, {
+      home, now, deps, out, err, triggerLease, chosen, eventId, jobId: id, quietSkips: true,
+      beforeRun: planned => { handle = planned; return store.claim(id, planned.runId, now); },
+    });
+    if (result.skip) {
+      let availableAt = now + 30000;
+      const runs = readRuns(home, { triggerId: job.triggerId, limit: 0 }).filter(r => r.outcome !== 'skipped');
+      if (result.skip === 'too_soon' && runs[0]) availableAt = runs[0].startedAt + definition.limits.minIntervalSeconds * 1000;
+      if (result.skip === 'over_daily_limit') {
+        const withinDay = runs.filter(r => r.startedAt > now - 86400000).sort((a, b) => a.startedAt - b.startedAt);
+        if (withinDay[0]) availableAt = withinDay[0].startedAt + 86400000;
+      }
+      if (result.skip === 'duplicate') {
+        // Reconcile a durable run record after a crash before job-state update.
+        const previous = runs.find(r => r.eventId === eventId);
+        if (store.claim(id, previous.runId, now)) store.finish(id, previous, now);
+      } else store.defer(id, result.skip, availableAt);
+      return 0;
+    }
+    store.finish(id, result.record ?? { exitCode: result.code, reason: 'no_match' });
+    return result.code;
+  } catch (error) {
+    if (handle && store.get(id).state === 'running') {
+      const record = { ...handle, jobId: id, outcome: 'failed', reason: 'model_error', exitCode: 1, endedAt: Date.now(), cwd: job.workspace };
+      appendRun(home, record);
+      store.finish(id, record);
+    }
+    throw error;
+  } finally { triggerLease.release(); }
+}

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}` : ''}`;
+}