wood-fired-tasks 2.2.0 → 2.3.0

package/dist/slack/mrkdwn.js

@@ -0,0 +1,26 @@
+/**
+ * Slack mrkdwn escaping primitive.
+ *
+ * Slack's mrkdwn parser treats `<...>` as control sequences: `<!channel>` /
+ * `<!here>` broadcast pings, `<@U123>` user mentions, and `<https://x|label>`
+ * spoofable links. User-controlled text (task/project/comment fields) flowing
+ * into a `mrkdwn` (or even a `plain_text`) block must be escaped so it renders
+ * as literal characters instead of injecting pings or fake links.
+ *
+ * Per Slack's spec only three characters need escaping, and ORDER MATTERS:
+ * `&` first so the `&amp;` we emit for `<`/`>` isn't itself re-escaped, then
+ * `<` → `&lt;`, then `>` → `&gt;`. Mirrors `escapeHtml` in `src/web/html.ts`.
+ *
+ * null / undefined collapse to '' so optional fields render cleanly without
+ * forcing every call site to defend against missing data.
+ */
+const AMP = /&/g;
+const LT = /</g;
+const GT = />/g;
+export function escapeSlackMrkdwn(value) {
+    if (value === null || value === undefined)
+        return '';
+    const s = typeof value === 'string' ? value : String(value);
+    return s.replace(AMP, '&amp;').replace(LT, '&lt;').replace(GT, '&gt;');
+}
+//# sourceMappingURL=mrkdwn.js.map

package/dist/slack/task-formatter.js

@@ -1,3 +1,4 @@
+import { escapeSlackMrkdwn } from './mrkdwn.js';
 // ---------------------------------------------------------------------------
 // Lookup maps — exported so project-formatter.ts can reuse them (Plan 02)
 // ---------------------------------------------------------------------------
@@ -54,12 +55,12 @@ export function formatTaskList(tasks) {
     for (const task of displayTasks) {
         const emoji = STATUS_EMOJI[task.status] ?? '❓';
         const priority = PRIORITY_INDICATOR[task.priority] ?? task.priority;
-        const assignee = task.assignee ? `@${task.assignee}` : '_unassigned_';
+        const assignee = task.assignee ? `@${escapeSlackMrkdwn(task.assignee)}` : '_unassigned_';
         const section = {
             type: 'section',
             text: {
                 type: 'mrkdwn',
-                text: `${emoji} *#${task.id} ${task.title}*\n${priority} · ${assignee}`,
+                text: `${emoji} *#${task.id} ${escapeSlackMrkdwn(task.title)}*\n${priority} · ${assignee}`,
             },
         };
         blocks.push(section);
@@ -91,20 +92,20 @@ export function formatTaskDetail(task) {
     const title = rawTitle.length > 150 ? rawTitle.slice(0, 147) + '...' : rawTitle;
     const header = {
         type: 'header',
-        text: { type: 'plain_text', text: title, emoji: true },
+        text: { type: 'plain_text', text: escapeSlackMrkdwn(title), emoji: true },
     };
     blocks.push(header);
     // Fields section — 2-column key/value pairs (max 10 items in Slack API)
     const fields = [
         { type: 'mrkdwn', text: `*Status*\n${STATUS_EMOJI[task.status] ?? '❓'} ${task.status}` },
         { type: 'mrkdwn', text: `*Priority*\n${PRIORITY_INDICATOR[task.priority] ?? task.priority}` },
-        { type: 'mrkdwn', text: `*Assignee*\n${task.assignee ?? '_unassigned_'}` },
-        { type: 'mrkdwn', text: `*Due Date*\n${task.due_date ?? '_none_'}` },
+        { type: 'mrkdwn', text: `*Assignee*\n${escapeSlackMrkdwn(task.assignee) || '_unassigned_'}` },
+        { type: 'mrkdwn', text: `*Due Date*\n${escapeSlackMrkdwn(task.due_date) || '_none_'}` },
         { type: 'mrkdwn', text: `*Project*\n#${task.project_id}` },
-        { type: 'mrkdwn', text: `*Created by*\n${task.created_by}` },
+        { type: 'mrkdwn', text: `*Created by*\n${escapeSlackMrkdwn(task.created_by)}` },
     ];
     if (task.tags.length > 0) {
-        fields.push({ type: 'mrkdwn', text: `*Tags*\n${task.tags.join(', ')}` });
+        fields.push({ type: 'mrkdwn', text: `*Tags*\n${escapeSlackMrkdwn(task.tags.join(', '))}` });
     }
     const fieldsSection = { type: 'section', fields };
     blocks.push(fieldsSection);
@@ -114,7 +115,7 @@ export function formatTaskDetail(task) {
         blocks.push(divider);
         const descSection = {
             type: 'section',
-            text: { type: 'mrkdwn', text: task.description.slice(0, 3000) },
+            text: { type: 'mrkdwn', text: escapeSlackMrkdwn(task.description.slice(0, 3000)) },
         };
         blocks.push(descSection);
     }
@@ -134,12 +135,12 @@ export function formatTaskNotification(event, projectName) {
     const emoji = STATUS_EMOJI[task.status] ?? '❓';
     const actor = metadata.actor ?? 'system';
     const label = EVENT_LABELS[eventType] ?? eventType;
-    const assignee = task.assignee ? `@${task.assignee}` : '_unassigned_';
+    const assignee = task.assignee ? `@${escapeSlackMrkdwn(task.assignee)}` : '_unassigned_';
     const priority = PRIORITY_INDICATOR[task.priority] ?? task.priority;
     const text = [
         `*${label}* by ${actor}`,
-        `${emoji} *#${task.id} ${task.title}*`,
-        ...(projectName ? [`_${projectName}_`] : []),
+        `${emoji} *#${task.id} ${escapeSlackMrkdwn(task.title)}*`,
+        ...(projectName ? [`_${escapeSlackMrkdwn(projectName)}_`] : []),
         `${priority} · ${assignee}`,
         `\`/tasks show ${task.id}\``,
     ].join('\n');

package/docs/INTERFACES.md

@@ -320,7 +320,14 @@ filters. MCP list tools wrap the same envelope under a domain key
 
 Global rate limit (`@fastify/rate-limit`) applies to every REST route except
 `/health*`; defaults are 1000 req/min, tunable via `RATE_LIMIT_MAX` and
-`RATE_LIMIT_TIME_WINDOW`. Response shape on breach:
+`RATE_LIMIT_TIME_WINDOW`. Sensitive auth/device routes (`/auth/login`,
+`/auth/callback`, `/auth/device/code`, `/auth/device/verify`,
+`/auth/device/token`) carry tighter per-route budgets (`RATE_LIMIT_AUTH_MAX`,
+default 10; `RATE_LIMIT_DEVICE_TOKEN_MAX`, default 30). Client identity is
+keyed on the authenticated principal when present, else `request.ip`; behind a
+reverse proxy set `TRUST_PROXY` (default off) so `request.ip` derives from
+`X-Forwarded-For` — with it off, a spoofed forwarded header cannot change a
+client's bucket. Response shape on breach:
 `{ error: 'TOO_MANY_REQUESTS', message }` with HTTP 429.
 
 ## Error handling cheatsheet

package/docs/SETUP.md

@@ -391,46 +391,47 @@ visiting `/auth/login`; otherwise the session cookie is dropped and login
 silently loops back to the login page. In `development`/`test` the cookie
 is non-`secure`, so plain `http://localhost` works.
 
+### 3a. Device-flow verification origin & trust boundary
+
+The RFC 8628 **device flow** returns a `verification_uri` derived **per-request**
+from the address the client connected to (`Host` / `X-Forwarded-{Host,Proto}`;
+see `resolveVerificationOrigin`) so a LAN/remote client gets a routable URL not
+`localhost`. It is **not** host-header injection — the URI is returned only to
+the requesting client, so a spoofed `Host` only misdirects the spoofer; the
+server trusts its front-proxy to set `X-Forwarded-*` honestly (the same trust
+`TRUST_PROXY` extends to rate-limit client identity). To pin the boundary, set
+`DEVICE_FLOW_TRUSTED_HOSTS` (comma-separated hostname allowlist): a `Host` not on
+it falls back to the `OIDC_REDIRECT_URI` origin; unset = all.
+
 ### 4. (Optional) `LEGACY_AUTH_SUNSET_DATE`
 
-[NOTE] The legacy `X-API-Key` auth path has been **removed** — the server now
-rejects that header with 401, so the `Deprecation`/`Sunset` headers it used to
-stamp no longer apply. The `LEGACY_AUTH_SUNSET_DATE` env var is still parsed for
-backward compatibility but has no runtime effect; new deployments can omit it.
-
-```bash
-# Still accepted (YYYY-MM-DD) but inert — retained for backward compatibility.
-LEGACY_AUTH_SUNSET_DATE=2026-12-31
-```
+[NOTE] The legacy `X-API-Key` auth path has been **removed** (rejected with 401),
+so this var is now inert — still parsed (`YYYY-MM-DD`) for backward
+compatibility but with no runtime effect. New deployments can omit it.
 
 ### 5. Verify the OIDC flow
 
 1. Restart the server (`npm run dev` locally).
 2. In a browser, visit `http://localhost:3000/auth/login`.
-3. You should be redirected to Google, complete consent, and land on
-   `/me`. The `/me` page shows your email, display name, and a list of
-   your PATs.
-4. From `/me` you can mint a new PAT (the value is shown **once**, copy
-   it then) or revoke an existing one.
+3. Complete Google consent and land on `/me` (shows your email, display
+   name, and PATs).
+4. From `/me` mint a new PAT (value shown **once**, copy it then) or revoke one.
 
 ### 6. Bootstrap a PAT without a browser (servers, CI, headless agents)
 
-For deployments where no browser is available, mint the first PAT
-directly against the SQLite database:
+For deployments where no browser is available, mint the first PAT directly
+against the SQLite database (`--user` = numeric id, email, or legacy
+display_name; `--name` = required label):
 
 ```bash
-# Adds a row to api_tokens for the named user.
-# --user accepts a numeric id, email (case-insensitive), or legacy display_name.
-# --name is a required human-readable label for the token.
 node dist/cli/bin/tasks.js db mint-token --user you@example.com --name my-laptop
 ```
 
 The command prints the raw PAT to stdout once. Use it as the
-`Authorization: Bearer wft_pat_<…>` value on subsequent requests, or as
-the `WFT_API_KEY` env var in MCP and CLI clients (the REST client switches
-to `Authorization: Bearer …` automatically when the value starts with
-`wft_pat_`). See [`SECURITY.md`](../SECURITY.md) →
-**Authentication Architecture** for the full chain.
+`Authorization: Bearer wft_pat_<…>` value on subsequent requests, or as the
+`WFT_API_KEY` env var in MCP/CLI clients (the REST client auto-switches to
+`Authorization: Bearer …` for `wft_pat_` values). See [`SECURITY.md`](../SECURITY.md)
+→ **Authentication Architecture** for the full chain.
 
 [WARNING] **PATs have NO default expiry.** The `api_tokens.expires_at`
 column is nullable (migration `008-identity-tables.ts`) and is written
@@ -1379,16 +1380,27 @@ variable the server reads, plus the CLI- and MCP-specific variables.
 | `SSE_MAX_CONNECTIONS_PER_KEY` | no | `4` | Per-credential (PAT) cap on concurrent SSE connections. 429 with `Retry-After` when exceeded. |
 | `SSE_MAX_CONNECTIONS_PER_IP` | no | `8` | Per-IP cap on concurrent SSE connections. |
 | `SSE_MAX_CONNECTIONS` | no | `200` | Global cap on concurrent SSE connections. |
+| `DEVICE_FLOW_TRUSTED_HOSTS` | no | — (all hosts honored) | Optional comma-separated allowlist of hostnames the device-flow `verification_uri` may be built from (`host` or `host:port`; port ignored in match). When set, a request whose `Host`/`X-Forwarded-Host` is not on the list falls back to the configured origin. See [§3a](#3a-device-flow-verification-origin--trust-boundary). |
 | `SLACK_BOT_TOKEN` | conditional | — | Slack bot token (`xoxb-…`). Required if any Slack var is set; refused alone (see [`docs/SLACK.md`](SLACK.md)). |
 | `SLACK_APP_TOKEN` | conditional | — | Slack app-level token (`xapp-…`) for Socket Mode. Must be set together with `SLACK_BOT_TOKEN` or neither. |
 | `SLACK_SIGNING_SECRET` | conditional | — | Slack request signing secret. Required when running Slack in HTTP mode; harmless in Socket Mode. |
 
-### Rate limiting (read directly in `src/api/server.ts`)
+### Rate limiting (validated in `src/config/env.ts`)
+
+The global limiter keys on the authenticated principal (PAT token id, else user
+id), falling back to `request.ip`; the five sensitive auth/device routes get a
+tighter per-route budget. `TRUST_PROXY` (default off — see [§3a](#3a-device-flow-verification-origin--trust-boundary))
+makes `request.ip` resolve from `X-Forwarded-For`; off, a spoofed header cannot
+move a bucket; behind a proxy, enable it or all clients share one IP bucket.
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `RATE_LIMIT_MAX` | no | `1000` | Maximum requests per window (global, via `@fastify/rate-limit`). `/health` is allow-listed. |
-| `RATE_LIMIT_TIME_WINDOW` | no | `1 minute` | Window string accepted by `@fastify/rate-limit`. |
+| `RATE_LIMIT_MAX` | no | `1000` | Global max requests/window. `/health` is allow-listed. |
+| `RATE_LIMIT_TIME_WINDOW` | no | `1 minute` | Global window string. |
+| `RATE_LIMIT_AUTH_MAX` | no | `10` | Per-route max for login, callback, device/code, device/verify. |
+| `RATE_LIMIT_AUTH_TIME_WINDOW` | no | `1 minute` | Window for the per-route auth limits (incl. device/token). |
+| `RATE_LIMIT_DEVICE_TOKEN_MAX` | no | `30` | Per-route max for `/auth/device/token` (CLI polls it — looser). |
+| `TRUST_PROXY` | no | `false` | `false`/unset = ignore forwarded headers; `true` = trust all hops; integer = trust N hops; `ip,cidr,…` = trust only those proxy IPs/CIDRs. |
 
 ### Model catalog (read directly in `src/index.ts`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wood-fired-tasks",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Network-wide task tracking system for Wood Fired Games",
   "keywords": [
     "task-tracker",
@@ -122,11 +122,11 @@
     "@fastify/cookie": "^11.0.2",
     "@fastify/formbody": "^8.0.2",
     "@fastify/helmet": "^13.0.2",
-    "@fastify/rate-limit": "^10.3.0",
+    "@fastify/rate-limit": "^11.0.0",
     "@fastify/secure-session": "^8.3.0",
     "@fastify/sse": "^0.4.0",
     "@fastify/swagger": "^9.7.0",
-    "@fastify/swagger-ui": "^5.2.6",
+    "@fastify/swagger-ui": "^6.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@slack/bolt": "^4.6.0",
     "better-sqlite3": "^12.6.2",
@@ -136,7 +136,7 @@
     "dotenv": "^17.3.1",
     "env-paths": "^4.0.0",
     "fastify": "^5.8.5",
-    "fastify-plugin": "^5.1.0",
+    "fastify-plugin": "^6.0.0",
     "fastify-type-provider-zod": "^6.1.0",
     "openid-client": "^6.8.4",
     "pino": "^10.3.1",
@@ -150,7 +150,7 @@
     "qs": "^6.15.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.16",
+    "@biomejs/biome": "2.5.0",
     "@fast-check/vitest": "^0.4.1",
     "@slack/types": "^2.20.0",
     "@slack/web-api": "^7.15.2",

package/packages/wft-router/README.md

@@ -68,6 +68,8 @@ wake their targets. Dedup: `sweep:<rule>:<floor(now / idempotency_window)>`,
 so a restart within the same window dispatches nothing. See
 [docs/event-router-design.md §Cold-start sweep](../../docs/event-router-design.md).
 
+**Periodic re-sweep** (opt-in, default off): `sweep_interval_s: <seconds>` (per rule or under `defaults:`) re-runs that sweep on a timer — no restart, no SSE event — re-kicking sessions that went idle mid-run; same per-window dedup.
+
 - **Recipes** (full walkthroughs): [docs/automation-recipes/](https://github.com/Wood-Fired-Games/wood-fired-tasks/tree/main/docs/automation-recipes)
   - [claude-routines.md](../../docs/automation-recipes/claude-routines.md) — dispatch a routine on task close
   - [persistent-agent-sessions.md](../../docs/automation-recipes/persistent-agent-sessions.md) — drive a long-lived agent session

package/packages/wft-router/dist/config/triggers-schema.d.ts

@@ -181,6 +181,7 @@ export declare const RuleSchema: z.ZodObject<{
     max_dispatches_per_minute: z.ZodOptional<z.ZodNumber>;
     max_retries: z.ZodOptional<z.ZodNumber>;
     sweep_on_start: z.ZodOptional<z.ZodBoolean>;
+    sweep_interval_s: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 /** `defaults:` block — optional, all sub-keys optional with documented values. */
 export declare const DefaultsSchema: z.ZodObject<{
@@ -189,6 +190,7 @@ export declare const DefaultsSchema: z.ZodObject<{
     max_dispatches_per_minute: z.ZodOptional<z.ZodNumber>;
     max_retries: z.ZodOptional<z.ZodNumber>;
     sweep_on_start: z.ZodOptional<z.ZodBoolean>;
+    sweep_interval_s: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 /** Top-level triggers.yaml schema. */
 export declare const TriggersConfigSchema: z.ZodObject<{
@@ -199,6 +201,7 @@ export declare const TriggersConfigSchema: z.ZodObject<{
         max_dispatches_per_minute: z.ZodOptional<z.ZodNumber>;
         max_retries: z.ZodOptional<z.ZodNumber>;
         sweep_on_start: z.ZodOptional<z.ZodBoolean>;
+        sweep_interval_s: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     rules: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -280,6 +283,7 @@ export declare const TriggersConfigSchema: z.ZodObject<{
         max_dispatches_per_minute: z.ZodOptional<z.ZodNumber>;
         max_retries: z.ZodOptional<z.ZodNumber>;
         sweep_on_start: z.ZodOptional<z.ZodBoolean>;
+        sweep_interval_s: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type TriggersConfig = z.infer<typeof TriggersConfigSchema>;

package/packages/wft-router/dist/config/triggers-schema.js

@@ -33,6 +33,7 @@
  * any specific receiver. (See docs/event-router-design.md §"Vendor-neutral
  * guardrails".)
  */
+import { lstatSync, realpathSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { parse as parseYaml } from 'yaml';
 import { z } from 'zod';
@@ -101,6 +102,16 @@ export const RuleSchema = z
      * handler path. Default OFF: absent = no startup behavior change.
      */
     sweep_on_start: z.boolean().optional(),
+    /**
+     * Periodic re-sweep interval in seconds (task #1035). When set (here or
+     * in `defaults:`), the daemon re-runs the SAME sweep this rule's
+     * `sweep_on_start` path uses, every `sweep_interval_s` seconds, with NO
+     * router restart and NO new SSE event — closing the steady-state gap
+     * where a session goes idle while the router is healthy. Bucket
+     * idempotency (`sweep:<rule>:<floor(now / idempotency_window)>`) caps it
+     * at one kick per window. Default OFF: absent (or 0) = no timer.
+     */
+    sweep_interval_s: z.number().int().positive().optional(),
 })
     .strict();
 /** `defaults:` block — optional, all sub-keys optional with documented values. */
@@ -116,6 +127,8 @@ export const DefaultsSchema = z
     max_retries: z.number().int().nonnegative().optional(),
     /** Global cold-start sweep opt-in; per-rule `sweep_on_start` overrides. Default false. */
     sweep_on_start: z.boolean().optional(),
+    /** Global periodic re-sweep interval (s); per-rule `sweep_interval_s` overrides. Default off. */
+    sweep_interval_s: z.number().int().positive().optional(),
 })
     .strict();
 /** Top-level triggers.yaml schema. */
@@ -213,6 +226,58 @@ function checkStringForTemplatingViolations(s, path, issues) {
             'at bare JSON value positions only)',
     });
 }
+/**
+ * Enforce the documented `triggers.yaml` trust posture at startup: the file
+ * that drives shell_exec / webhook_post / create_task / agent dispatch MUST be
+ * owner-only (mode `0600`) and owned by the router user, because edit access is
+ * equivalent to arbitrary code execution as the router. See
+ * docs/event-router-design.md §"`triggers.yaml` trust posture".
+ *
+ * Mirrors the stat/owner/symlink hardening already used by
+ * `handlers/agent-session-dispatch.ts:resolveAdapter`, applied to a SINGLE file:
+ *   - The path is resolved through {@link realpathSync} and the REAL file is
+ *     stat'd, so a symlink cannot point at a 0600 file while the link target is
+ *     attacker-writable.
+ *   - Mode is rejected if ANY group/other bit is set — `(mode & 0o077) !== 0`.
+ *     This is the strict `0600` reading promised by the design doc, so
+ *     0640/0644/0660/0666 all fail while 0600 passes.
+ *   - Owner is rejected (POSIX only) when `process.getuid()` is defined and the
+ *     real file's `uid` differs. `getuid` is undefined on Windows, where mode
+ *     and uid bits are not meaningful — there, enforcement is skipped and file
+ *     permissions are a deployment requirement.
+ *
+ * Returns `null` when the file passes (or the platform is non-POSIX); otherwise
+ * a single `  - <file>: <message>` error string in the established result shape.
+ */
+function checkTriggersFilePermissions(filePath) {
+    const routerUid = process.getuid?.();
+    // Non-POSIX (Windows): mode/uid bits are unreliable. Skip enforcement — file
+    // permissions are a documented deployment requirement on that platform.
+    if (routerUid === undefined) {
+        return null;
+    }
+    let st;
+    try {
+        // Resolve symlinks so the bytes actually read are the ones we vet. lstat
+        // first to surface a dangling-symlink/missing-target clearly.
+        lstatSync(filePath);
+        const realPath = realpathSync(filePath);
+        st = statSync(realPath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `  - ${filePath}: cannot stat for permission check: ${message}`;
+    }
+    if ((st.mode & 0o077) !== 0) {
+        return `  - ${filePath}: insecure permissions (mode ${(st.mode & 0o777)
+            .toString(8)
+            .padStart(4, '0')}); must be mode 0600 / not accessible to group or other`;
+    }
+    if (st.uid !== routerUid) {
+        return `  - ${filePath}: not owned by the router user (file uid ${st.uid}, router uid ${routerUid})`;
+    }
+    return null;
+}
 /**
  * Read a `triggers.yaml` file from disk, parse it, run the zod schema, and
  * then run the templating-safety pass. On success returns the typed config;
@@ -229,6 +294,13 @@ export async function loadAndValidateTriggers(filePath) {
         const message = err instanceof Error ? err.message : String(err);
         return { ok: false, errors: [`  - <file>: cannot read ${filePath}: ${message}`] };
     }
+    // Trust gate: the file just read must be owner-only and owned by the router
+    // user (POSIX). Reject before parsing so an attacker-writable config never
+    // reaches the handler dispatch surface. See checkTriggersFilePermissions.
+    const permError = checkTriggersFilePermissions(filePath);
+    if (permError !== null) {
+        return { ok: false, errors: [permError] };
+    }
     let parsed;
     try {
         parsed = parseYaml(raw);

package/packages/wft-router/dist/daemon.d.ts

@@ -74,6 +74,29 @@ export type HandlerRegistry = Record<TriggersRule['do'], Handler>;
  * this seam so tests can hand it a fake generator they fully control.
  */
 export type SSESourceFactory = (signal: AbortSignal) => AsyncGenerator<SSEEvent, ExitCode>;
+/** Opaque handle returned by an {@link IntervalScheduler}'s `set`. */
+export type IntervalHandle = unknown;
+/**
+ * Minimal interval-scheduler seam (task #1035). The periodic re-sweep timer
+ * fires through this rather than calling `setInterval` directly, so tests can
+ * inject a fake that captures the callback and drive it deterministically
+ * alongside the injected `now` clock (the sweep's bucket identity is derived
+ * from `now`, so the two must advance together under test control). Production
+ * defaults to {@link DEFAULT_INTERVAL_SCHEDULER} (real `setInterval`, unref'd
+ * so the timer never independently holds the event loop open).
+ */
+export interface IntervalScheduler {
+    /** Schedule `cb` to run every `ms`; return an opaque cancel handle. */
+    set(cb: () => void, ms: number): IntervalHandle;
+    /** Cancel a previously scheduled interval. */
+    clear(handle: IntervalHandle): void;
+}
+/**
+ * Production interval scheduler: real `setInterval`/`clearInterval`. The
+ * timer is `unref`'d so it never keeps the process alive on its own — the SSE
+ * consume loop owns process liveness; the periodic sweep is a passenger.
+ */
+export declare const DEFAULT_INTERVAL_SCHEDULER: IntervalScheduler;
 /** Minimal structured-logger surface the daemon needs (pino-compatible). */
 export interface DaemonLogger extends HandlerLogger {
     info(obj: Record<string, unknown>, msg?: string): void;
@@ -118,6 +141,13 @@ export interface DaemonDeps {
     env?: NodeJS.ProcessEnv;
     /** Injected clock for debounce/rate-limit math in tests. Default: Date.now. */
     now?: () => number;
+    /**
+     * Injected interval scheduler for the periodic re-sweep timer (task #1035).
+     * Default: {@link DEFAULT_INTERVAL_SCHEDULER} (real, unref'd `setInterval`).
+     * Tests inject a fake that captures the tick callback so the periodic sweep
+     * can be driven deterministically together with the injected `now`.
+     */
+    intervalScheduler?: IntervalScheduler;
     /**
      * Optional Prometheus metrics registry. ADDITIVE (task #434): when present,
      * the daemon increments it at the pipeline points it already tracks (events
@@ -189,6 +219,8 @@ export declare class WftRouterDaemon {
     private readonly metrics?;
     /** Injected clock (shared with debounce/rate-limit; drives sweep buckets). */
     private readonly now;
+    /** Injected interval scheduler for the periodic re-sweep timer (task #1035). */
+    private readonly intervalScheduler;
     private phase;
     private readonly abortController;
     /** The background consume loop; awaited by `stop()` so drain is ordered. */
@@ -203,6 +235,8 @@ export declare class WftRouterDaemon {
     private exitCode;
     /** The one-shot cold-start sweep (task #1005); null when no rule opted in. */
     private sweepPromise;
+    /** Live periodic re-sweep timer handles (task #1035); cleared in `stop()`. */
+    private readonly intervalHandles;
     constructor(deps: DaemonDeps);
     /**
      * Begin consuming the SSE generator in a background loop. Returns
@@ -217,6 +251,14 @@ export declare class WftRouterDaemon {
      * can deterministically observe "sweep finished" without racing `stop()`.
      */
     waitForSweep(): Promise<void>;
+    /**
+     * Await every currently in-flight dispatch fan-out + sweep tick (task
+     * #1035). Exposed so tests driving the periodic timer can deterministically
+     * observe a tick's sweep settling without calling `stop()` (which would
+     * tear the timer down). Snapshots the set so work scheduled AFTER the call
+     * does not extend the wait.
+     */
+    settle(): Promise<void>;
     /**
      * Abort the SSE generator, then drain all in-flight dispatch fan-outs and
      * any pending debounced buckets. Idempotent — a second call returns the
@@ -258,6 +300,16 @@ export declare class WftRouterDaemon {
      * down the live SSE pipeline.
      */
     private runStartupSweep;
+    /**
+     * Periodic re-sweep (task #1035): schedule a timer that re-runs THIS rule's
+     * sweep every `intervalMs`. The tick runs `sweepRule` — the exact same
+     * query → predicate → at-most-one-dispatch path the cold-start sweep uses —
+     * so the deterministic `sweep:<rule>:<bucket>` identity + idempotency claim
+     * cap it at one kick per window (AC #1/#2). A tick error is isolated: it
+     * logs a WARN and the timer keeps firing (AC #4). Each tick's in-flight
+     * work is `track`ed so `stop()` drains it (AC #5).
+     */
+    private startPeriodicSweep;
     /** Sweep ONE rule: query, predicate-match, then dispatch at most once. */
     private sweepRule;
     /**

package/packages/wft-router/dist/daemon.js

@@ -60,6 +60,23 @@ import { findFirstMatchingOpenTask, sweepEventId } from './dispatch/startup-swee
 import { agentSessionDispatch, createTaskInProject, shellExec, webhookPost, } from './handlers/index.js';
 import { ExitCode, isControlEvent } from './sse/index.js';
 import { omitUndefined } from './util/omit-undefined.js';
+/**
+ * Production interval scheduler: real `setInterval`/`clearInterval`. The
+ * timer is `unref`'d so it never keeps the process alive on its own — the SSE
+ * consume loop owns process liveness; the periodic sweep is a passenger.
+ */
+export const DEFAULT_INTERVAL_SCHEDULER = {
+    set(cb, ms) {
+        const handle = setInterval(cb, ms);
+        if (typeof handle.unref === 'function') {
+            handle.unref();
+        }
+        return handle;
+    },
+    clear(handle) {
+        clearInterval(handle);
+    },
+};
 /**
  * The default production handler registry: the four real handlers keyed by
  * their `do:` name. Tests override this with recording fakes.
@@ -155,6 +172,8 @@ export class WftRouterDaemon {
     metrics;
     /** Injected clock (shared with debounce/rate-limit; drives sweep buckets). */
     now;
+    /** Injected interval scheduler for the periodic re-sweep timer (task #1035). */
+    intervalScheduler;
     phase = 'idle';
     abortController = new AbortController();
     /** The background consume loop; awaited by `stop()` so drain is ordered. */
@@ -169,6 +188,8 @@ export class WftRouterDaemon {
     exitCode = ExitCode.CleanShutdown;
     /** The one-shot cold-start sweep (task #1005); null when no rule opted in. */
     sweepPromise = null;
+    /** Live periodic re-sweep timer handles (task #1035); cleared in `stop()`. */
+    intervalHandles = [];
     constructor(deps) {
         this.config = deps.config;
         this.store = deps.store;
@@ -194,6 +215,7 @@ export class WftRouterDaemon {
         }
         const now = deps.now ?? Date.now;
         this.now = now;
+        this.intervalScheduler = deps.intervalScheduler ?? DEFAULT_INTERVAL_SCHEDULER;
         this.rateLimiter =
             deps.rateLimiter ??
                 new RateLimiter({
@@ -236,6 +258,19 @@ export class WftRouterDaemon {
             this.sweepPromise = this.runStartupSweep(sweepRules);
             this.track(this.sweepPromise);
         }
+        // Periodic re-sweep (task #1035): OPT-IN timed re-run of the SAME sweep
+        // for rules with a positive `sweep_interval_s` (per-rule or via
+        // `defaults:`). Independent of `sweep_on_start` — a rule may opt into the
+        // periodic path alone. Each opted-in rule gets its OWN timer so one rule's
+        // sweep failure can never stall another's (per-rule error isolation,
+        // AC #4). Absent / non-positive interval = no timer (zero behavior change,
+        // AC #3). Cleared in `stop()`.
+        for (const rule of this.config.rules) {
+            const intervalS = rule.sweep_interval_s ?? this.config.defaults?.sweep_interval_s ?? 0;
+            if (intervalS > 0) {
+                this.startPeriodicSweep(rule, intervalS * 1000);
+            }
+        }
     }
     /**
      * Await the cold-start sweep's completion (resolves immediately when no
@@ -247,6 +282,16 @@ export class WftRouterDaemon {
             await this.sweepPromise;
         }
     }
+    /**
+     * Await every currently in-flight dispatch fan-out + sweep tick (task
+     * #1035). Exposed so tests driving the periodic timer can deterministically
+     * observe a tick's sweep settling without calling `stop()` (which would
+     * tear the timer down). Snapshots the set so work scheduled AFTER the call
+     * does not extend the wait.
+     */
+    async settle() {
+        await Promise.allSettled(Array.from(this.inFlight));
+    }
     /**
      * Abort the SSE generator, then drain all in-flight dispatch fan-outs and
      * any pending debounced buckets. Idempotent — a second call returns the
@@ -267,8 +312,14 @@ export class WftRouterDaemon {
             return;
         }
         this.phase = 'stopping';
-        // 1. Stop reading new SSE events immediately.
+        // 1. Stop reading new SSE events immediately, and cancel the periodic
+        //    re-sweep timers so no new tick fires during drain (task #1035). Any
+        //    tick already in flight is awaited at step 4 via `inFlight`.
         this.abortController.abort();
+        for (const handle of this.intervalHandles) {
+            this.intervalScheduler.clear(handle);
+        }
+        this.intervalHandles.length = 0;
         // 2. Flush debounced buckets so their trailing-edge dispatch fires now
         //    rather than waiting the full window on the way down.
         await this.debouncer.flushAll();
@@ -354,6 +405,28 @@ export class WftRouterDaemon {
             }
         }
     }
+    /**
+     * Periodic re-sweep (task #1035): schedule a timer that re-runs THIS rule's
+     * sweep every `intervalMs`. The tick runs `sweepRule` — the exact same
+     * query → predicate → at-most-one-dispatch path the cold-start sweep uses —
+     * so the deterministic `sweep:<rule>:<bucket>` identity + idempotency claim
+     * cap it at one kick per window (AC #1/#2). A tick error is isolated: it
+     * logs a WARN and the timer keeps firing (AC #4). Each tick's in-flight
+     * work is `track`ed so `stop()` drains it (AC #5).
+     */
+    startPeriodicSweep(rule, intervalMs) {
+        const handle = this.intervalScheduler.set(() => {
+            // A tick that fires mid-shutdown (timer not yet cleared) is a no-op.
+            if (this.phase !== 'running') {
+                return;
+            }
+            const tick = this.sweepRule(rule).catch((err) => {
+                this.logger.warn({ rule_name: rule.name, error: err instanceof Error ? err.message : String(err) }, 'wft_router_periodic_sweep_failed');
+            });
+            this.track(tick);
+        }, intervalMs);
+        this.intervalHandles.push(handle);
+    }
     /** Sweep ONE rule: query, predicate-match, then dispatch at most once. */
     async sweepRule(rule) {
         const match = await findFirstMatchingOpenTask(rule, {