instar 0.28.76 → 0.28.78

package/dist/server/routes.js

@@ -20,6 +20,8 @@ import { dayKeyFor } from '../core/StopGateDb.js';
 import { randomUUID as cryptoRandomUUID } from 'node:crypto';
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
+import { SafeGitExecutor } from '../core/SafeGitExecutor.js';
+import { SafeFsExecutor } from '../core/SafeFsExecutor.js';
 const execFile = promisify(execFileCb);
 /**
  * Per-session continue-ceiling (spec § (b) Outcomes).
@@ -80,6 +82,286 @@ import { ScopeCoherenceTracker } from '../core/ScopeCoherenceTracker.js';
 import { isJunkPayload } from '../core/junk-payload.js';
 import { TruncationDetector } from '../paste/TruncationDetector.js';
 import { SecretDrop } from './SecretDrop.js';
+import { matchesSystemTemplate } from '../messaging/system-templates.js';
+import { resolvePendingRelayPath } from '../messaging/pending-relay-store.js';
+import Database from 'better-sqlite3';
+/**
+ * Build the /whoami request handler.
+ *
+ * Spec docs/specs/telegram-delivery-robustness.md § Layer 1c. Exported
+ * separately from createRoutes so unit tests can mount it on a minimal
+ * Express app without instantiating the entire RouteContext.
+ *
+ * Behavior:
+ *   - 403 `{error: 'agent_id_header_required'}` when X-Instar-AgentId is
+ *     absent. The middleware accepts bare-token requests during the
+ *     deprecation window for *other* endpoints; /whoami does not, because
+ *     accepting a bare-token request here would let a caller learn the
+ *     expected agent-id from the response (discovery oracle).
+ *   - 403 `{error: 'agent_id_mismatch', expected}` when the header is
+ *     present but does not match.
+ *   - 429 with retry hint when the per-source rate limit (1 req/s) is
+ *     exceeded — the bucket is keyed on (agent-id, remoteAddress) so a
+ *     single misbehaving caller can't starve the budget for legitimate
+ *     sentinel callers from other source addresses.
+ *   - 200 `{agentId, port}` on a clean request. (We deliberately do NOT
+ *     return `version`: an authed identity probe shouldn't double as a
+ *     CVE-targeting oracle for an authed peer who has stolen a token.)
+ */
+export function createWhoamiHandler(opts) {
+    const WHOAMI_WINDOW_MS = 1000;
+    // Bucket key is `${agentId}|${remoteAddress}` so a single noisy caller
+    // can't starve the budget for legitimate sentinel callers from other
+    // source addresses on the same authed agent-id.
+    const buckets = new Map();
+    const cleanup = setInterval(() => {
+        const cutoff = Date.now() - WHOAMI_WINDOW_MS * 60;
+        for (const [k, t] of buckets) {
+            if (t < cutoff)
+                buckets.delete(k);
+        }
+    }, WHOAMI_WINDOW_MS * 60);
+    cleanup.unref();
+    return (req, res) => {
+        const headerVal = req.headers['x-instar-agentid'];
+        const provided = Array.isArray(headerVal) ? headerVal[0] : headerVal;
+        const expected = opts.agentId;
+        if (!provided) {
+            res.status(403).json({ error: 'agent_id_header_required', expected });
+            return;
+        }
+        if (provided !== expected) {
+            // Defense-in-depth — auth middleware should have already caught this.
+            res.status(403).json({ error: 'agent_id_mismatch', expected });
+            return;
+        }
+        const remote = req.ip || req.socket?.remoteAddress || 'unknown';
+        const bucketKey = `${provided}|${remote}`;
+        const now = Date.now();
+        const last = buckets.get(bucketKey);
+        if (last !== undefined && now - last < WHOAMI_WINDOW_MS) {
+            res.status(429).json({
+                error: 'Rate limit exceeded',
+                retryAfterMs: WHOAMI_WINDOW_MS - (now - last),
+            });
+            return;
+        }
+        buckets.set(bucketKey, now);
+        // Deliberately omit `version`: an authed identity probe shouldn't
+        // double as a CVE-targeting oracle for a peer whose token has been
+        // stolen. Layer 3's recovery path needs agentId + port, not version.
+        // (`opts.configVersion` retained on the type for forward-compat
+        // — callers who need version must read it from a separate route.)
+        res.json({
+            agentId: expected,
+            port: opts.port,
+        });
+    };
+}
+/**
+ * Build the `POST /events/delivery-failed` request handler.
+ *
+ * Spec: docs/specs/telegram-delivery-robustness.md § Layer 2c.
+ *
+ * Contract:
+ *   - Body: `{ delivery_id, topic_id, text_hash, http_code,
+ *              error_body?, attempted_port, attempts }` — strict
+ *     (any extra field rejected with 400).
+ *   - Caps: text-equivalent fields ≤ 8KB, error_body ≤ 1KB, total
+ *     body ≤ 16KB. The endpoint *does not store anything* — the
+ *     SQLite queue on the script side is the durable record. This
+ *     route only fans out an SSE event so listeners (the Layer 3
+ *     sentinel, the dashboard) can react in real time.
+ *   - Per-(agentId, remote) token bucket: 10 req/s sustained, burst 50.
+ *   - Auth handled by upstream `authMiddleware`; we additionally
+ *     reject responses missing `X-Instar-AgentId` so the auth-mismatch
+ *     path returns the same structured 403 even when the route is
+ *     mounted in tests without the full middleware stack.
+ *
+ * Validation is hand-rolled (rather than zod) for two reasons:
+ *   (1) the schema is small and we want every failure mode to map to a
+ *       precise error code without translating zod's verbose message
+ *       shape; (2) zod is in deps but adds a non-trivial import-time
+ *       cost on a hot route.
+ */
+export function createDeliveryFailedHandler(opts) {
+    const now = opts.now ?? (() => Date.now());
+    // Per-source token bucket. Burst 50; refill 10 tokens/sec.
+    // Keyed on `${agentId}|${remoteAddress}` — the agent-id is opaque to
+    // the bucket itself but having it in the key means tests that mount
+    // multiple agents on a single Express app each get their own budget.
+    const BURST = 50;
+    const REFILL_PER_SEC = 10;
+    const buckets = new Map();
+    // Periodic GC so a large cardinality of (agent, IP) pairs doesn't bloat the map.
+    const gc = setInterval(() => {
+        const cutoff = now() - 5 * 60 * 1000;
+        for (const [k, b] of buckets) {
+            if (b.lastRefillMs < cutoff)
+                buckets.delete(k);
+        }
+    }, 60 * 1000);
+    gc.unref();
+    function takeToken(key) {
+        const t = now();
+        let b = buckets.get(key);
+        if (!b) {
+            b = { tokens: BURST, lastRefillMs: t };
+            buckets.set(key, b);
+        }
+        else {
+            const elapsedMs = t - b.lastRefillMs;
+            if (elapsedMs > 0) {
+                b.tokens = Math.min(BURST, b.tokens + (elapsedMs / 1000) * REFILL_PER_SEC);
+                b.lastRefillMs = t;
+            }
+        }
+        if (b.tokens < 1)
+            return false;
+        b.tokens -= 1;
+        return true;
+    }
+    // Caps — defense-in-depth on top of the body-parser limit.
+    const MAX_TOTAL_BYTES = 16 * 1024;
+    const MAX_TEXT_FIELD_BYTES = 8 * 1024;
+    const MAX_ERROR_BODY_BYTES = 1 * 1024;
+    const HEX64 = /^[a-f0-9]{64}$/i;
+    const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    const allowedFields = new Set([
+        'delivery_id',
+        'topic_id',
+        'text_hash',
+        'http_code',
+        'error_body',
+        'attempted_port',
+        'attempts',
+    ]);
+    /** Strip control chars (except \n, \t) and length-cap. */
+    function sanitizeErrorBody(s) {
+        // eslint-disable-next-line no-control-regex
+        const stripped = s.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
+        return stripped.length > MAX_ERROR_BODY_BYTES
+            ? stripped.slice(0, MAX_ERROR_BODY_BYTES)
+            : stripped;
+    }
+    return (req, res) => {
+        // Auth-mismatch defense in depth — emit a single 403 audit line and do
+        // not echo the body. The upstream auth middleware should already have
+        // rejected, but the route is mountable bare in tests, so we re-check.
+        const headerVal = req.headers['x-instar-agentid'];
+        const provided = Array.isArray(headerVal) ? headerVal[0] : headerVal;
+        if (provided !== undefined && provided !== opts.agentId) {
+            const remote = req.ip || req.socket?.remoteAddress || 'unknown';
+            console.warn(`[delivery-failed] auth_failure: agent_id_mismatch from ${remote} ` +
+                `(provided=${JSON.stringify(provided).slice(0, 64)}, expected=${opts.agentId})`);
+            res.status(403).json({ error: 'agent_id_mismatch', expected: opts.agentId });
+            return;
+        }
+        // Rate limit.
+        const remote = req.ip || req.socket?.remoteAddress || 'unknown';
+        const bucketKey = `${opts.agentId}|${remote}`;
+        if (!takeToken(bucketKey)) {
+            res.status(429).json({
+                error: 'Rate limit exceeded',
+                limit: { rps: REFILL_PER_SEC, burst: BURST },
+            });
+            return;
+        }
+        const body = req.body;
+        if (!body || typeof body !== 'object' || Array.isArray(body)) {
+            res.status(400).json({ error: 'body must be a JSON object' });
+            return;
+        }
+        // Total-body cap. Express's body-parser already imposes a limit, but we
+        // re-measure here so a misconfigured upstream limit can't smuggle through.
+        let totalBytes;
+        try {
+            totalBytes = Buffer.byteLength(JSON.stringify(body), 'utf-8');
+        }
+        catch {
+            res.status(400).json({ error: 'body not serializable' });
+            return;
+        }
+        if (totalBytes > MAX_TOTAL_BYTES) {
+            res.status(413).json({ error: 'body too large', maxBytes: MAX_TOTAL_BYTES });
+            return;
+        }
+        // Strict field set — reject extras.
+        for (const k of Object.keys(body)) {
+            if (!allowedFields.has(k)) {
+                res.status(400).json({ error: `unexpected field: ${k}` });
+                return;
+            }
+        }
+        const { delivery_id, topic_id, text_hash, http_code, error_body, attempted_port, attempts, } = body;
+        if (typeof delivery_id !== 'string' || !UUID.test(delivery_id)) {
+            res.status(400).json({ error: 'delivery_id must be a UUIDv4 string' });
+            return;
+        }
+        if (typeof topic_id !== 'number' || !Number.isInteger(topic_id) || topic_id < 0) {
+            res.status(400).json({ error: 'topic_id must be a non-negative integer' });
+            return;
+        }
+        if (typeof text_hash !== 'string' || !HEX64.test(text_hash)) {
+            res.status(400).json({ error: 'text_hash must be a 64-char hex string' });
+            return;
+        }
+        if (typeof http_code !== 'number' || !Number.isInteger(http_code) || http_code < 0 || http_code > 999) {
+            res.status(400).json({ error: 'http_code must be an integer in [0,999]' });
+            return;
+        }
+        if (typeof attempted_port !== 'number' || !Number.isInteger(attempted_port) || attempted_port < 1 || attempted_port > 65535) {
+            res.status(400).json({ error: 'attempted_port must be an integer in [1,65535]' });
+            return;
+        }
+        if (typeof attempts !== 'number' || !Number.isInteger(attempts) || attempts < 1) {
+            res.status(400).json({ error: 'attempts must be a positive integer' });
+            return;
+        }
+        let sanitizedErrorBody = null;
+        if (error_body !== undefined && error_body !== null) {
+            if (typeof error_body !== 'string') {
+                res.status(400).json({ error: 'error_body must be a string when present' });
+                return;
+            }
+            if (Buffer.byteLength(error_body, 'utf-8') > MAX_TEXT_FIELD_BYTES) {
+                // We could just silently truncate, but the script's contract caps at
+                // 1KB before send — anything bigger is a contract violation worth
+                // reporting back. Cap at 8KB as the field-size hard upper bound;
+                // sanitization below handles the per-field 1KB normalization.
+                res.status(413).json({ error: 'error_body too large', maxBytes: MAX_TEXT_FIELD_BYTES });
+                return;
+            }
+            sanitizedErrorBody = sanitizeErrorBody(error_body);
+        }
+        // Fan out to listeners. We do NOT persist anything — that's the script's
+        // job. Listeners care about the *fact* of failure plus enough metadata to
+        // look up the queued row.
+        const event = {
+            type: 'delivery_failed',
+            agentId: opts.agentId,
+            delivery_id,
+            topic_id,
+            text_hash,
+            http_code,
+            attempted_port,
+            attempts,
+            error_body: sanitizedErrorBody,
+            receivedAt: new Date(now()).toISOString(),
+        };
+        if (opts.emit) {
+            try {
+                opts.emit(event);
+            }
+            catch (err) {
+                // The endpoint must not fail because a listener crashed. The script
+                // already has the row in SQLite; the event is best-effort signal.
+                console.error('[delivery-failed] emit handler threw:', err);
+            }
+        }
+        res.status(202).json({ accepted: true, delivery_id });
+    };
+}
 // Validation patterns for route parameters
 const SESSION_NAME_RE = /^[a-zA-Z0-9_-]{1,200}$/;
 const JOB_SLUG_RE = /^[a-zA-Z0-9_-]{1,100}$/;
@@ -130,6 +412,36 @@ export function createRoutes(ctx) {
     const homeostasisMonitor = new HomeostasisMonitor(ctx.config.stateDir);
     // Truncation detector for Telegram messages (Drop Zone integration)
     const truncationDetector = new TruncationDetector();
+    // ── /telegram/reply X-Instar-DeliveryId dedup LRU (Layer 3 §3d step 4) ──
+    // 24h sliding window of seen delivery_ids. Map preserves insertion order;
+    // we GC entries whose timestamp is older than 24h on each access.
+    const DELIVERY_LRU_MAX = 10_000;
+    const DELIVERY_LRU_TTL_MS = 24 * 60 * 60 * 1000;
+    const deliveryIdLru = new Map();
+    function deliveryLruHas(id) {
+        const at = deliveryIdLru.get(id);
+        if (at === undefined)
+            return false;
+        if (Date.now() - at > DELIVERY_LRU_TTL_MS) {
+            deliveryIdLru.delete(id);
+            return false;
+        }
+        return true;
+    }
+    function deliveryLruRecord(id) {
+        if (deliveryIdLru.size >= DELIVERY_LRU_MAX) {
+            // Drop oldest insertion-ordered entry.
+            const first = deliveryIdLru.keys().next().value;
+            if (first !== undefined)
+                deliveryIdLru.delete(first);
+        }
+        deliveryIdLru.set(id, Date.now());
+    }
+    // Wrap Map.has to use TTL-aware logic without rewriting call sites.
+    // We export via a small object so the route handler can call .has and .set.
+    // (Not using a Set — we need TTL.) Helper functions above provide that.
+    const deliveryIdLruHelpers = { has: deliveryLruHas, record: deliveryLruRecord };
+    void deliveryIdLruHelpers; // referenced via the helpers; alias kept for grep
     // ── Messaging tone gate ──────────────────────────────────────────
     //
     // Invoked before forwarding agent-authored messages to a user. Runs the
@@ -477,6 +789,46 @@ export function createRoutes(ctx) {
         }
         res.json(base);
     });
+    // GET /whoami — authenticated identity probe.
+    //
+    // Spec § Layer 1c: the sentinel hits this BEFORE any auth-bearing
+    // POST /telegram/reply during recovery. It returns this server's
+    // agentId/port/version so the caller can verify it's talking to the
+    // right agent before sending content.
+    //
+    // Hard requirement (no deprecation exception): the X-Instar-AgentId
+    // header MUST be present AND match this server's agent-id. If we
+    // accepted bare-token requests here, the endpoint would become a
+    // discovery oracle for token→port→agent-id triples. The auth
+    // middleware already validates the token and (when header present)
+    // the agent-id; we re-check the header presence here to close the
+    // deprecation hole that otherwise lets bare-token callers learn the
+    // expected agent-id from the response.
+    router.get('/whoami', createWhoamiHandler({
+        agentId: ctx.config.projectName,
+        port: ctx.config.port,
+        configVersion: ctx.config.version,
+    }));
+    // POST /events/delivery-failed — fan-out for the script-side detector.
+    //
+    // Spec § Layer 2c. The relay script INSERTs into its local SQLite queue
+    // and then best-effort POSTs here so the in-process Layer 3 sentinel
+    // can react in <1s rather than waiting for its 5-minute watchdog tick.
+    // The endpoint itself does not persist anything — SQLite is the
+    // durable record on the script side.
+    router.post('/events/delivery-failed', createDeliveryFailedHandler({
+        agentId: ctx.config.projectName,
+        emit: ctx.wsManager
+            ? (event) => {
+                // wsManager is set lazily after server.listen; if it's still
+                // null at request time we just no-op the broadcast — the
+                // event was still accepted, and the Layer 3 backstop watchdog
+                // (5-min tick over SQLite) catches up.
+                if (ctx.wsManager)
+                    ctx.wsManager.broadcastEvent(event);
+            }
+            : undefined,
+    }));
     /**
      * Get all feature degradation events.
      * A degradation means a feature fallback activated — the primary path failed.
@@ -2019,8 +2371,7 @@ export function createRoutes(ctx) {
                 let gitSyncJobEnabled = false;
                 if (hasGitRepo) {
                     try {
-                        // safe-git-allow: incremental-migration
-                        const remote = execFileSync('git', ['remote'], { cwd: projectDir, stdio: 'pipe' }).toString().trim();
+                        const remote = SafeGitExecutor.readSync(['remote'], { cwd: projectDir, stdio: 'pipe', operation: 'src/server/routes.ts:2286' }).toString().trim();
                         hasRemote = remote.length > 0;
                     }
                     catch { /* no remote */ }
@@ -2700,13 +3051,10 @@ export function createRoutes(ctx) {
         // Detect GitHub repo from git remote
         let repo = null;
         try {
-            // safe-git-allow: incremental-migration
-            const remoteUrl = execFileSync('git', ['remote', 'get-url', 'origin'], {
-                cwd: projectDir,
+            const remoteUrl = SafeGitExecutor.readSync(['remote', 'get-url', 'origin'], { cwd: projectDir,
                 encoding: 'utf-8',
                 timeout: 5000,
-                stdio: ['pipe', 'pipe', 'pipe'],
-            }).trim();
+                stdio: ['pipe', 'pipe', 'pipe'], operation: 'src/server/routes.ts:3037' }).trim();
             // Extract owner/repo from SSH or HTTPS URL
             const match = remoteUrl.match(/github\.com[:/](.+?)(?:\.git)?$/);
             if (match)
@@ -2830,8 +3178,7 @@ export function createRoutes(ctx) {
                 const fpath = path.join(failDir, fname);
                 try {
                     if (fs.statSync(fpath).mtimeMs < cutoff) {
-                        // safe-git-allow: incremental-migration
-                        fs.unlinkSync(fpath);
+                        SafeFsExecutor.safeUnlinkSync(fpath, { operation: 'src/server/routes.ts:3177' });
                         purgedFiles++;
                     }
                 }
@@ -3019,6 +3366,64 @@ export function createRoutes(ctx) {
             res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
         }
     });
+    // ── Token Ledger ────────────────────────────────────────────────
+    // Read-only token-usage observability backed by SQLite. Source data
+    // is Claude Code's per-session JSONL transcripts at
+    // ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl.
+    // Auth is enforced globally by authMiddleware.
+    const TOKEN_DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000;
+    const TOKEN_DEFAULT_ORPHAN_IDLE_MS = 30 * 60 * 1000;
+    function parseSinceMs(raw) {
+        if (typeof raw === 'string' && /^\d+$/.test(raw)) {
+            const n = Number(raw);
+            if (n >= 0)
+                return n;
+        }
+        return Date.now() - TOKEN_DEFAULT_WINDOW_MS;
+    }
+    router.get('/tokens/summary', (req, res) => {
+        if (!ctx.tokenLedger) {
+            res.status(503).json({ error: 'token ledger unavailable' });
+            return;
+        }
+        const sinceMs = parseSinceMs(req.query.since);
+        res.json({ sinceMs, summary: ctx.tokenLedger.summary({ sinceMs }) });
+    });
+    router.get('/tokens/sessions', (req, res) => {
+        if (!ctx.tokenLedger) {
+            res.status(503).json({ error: 'token ledger unavailable' });
+            return;
+        }
+        const sinceMs = parseSinceMs(req.query.since);
+        let limit = 20;
+        if (typeof req.query.limit === 'string' && /^\d+$/.test(req.query.limit)) {
+            const n = Number(req.query.limit);
+            if (n > 0 && n <= 500)
+                limit = n;
+        }
+        res.json({ sinceMs, limit, sessions: ctx.tokenLedger.topSessions({ limit, sinceMs }) });
+    });
+    router.get('/tokens/by-project', (req, res) => {
+        if (!ctx.tokenLedger) {
+            res.status(503).json({ error: 'token ledger unavailable' });
+            return;
+        }
+        const sinceMs = parseSinceMs(req.query.since);
+        res.json({ sinceMs, projects: ctx.tokenLedger.byProject({ sinceMs }) });
+    });
+    router.get('/tokens/orphans', (req, res) => {
+        if (!ctx.tokenLedger) {
+            res.status(503).json({ error: 'token ledger unavailable' });
+            return;
+        }
+        let idleMs = TOKEN_DEFAULT_ORPHAN_IDLE_MS;
+        if (typeof req.query.idleMs === 'string' && /^\d+$/.test(req.query.idleMs)) {
+            const n = Number(req.query.idleMs);
+            if (n > 0)
+                idleMs = n;
+        }
+        res.json({ idleMs, orphans: ctx.tokenLedger.orphans({ idleMs }) });
+    });
     // ── Jobs ────────────────────────────────────────────────────────
     router.get('/jobs', (_req, res) => {
         if (!ctx.scheduler) {
@@ -3654,6 +4059,30 @@ export function createRoutes(ctx) {
             res.status(400).json({ error: '"text" must be 4096 characters or fewer' });
             return;
         }
+        // ── X-Instar-DeliveryId server-side dedup (Layer 3 spec §3d step 4) ──
+        // 24h LRU keyed on the header value. A duplicate POST with the same
+        // delivery_id returns 200 idempotent without sending again. This
+        // closes the "200-but-client-blind" double-send class where the
+        // sentinel re-sends a queued message that actually landed the first
+        // time but the script-side response was lost.
+        const deliveryIdHeader = req.headers['x-instar-deliveryid'];
+        const deliveryId = Array.isArray(deliveryIdHeader) ? deliveryIdHeader[0] : deliveryIdHeader;
+        if (deliveryId && typeof deliveryId === 'string' && /^[0-9a-f-]{16,64}$/i.test(deliveryId)) {
+            if (deliveryLruHas(deliveryId)) {
+                res.json({ ok: true, topicId, idempotent: true });
+                return;
+            }
+        }
+        // ── X-Instar-System bypass (Layer 3 spec §3f) ──
+        // For sentinel-emitted templates, bypass the tone gate IF the body
+        // matches a known system template. The bypass is deliberately
+        // restricted to fixed templates whose content was reviewed at
+        // code-review time. Membership check uses regex / SHA-256 against
+        // the compiled-in template set; arbitrary text fails through to the
+        // normal gate.
+        const systemHeader = req.headers['x-instar-system'];
+        const systemFlag = Array.isArray(systemHeader) ? systemHeader[0] : systemHeader;
+        const isSystemTemplate = systemFlag === 'true' && matchesSystemTemplate(text);
         // Outbound gate — single authority. Skipped for proxy messages (PresenceProxy
         // etc. are system-generated). The authority receives structured signals from
         // the junk-payload and dedup detectors alongside conversational context, and
@@ -3663,6 +4092,7 @@ export function createRoutes(ctx) {
         const allowDebugText = metadata?.allowDebugText === true;
         const allowDuplicate = metadata?.allowDuplicate === true;
         if (!isProxy &&
+            !isSystemTemplate &&
             (await checkOutboundMessage(text, 'telegram', res, {
                 topicId,
                 allowDebugText,
@@ -3676,12 +4106,63 @@ export function createRoutes(ctx) {
             if (!isProxy) {
                 ctx.sessionManager.clearInjectionTracker(topicId);
             }
+            // Record successful delivery in the dedup LRU so a sentinel retry
+            // with the same delivery_id returns 200-idempotent.
+            if (deliveryId && typeof deliveryId === 'string' && /^[0-9a-f-]{16,64}$/i.test(deliveryId)) {
+                deliveryLruRecord(deliveryId);
+            }
             res.json({ ok: true, topicId });
         }
         catch (err) {
             res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
         }
     });
+    // ── GET /delivery-queue (Layer 3 spec §3i) ──
+    // Authed read-only view of the pending-relay queue depth/oldest age
+    // for the current agent. Used by the dashboard "Pending Replies" panel
+    // and ops health checks. Read-only: never mutates queue rows.
+    router.get('/delivery-queue', (_req, res) => {
+        const stateDir = ctx.config.stateDir;
+        const agentId = ctx.config.projectName;
+        if (!stateDir || !agentId) {
+            res.status(503).json({ error: 'state directory or agent id not configured' });
+            return;
+        }
+        const dbPath = resolvePendingRelayPath(stateDir, agentId);
+        let db = null;
+        try {
+            db = new Database(dbPath, { readonly: true, fileMustExist: true });
+            const totalRow = db.prepare('SELECT COUNT(*) AS n FROM entries').get();
+            const total = totalRow?.n ?? 0;
+            const byState = db.prepare('SELECT state, COUNT(*) AS n FROM entries GROUP BY state').all();
+            const oldestRow = db.prepare("SELECT MIN(attempted_at) AS oldest FROM entries WHERE state IN ('queued','claimed')").get();
+            const oldestAgeSeconds = oldestRow?.oldest
+                ? Math.max(0, Math.floor((Date.now() - Date.parse(oldestRow.oldest)) / 1000))
+                : 0;
+            res.json({
+                depth: total,
+                oldest_age_seconds: oldestAgeSeconds,
+                by_state: Object.fromEntries(byState.map((r) => [r.state, r.n])),
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // Missing-file is a normal "no queue yet" state — return zeros, not 500.
+            if (/unable to open|no such file|does not exist|cannot open/i.test(msg)) {
+                res.json({ depth: 0, oldest_age_seconds: 0, by_state: {} });
+                return;
+            }
+            res.status(500).json({ error: msg });
+        }
+        finally {
+            if (db) {
+                try {
+                    db.close();
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    });
     // POST /build/heartbeat — /build pipeline status relay.
     //
     // BUILD-STALL-VISIBILITY-SPEC Fix 2. The /build skill / build-state.py calls
@@ -3872,6 +4353,80 @@ export function createRoutes(ctx) {
         }
         res.json(ctx.telegram.getLogStats());
     });
+    // ── Threadline → Telegram Bridge: settings surface ─────────────
+    //
+    // Read/write toggles + allow-list/deny-list that gate the bridge module
+    // (deliverable b). Default-OFF auto-create is a hard requirement — these
+    // endpoints are how the user opts in. Bearer-auth enforced globally.
+    router.get('/threadline/telegram-bridge/config', (_req, res) => {
+        if (!ctx.telegramBridgeConfig) {
+            res.status(503).json({ error: 'Telegram bridge config not initialized' });
+            return;
+        }
+        res.json(ctx.telegramBridgeConfig.getSettings());
+    });
+    // ── Threadline observability — read-only views over inbox/outbox/bindings ──
+    router.get('/threadline/observability/threads', (req, res) => {
+        if (!ctx.threadlineObservability) {
+            res.status(503).json({ error: 'Threadline observability not initialized' });
+            return;
+        }
+        const remoteAgent = typeof req.query.remoteAgent === 'string' ? req.query.remoteAgent : undefined;
+        const sinceIso = typeof req.query.since === 'string' ? req.query.since : undefined;
+        const untilIso = typeof req.query.until === 'string' ? req.query.until : undefined;
+        const hasTopicRaw = typeof req.query.hasTopic === 'string' ? req.query.hasTopic : undefined;
+        const hasTopic = hasTopicRaw === 'yes' || hasTopicRaw === 'no' ? hasTopicRaw : undefined;
+        const threads = ctx.threadlineObservability.listThreads({ remoteAgent, sinceIso, untilIso, hasTopic });
+        res.json({ threads, count: threads.length });
+    });
+    router.get('/threadline/observability/threads/:threadId', (req, res) => {
+        if (!ctx.threadlineObservability) {
+            res.status(503).json({ error: 'Threadline observability not initialized' });
+            return;
+        }
+        const detail = ctx.threadlineObservability.getThread(req.params.threadId);
+        if (!detail) {
+            res.status(404).json({ error: 'Thread not found' });
+            return;
+        }
+        res.json(detail);
+    });
+    router.get('/threadline/observability/search', (req, res) => {
+        if (!ctx.threadlineObservability) {
+            res.status(503).json({ error: 'Threadline observability not initialized' });
+            return;
+        }
+        const q = typeof req.query.q === 'string' ? req.query.q : '';
+        const limitRaw = typeof req.query.limit === 'string' ? parseInt(req.query.limit, 10) : 50;
+        const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? Math.min(limitRaw, 200) : 50;
+        const hits = ctx.threadlineObservability.searchMessages(q, limit);
+        res.json({ hits, count: hits.length });
+    });
+    router.patch('/threadline/telegram-bridge/config', (req, res) => {
+        if (!ctx.telegramBridgeConfig) {
+            res.status(503).json({ error: 'Telegram bridge config not initialized' });
+            return;
+        }
+        try {
+            const body = req.body;
+            const patch = {};
+            if ('enabled' in body)
+                patch.enabled = body.enabled;
+            if ('autoCreateTopics' in body)
+                patch.autoCreateTopics = body.autoCreateTopics;
+            if ('mirrorExisting' in body)
+                patch.mirrorExisting = body.mirrorExisting;
+            if ('allowList' in body)
+                patch.allowList = body.allowList;
+            if ('denyList' in body)
+                patch.denyList = body.denyList;
+            const settings = ctx.telegramBridgeConfig.update(patch);
+            res.json(settings);
+        }
+        catch (err) {
+            res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
     // ── Slack ──────────────────────────────────────────────────────
     router.post('/slack/reply/:channelId', async (req, res) => {
         if (!ctx.slack) {
@@ -8056,9 +8611,8 @@ export function createRoutes(ctx) {
             auth.deprovision();
             // Clear submissions log
             const submissionsLog = path.join(ctx.config.stateDir, 'telemetry', 'submissions.jsonl');
-            // safe-git-allow: incremental-migration
             try {
-                fs.unlinkSync(submissionsLog);
+                SafeFsExecutor.safeUnlinkSync(submissionsLog, { operation: 'src/server/routes.ts:8932' });
             }
             catch { /* may not exist */ }
             // Update config.json
@@ -9257,6 +9811,37 @@ export function createRoutes(ctx) {
                                                         : tl?.handled === false ? 'queued (no live session)'
                                                             : 'accepted';
                                     console.log(`[relay-send] Local delivery to ${localTarget.name}:${localTarget.port} (thread: ${effectiveThreadId}) — ${outcome}`);
+                                    // Canonical outbox write — single source of truth for outbound messages
+                                    // across BOTH delivery paths (local + relay). Powers the dashboard
+                                    // observability tab. Mirrors the inbound canonical write from PR #113.
+                                    if (ctx.listenerManager) {
+                                        try {
+                                            ctx.listenerManager.appendCanonicalOutboxEntry({
+                                                from: ctx.config.projectName ?? 'self',
+                                                senderName: ctx.config.projectName ?? 'self',
+                                                to: localTarget.name,
+                                                recipientName: localTarget.name,
+                                                threadId: effectiveThreadId,
+                                                text: message,
+                                                messageId: msgId,
+                                                outcome,
+                                            });
+                                        }
+                                        catch (err) {
+                                            console.warn(`[relay-send] Canonical outbox append failed (non-fatal): ${err instanceof Error ? err.message : err}`);
+                                        }
+                                    }
+                                    // Mirror outbound into Telegram bridge (relay-only — best effort).
+                                    if (ctx.telegramBridge) {
+                                        ctx.telegramBridge.mirrorOutbound({
+                                            threadId: effectiveThreadId,
+                                            remoteAgent: localTarget.name,
+                                            remoteAgentName: localTarget.name,
+                                            text: message,
+                                            messageId: msgId,
+                                            outcome,
+                                        }).catch(() => { });
+                                    }
                                     if (waitForReply) {
                                         const reply = await waitForThreadlineReply(ctx, localTarget.name, effectiveThreadId, timeoutSeconds);
                                         res.json({
@@ -9314,6 +9899,36 @@ export function createRoutes(ctx) {
             }
             const relayMsgId = relayClient.sendAuto(resolvedId, message, threadId);
             const effectiveRelayThreadId = threadId ?? relayMsgId;
+            // Canonical outbox write for the relay-delivery path — same shape as the
+            // local-delivery path above, so the observability tab sees both paths.
+            if (ctx.listenerManager) {
+                try {
+                    ctx.listenerManager.appendCanonicalOutboxEntry({
+                        from: ctx.config.projectName ?? 'self',
+                        senderName: ctx.config.projectName ?? 'self',
+                        to: resolvedId,
+                        recipientName: targetAgent,
+                        threadId: effectiveRelayThreadId,
+                        text: message,
+                        messageId: relayMsgId,
+                        outcome: 'relay-sent',
+                    });
+                }
+                catch (err) {
+                    console.warn(`[relay-send] Canonical outbox append failed (non-fatal): ${err instanceof Error ? err.message : err}`);
+                }
+            }
+            // Mirror outbound into Telegram bridge (relay-only — best effort).
+            if (ctx.telegramBridge) {
+                ctx.telegramBridge.mirrorOutbound({
+                    threadId: effectiveRelayThreadId,
+                    remoteAgent: resolvedId,
+                    remoteAgentName: targetAgent,
+                    text: message,
+                    messageId: relayMsgId,
+                    outcome: 'relay-sent',
+                }).catch(() => { });
+            }
             if (waitForReply) {
                 const reply = await waitForThreadlineReply(ctx, resolvedId, effectiveRelayThreadId, timeoutSeconds);
                 res.json({