@goodandready/dsh-cron 0.2.51 → 0.3.0

package/lib/client.js

@@ -140,16 +140,10 @@ window.__ModuleLoader__.load({
         'history.stage_validation': 'Validation',
         'history.stage_delivery': 'Delivery',
         'history.refresh': 'Refresh history',
-        'history.stoppedReasonTitle': '停止原因:',
-        'history.retryDelivery': '重试推送',
-        'history.retryingDelivery': '重试中...',
-        'history.statusValidationFailed': '校验未通过',
-        'history.stage_queue': '排队',
-        'history.stage_preflight': '前置检查',
-        'history.stage_execution': '执行',
-        'history.stage_validation': '校验',
-        'history.stage_delivery': '推送',
-        'history.statusSuccess': 'Success',
+        'history.statusSuccess': 'Success', 'history.statusUncertain': 'Uncertain',
+        'history.artifacts': 'Artifacts',
+        'history.resolveCompleted': 'Mark Completed', 'history.resolveFailed': 'Mark Failed',
+        'history.statusUncertainHint': 'Interrupted by restart — verify outcome',
         'history.statusSkipped': 'Skipped',
         'history.statusMissed': 'Missed',
         'history.statusTimeout': 'Timeout',
@@ -367,6 +361,12 @@ window.__ModuleLoader__.load({
         'form.targetSessionResetDaily': 'Daily rotation (new session each day)',
         'form.targetSessionResetWeekly': 'Weekly rotation (new session each week)',
         'form.targetSessionResetHint': 'Automatically rotates the session identifier to prevent context window explosion over long periods.',
+                'form.requireApprovalLabel': 'Require human approval before execution',
+        'form.requireApprovalHint': 'When enabled, the task will not execute until an authorized user approves the run proposal (#318).',
+        'actions.approve': 'Approve', 'actions.reject': 'Reject',
+        'approval.waiting': 'Awaiting human approval',
+        'approval.approved': 'Approved', 'approval.rejected': 'Rejected',
+        'recipe.dependenciesMissing': 'Missing required integrations or credentials',
         'form.previewSchedule': 'Preview next runs',
         'form.previewScheduleTitle': 'Next 5 scheduled runs:',
       },
@@ -507,6 +507,10 @@ window.__ModuleLoader__.load({
         'history.summaryCost': '预估成本: ${cost}',
         'history.errorLabel': '错误详情:',
         'history.outputLabel': '执行输出:',
+        'history.statusUncertain': '不确定',
+        'history.artifacts': '产物文件',
+        'history.resolveCompleted': '标记已完成', 'history.resolveFailed': '标记失败',
+        'history.statusUncertainHint': '服务重启中断 — 请确认结果',
         'form.titleLabel': '任务名称 *',
         'form.titlePlaceholder': '例如: 每周备份检查',
         'form.typeLabel': '执行类型 *',
@@ -616,6 +620,12 @@ window.__ModuleLoader__.load({
         'dsh.startFailed': '启动智能体对话失败: {error}',
         'dsh.launchError': '执行错误: {error}',
         'confirm.delete': '确定删除该任务吗？',
+                'form.requireApprovalLabel': '执行前需人工确认审批',
+        'form.requireApprovalHint': '开启后，任务执行前将挂起并等待授权用户批准提议 (#318)。',
+        'actions.approve': '批准', 'actions.reject': '拒绝',
+        'approval.waiting': '等待人工审批',
+        'approval.approved': '已批准', 'approval.rejected': '已拒绝',
+        'recipe.dependenciesMissing': '缺少必要集成服务或凭据',
         'list.loadErrorPrefix': '加载任务列表失败'
       }
     };
@@ -882,11 +892,6 @@ window.__ModuleLoader__.load({
     const STYLE_HEAL_KEY = '__dshCronStyleHeal';
     const STYLE_HEAL_INTERVAL_MS = 2000;
 
-    /**
-     * Keep the stylesheet attached: watch <head> (and <html>, which catches a
-     * replaced <head>) and re-attach on demand, with a slow interval as the
-     * backstop. heal() is idempotent and writes nothing while healthy.
-     */
     function startStyleSelfHeal() {
       if (typeof document === 'undefined') return () => {};
       if (typeof window !== 'undefined' && typeof window[STYLE_HEAL_KEY] === 'function') {
@@ -989,7 +994,6 @@ window.__ModuleLoader__.load({
     const DELIVERY_SETTING_KEYS = DELIVERY_SETTING_FIELDS.map((f) => f.key);
     const TEMPLATE_SETTING_KEYS = ['template', 'channelTemplates'];
 
-    /** Collect every delivery key the settings endpoints may return. */
     function parseEnvText(text) {
       const env = {};
       for (const rawLine of String(text || '').split('\n')) {
@@ -1083,15 +1087,10 @@ window.__ModuleLoader__.load({
       if (status === 'skipped') return T_KEY(t, 'history.statusSkipped');
       if (status === 'missed') return T_KEY(t, 'history.statusMissed');
       if (status === 'timeout') return T_KEY(t, 'history.statusTimeout');
+      if (status === 'uncertain') return T_KEY(t, 'history.statusUncertain');
       return T_KEY(t, 'history.statusFailed');
     }
 
-    /**
-     * A config-declared task is owned by the profile config file (#50): the
-     * panel shows it, but editing, pausing or deleting it here would be undone
-     * at the next start, so the row keeps the source label instead of the
-     * actions that cannot stick.
-     */
     function isConfigManaged(task) {
       return Boolean(task) && task.managedBy === 'config';
     }
@@ -1099,10 +1098,6 @@ window.__ModuleLoader__.load({
       return (typeof t === 'function' ? t : translate)(key, vars);
     }
 
-    /**
-     * Issue #307: universal fetch with AbortController timeout (default 15s).
-     * Connects with caller signal if supplied and fails closed on timeouts.
-     */
     const fetchWithTimeout = async (url, options = {}, timeoutMs = 15000) => {
       const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
       const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
@@ -1131,9 +1126,6 @@ window.__ModuleLoader__.load({
       }
     };
 
-    /**
-     * Issue #307: universal JSON fetch helper with timeout and aborted body protection.
-     */
     const fetchJsonWithTimeout = async (url, options = {}, timeoutMs = 15000) => {
       const res = await fetchWithTimeout(url, options, timeoutMs);
       let data = {};
@@ -1158,11 +1150,6 @@ window.__ModuleLoader__.load({
       return out;
     }
 
-    /**
-     * Shared delivery form used by both the task panel modal and the plugin
-     * settings card, so a new channel is added in exactly one place.
-     * Sections collapse via the canonical aria-expanded head contract.
-     */
     function renderDeliverySettings({ T, values, onChange, onChannelTemplate, sections, onToggleSection }) {
       const val = (key) => (values[key] === undefined || values[key] === null ? '' : String(values[key]));
       const field = (f) => React.createElement('div', { className: 'dsh-cron-form-group', key: f.key, style: { marginBottom: '10px' } },
@@ -1239,7 +1226,6 @@ window.__ModuleLoader__.load({
       ];
     }
 
-    /** Parse a KEY=VALUE textarea into the task env object (#38). */
     function CronScreen(props) {
       const { ctx, toggle, onClose } = props;
       const t = props.t || translate;
@@ -1272,6 +1258,7 @@ window.__ModuleLoader__.load({
       const [formFallbackModel, setFormFallbackModel] = React.useState('');
       const [formSilentRule, setFormSilentRule] = React.useState('');
       const [formInspectOnFailure, setFormInspectOnFailure] = React.useState(false);
+      const [formRequireApproval, setFormRequireApproval] = React.useState(false);
       const [formDelivery, setFormDelivery] = React.useState('isolated');
       const [selectedTaskMeta, setSelectedTaskMeta] = React.useState(null);
       const [modalTab, setModalTab] = React.useState('params');
@@ -1341,6 +1328,7 @@ window.__ModuleLoader__.load({
         fallbackModel: String(formFallbackModel || ''),
         silentRule: String(formSilentRule || ''),
         inspectOnFailure: Boolean(formInspectOnFailure),
+        requireApproval: Boolean(formRequireApproval),
         delivery: String(formDelivery || 'isolated'),
         notifyTelegram: Boolean(formNotifyTelegram),
         channels: Array.isArray(formChannels) ? [...formChannels].sort() : [],
@@ -1450,7 +1438,6 @@ window.__ModuleLoader__.load({
         return () => window.removeEventListener('keydown', onKey);
       }, [manualModalOpen, settingsModalOpen, dshModalOpen, dropdownOpen, onClose]);
 
-      /** #40: facet filtering happens client-side over the loaded list. */
       const visibleTasks = React.useMemo(() => {        let list = tasks;
         if (filterType) list = list.filter((x) => (x.type || 'llm') === filterType);
         if (filterModel) list = list.filter((x) => String(x.model || '').split('/').pop() === filterModel);
@@ -1481,7 +1468,6 @@ window.__ModuleLoader__.load({
         setFilterChannel('');
       };
 
-      /** #34: scroll to and flash the task the sidebar list asked for. */
       React.useEffect(() => {
         if (!pendingTaskHighlight || tasks.length === 0) return;
         const id = pendingTaskHighlight;
@@ -1708,7 +1694,6 @@ window.__ModuleLoader__.load({
         }
       };
 
-      /** #41: duplicate a task; the server copies config, resets run state (#41). */
       const handleDryRun = async (taskId) => {
         try {
           const { res, data } = await fetchJsonWithTimeout('/dsh-cron/tasks/' + encodeURIComponent(taskId) + '/dry-run', { method: 'POST' });
@@ -1767,10 +1752,8 @@ window.__ModuleLoader__.load({
         }
       };
 
-      /** A task id must not shadow a collection route (#42 review finding). */
       const RESERVED_TASK_IDS = ['export', 'import'];
 
-      /** Import needs the script-confirm header when the file has code tasks. */
       const isCodeTaskForm = (x) => {
         if (!x || typeof x !== 'object') return false;
         if (CODE_FORM_TYPES.includes(x.type)) return true;
@@ -1787,7 +1770,6 @@ window.__ModuleLoader__.load({
         return headers;
       };
 
-      /** #42, #240: download the task configuration with honest disclosure and sanitized export choice. */
       const handleExport = async () => {
         setTransferBusy(true);
         try {
@@ -1817,7 +1799,6 @@ window.__ModuleLoader__.load({
         }
       };
 
-      /** #42: read the picked file, validate it server-side and show the plan. */
       const handleImportFile = async (e) => {
         const file = e.target.files && e.target.files[0];
         e.target.value = '';
@@ -1874,7 +1855,6 @@ window.__ModuleLoader__.load({
         }
       };
 
-      /** #49: tune an existing task in a dialogue instead of editing fields. */
       const handleTuneWithDsh = async (task) => {
         const lines = [
           `Tune the existing scheduled task "${task.title}" (id: ${task.id}).`,
@@ -1907,6 +1887,42 @@ window.__ModuleLoader__.load({
         }
       };
 
+      const handleApproveProposal = async (taskId, proposalId) => {
+        try {
+          const { res, data } = await fetchJsonWithTimeout('/dsh-cron/tasks/' + encodeURIComponent(taskId) + '/approve', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ proposalId, decidedBy: 'web-user' })
+          });
+          if (data && data.ok) {
+            alert(T_KEY(t, 'approval.approved') || 'Approved');
+            setTimeout(() => fetchTasks(), 1000);
+          } else {
+            alert('Approval failed: ' + ((data && data.error) || ''));
+          }
+        } catch (err) {
+          alert('Approval request failed: ' + err.message);
+        }
+      };
+
+      const handleRejectProposal = async (taskId, proposalId) => {
+        try {
+          const { res, data } = await fetchJsonWithTimeout('/dsh-cron/tasks/' + encodeURIComponent(taskId) + '/reject', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ proposalId, decidedBy: 'web-user' })
+          });
+          if (data && data.ok) {
+            alert(T_KEY(t, 'approval.rejected') || 'Rejected');
+            setTimeout(() => fetchTasks(), 1000);
+          } else {
+            alert('Rejection failed: ' + ((data && data.error) || ''));
+          }
+        } catch (err) {
+          alert('Rejection request failed: ' + err.message);
+        }
+      };
+
       const handleDelete = async (id) => {
         if (!confirm(T_KEY(t, 'confirm.delete'))) return;
         try {
@@ -1961,11 +1977,6 @@ window.__ModuleLoader__.load({
         }
       };
 
-      /**
-       * Update one delivery setting without dropping the rest of the object.
-       * `undefined` removes the key so the server default applies again; an
-       * empty string is kept so a text field can be cleared on purpose.
-       */
       const updateDelivery = (key, value) => {
         setSettingsDelivery((prev) => {
           const next = Object.assign({}, prev);
@@ -1975,7 +1986,6 @@ window.__ModuleLoader__.load({
         });
       };
 
-      /** Per-channel template overrides live in a nested map on the server. */
       const updateChannelTemplate = (channelId, value) => {
         setSettingsDelivery((prev) => {
           const templates = Object.assign({}, prev.channelTemplates || {});
@@ -2049,6 +2059,7 @@ window.__ModuleLoader__.load({
         setFormFallbackModel('');
         setFormSilentRule('');
         setFormInspectOnFailure(false);
+        setFormRequireApproval(false);
         if (preset) {
           setFormTitle(preset.title || '');
           setFormSchedule(preset.schedule || '');
@@ -2058,6 +2069,7 @@ window.__ModuleLoader__.load({
           if (preset.silentRule !== undefined) setFormSilentRule(preset.silentRule || '');
           if (preset.fallbackModel !== undefined) setFormFallbackModel(preset.fallbackModel || '');
           if (preset.inspectOnFailure !== undefined) setFormInspectOnFailure(Boolean(preset.inspectOnFailure));
+          if (preset.requireApproval !== undefined) setFormRequireApproval(Boolean(preset.requireApproval));
           setFormOnlyOnFailure(Boolean(preset.onlyOnFailure));
           setFormProvider(defaultModelInfo?.provider || '');
           setFormModel(defaultModelInfo?.model || '');
@@ -2080,6 +2092,7 @@ window.__ModuleLoader__.load({
           fallbackModel: String((preset && preset.fallbackModel) || '').trim(),
           silentRule: String((preset && preset.silentRule) || '').trim(),
           inspectOnFailure: Boolean(preset && preset.inspectOnFailure),
+          requireApproval: Boolean(preset && preset.requireApproval),
           delivery: 'isolated',
           notifyTelegram: false,
           channels: Array.isArray(preset && preset.channels) ? [...preset.channels].filter((c) => DELIVERY_CHANNELS.includes(c)).sort() : [],
@@ -2146,6 +2159,23 @@ window.__ModuleLoader__.load({
         }
       };
 
+      const handleResolveUncertain = async (taskId, runId, resolution) => {
+        try {
+          const { res, data } = await fetchJsonWithTimeout('/dsh-cron/tasks/' + encodeURIComponent(taskId) + '/resolve-uncertain', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ runId, resolution }),
+          });
+          if (data && data.ok) {
+            await loadTaskHistory(taskId);
+          } else {
+            alert(data?.error || 'Failed to resolve uncertain run');
+          }
+        } catch (e) {
+          alert(e.message || 'Error resolving uncertain run');
+        }
+      };
+
       const loadTaskHistory = async (taskId) => {
         setHistoryLoading(true);
         try {
@@ -2174,6 +2204,7 @@ window.__ModuleLoader__.load({
         setFormFallbackModel(task.fallbackModel || '');
         setFormSilentRule(task.silentRule || '');
         setFormInspectOnFailure(Boolean(task.inspectOnFailure));
+        setFormRequireApproval(Boolean(task.requireApproval));
         setFormDelivery(task.delivery || 'isolated');
         setFormNotifyTelegram(Boolean(task.notifyTelegram));
         setFormChannels(Array.isArray(task.channels) ? task.channels.filter((c) => DELIVERY_CHANNELS.includes(c)) : []);
@@ -2271,6 +2302,7 @@ window.__ModuleLoader__.load({
             concurrencyGroup: formConcurrencyGroup.trim() || 'default',
             selfHealingCommand: formSelfHealingCommand.trim() || undefined,
             autoDiagnose: Boolean(formAutoDiagnose),
+            requireApproval: Boolean(formRequireApproval),
             env: parseEnvText(formEnv),
             cwd: formCwd.trim(),
             workspaceId: formWorkspaceId.trim(),
@@ -2777,6 +2809,41 @@ window.__ModuleLoader__.load({
                           onClick: () => handleRetryDelivery(formId, run.id)
                         }, retryingDeliveryId === run.id ? T_KEY(t, 'history.retryingDelivery') : T_KEY(t, 'history.retryDelivery'))
                       ),
+                      run.artifacts && run.artifacts.length > 0 && React.createElement('div', {
+                        style: { display: 'flex', flexWrap: 'wrap', gap: '6px', marginTop: '6px', alignItems: 'center' }
+                      },
+                        React.createElement('span', { className: 'dsh-cron-hint', style: { fontSize: '11px' } }, '📦 ' + T_KEY(t, 'history.artifacts') + ':'),
+                        run.artifacts.map((art) => React.createElement('a', {
+                          key: art.name || art.id,
+                          href: '/dsh-cron/runs/' + encodeURIComponent(run.id) + '/artifacts/' + encodeURIComponent(art.name) + '/preview',
+                          target: '_blank',
+                          rel: 'noopener noreferrer',
+                          className: 'dsh-cron-btn-secondary',
+                          style: { padding: '2px 8px', fontSize: '11px', textDecoration: 'none' },
+                          title: art.name + ' (' + Math.round((art.size || 0) / 1024 * 10) / 10 + ' KB)'
+                        }, art.name))
+                      ),
+                      run.status === 'uncertain' && React.createElement('div', {
+                        className: 'dsh-cron-status-banner',
+                        'data-type': 'warning',
+                        style: { marginTop: '8px', display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: '8px' }
+                      },
+                        React.createElement('span', null, '⚠️ ' + T_KEY(t, 'history.statusUncertainHint')),
+                        React.createElement('div', { style: { display: 'flex', gap: '6px' } },
+                          React.createElement('button', {
+                            type: 'button',
+                            className: 'dsh-cron-btn-secondary',
+                            style: { padding: '2px 8px', fontSize: '11px' },
+                            onClick: () => handleResolveUncertain(formId, run.id, 'completed')
+                          }, '✓ ' + T_KEY(t, 'history.resolveCompleted')),
+                          React.createElement('button', {
+                            type: 'button',
+                            className: 'dsh-cron-btn-secondary',
+                            style: { padding: '2px 8px', fontSize: '11px' },
+                            onClick: () => handleResolveUncertain(formId, run.id, 'failed')
+                          }, '✕ ' + T_KEY(t, 'history.resolveFailed'))
+                        )
+                      ),
                       run.diagnosis && React.createElement('div', {
                         className: 'dsh-cron-status-banner',
                         'data-type': 'info',
@@ -3057,7 +3124,16 @@ window.__ModuleLoader__.load({
                     }),
                     React.createElement('span', null, T_KEY(t, 'form.inspectOnFailureLabel'))
                   ),
-                  formInspectOnFailure && React.createElement('div', { className: 'dsh-cron-hint' }, T_KEY(t, 'form.inspectOnFailureHint'))
+                  formInspectOnFailure && React.createElement('div', { className: 'dsh-cron-hint' }, T_KEY(t, 'form.inspectOnFailureHint')),
+                  React.createElement('label', { className: 'dsh-cron-checkbox-row', style: { marginTop: '8px' } },
+                    React.createElement('input', {
+                      type: 'checkbox',
+                      checked: formRequireApproval,
+                      onChange: (e) => setFormRequireApproval(e.target.checked)
+                    }),
+                    React.createElement('span', null, T_KEY(t, 'form.requireApprovalLabel'))
+                  ),
+                  formRequireApproval && React.createElement('div', { className: 'dsh-cron-hint' }, T_KEY(t, 'form.requireApprovalHint'))
                 ),
                 formType === 'http' && React.createElement('div', { className: 'dsh-cron-form-row' },
                   React.createElement('div', { className: 'dsh-cron-form-group' },
@@ -3291,7 +3367,7 @@ window.__ModuleLoader__.load({
                     React.createElement('div', { className: 'dsh-cron-hint' }, T_KEY(t, 'form.silentRuleHint'))
                   )
                 ),
-                
+
                   React.createElement('div', {
                     style: {
                       marginTop: '16px',
@@ -3425,7 +3501,6 @@ window.__ModuleLoader__.load({
           )
         ),
 
-
         dryRunResult && React.createElement('div', { className: 'dsh-cron-modal-overlay', onClick: () => setDryRunResult(null) },
           React.createElement('div', {
             className: 'dsh-cron-modal',
@@ -4107,18 +4182,9 @@ window.__ModuleLoader__.load({
       return entry;
     }
 
-    /**
-     * Collapsible list of active jobs under the sidebar entry (#34).
-     *
-     * Vanilla DOM like the entry itself: the sidebar is not a React root here.
-     * Collapsed by default, state persisted, capped at a few rows with an
-     * "and N more" line so a busy schedule cannot push the rest of the sidebar
-     * off screen. Clicking a row opens the panel and highlights that task.
-     */
     const SIDEBAR_JOBS_KEY = 'dsh-cron-sidebar-open';
     const SIDEBAR_JOBS_MAX_ROWS = 5;
 
-    /** Sidebar job row: title plus next run time or the live running state. */
     function buildSidebarJobRow(state, task) {
       const row = document.createElement('button');
       row.type = 'button';
@@ -4214,7 +4280,6 @@ window.__ModuleLoader__.load({
       return root;
     }
 
-    /** Keep the section mounted under the sidebar entry across re-renders. */
     function placeSidebarJobs(state, label) {
       if (state.root !== undefined && state.root.isConnected) return;
       const entry = document.querySelector('[' + ENTRY_ATTR + ']');
@@ -4230,14 +4295,6 @@ window.__ModuleLoader__.load({
       applySidebarJobsOpen(state);
     }
 
-    /**
-     * Collapsible list of active jobs under the sidebar entry (#34).
-     *
-     * Vanilla DOM like the entry itself: the sidebar is not a React root here.
-     * Collapsed by default, state persisted, capped at a few rows with an
-     * "and N more" line so a busy schedule cannot push the rest of the sidebar
-     * off screen. Clicking a row opens the panel and highlights that task.
-     */
     function mountSidebarJobs(toggle, label, openTaskSignal) {
       if (typeof document === 'undefined') return () => {};
       const state = { toggle, openTaskSignal, root: undefined, listEl: undefined, headEl: undefined, open: false };
@@ -4377,12 +4434,6 @@ window.__ModuleLoader__.load({
       };
     }
 
-    /**
-     * Register a card into a DSH mount point. Mount points are populated via
-     * ctx.slots.inject(mount, cb) — a direct slots.register does not throw but
-     * also never appears in the target surface (settings plugins tab, header),
-     * so the inject contract is mandatory (#85).
-     */
     function registerIntoMount(ctx, mountName, entry, component) {
       if (!ctx || !ctx.slots || typeof ctx.slots.inject !== 'function') return false;
       try {

package/lib/cron-tool.js

@@ -152,6 +152,10 @@ export const cronToolParameters = {
     enum: ['default', 'read-only', 'workspace-write', 'full'],
     description: 'Permission preset applied to the task session (only used for agent session tasks: llm, skill, workflow)',
   },
+  requireApproval: {
+    type: 'boolean',
+    description: 'Require explicit human approval before execution (#318)',
+  },
   validators: {
     type: 'array',
     description: 'Declarative post-execution validation checks (json, regex, text, exitCode, file)',

package/lib/durable-journal.js

@@ -0,0 +1,188 @@
+import { createHash, randomUUID } from 'node:crypto';
+
+/**
+ * States for durable task execution lifecycle (#317)
+ */
+export const JOURNAL_STATES = {
+  QUEUED: 'queued',
+  RUNNING: 'running',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled',
+  UNCERTAIN: 'uncertain',
+};
+
+export class DurableJournal {
+  constructor(store) {
+    this.store = store;
+  }
+
+  /**
+   * Generates a deterministic idempotency key for a task run
+   */
+  generateIdempotencyKey(taskId, scheduleTick) {
+    const raw = `${taskId}:${scheduleTick || Date.now()}`;
+    return 'idem_' + createHash('sha256').update(raw).digest('hex').slice(0, 24);
+  }
+
+  /**
+   * Checks whether a run with this idempotency key was already completed
+   */
+  isIdempotencyKeyExecuted(taskId, idempotencyKey) {
+    if (!idempotencyKey) return null;
+    const history = this.store.getHistory(taskId) || [];
+    return history.find(
+      (r) => r.idempotencyKey === idempotencyKey &&
+             (r.status === JOURNAL_STATES.COMPLETED || r.status === 'success')
+    ) || null;
+  }
+
+  /**
+   * Pre-allocates a durable run entry before execution starts (#317)
+   */
+  createRunRecord(taskId, { idempotencyKey, chainRunId, trigger = 'scheduler', scheduleTick } = {}) {
+    const runId = 'run_' + randomUUID().replace(/-/g, '').slice(0, 16);
+    const key = idempotencyKey || this.generateIdempotencyKey(taskId, scheduleTick);
+
+    const record = {
+      id: runId,
+      taskId,
+      at: Date.now(),
+      status: JOURNAL_STATES.QUEUED,
+      trigger,
+      idempotencyKey: key,
+      chainRunId: chainRunId || null,
+      stages: [
+        { name: 'queue', status: 'success', startedAt: Date.now(), finishedAt: Date.now() },
+        { name: 'preflight', status: 'pending' },
+        { name: 'execution', status: 'pending' },
+        { name: 'validation', status: 'pending' },
+        { name: 'delivery', status: 'pending' },
+      ],
+      stoppedReason: null,
+      createdAt: Date.now(),
+    };
+
+    // Record initial queued entry into history/store
+    this.store.recordRun(taskId, record);
+    return record;
+  }
+
+  /**
+   * Transitions a run record to a new state and updates history entry
+   */
+  transition(taskId, runId, toState, metadata = {}) {
+    const runs = this.store.history.get(taskId) || [];
+    const index = runs.findIndex((r) => r.id === runId);
+    if (index === -1) return null;
+
+    const existing = runs[index];
+    const updated = {
+      ...existing,
+      ...metadata,
+      status: toState,
+      updatedAt: Date.now(),
+    };
+
+    if (
+      toState === JOURNAL_STATES.COMPLETED ||
+      toState === JOURNAL_STATES.FAILED ||
+      toState === JOURNAL_STATES.CANCELLED ||
+      toState === JOURNAL_STATES.UNCERTAIN
+    ) {
+      updated.finishedAt = Date.now();
+      if (updated.startedAt && !updated.durationMs) {
+        updated.durationMs = updated.finishedAt - updated.startedAt;
+      }
+    }
+
+    runs[index] = updated;
+    this.store.history.set(taskId, runs);
+    this.store.scheduleSave(50);
+    return updated;
+  }
+
+  /**
+   * Recovers uncompleted / in-flight runs on daemon restart (#317)
+   */
+  recoverPendingRuns(scheduler) {
+    const tasks = this.store.list();
+    const recovered = { uncertain: [], requeued: [] };
+
+    for (const task of tasks) {
+      const history = this.store.history.get(task.id) || [];
+      let historyChanged = false;
+
+      for (let i = 0; i < history.length; i++) {
+        const run = history[i];
+        if (run.status === JOURNAL_STATES.RUNNING) {
+          // Crash during execution -> transition to UNCERTAIN to prevent blind rerun
+          history[i] = {
+            ...run,
+            status: JOURNAL_STATES.UNCERTAIN,
+            stoppedReason: 'interrupted_by_restart',
+            uncertainAt: Date.now(),
+          };
+          historyChanged = true;
+          recovered.uncertain.push({ taskId: task.id, runId: run.id });
+        } else if (run.status === JOURNAL_STATES.QUEUED) {
+          // Queued run that didn't start yet: if task is still active and recent (<1 hour), re-enqueue
+          const ageMs = Date.now() - (run.createdAt || run.at);
+          if (task.status === 'active' && ageMs < 3600000 && scheduler && typeof scheduler.runTask === 'function') {
+            scheduler.queue = scheduler.queue || [];
+            if (!scheduler.queue.includes(task.id)) {
+              scheduler.queue.push(task.id);
+              recovered.requeued.push({ taskId: task.id, runId: run.id });
+            }
+          } else {
+            // Expired or cancelled queued run
+            history[i] = {
+              ...run,
+              status: JOURNAL_STATES.CANCELLED,
+              stoppedReason: 'Queued run expired or cancelled across restart',
+            };
+            historyChanged = true;
+          }
+        }
+      }
+
+      if (historyChanged) {
+        this.store.scheduleSave(50);
+      }
+    }
+
+    return recovered;
+  }
+
+  /**
+   * Manually resolves an uncertain run record (#317)
+   */
+  resolveUncertain(taskId, runId, { decision, note, resolvedBy = 'user' } = {}) {
+    const runs = this.store.history.get(taskId) || [];
+    const index = runs.findIndex((r) => r.id === runId);
+    if (index === -1) return { ok: false, error: 'Run not found' };
+
+    const run = runs[index];
+    if (run.status !== JOURNAL_STATES.UNCERTAIN) {
+      return { ok: false, error: `Run is in status "${run.status}", not uncertain` };
+    }
+
+    let nextStatus = JOURNAL_STATES.FAILED;
+    if (decision === 'completed' || decision === 'mark_completed') nextStatus = JOURNAL_STATES.COMPLETED;
+    else if (decision === 'failed' || decision === 'mark_failed') nextStatus = JOURNAL_STATES.FAILED;
+    else if (decision === 'cancel' || decision === 'cancelled') nextStatus = JOURNAL_STATES.CANCELLED;
+
+    const resolved = {
+      ...run,
+      status: nextStatus,
+      stoppedReason: `Uncertain run resolved by ${resolvedBy}: ${note || decision}`,
+      resolvedBy,
+      resolvedAt: Date.now(),
+    };
+
+    runs[index] = resolved;
+    this.store.history.set(taskId, runs);
+    this.store.scheduleSave(50);
+    return { ok: true, run: resolved };
+  }
+}