@aion0/forge 0.6.1 → 0.8.0

package/lib/help-docs/19-jobs.md

@@ -0,0 +1,140 @@
+# Jobs
+
+A **Job** runs a connector tool on a schedule, dedups items, and dispatches
+each new item to a Pipeline or a Chat session.
+
+Typical examples:
+- Every 30 min, search Mantis for open bugs in version 25.4 → for each new
+  bug, trigger the `bug-triage` pipeline bound to project `my-app`.
+- Every 5 min, list Teams messages in the current chat → for each new
+  message, POST to a chat session that drafts a reply.
+
+Job is a separate primitive from Task and Pipeline. The CLI keeps
+`forge task` (single agent invocation) and `forge pipeline` (DAG of tasks)
+unchanged. `forge jobs` is new.
+
+## Anatomy
+
+| Field | Purpose |
+|---|---|
+| `source_connector`, `source_tool` | Which connector + tool to call each tick (e.g. `mantis.search_bugs`) |
+| `source_input` | JSON passed verbatim to the tool |
+| `items_path` | Dotted path into the tool's response to find the item array (`bugs`, empty = whole response if already an array) |
+| `dedup_field` | Field on each item used as the dedup key (e.g. `id`) |
+| `schedule_interval_minutes` | How often the scheduler ticks this job |
+| `dispatch_type` | `pipeline` or `chat` |
+| `dispatch_params` | Shape depends on dispatch_type — see below |
+
+### `dispatch_type: pipeline`
+
+```json
+{
+  "workflow_name": "bug-triage",
+  "project_path": "/Users/me/code/my-app",
+  "project_name": "my-app",
+  "input_template": {
+    "bug_id": "{{item.id}}",
+    "summary": "{{item.summary}}"
+  }
+}
+```
+
+Per new item, Forge renders `input_template` and calls the existing
+`triggerPipeline`. The pipeline shows up in the regular Pipelines view.
+
+### `dispatch_type: chat`
+
+```json
+{
+  "agent_profile": "my-litellm",
+  "session_title_template": "Bug {{item.id}}: {{item.summary}}",
+  "message_template": "Triage bug {{item.id}}.\nSummary: {{item.summary}}",
+  "reuse_session": false
+}
+```
+
+Per new item, Forge creates (or reuses, if `reuse_session: true`) a chat
+session and POSTs a message rendered from `message_template`. The chat
+agent gets the message and decides what tools to call.
+
+## Template syntax
+
+Only `{{item.<dotted.path>}}` is supported in v1. Missing paths render to
+empty string; objects render via `JSON.stringify`. `{{item}}` alone dumps
+the full item.
+
+## Backfill guard
+
+New jobs default to `mark_existing_as_seen: true` — on first tick, every
+item the connector returns is added to `job_seen` but **no dispatch
+happens**. This stops a fresh job from firing on historical data. Set to
+`false` at create time to dispatch immediately on first tick.
+
+## CLI
+
+```
+forge jobs                              # list
+forge jobs show <id>                    # full JSON detail
+forge jobs runs <id>                    # recent ticks (summary line per run)
+forge jobs dispatches <id> <run_id>     # per-item dispatches for one run (target ids)
+forge jobs run <id>                     # fire now (manual trigger)
+forge jobs enable <id>
+forge jobs disable <id>
+forge jobs reset <id>                   # wipe dedup state — next tick re-processes everything
+forge jobs rm <id>
+```
+
+## Tracking results
+
+| Want to know | Where |
+|---|---|
+| Job list, schedule, enabled, last/next run | Extension → Jobs tab |
+| Last 10 ticks summary (seen/new/dispatched, error) | Expand a job in Jobs tab |
+| Which items got dispatched in a single tick | Expand a run row — shows item_key + preview + target id + open-link |
+| What the resulting pipeline run did | Click "open →" on a pipeline dispatch — deep-links to Forge web Pipelines view |
+| What the resulting chat session said | Click "open →" on a chat dispatch — switches the side panel to chat tab and loads that session |
+| Run / dispatch detail from terminal | `forge jobs runs <id>` then `forge jobs dispatches <id> <run_id>` |
+| Raw rows | sqlite: `select * from job_runs / job_dispatches` |
+| Server-side log lines (every tick / error / dispatch) | Forge web → Logs view, search `[jobs]` (per-job: `[jobs] <job_id>`). The Jobs view has "View logs" buttons that pre-fill this filter. CLI: `tail -f ~/.forge/data/forge.log \| grep '\[jobs\]'`. |
+| Why a run shows 0 dispatches | Read the italic note under the run row — the scheduler writes a `notes` field explaining backfill / non-JSON response / items_path mismatch. |
+
+Create + edit happen via the Forge extension Jobs tab, or by `curl`ing
+`POST /api/jobs`. There is no YAML-on-disk format for Jobs (definitions
+live in sqlite).
+
+## Lifecycle
+
+1. Scheduler ticks every 60s. For each enabled job where `next_run_at`
+   has elapsed:
+2. Skip if a previous tick is still running (idempotent).
+3. Advance `next_run_at = now + schedule_interval_minutes`.
+4. Spawn a background tick:
+   - Call the connector via the chat tool-dispatcher (handles
+     `http` / `shell` / `browser` protocols uniformly).
+   - Parse the response — find items via `items_path`.
+   - For each item, compute `dedup_key = item[dedup_field]`,
+     `INSERT OR IGNORE INTO job_seen`. If new: dispatch.
+   - Update the `job_runs` row with counts + status.
+
+## Browser-protocol caveat
+
+If `source_connector` is a `protocol: browser` connector (Mantis, GitLab,
+Teams, PMDB), the job tick can only fire **when the extension bridge is
+connected** — the tool needs a live tab and `chrome.scripting`. A tick
+with no extension fails with `connector ... failed: No extension
+connected to the bridge`. The run is marked errored; the next tick
+retries.
+
+For 24/7 background polling, prefer connectors with `protocol: http`
+(e.g. `github-api`) — those run server-side and don't need a browser.
+
+## Tables
+
+```
+jobs                — definition (one row per job)
+job_runs            — one row per tick (success / failure)
+job_seen            — dedup keys per job (PRIMARY KEY (job_id, dedup_key))
+job_dispatches      — one row per per-item dispatch attempt (link to pipeline run / chat session)
+```
+
+All cascaded on `ON DELETE`.

package/lib/help-docs/20-mantis-bug-fix.md

@@ -0,0 +1,115 @@
+# Mantis → Bug Fix → MR pipeline
+
+End-to-end: a Mantis bug surfaces (via a Forge **Job** polling mantis.get_bug
+/ mantis.search_bugs) → triggers a Pipeline → Pipeline checks out the right
+base branch in a worktree → headless Claude implements the fix → pipeline
+opens a GitLab MR via `glab` → pipeline pings the assignee + reporter on
+Teams with the MR URL.
+
+Mirrors the `gitlab-issue-fix-and-review` builtin but driven by Mantis
+content (description / priority / category / assignee / reporter), MR
+opens against an explicit `base_branch` you pass in from the Job (because
+Mantis doesn't carry milestones the way GitLab issues do).
+
+## Builtin name
+
+`mantis-bug-fix-and-mr` — registered in Forge's built-in workflow set,
+visible in the Pipelines view's workflow dropdown and pickable from the
+extension Jobs tab when you wire a Pipeline-dispatch Job.
+
+## Inputs (set by the Job's `input_template`)
+
+| Key | Required | Source |
+|---|---|---|
+| `bug_id` | yes | `{{item.id}}` |
+| `project` | yes | injected by `triggerPipeline` from the Job's project setting |
+| `base_branch` | **yes** | `{{item.product_version}}` mapped to a branch, OR a literal like `"release/25.4"` you write into the template |
+| `summary` | yes | `{{item.summary}}` |
+| `description` | yes | `{{item.description}}` |
+| `priority` | opt | `{{item.priority}}` |
+| `category` | opt | `{{item.category}}` |
+| `assignee` | opt | `{{item.assignee}}` — used as Teams chat name |
+| `reporter` | opt | `{{item.reporter}}` — used as Teams chat name |
+| `extra_context` | opt | literal hint text for Claude |
+| `mr_title_template` | opt | default `Fix Mantis #{bug_id}: {summary}` |
+| `mr_body_template` | opt | default closes-ref + Claude summary; vars `{bug_id} {summary} {description} {claude_summary}` |
+| `teams_message_template` | opt | default `🤖 Mantis #{bug_id} fixed — please review MR: {mr_url}\nBug: {summary}`; vars `{bug_id} {summary} {role} {mr_url}` |
+
+## Nodes
+
+```
+resolve              parse git remote → HOST + PROJECT_PATH; check glab; require base_branch
+worktree-setup       git worktree add -b fix/mantis-<id> .forge/worktrees/mantis-<id> origin/<base>
+fix-code             headless Claude — reads bug context, edits in worktree, commits
+push-and-mr          if any commits: push fix/mantis-<id>, glab mr create → MR_URL
+notify-teams         curl /api/connector-tool teams.send_message twice (assignee + reporter)
+```
+
+`fix-code` runs as a normal Claude task (not shell) so it can think, browse,
+edit, and commit. `notify-teams` short-circuits if `push-and-mr` couldn't
+create an MR (e.g. Claude made no changes).
+
+## Talking to connectors from a pipeline
+
+`notify-teams` calls `POST http://127.0.0.1:8403/api/connector-tool` —
+a loopback-only endpoint that wraps `lib/chat/tool-dispatcher`. Body:
+
+```json
+{ "plugin_id": "teams", "tool": "send_message",
+  "input": { "name": "Alice", "text": "MR: https://..." } }
+```
+
+Returns the standard `{ content, is_error }` tool-result shape. Works for
+`browser` / `http` / `shell` protocol connectors. Browser-protocol calls
+need the extension bridge connected at pipeline runtime (Chrome open +
+extension signed in).
+
+## Wiring it up from a Job
+
+1. Confirm `glab` is installed + authed for the target host:
+   `glab auth login --hostname <your-gitlab.example.com>`
+2. Make sure the project has a git remote (`git remote get-url origin`) the
+   `glab mr create` call can reach.
+3. Forge extension → Jobs → + New job. Pick:
+   - Connector / tool: `mantis` / `get_bug` (single bug) or `search_bugs` (a query)
+   - dispatch: Pipeline → workflow `mantis-bug-fix-and-mr` → your project
+   - `input_template` (auto-prefilled when you pick the workflow; map item
+     keys to inputs, hardcode `base_branch` if Mantis doesn't carry it):
+     ```json
+     {
+       "bug_id":      "{{item.id}}",
+       "summary":     "{{item.summary}}",
+       "description": "{{item.description}}",
+       "priority":    "{{item.priority}}",
+       "category":    "{{item.category}}",
+       "assignee":    "{{item.assignee}}",
+       "reporter":    "{{item.reporter}}",
+       "base_branch": "release/25.4"
+     }
+     ```
+4. Save → Run now (first tick is a backfill-no-op; click Reset dedup +
+   Run now to force one actual dispatch for testing).
+
+## Customising
+
+- Branch derivation rules (e.g. `target_version` → `release/<major.minor>`):
+  edit the `resolve` node in your local copy at
+  `~/.forge/data/flows/mantis-bug-fix-and-mr.yaml` (a copy will be created
+  when you click Edit in the Pipelines view; once a local file exists it
+  overrides the builtin).
+- MR title / body templates: set via the Job's `input_template` — no
+  pipeline edit needed.
+- Teams routing: today it uses the Mantis username verbatim as the Teams
+  chat name (substring match). For better mapping, post-process in
+  `notify-teams` to convert username → real name via a lookup table or
+  a second connector call.
+
+## Troubleshooting
+
+| Symptom | Cause + fix |
+|---|---|
+| `ERROR: base_branch is required` | The Job's `input_template` didn't supply it — Mantis bugs don't always carry one. Hardcode it in the template or map from `product_version`. |
+| `NO_CHANGES — Claude did not commit` | Bug description was too thin or Claude couldn't find the affected code. Add hints via `extra_context` or open the worktree manually and iterate. |
+| `glab mr create` returns nothing | Token expired / target branch protected / source branch already has an open MR. The pipeline falls back to `glab mr view` to surface the existing URL — check Pipelines log. |
+| Teams send returns `No extension connected to the bridge` | The pipeline ran when Chrome / extension weren't online. Notification fails but the MR still landed; re-fire the `notify-teams` node manually or message the people yourself. |
+| Mantis username doesn't match any Teams chat | The fuzzy substring match in `teams.send_message` falls back to whatever the LLM-less DOM script can match. Add a lookup step before `notify-teams` to translate names. |

package/lib/help-docs/CLAUDE.md

@@ -45,6 +45,11 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 | `12-usage.md` | Token usage analytics — charts, heatmap, cost estimation, by model/project/source |
 | `13-ide-plugins.md` | VSCode extension + IntelliJ plugin — install, tabs, multi-connection, agent terminal launching |
 | `15-crafts.md` | Crafts — project-scoped mini-app tabs with SDK; AI-generated via "+ Craft" button |
+| `16-gitlab-autofix.md` | GitLab issue auto-fix — worktree + base-branch rule + Premium epic context + image attachments |
+| `17-connectors.md` | Browser extension connectors — plugin schema, HTTP API, settings sync, Mantis + GitLab built-ins |
+| `18-chrome-mcp.md` | Connect Forge Claude Code sessions to a real Chrome via chrome-devtools-mcp — dev-time browser access for connector authoring |
+| `19-jobs.md` | Jobs — scheduled connector polls that dedup and fan out to Pipeline / Chat |
+| `20-mantis-bug-fix.md` | Mantis → Bug Fix → MR builtin pipeline (mantis-bug-fix-and-mr) |
 
 ## Matching questions to docs
 
@@ -69,3 +74,8 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 - VSCode/IntelliJ/IDE plugin/extension/marketplace → `13-ide-plugins.md`
 - vsce/vsix/JetBrains marketplace publish → `13-ide-plugins.md`
 - Craft/custom tab/mini-app/extend project/AI-generated tab/builder → `15-crafts.md`
+- GitLab/glab/MR/merge request/issue auto-fix/epic → `16-gitlab-autofix.md`
+- Connector/browser extension/plugin schema/Mantis/category=connector → `17-connectors.md`
+- Chrome MCP / chrome-devtools-mcp / dev-time browser / CDP / remote debugging → `18-chrome-mcp.md`
+- Job / scheduled job / connector poll / dedup / periodic fetch / Teams poll / Mantis bug poll → `19-jobs.md`
+- Mantis bug fix pipeline / mantis-bug-fix-and-mr / open MR for Mantis bug / notify Teams from pipeline / connector-tool endpoint → `20-mantis-bug-fix.md`

package/lib/init.ts

@@ -71,47 +71,60 @@ export function ensureInitialized() {
   if (gInit[initKey]) return;
   gInit[initKey] = true;
 
-  // Add timestamps to all console output
-  try { const { initLogger } = require('./logger'); initLogger(); } catch {}
-
-  // Migrate old data layout (~/.forge/* → ~/.forge/data/*) on first run
-  try { const { migrateDataDir } = require('./dirs'); migrateDataDir(); } catch {}
-
-  // Migrate plaintext secrets on startup
-  migrateSecrets();
-
-  // Cleanup old notifications
-  try {
-    const { cleanupNotifications } = require('./notifications');
-    cleanupNotifications();
-  } catch {}
-
-  // Auto-detect claude path if not configured
-  autoDetectAgents();
-
-  // Install/update forge skills to ~/.claude/skills/ on every startup
-  try {
-    const { installForgeSkills } = require('./workspace/skill-installer');
-    installForgeSkills('', '', '', Number(process.env.PORT) || 8403);
-    console.log('[init] Forge skills installed/updated');
-  } catch {}
+  // Per-step timing — earlier startup hangs were invisible because all
+  // these steps log heterogeneously (or not at all). \`time(label, fn)\`
+  // prints \`[init] <label> took 1234ms\` for anything taking >250ms so
+  // we can spot the slow one without instrumenting elsewhere.
+  const time = <T>(label: string, fn: () => T): T => {
+    const t = Date.now();
+    try { return fn(); }
+    finally {
+      const ms = Date.now() - t;
+      if (ms >= 250) console.log(`[init] ${label} took ${ms}ms`);
+    }
+  };
+
+  time('logger', () => { try { const { initLogger } = require('./logger'); initLogger(); } catch {} });
+  time('migrateDataDir', () => { try { const { migrateDataDir } = require('./dirs'); migrateDataDir(); } catch {} });
+  time('migrateSecrets', migrateSecrets);
+  time('migratePluginSecrets', () => {
+    try {
+      const { migratePluginSecrets } = require('./plugins/registry');
+      migratePluginSecrets();
+    } catch (e) { console.warn('[init] migratePluginSecrets failed:', (e as Error).message); }
+  });
+  time('cleanupNotifications', () => { try { const { cleanupNotifications } = require('./notifications'); cleanupNotifications(); } catch {} });
+  time('autoDetectAgents', autoDetectAgents);
+  time('logToolStatus', () => {
+    try { const { logToolStatus } = require('./health'); logToolStatus(); }
+    catch (e) { console.warn('[tools] health check failed:', (e as Error).message); }
+  });
+  time('installForgeSkills', () => {
+    try {
+      const { installForgeSkills } = require('./workspace/skill-installer');
+      installForgeSkills('', '', '', Number(process.env.PORT) || 8403);
+      console.log('[init] Forge skills installed/updated');
+    } catch {}
+  });
 
   // Sync help docs + CLAUDE.md to data dir on startup
-  try {
-    const { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } = require('node:fs');
-    const { join: joinPath } = require('node:path');
-    const { getConfigDir, getDataDir } = require('./dirs');
-    const helpDir = joinPath(getConfigDir(), 'help');
-    const sourceDir = joinPath(process.cwd(), 'lib', 'help-docs');
-    if (existsSync(sourceDir)) {
-      if (!existsSync(helpDir)) mkdirSync(helpDir, { recursive: true });
-      for (const f of readdirSync(sourceDir)) {
-        if (f.endsWith('.md')) writeFileSync(joinPath(helpDir, f), readFileSync(joinPath(sourceDir, f)));
+  time('syncHelpDocs', () => {
+    try {
+      const { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } = require('node:fs');
+      const { join: joinPath } = require('node:path');
+      const { getConfigDir, getDataDir } = require('./dirs');
+      const helpDir = joinPath(getConfigDir(), 'help');
+      const sourceDir = joinPath(process.cwd(), 'lib', 'help-docs');
+      if (existsSync(sourceDir)) {
+        if (!existsSync(helpDir)) mkdirSync(helpDir, { recursive: true });
+        for (const f of readdirSync(sourceDir)) {
+          if (f.endsWith('.md')) writeFileSync(joinPath(helpDir, f), readFileSync(joinPath(sourceDir, f)));
+        }
+        const claudeMd = joinPath(helpDir, 'CLAUDE.md');
+        if (existsSync(claudeMd)) writeFileSync(joinPath(getDataDir(), 'CLAUDE.md'), readFileSync(claudeMd));
       }
-      const claudeMd = joinPath(helpDir, 'CLAUDE.md');
-      if (existsSync(claudeMd)) writeFileSync(joinPath(getDataDir(), 'CLAUDE.md'), readFileSync(claudeMd));
-    }
-  } catch {}
+    } catch {}
+  });
 
   // Sync skills registry (async, non-blocking) — on startup + every 30 min
   try {
@@ -120,24 +133,44 @@ export function ensureInitialized() {
     setInterval(() => { syncSkills().catch(() => {}); }, 60 * 60 * 1000);
   } catch {}
 
-  // Usage scanner — scan JSONL files for token usage on startup + every hour
-  try {
-    const { scanUsage } = require('./usage-scanner');
-    scanUsage();
-    setInterval(() => { try { scanUsage(); } catch {} }, 60 * 60 * 1000);
-  } catch {}
+  // Usage scanner — defer to next tick so it doesn't block ensureInitialized().
+  // On a host with hundreds of project dirs in ~/.claude/projects/, the
+  // synchronous readdirSync + statSync loop can take 5-10s; running it on
+  // the critical path of the first API request made startup feel hung.
+  // setImmediate keeps it in the same process but yields the event loop first.
+  setImmediate(() => {
+    time('scanUsage (initial)', () => {
+      try { const { scanUsage } = require('./usage-scanner'); scanUsage(); } catch {}
+    });
+  });
+  time('require usage-scanner + hourly', () => {
+    try {
+      const { scanUsage } = require('./usage-scanner');
+      setInterval(() => { try { scanUsage(); } catch {} }, 60 * 60 * 1000);
+    } catch {}
+  });
 
   // Task runner is safe in every worker (DB-level coordination)
-  ensureRunnerStarted();
+  time('ensureRunnerStarted', ensureRunnerStarted);
 
   // Session watcher is safe (file-based, idempotent)
-  startWatcherLoop();
+  time('startWatcherLoop', startWatcherLoop);
 
   // Pipeline scheduler — periodic execution + issue scanning for project-bound workflows
-  try {
-    const { startScheduler } = require('./pipeline-scheduler');
-    startScheduler();
-  } catch {}
+  time('pipeline-scheduler', () => {
+    try {
+      const { startScheduler } = require('./pipeline-scheduler');
+      startScheduler();
+    } catch {}
+  });
+
+  // Jobs scheduler — periodic connector polls that fan out to pipelines / chat
+  time('jobs-scheduler', () => {
+    try {
+      const { startScheduler: startJobsScheduler } = require('./jobs/scheduler');
+      startJobsScheduler();
+    } catch (e) { console.error('[jobs-scheduler] start failed', e); }
+  });
 
   // If services are managed externally (forge-server), skip
   if (process.env.FORGE_EXTERNAL_SERVICES === '1') {
@@ -163,6 +196,8 @@ export function ensureInitialized() {
   startTerminalProcess();
   startTelegramProcess(); // spawns telegram-standalone
   startWorkspaceProcess(); // spawns workspace-standalone
+  startBrowserBridgeProcess(); // spawns browser-bridge-standalone
+  startChatProcess(); // spawns chat-standalone
 
   const settings = loadSettings();
   if (settings.tunnelAutoStart) {
@@ -264,3 +299,55 @@ function launchWorkspaceDaemon() {
   workspaceChild.on('exit', () => { workspaceChild = null; });
   console.log('[workspace] Started daemon (pid:', workspaceChild.pid, ')');
 }
+
+let chatChild: ReturnType<typeof spawn> | null = null;
+
+function startChatProcess() {
+  if (chatChild) return;
+
+  const chatPort = Number(process.env.CHAT_PORT) || 8408;
+
+  const net = require('node:net');
+  const tester = net.createServer();
+  tester.once('error', () => {
+    console.log(`[chat] Port ${chatPort} already in use, reusing existing`);
+  });
+  tester.once('listening', () => {
+    tester.close();
+    const script = join(process.cwd(), 'lib', 'chat-standalone.ts');
+    chatChild = spawn('npx', ['tsx', script], {
+      stdio: ['ignore', 'inherit', 'inherit'],
+      env: { ...process.env },
+      detached: false,
+    });
+    chatChild.on('exit', () => { chatChild = null; });
+    console.log('[chat] Started standalone (pid:', chatChild.pid, ')');
+  });
+  tester.listen(chatPort);
+}
+
+let bridgeChild: ReturnType<typeof spawn> | null = null;
+
+function startBrowserBridgeProcess() {
+  if (bridgeChild) return;
+
+  const bridgePort = Number(process.env.BRIDGE_PORT) || 8407;
+
+  const net = require('node:net');
+  const tester = net.createServer();
+  tester.once('error', () => {
+    console.log(`[bridge] Port ${bridgePort} already in use, reusing existing`);
+  });
+  tester.once('listening', () => {
+    tester.close();
+    const script = join(process.cwd(), 'lib', 'browser-bridge-standalone.ts');
+    bridgeChild = spawn('npx', ['tsx', script], {
+      stdio: ['ignore', 'inherit', 'inherit'],
+      env: { ...process.env },
+      detached: false,
+    });
+    bridgeChild.on('exit', () => { bridgeChild = null; });
+    console.log('[bridge] Started standalone (pid:', bridgeChild.pid, ')');
+  });
+  tester.listen(bridgePort);
+}

package/lib/iso-time.ts

@@ -0,0 +1,30 @@
+/**
+ * SQLite-friendly timestamp normalization.
+ *
+ * SQLite's `datetime('now')` returns "2026-05-19 18:30:00" — UTC, but no
+ * timezone marker. When that string lands in JavaScript:
+ *   new Date('2026-05-19 18:30:00')   // parsed as LOCAL time (wrong)
+ *
+ * Browsers shift the displayed value by the user's offset — a UTC 18:30
+ * looks like 18:30 in their local clock if treated as local, hours off
+ * from the real moment. Frontend Date.toLocaleString() then renders the
+ * wrong number.
+ *
+ * Append a 'Z' so JS treats it as UTC, and Date.toLocaleString() will
+ * automatically convert to the user's local timezone.
+ *
+ * Idempotent: if the string already has a 'Z' or a numeric offset, or
+ * is already in ISO 8601 (T separator), it's returned unchanged.
+ */
+export function toIsoUTC(s: string | null | undefined): string | null {
+  if (!s) return null;
+  // Already ISO with T separator → just ensure it has a TZ marker.
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(s)) {
+    return /Z$|[+-]\d{2}:?\d{2}$/.test(s) ? s : s + 'Z';
+  }
+  // SQLite datetime('now') shape: "YYYY-MM-DD HH:MM:SS"
+  if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(\.\d+)?$/.test(s)) {
+    return s.replace(' ', 'T') + 'Z';
+  }
+  return s;
+}