@desplega.ai/agent-swarm 1.161.0 → 1.162.0

package/src/tests/workflow-agent-task-retry.test.ts

@@ -0,0 +1,363 @@
+import { afterAll, afterEach, beforeAll, describe, expect, spyOn, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { z } from "zod";
+import * as db from "../be/db";
+import {
+  cancelTask,
+  closeDb,
+  completeTask,
+  createWorkflow,
+  failTask,
+  getTaskById,
+  getTaskByWorkflowRunStepId,
+  getWorkflowRun,
+  getWorkflowRunStepsByRunId,
+  initDb,
+} from "../be/db";
+import type { AgentTask, WorkflowDefinition, WorkflowRunStep } from "../types";
+import { startWorkflowExecution } from "../workflows/engine";
+import { workflowEventBus } from "../workflows/event-bus";
+import { AgentTaskExecutor } from "../workflows/executors/agent-task";
+import {
+  BaseExecutor,
+  type ExecutorDependencies,
+  type ExecutorResult,
+} from "../workflows/executors/base";
+import { ExecutorRegistry } from "../workflows/executors/registry";
+import { recoverIncompleteRuns } from "../workflows/recovery";
+import { setupWorkflowResumeListener } from "../workflows/resume";
+import { startRetryPoller, stopRetryPoller } from "../workflows/retry-poller";
+import { interpolate } from "../workflows/template";
+
+const TEST_DB_PATH = "./test-workflow-agent-task-retry.sqlite";
+
+class NotifyStubExecutor extends BaseExecutor<
+  typeof NotifyStubExecutor.schema,
+  typeof NotifyStubExecutor.outSchema
+> {
+  static readonly schema = z.object({ channel: z.string(), template: z.string() });
+  static readonly outSchema = z.object({ sent: z.boolean() });
+
+  readonly type = "notify";
+  readonly mode = "instant" as const;
+  readonly configSchema = NotifyStubExecutor.schema;
+  readonly outputSchema = NotifyStubExecutor.outSchema;
+
+  protected async execute(): Promise<ExecutorResult<z.infer<typeof NotifyStubExecutor.outSchema>>> {
+    return { status: "success", output: { sent: true } };
+  }
+}
+
+const deps: ExecutorDependencies = {
+  db: db as typeof import("../be/db"),
+  eventBus: workflowEventBus,
+  interpolate: (template, ctx) => interpolate(template, ctx).result,
+};
+
+let registry: ExecutorRegistry;
+let teardownResumeListener: (() => void) | undefined;
+
+beforeAll(() => {
+  initDb(TEST_DB_PATH);
+  registry = new ExecutorRegistry();
+  registry.register(new NotifyStubExecutor(deps));
+  registry.register(new AgentTaskExecutor(deps));
+  teardownResumeListener = setupWorkflowResumeListener(workflowEventBus, registry);
+});
+
+afterEach(() => {
+  stopRetryPoller();
+});
+
+afterAll(async () => {
+  // Detach from the process-wide singleton bus (see setupWorkflowResumeListener).
+  teardownResumeListener?.();
+  stopRetryPoller();
+  closeDb();
+  await unlink(TEST_DB_PATH).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-wal`).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-shm`).catch(() => {});
+});
+
+let counter = 0;
+
+/** synthesize (agent-task) → done (notify); `retry` lands on the node itself. */
+async function startRun(opts: {
+  retry?: WorkflowDefinition["nodes"][number]["retry"];
+  onNodeFailure?: "fail" | "continue";
+}): Promise<string> {
+  counter++;
+  const workflow = await createWorkflow({
+    name: `agent-task-retry-${counter}-${Date.now()}`,
+    definition: {
+      ...(opts.onNodeFailure ? { onNodeFailure: opts.onNodeFailure } : {}),
+      nodes: [
+        {
+          id: "synthesize",
+          type: "agent-task",
+          config: { template: "Synthesize" },
+          ...(opts.retry ? { retry: opts.retry } : {}),
+          next: "done",
+        },
+        { id: "done", type: "notify", config: { channel: "swarm", template: "done" } },
+      ],
+    },
+  });
+  const runId = await startWorkflowExecution(workflow, {}, registry);
+  expect((await getWorkflowRun(runId))!.status).toBe("waiting");
+  return runId;
+}
+
+async function synthesizeStep(runId: string): Promise<WorkflowRunStep> {
+  const steps = await getWorkflowRunStepsByRunId(runId);
+  return steps.find((s) => s.nodeId === "synthesize")!;
+}
+
+async function waitFor<T>(
+  probe: () => Promise<T | null | undefined | false>,
+  label: string,
+  timeoutMs = 3000,
+): Promise<T> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const value = await probe();
+    if (value) return value;
+    await new Promise((r) => setTimeout(r, 10));
+  }
+  throw new Error(`Timed out waiting for ${label}`);
+}
+
+/** Wait until a task other than `previous` is bound to the step. */
+async function waitForRedrive(stepId: string, previous: AgentTask): Promise<AgentTask> {
+  return waitFor(async () => {
+    const bound = await getTaskByWorkflowRunStepId(stepId);
+    return bound && bound.id !== previous.id ? bound : null;
+  }, "redriven task");
+}
+
+const RETRY_ONCE = { maxRetries: 1, strategy: "static" as const, baseDelayMs: 0, maxDelayMs: 0 };
+
+describe("agent-task node.retry on task failure", () => {
+  test("a superseded task with retry {maxRetries:1} is redriven once and the run continues", async () => {
+    const runId = await startRun({ retry: RETRY_ONCE });
+    const step = await synthesizeStep(runId);
+    const first = (await getTaskByWorkflowRunStepId(step.id))!;
+
+    await failTask(first.id, "superseded_workflow_task");
+
+    // Queued for the poller: step failed with nextRetryAt, run not failed,
+    // failed task detached so the executor creates a fresh one.
+    const queued = await waitFor(async () => {
+      const s = await synthesizeStep(runId);
+      return s.status === "failed" && s.nextRetryAt != null ? s : null;
+    }, "step queued for retry");
+    expect(queued.retryCount).toBe(1);
+    expect(queued.error).toBe("superseded_workflow_task");
+    expect((await getWorkflowRun(runId))!.status).toBe("waiting");
+    expect((await getTaskById(first.id))!.workflowRunStepId).toBeFalsy();
+
+    startRetryPoller(registry, 10);
+    const second = await waitForRedrive(step.id, first);
+    expect(second.status).not.toBe("failed");
+    const waiting = await waitFor(async () => {
+      const s = await synthesizeStep(runId);
+      return s.status === "waiting" ? s : null;
+    }, "step waiting on redriven task");
+    expect(waiting.id).toBe(step.id);
+    stopRetryPoller();
+
+    await completeTask(second.id, "synthesis done");
+    const run = await waitFor(async () => {
+      const r = await getWorkflowRun(runId);
+      return r?.status === "completed" ? r : null;
+    }, "run completed");
+    expect(run.status).toBe("completed");
+    const steps = await getWorkflowRunStepsByRunId(runId);
+    expect(steps.filter((s) => s.nodeId === "synthesize")).toHaveLength(1);
+    expect(steps.find((s) => s.nodeId === "done")?.status).toBe("completed");
+  });
+
+  test("a second failure exhausts retries and falls through to onNodeFailure", async () => {
+    const runId = await startRun({ retry: RETRY_ONCE, onNodeFailure: "continue" });
+    const step = await synthesizeStep(runId);
+    const first = (await getTaskByWorkflowRunStepId(step.id))!;
+
+    await failTask(first.id, "superseded_workflow_task");
+    startRetryPoller(registry, 10);
+    const second = await waitForRedrive(step.id, first);
+    await waitFor(async () => {
+      const s = await synthesizeStep(runId);
+      return s.status === "waiting" ? s : null;
+    }, "step waiting on redriven task");
+    stopRetryPoller();
+
+    // A late duplicate event for the FIRST task must not consume the retry
+    // budget or touch the step now bound to the second task.
+    workflowEventBus.emit("task.failed", {
+      taskId: first.id,
+      failureReason: "duplicate",
+      workflowRunId: runId,
+      workflowRunStepId: step.id,
+    });
+    await new Promise((r) => setTimeout(r, 20));
+    expect((await synthesizeStep(runId)).status).toBe("waiting");
+
+    await failTask(second.id, "superseded_workflow_task");
+    const run = await waitFor(async () => {
+      const r = await getWorkflowRun(runId);
+      return r?.status === "completed" ? r : null;
+    }, "run completed via onNodeFailure:continue");
+    expect(run.status).toBe("completed");
+    const finalStep = await synthesizeStep(runId);
+    expect(finalStep.status).toBe("completed");
+    expect(finalStep.retryCount).toBe(1);
+    expect(finalStep.nextRetryAt).toBeFalsy();
+    expect(JSON.stringify(finalStep.output)).toContain("[FAILED:");
+    // No third task was ever created.
+    expect((await getTaskByWorkflowRunStepId(step.id))!.id).toBe(second.id);
+  });
+
+  test("a node without retry fails the run exactly as before", async () => {
+    const runId = await startRun({});
+    const step = await synthesizeStep(runId);
+    const first = (await getTaskByWorkflowRunStepId(step.id))!;
+
+    await failTask(first.id, "superseded_workflow_task");
+
+    const run = await waitFor(async () => {
+      const r = await getWorkflowRun(runId);
+      return r?.status === "failed" ? r : null;
+    }, "run failed");
+    expect(run.error).toContain("superseded_workflow_task");
+    const failedStep = await synthesizeStep(runId);
+    expect(failedStep.status).toBe("failed");
+    expect(failedStep.retryCount).toBe(0);
+    expect(failedStep.nextRetryAt).toBeFalsy();
+    expect((await getTaskByWorkflowRunStepId(step.id))!.id).toBe(first.id);
+  });
+
+  test("a cancelled task never retries, even with retry set", async () => {
+    const runId = await startRun({ retry: RETRY_ONCE });
+    const step = await synthesizeStep(runId);
+    const first = (await getTaskByWorkflowRunStepId(step.id))!;
+
+    await cancelTask(first.id, "operator cancel");
+
+    const run = await waitFor(async () => {
+      const r = await getWorkflowRun(runId);
+      return r?.status === "failed" ? r : null;
+    }, "run failed");
+    expect(run.error).toContain("cancelled");
+    const failedStep = await synthesizeStep(runId);
+    expect(failedStep.retryCount).toBe(0);
+    expect(failedStep.nextRetryAt).toBeFalsy();
+    expect((await getTaskByWorkflowRunStepId(step.id))!.id).toBe(first.id);
+  });
+
+  test("the recovery sweep applies the same retry when it sees the failed task first", async () => {
+    const runId = await startRun({ retry: RETRY_ONCE });
+    const step = await synthesizeStep(runId);
+    const first = (await getTaskByWorkflowRunStepId(step.id))!;
+
+    // Detach the live listener so only the heartbeat sweep sees the failure.
+    teardownResumeListener?.();
+    try {
+      await failTask(first.id, "superseded_workflow_task");
+      await new Promise((r) => setTimeout(r, 20));
+      await recoverIncompleteRuns(registry);
+    } finally {
+      teardownResumeListener = setupWorkflowResumeListener(workflowEventBus, registry);
+    }
+
+    const queued = await synthesizeStep(runId);
+    expect(queued.status).toBe("failed");
+    expect(queued.nextRetryAt).toBeTruthy();
+    expect(queued.retryCount).toBe(1);
+    expect((await getWorkflowRun(runId))!.status).toBe("waiting");
+
+    startRetryPoller(registry, 10);
+    const second = await waitForRedrive(step.id, first);
+    expect(second.id).not.toBe(first.id);
+  });
+});
+
+describe("recovery sweep holding a stale failed-task snapshot", () => {
+  /**
+   * Recovery snapshots task A as failed, then pauses. Meanwhile the live
+   * task.failed handler queues A's retry and the poller binds task B to the
+   * same step, back in `waiting`. When recovery resumes on its stale A row it
+   * must leave the step bound to B alone.
+   */
+  async function raceStaleRecovery(maxRetries: number) {
+    const runId = await startRun({ retry: { ...RETRY_ONCE, maxRetries } });
+    const step = await synthesizeStep(runId);
+    const first = (await getTaskByWorkflowRunStepId(step.id))!;
+
+    let releaseSnapshot!: () => void;
+    const snapshotHeld = new Promise<void>((r) => {
+      releaseSnapshot = r;
+    });
+    let snapshotTaken!: () => void;
+    const snapshotReady = new Promise<void>((r) => {
+      snapshotTaken = r;
+    });
+    const realGetStuck = db.getStuckWorkflowRuns;
+    const spy = spyOn(db, "getStuckWorkflowRuns").mockImplementation(async () => {
+      const rows = await realGetStuck();
+      snapshotTaken();
+      await snapshotHeld;
+      return rows;
+    });
+
+    let recovery: Promise<unknown> | undefined;
+    try {
+      // Fail A with the listener detached so the sweep's snapshot sees it.
+      teardownResumeListener?.();
+      try {
+        await failTask(first.id, "superseded_workflow_task");
+        recovery = recoverIncompleteRuns(registry);
+        await snapshotReady;
+      } finally {
+        teardownResumeListener = setupWorkflowResumeListener(workflowEventBus, registry);
+      }
+
+      // The live event for A arrives late: retry queued, B dispatched.
+      workflowEventBus.emit("task.failed", {
+        taskId: first.id,
+        failureReason: "superseded_workflow_task",
+        workflowRunId: runId,
+        workflowRunStepId: step.id,
+      });
+      startRetryPoller(registry, 10);
+      const second = await waitForRedrive(step.id, first);
+      await waitFor(async () => {
+        const s = await synthesizeStep(runId);
+        return s.status === "waiting" ? s : null;
+      }, "step waiting on redriven task");
+      stopRetryPoller();
+
+      releaseSnapshot();
+      await recovery;
+      recovery = undefined;
+
+      const after = await synthesizeStep(runId);
+      expect(after.status).toBe("waiting");
+      expect(after.retryCount).toBe(1);
+      expect(after.nextRetryAt).toBeFalsy();
+      expect((await getWorkflowRun(runId))!.status).toBe("waiting");
+      expect((await getTaskByWorkflowRunStepId(step.id))!.id).toBe(second.id);
+    } finally {
+      releaseSnapshot();
+      await recovery;
+      spy.mockRestore();
+    }
+  }
+
+  test("with retries left, the stale snapshot does not consume another retry", async () => {
+    await raceStaleRecovery(3);
+  });
+
+  test("with retries exhausted, the stale snapshot does not route onNodeFailure", async () => {
+    await raceStaleRecovery(1);
+  });
+});

package/src/tests/workflow-definition-telemetry.test.ts

@@ -44,7 +44,7 @@ describe("workflow definition telemetry", () => {
     await removeTestDb();
   });
 
-  test("emits workflow.created with definition size and known source", async () => {
+  test("emits workflow.created with definition size and known interface (via)", async () => {
     const workflow = await createWorkflow(
       {
         name: "created telemetry",
@@ -65,7 +65,7 @@ describe("workflow definition telemetry", () => {
         props: {
           workflowId: workflow.id,
           nodeCount: 2,
-          source: "api",
+          via: "api",
         },
       },
     ]);
@@ -91,13 +91,13 @@ describe("workflow definition telemetry", () => {
         event: "deleted",
         props: {
           workflowId: workflow.id,
-          source: "mcp",
+          via: "mcp",
         },
       },
     ]);
   });
 
-  test("omits source for direct internal workflow mutations", async () => {
+  test("omits via for direct internal workflow mutations", async () => {
     const workflow = await createWorkflow({
       name: "internal telemetry",
       definition: { nodes: [] },

package/src/tools/poll-task.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { addMinutes } from "date-fns";
 import * as z from "zod";
+import { isApiDraining } from "@/be/api-drain";
 import {
   getActiveTaskCount,
   getAgentById,
@@ -132,7 +133,9 @@ export const registerPollTaskTool = (server: McpServer) => {
       while (new Date() < maxTime) {
         // Fetch and update in a single transaction to avoid race conditions
         const outcome = await getDbClient().transaction(
-          async (): Promise<AgentTask | "at-capacity" | "runtime-unavailable" | null> => {
+          async (): Promise<
+            AgentTask | "at-capacity" | "runtime-unavailable" | "draining" | null
+          > => {
             // The entry gate only proves liveness when the long poll began;
             // the runtime must be live at the exact moment work is acquired,
             // so revalidate in the same transaction that can start the task.
@@ -147,6 +150,9 @@ export const registerPollTaskTool = (server: McpServer) => {
               return "runtime-unavailable";
             }
 
+            // A draining API dispatches nothing; see src/be/api-drain.ts.
+            if (isApiDraining()) return "draining";
+
             const agentNow = (await getAgentById(agentId))!;
 
             if (agentNow.status !== "busy") {
@@ -188,6 +194,19 @@ export const registerPollTaskTool = (server: McpServer) => {
           });
         }
 
+        if (outcome === "draining") {
+          // Like a runtime refusal, this is not an empty poll: skip the exit counter.
+          return toolOk("No task available.", {
+            details: "The API is draining for a restart and dispatches no new work. Retry shortly.",
+            data: {
+              yourAgentId: requestInfo.agentId,
+              offeredTasks: [],
+              availableCount: 0,
+              waitedForSeconds: Math.round((Date.now() - now.getTime()) / 1000),
+            },
+          });
+        }
+
         if (outcome === "at-capacity") {
           // A capacity refusal is not an empty poll (refused ≠ empty, D-R3):
           // return without advancing the exit counter.

package/src/tools/send-task.ts

@@ -15,6 +15,7 @@ import {
   getUserById,
   hasCapacity,
   isExtensionAgent,
+  isLinearTrackerContextKey,
 } from "@/be/db";
 import { repointTrackerSyncBySwarmId } from "@/be/db-queries/tracker";
 import { explicitModelErrorForAgent } from "@/be/model-validation";
@@ -467,11 +468,12 @@ export async function sendTaskHandler(
   } | null> => {
     const existingTrackerWork = await findExistingLinearTrackerContextWork(
       effectiveParentTask?.contextKey,
+      effectiveParentTask?.id,
     );
     if (existingTrackerWork) {
       const msg = `Skipped: Linear tracker contextKey ${effectiveParentTask?.contextKey} already has ${existingTrackerWork.reason === "active_task" ? "active task" : "linked open PR"} ${existingTrackerWork.task.id.slice(0, 8)}.`;
       console.log(`[send-task] ${msg}`);
-      return { ok: true, message: msg, task: existingTrackerWork.task };
+      return { ok: false, message: msg, task: existingTrackerWork.task };
     }
 
     // Dedup guard: check for similar recent tasks
@@ -559,6 +561,12 @@ export async function sendTaskHandler(
     const raced = await evaluateDedupGuards();
     if (raced) return { success: raced.ok, message: raced.message, task: raced.task };
 
+    // This transaction already checked the tracker key, excluding the caller's
+    // lineage. The creation guard would otherwise match work in that lineage.
+    if (isLinearTrackerContextKey(effectiveParentTask?.contextKey)) {
+      taskOptions.bypassTrackerContextDedup = true;
+    }
+
     // If no agentId (and no auto-routed agentId), create an unassigned task for the pool
     const targetAgentId = taskOptions.offeredTo ?? taskOptions.agentId ?? undefined;
     if (!targetAgentId) {

package/src/tools/task-action.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
+import { isApiDraining } from "@/be/api-drain";
 import { AssetKeyAuthorizationError, authorizeAssetKeyWrite } from "@/be/asset-key-auth";
 import { resolveTaskAuditUserId } from "@/be/audit-user";
 import { canClaim } from "@/be/budget-admission";
@@ -177,6 +178,14 @@ async function staleRuntimeResult(ctx: ToolCtx, agentId: string): Promise<TaskAc
   };
 }
 
+/** A draining API dispatches nothing (src/be/api-drain.ts); claim and accept wait for the next API. */
+function apiDrainingResult(action: "claim" | "accept"): TaskActionResult {
+  return {
+    success: false,
+    message: `The API is draining for a restart and dispatches no new work, so this ${action} was not made. Retry shortly.`,
+  };
+}
+
 function taskActionResult(result: TaskActionResult, agentId?: string): SwarmToolResult {
   const { refusalSideEffects: _omit, success, message, ...rest } = result;
   const data = {
@@ -353,6 +362,7 @@ export async function taskActionHandler(
         }
         const staleClaimRuntime = await staleRuntimeResult(ctx, agentId);
         if (staleClaimRuntime) return staleClaimRuntime;
+        if (isApiDraining()) return apiDrainingResult("claim");
         // Check capacity before claiming
         if (!(await hasCapacity(agentId))) {
           const activeCount = await getActiveTaskCount(agentId);
@@ -462,6 +472,7 @@ export async function taskActionHandler(
         // budget admission below so a retired process cannot take the offer.
         const staleAcceptRuntime = await staleRuntimeResult(ctx, agentId);
         if (staleAcceptRuntime) return staleAcceptRuntime;
+        if (isApiDraining()) return apiDrainingResult("accept");
         const existingTask = await getTaskById(taskId);
         if (!existingTask) {
           return { success: false, message: `Task "${taskId}" not found.` };

package/src/types.ts

@@ -364,6 +364,7 @@ export const AgentTaskSourceSchema = z.enum([
   "workflow",
   "linear",
   "jira",
+  "comb",
 ]);
 export type AgentTaskSource = z.infer<typeof AgentTaskSourceSchema>;
 
@@ -1045,7 +1046,7 @@ export type InboxItemState = z.infer<typeof InboxItemStateSchema>;
 // User Favorites (principal-scoped stars for app navigation)
 // ============================================================================
 
-export const FavoriteItemTypeSchema = z.enum(["page", "workflow", "schedule"]);
+export const FavoriteItemTypeSchema = z.enum(["page", "workflow", "schedule", "agent-fs-path"]);
 export type FavoriteItemType = z.infer<typeof FavoriteItemTypeSchema>;
 
 export const UserFavoriteSchema = z

package/src/utils/api-drain.ts

@@ -0,0 +1,24 @@
+/**
+ * Wire contract for the API drain, shared by the API server and the workers.
+ * Keep this file free of DB and server imports: `src/commands/` reads it.
+ *
+ * While the API is draining (SIGTERM received, still serving) it adds
+ * `X-Swarm-Draining: 1` to every response. A worker that sees the header hands
+ * off its in-flight tasks and stops taking new ones. An API that never drains
+ * never sends the header, so older and newer sides interoperate unchanged.
+ */
+
+export const API_DRAINING_HEADER = "X-Swarm-Draining";
+
+/**
+ * Upper bound for `API_DRAIN_MAX_MS`. The config validator and the resolver in
+ * `src/be/api-drain.ts` both read it, so the config API cannot accept a value
+ * the shutdown path would clamp. Keep the API's `stop_grace_period` above the
+ * cap plus the time the API needs to close.
+ */
+export const API_DRAIN_MAX_MS_LIMIT = 120_000;
+
+/** True when an API response carries the drain header. */
+export function isApiDrainingResponse(response: { headers: Headers }): boolean {
+  return response.headers.get(API_DRAINING_HEADER) === "1";
+}

package/src/utils/constants.ts

@@ -2,6 +2,8 @@
  * Shared constants used across worker- and server-side code.
  */
 
+import { isEnvFlagEnabled } from "./env-flag";
+
 /** Maximum profile-file length in JavaScript characters (not UTF-8 bytes). */
 export const MAX_PROFILE_FILE_LENGTH = 256 * 1024;
 
@@ -106,20 +108,24 @@ export function getAgentFsDefaultDriveId(): string | undefined {
   return raw || undefined;
 }
 
-/**
- * Resolve a public agent-fs live URL for an attachment when we have enough
- * info — `path` plus a matched `orgId`/`driveId` pair. When a row supplies
- * neither ID, the pair may come from env-var defaults. A partial row never
- * mixes its ID with a default; callers fall back to the raw
- * `agent-fs:<path>` display instead.
- *
- * Shape:  ${liveHost}/file/~/<orgId>/<driveId>/<normalized-path>
- */
-export function buildAgentFsLiveUrl(opts: {
+/** An agent-fs file for a link: its path plus an optional org/drive pair. */
+export interface AgentFsFileRef {
   path?: string | null;
   orgId?: string | null;
   driveId?: string | null;
-}): string | null {
+}
+
+/** A "." or ".." path segment, raw or encoded (`%2e`). */
+const DOT_SEGMENT_RE = /^(?:\.|%2e){1,2}$/i;
+
+/**
+ * `<orgId>/<driveId>/<encoded-path>` for an agent-fs file link, when we have
+ * enough info: `path` plus a matched `orgId`/`driveId` pair. When a row
+ * supplies neither ID, the pair may come from env-var defaults. A partial row
+ * never mixes its ID with a default. A "." or ".." segment returns null: the
+ * browser would resolve it to a path outside the drive.
+ */
+export function agentFsFileRoute(opts: AgentFsFileRef): string | null {
   const path = opts.path?.trim();
   if (!path) return null;
   const rowOrgId = opts.orgId?.trim();
@@ -128,13 +134,48 @@ export function buildAgentFsLiveUrl(opts: {
   const orgId = hasRowId ? rowOrgId : getAgentFsDefaultOrgId();
   const driveId = hasRowId ? rowDriveId : getAgentFsDefaultDriveId();
   if (!orgId || !driveId) return null;
-  const host = getAgentFsLiveUrl();
-  const normalizedPath = path.replace(/^\/+/, "");
+  const segments = path.replace(/^\/+/, "").split("/");
+  if (segments.some((segment) => DOT_SEGMENT_RE.test(segment))) return null;
   // Never double-encode an already-encoded segment: preserve existing %HH
   // escapes byte-for-byte, including in segments that also contain raw text.
-  const encodedPath = normalizedPath
-    .split("/")
+  const encodedPath = segments
     .map((segment) => encodeURIComponent(segment).replace(/%25([0-9a-f]{2})/gi, "%$1"))
     .join("/");
-  return `${host}/file/~/${orgId}/${driveId}/${encodedPath}`;
+  return `${orgId}/${driveId}/${encodedPath}`;
+}
+
+/**
+ * Resolve a public agent-fs live URL for an attachment (see
+ * {@link agentFsFileRoute} for the id, dot-segment, and encoding rules). Null
+ * when that route is null; callers fall back to the raw `agent-fs:<path>`
+ * display instead.
+ *
+ * Shape:  ${liveHost}/file/~/<orgId>/<driveId>/<normalized-path>
+ */
+export function buildAgentFsLiveUrl(opts: AgentFsFileRef): string | null {
+  const route = agentFsFileRoute(opts);
+  return route ? `${getAgentFsLiveUrl()}/file/~/${route}` : null;
+}
+
+/**
+ * Comb (the agent-fs review space in the dashboard) is on: `COMB_ENABLED` plus
+ * an agent-fs API URL. `getCombConfig()` (`src/comb/config.ts`) reports it.
+ */
+export function isCombEnabled(): boolean {
+  const apiUrl = process.env.AGENT_FS_API_URL?.trim().replace(/\/+$/, "");
+  return isEnvFlagEnabled("COMB_ENABLED", false) && Boolean(apiUrl);
+}
+
+/**
+ * The dashboard (Comb) URL for an agent-fs file, same id and encoding rules as
+ * {@link buildAgentFsLiveUrl}. Null unless Comb is on AND an explicit
+ * `APP_URL` / `DASHBOARD_URL` is set: the hosted default dashboard cannot open
+ * a self-hosted swarm's files.
+ *
+ * Shape:  ${appUrl}/file/~/<orgId>/<driveId>/<normalized-path>
+ */
+export function buildCombFileUrl(opts: AgentFsFileRef): string | null {
+  if (!isCombEnabled() || getConfiguredAppUrls().length === 0) return null;
+  const route = agentFsFileRoute(opts);
+  return route ? `${getAppUrl()}/file/~/${route}` : null;
 }