@desplega.ai/agent-swarm 1.135.2 → 1.136.0

package/src/http/route-def.ts

@@ -179,19 +179,85 @@ export interface RequestRouteDescriptor {
    * `{METHOD} {route-template}`.
    *
    * - Matched `route()` handler: `GET /api/tasks/{id}`
-   * - Unmatched (core /health /ping /me, MCP transport, 404s): `GET /<first-segment>`
+   * - Static core path (see `CORE_ROUTE_TEMPLATES`): `GET /health`, `POST /mcp`
+   * - Otherwise unmatched (deeper MCP paths, 404s): `GET /<first-segment>`
    * - Root or empty path: bare `GET`
    */
   spanName: string;
   /**
    * Value for the `http.route` span attribute — the bounded-cardinality route
-   * template (e.g. `/api/tasks/{id}`). Set ONLY when a `route()` handler
-   * matched; left `undefined` for core/MCP/404 paths so callers omit the
-   * attribute rather than fabricating a value.
+   * template (e.g. `/api/tasks/{id}`). Set when a `route()` handler matched,
+   * or when the request matches a static core path in `CORE_ROUTE_TEMPLATES`
+   * on a method and query-string form that handler actually accepts. Left
+   * `undefined` for genuinely unmatched paths so callers omit the attribute
+   * rather than fabricating a value.
    */
   httpRoute?: string;
 }
 
+/**
+ * Static literal paths handled outside the `route()` factory (core.ts, mcp.ts)
+ * that would otherwise fall through to the low-cardinality `{METHOD}
+ * /{first-segment}` fallback below. Each of these is a single, fixed path —
+ * not a template with params — so mapping it to `http.route` is not
+ * fabricating a value, just naming a route that doesn't happen to go through
+ * `route()`. `/health` in particular is high-volume liveness-probe traffic;
+ * leaving it in the anonymous `GET` bucket makes that bucket useless to
+ * aggregate on.
+ *
+ * `methods` mirrors the method gate `handleCore` actually applies to that
+ * path — `undefined` means `handleCore` has no method check there (the
+ * handler runs for any verb). A method NOT in this list is a path
+ * `handleCore` 404s, so it must not carry `http.route` either — otherwise the
+ * attribute lies about a request that never matched a real handler.
+ *
+ * `toleratesQueryString` mirrors whether `handleCore` matches the path when
+ * the raw URL carries a `?`. Most of these entries compare the raw URL with
+ * strict equality (`req.url === "/health"` and similarly for
+ * `openapi.json`/`docs`/`internal/reload-config`/`mcp`/`mcp-user`), so
+ * `GET /health?t=123` 404s in `handleCore` even though `pathSegments` still
+ * resolves to `health`. `/me` and `/cancelled-tasks` explicitly accept the
+ * `?`-suffixed form (`req.url === "/me" || req.url?.startsWith("/me?")`), so
+ * those two tolerate a query string. Default is `false` (no tolerance) —
+ * verified against every comparison in `src/http/core.ts`, `src/http/mcp.ts`,
+ * and `src/http/mcp-user.ts`.
+ *
+ * `toleratesTrailingSlash` mirrors the same strict-equality problem for a
+ * trailing `/`: `getPathSegments("/health/")` returns `["health"]` (trailing
+ * empty segment is filtered), so without this gate a `GET /health/` request —
+ * which `handleCore` 404s on `req.url === "/health"` strict equality — would
+ * still get `http.route: "/health"` fabricated onto its span. `docs` is the
+ * one intentional exception: `handleCore` explicitly accepts
+ * `req.url === "/docs" || req.url === "/docs/"`. Default is `false`.
+ *
+ * Keyed by the joined path segments (no leading slash, no query string) so a
+ * deeper unmatched path under the same first segment — e.g.
+ * `/mcp/<session>/messages` — does NOT match and correctly falls through to
+ * the bounded first-segment fallback instead of fabricating a template.
+ */
+const CORE_ROUTE_TEMPLATES: Record<
+  string,
+  {
+    path: string;
+    methods?: string[];
+    toleratesQueryString?: boolean;
+    toleratesTrailingSlash?: boolean;
+  }
+> = {
+  health: { path: "/health" },
+  "openapi.json": { path: "/openapi.json" },
+  docs: { path: "/docs", toleratesTrailingSlash: true },
+  me: { path: "/me", methods: ["GET"], toleratesQueryString: true },
+  "cancelled-tasks": {
+    path: "/cancelled-tasks",
+    methods: ["GET"],
+    toleratesQueryString: true,
+  },
+  "internal/reload-config": { path: "/internal/reload-config", methods: ["POST"] },
+  mcp: { path: "/mcp", methods: ["GET", "POST", "DELETE"] },
+  "mcp-user": { path: "/mcp-user", methods: ["GET", "POST", "DELETE"] },
+};
+
 /**
  * Describe an inbound HTTP request for OTel: a low-cardinality span name plus
  * the `http.route` attribute value (per the HTTP server semantic conventions).
@@ -199,14 +265,37 @@ export interface RequestRouteDescriptor {
  * Never embeds raw path params or query strings — the goal is one span name and
  * one `http.route` value per endpoint so SigNoz can group/filter/aggregate by
  * them. The raw path is still preserved on the `url.path` attribute.
+ *
+ * `hasQueryString` reflects whether the raw request URL carried a `?`. A
+ * core-route entry without `toleratesQueryString` is a path `handleCore`
+ * 404s once a query string is present (see `CORE_ROUTE_TEMPLATES`), so that
+ * combination must not carry `http.route` either — same "omitted, never
+ * fabricated" contract as the method-mismatch case above it.
+ *
+ * `hasTrailingSlash` reflects whether the raw request path (query string
+ * excluded) ended in `/` for a path with more than one character — i.e. `/`
+ * itself is not "trailing slash". A core-route entry without
+ * `toleratesTrailingSlash` is a path `handleCore` 404s once a trailing slash
+ * is present, so that combination must not carry `http.route` either.
  */
 export function describeRequestRoute(
   method: string | undefined,
   pathSegments: string[],
+  hasQueryString = false,
+  hasTrailingSlash = false,
 ): RequestRouteDescriptor {
   const m = (method ?? "").toUpperCase() || "UNKNOWN";
   const matched = findRoute(method, pathSegments);
   if (matched) return { spanName: `${m} ${matched.path}`, httpRoute: matched.path };
+  const coreTemplate = CORE_ROUTE_TEMPLATES[pathSegments.join("/")];
+  if (
+    coreTemplate &&
+    (!coreTemplate.methods || coreTemplate.methods.includes(m)) &&
+    (!hasQueryString || coreTemplate.toleratesQueryString) &&
+    (!hasTrailingSlash || coreTemplate.toleratesTrailingSlash)
+  ) {
+    return { spanName: `${m} ${coreTemplate.path}`, httpRoute: coreTemplate.path };
+  }
   const first = pathSegments[0];
   return { spanName: first ? `${m} /${first}` : m };
 }

package/src/http/stats.ts

@@ -11,6 +11,7 @@ import {
   getTaskStats,
   withFavoriteFlags,
 } from "../be/db";
+import { getDbRetentionStats } from "../be/db-retention";
 import { isSteeringEnabled } from "../be/steering";
 import type { AgentLog } from "../types";
 import { AgentLogSchema, ScheduledTaskSchema, ServiceSchema } from "../types";
@@ -57,6 +58,38 @@ const SwarmMetricsSchema = z.object({
   pages: z.object({ total: z.number() }),
   sessions: z.object({ active: z.number() }),
   skills: z.object({ total: z.number() }),
+  retention: z.object({
+    sessionLogs: z
+      .object({
+        at: z.string(),
+        rowsDeleted: z.number(),
+        batches: z.number(),
+        durationMs: z.number(),
+        dryRun: z.boolean(),
+        cumulativeRowsDeleted: z.number(),
+      })
+      .optional(),
+    agentLog: z
+      .object({
+        at: z.string(),
+        rowsDeleted: z.number(),
+        batches: z.number(),
+        durationMs: z.number(),
+        dryRun: z.boolean(),
+        cumulativeRowsDeleted: z.number(),
+      })
+      .optional(),
+    events: z
+      .object({
+        at: z.string(),
+        rowsDeleted: z.number(),
+        batches: z.number(),
+        durationMs: z.number(),
+        dryRun: z.boolean(),
+        cumulativeRowsDeleted: z.number(),
+      })
+      .optional(),
+  }),
 });
 
 /** Mirrors `ConcurrentContext` (src/be/db.ts). */
@@ -242,7 +275,10 @@ export async function handleStats(
   }
 
   if (getMetrics.match(req.method, pathSegments)) {
-    getMetrics.respond(res, 200, await getSwarmMetrics());
+    getMetrics.respond(res, 200, {
+      ...(await getSwarmMetrics()),
+      retention: getDbRetentionStats(),
+    });
     return true;
   }
 

package/src/http/tasks.ts

@@ -24,6 +24,7 @@ import {
   markSteeringDelivered,
   markSteeringHandled,
   pauseTask,
+  promoteDraftTask,
   resumeTask,
   supersedeTask,
   updateAgentStatusFromCapacity,
@@ -233,6 +234,14 @@ const createTask = route({
     model: z.string().optional(),
     modelTier: ModelTierSchema.optional(),
     effort: ReasoningEffortSchema.optional(),
+    /**
+     * Create in `draft` status instead of the normal pending/unassigned/offered
+     * status (#1240) — the task exists and is visible to its owner, but is not
+     * dispatch-eligible. Used by the UI composer while attachments are still
+     * uploading; the caller MUST promote it via `POST /api/tasks/{id}/promote-draft`
+     * once the upload batch settles (or it self-promotes on a timeout).
+     */
+    draft: z.boolean().optional(),
   }),
   responses: {
     201: { description: "Task created", schema: AgentTaskSchema },
@@ -240,6 +249,23 @@ const createTask = route({
   },
 });
 
+const promoteDraftTaskRoute = route({
+  method: "post",
+  path: "/api/tasks/{id}/promote-draft",
+  pattern: ["api", "tasks", null, "promote-draft"],
+  summary: "Promote a draft task out of the pre-dispatch draft state",
+  description:
+    "Transitions a `draft` task (#1240 — created with attachments still uploading) to its normal dispatch-eligible status: `offered` if it was offered to an agent, `pending` if it has an owning agent (the common case — UI-composer tasks default to Lead), otherwise `unassigned`. Called by the UI composer once its attachment upload batch settles, whether every file uploaded, some failed, or all failed — a draft must never be stranded by an upload error. Idempotent: calling it on a task that already left `draft` returns the current task unchanged rather than erroring, so a retried request is safe.",
+  tags: ["Tasks"],
+  params: z.object({ id: z.string() }),
+  rbac: { permission: "task.action.own" },
+  responses: {
+    200: { description: "Task promoted (or already out of draft)", schema: AgentTaskSchema },
+    403: { description: "Caller does not own this task" },
+    404: { description: "Task not found" },
+  },
+});
+
 const updateSession = route({
   method: "put",
   path: "/api/tasks/{id}/session",
@@ -621,6 +647,42 @@ async function canSteerTask(
   return can({ principal, verb, resource, source: "http" }).allow;
 }
 
+/**
+ * Ownership gate for `task.action.own` — single verb, no `.any` counterpart:
+ * the underlying `requester-owns-task` policy already lets any non-user
+ * principal (agent/operator) through, so agent-side callers never need a
+ * separate escalated verb. User principals must match the task's
+ * `requestedByUserId`. Used by `POST /api/tasks/{id}/promote-draft`.
+ */
+async function canActOnOwnTask(
+  req: IncomingMessage,
+  myAgentId: string | undefined,
+  task: AgentTask,
+): Promise<boolean> {
+  const resource: RbacResource = {
+    kind: "task",
+    taskId: task.id,
+    requestedByUserId: task.requestedByUserId,
+    creatorAgentId: task.creatorAgentId,
+    agentId: task.agentId,
+  };
+  let principal: RbacPrincipal;
+
+  const auth = getRequestAuth(req);
+  if (auth?.kind === "operator") {
+    principal = { kind: "operator" };
+  } else if (auth?.kind === "user") {
+    principal = { kind: "user", userId: auth.userId };
+  } else {
+    if (!myAgentId) return false;
+    const agent = await getAgentById(myAgentId);
+    if (!agent) return false;
+    principal = { kind: "agent", agentId: myAgentId, isLead: agent.isLead };
+  }
+
+  return can({ principal, verb: "task.action.own", resource, source: "http" }).allow;
+}
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleTasks(
@@ -773,6 +835,7 @@ export async function handleTasks(
         outputSchema: parsed.body.outputSchema || undefined,
         contextKey: parsed.body.contextKey || undefined,
         requestedByUserId,
+        status: parsed.body.draft ? "draft" : undefined,
         ...splitLegacyModelAlias({
           model: parsed.body.model,
           modelTier: parsed.body.modelTier,
@@ -804,6 +867,36 @@ export async function handleTasks(
     return true;
   }
 
+  if (promoteDraftTaskRoute.match(req.method, pathSegments)) {
+    const parsed = await promoteDraftTaskRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const existingTask = await getTaskById(parsed.params.id);
+    if (!existingTask) {
+      jsonError(res, "Task not found", 404);
+      return true;
+    }
+
+    const allowed = await canActOnOwnTask(req, myAgentId, existingTask);
+    if (!allowed) {
+      jsonError(res, "Not authorized to act on this task", 403);
+      return true;
+    }
+
+    // Idempotent: a task already out of `draft` (already promoted, or a
+    // retried request) is returned as-is rather than erroring — the UI calls
+    // this exactly once per upload batch but must stay safe under retry.
+    const promoted =
+      existingTask.status === "draft" ? await promoteDraftTask(parsed.params.id) : existingTask;
+    if (!promoted) {
+      jsonError(res, "Task not found", 404);
+      return true;
+    }
+
+    promoteDraftTaskRoute.respond(res, 200, promoted);
+    return true;
+  }
+
   if (updateSession.match(req.method, pathSegments)) {
     const parsed = await updateSession.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;

package/src/http/utils.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { getActiveTaskCount } from "../be/db";
+import type { SwarmSpan } from "../otel";
 import { scrubSecrets } from "../utils/secret-scrubber";
 
 export function setCorsHeaders(req: IncomingMessage, res: ServerResponse) {
@@ -47,6 +48,99 @@ export function getPathSegments(url: string): string[] {
   return path.split("/").filter(Boolean);
 }
 
+/**
+ * `http.response.status_code` for a request span whose response connection
+ * closed before completion. `statusCode` initializes to `200` and is only
+ * ever updated by `writeHead` — on the premature-close path that never ran,
+ * so reporting it verbatim would claim a 200 response was sent when none was.
+ * Omitted (not fabricated) when `headersSent` is false.
+ *
+ * Node emits `close` for BOTH a completed response and a connection
+ * terminated early, so this path proves the response did not complete — not
+ * that the client was the actor.
+ */
+export function abortedStatusCodeAttribute(
+  headersSent: boolean,
+  statusCode: number,
+): number | undefined {
+  return headersSent ? statusCode : undefined;
+}
+
+/**
+ * Minimal `ServerResponse` surface `wireHttpSpanLifecycle` needs — narrowed so
+ * tests can pass a plain mock instead of a real Node response.
+ */
+export interface SpanLifecycleResponse {
+  readonly headersSent: boolean;
+  on(event: "finish" | "error" | "close", listener: (err?: Error) => void): unknown;
+}
+
+/**
+ * Wires a request span to its response's terminal events so the span always
+ * ends exactly once, regardless of which event fires first.
+ *
+ * `finish` and `error` are the two ways Node signals a completed response;
+ * `close` additionally fires on a connection that terminates early —
+ * including AFTER `finish` on the happy path, which is why every branch
+ * guards on `spanEnded` before touching the span. Extracted out of
+ * `src/http/index.ts` (which binds a port at module scope and so cannot be
+ * imported directly in a test) so the close-before-finish ordering and the
+ * end-exactly-once guarantee can be exercised with a mocked response/span.
+ */
+export function wireHttpSpanLifecycle(
+  res: SpanLifecycleResponse,
+  span: SwarmSpan,
+  getStatusCode: () => number,
+  startTime: number,
+): void {
+  let spanEnded = false;
+
+  res.on("finish", () => {
+    if (spanEnded) return;
+    spanEnded = true;
+    const statusCode = getStatusCode();
+    span.setAttributes({
+      "http.response.status_code": statusCode,
+      "agentswarm.http.duration_ms": Math.round((performance.now() - startTime) * 10) / 10,
+    });
+    if (statusCode >= 500) {
+      span.setStatus({ code: 2, message: `HTTP ${statusCode}` });
+    }
+    span.end();
+  });
+
+  res.on("error", (err) => {
+    if (spanEnded) return;
+    spanEnded = true;
+    if (err) span.recordException(err);
+    span.setStatus({ code: 2, message: err?.message });
+    span.end();
+  });
+
+  // `close` fires after `finish` on the happy path (the `spanEnded` guard
+  // already covers that), but a response connection that terminates early
+  // fires neither `finish` nor `error` — without this, the span stays open
+  // and is never exported. Verified against Bun 1.4.0 (pinned): `close`
+  // fires on a premature close even with `headersSent === false`; Bun
+  // 1.3.14 never fires it.
+  res.on("close", () => {
+    if (spanEnded) return;
+    spanEnded = true;
+    span.setAttributes({
+      "http.response.status_code": abortedStatusCodeAttribute(res.headersSent, getStatusCode()),
+      "agentswarm.http.duration_ms": Math.round((performance.now() - startTime) * 10) / 10,
+      "agentswarm.http.aborted": true,
+    });
+    // Status left Unset. `close` cannot distinguish an intentional client
+    // cancellation from a response-write failure, and the dominant case
+    // here is the former: a normal SSE teardown on /mcp or /mcp-user.
+    // Marking every premature close ERROR would put that routine traffic
+    // in the service error rate. `agentswarm.http.aborted` carries the
+    // signal instead. Revisit if a discriminator becomes available.
+    span.end();
+  });
+}
+
 export function safeRequestUrlForLog(rawUrl: string | undefined): string {
   if (!rawUrl) return "";
 

package/src/otel-impl.ts

@@ -5,7 +5,9 @@ import {
   propagation,
   ROOT_CONTEXT,
   type Span,
+  SpanKind,
   SpanStatusCode,
+  type Tracer,
   trace,
 } from "@opentelemetry/api";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
@@ -20,7 +22,7 @@ import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
 import pkg from "../package.json";
-import type { SwarmSpan } from "./otel";
+import type { SpanOptions, SwarmSpan, SwarmSpanKind } from "./otel";
 import { scrubSecrets } from "./utils/secret-scrubber";
 
 type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
@@ -219,9 +221,21 @@ export async function withSpan<T>(
   });
 }
 
-export function startSpan(name: string, attributes?: Attributes): SwarmSpan {
-  const span = trace.getTracer(TRACER_NAME).startSpan(name, {
+const SPAN_KIND_MAP: Record<SwarmSpanKind, SpanKind> = {
+  internal: SpanKind.INTERNAL,
+  server: SpanKind.SERVER,
+  client: SpanKind.CLIENT,
+  producer: SpanKind.PRODUCER,
+  consumer: SpanKind.CONSUMER,
+};
+
+let tracerOverrideForTests: Tracer | undefined;
+
+export function startSpan(name: string, attributes?: Attributes, options?: SpanOptions): SwarmSpan {
+  const tracer = tracerOverrideForTests ?? trace.getTracer(TRACER_NAME);
+  const span = tracer.startSpan(name, {
     attributes: cleanAttributes(attributes),
+    kind: options?.kind ? SPAN_KIND_MAP[options.kind] : undefined,
   });
   return spanAdapter(span);
 }
@@ -326,3 +340,7 @@ export function _injectCountersForTests(
   tokenCounter = token;
   costDriftCounter = drift;
 }
+
+export function _injectTracerForTests(tracer: Tracer | undefined): void {
+  tracerOverrideForTests = tracer;
+}

package/src/otel.ts

@@ -1,7 +1,7 @@
 export type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
 export type Attributes = Record<string, AttributeValue | undefined>;
 
-type SpanStatus = {
+export type SpanStatus = {
   code: number;
   message?: string;
 };
@@ -15,6 +15,15 @@ export type SwarmSpan = {
   end: () => void;
 };
 
+// Backend-agnostic mirror of OTel's `SpanKind`. Kept as a string union (not a
+// value import of `@opentelemetry/api`) so this dependency-free module, loaded
+// by every worker process, never eagerly pulls in the OTel API. `otel-impl.ts`
+// maps this onto the real `SpanKind` only when OTLP is configured.
+export type SwarmSpanKind = "internal" | "server" | "client" | "producer" | "consumer";
+export interface SpanOptions {
+  kind?: SwarmSpanKind;
+}
+
 // eslint-disable-next-line import/no-duplicates -- type-only import, no side-effects
 import type { SessionCostMetric } from "./otel-impl";
 export type { SessionCostMetric };
@@ -51,7 +60,9 @@ let realWithSpan:
       attributes?: Attributes,
     ) => Promise<T>)
   | undefined;
-let realStartSpan: ((name: string, attributes?: Attributes) => SwarmSpan) | undefined;
+let realStartSpan:
+  | ((name: string, attributes?: Attributes, options?: SpanOptions) => SwarmSpan)
+  | undefined;
 let realWithRemoteContext:
   | (<T>(carrier: Record<string, unknown>, fn: () => Promise<T> | T) => Promise<T>)
   | undefined;
@@ -102,11 +113,11 @@ export async function withSpan<T>(
   return realWithSpan(name, fn, attributes);
 }
 
-export function startSpan(name: string, attributes?: Attributes): SwarmSpan {
+export function startSpan(name: string, attributes?: Attributes, options?: SpanOptions): SwarmSpan {
   if (!otelConfigured() || !realStartSpan) {
     return NOOP_SPAN;
   }
-  return realStartSpan(name, attributes);
+  return realStartSpan(name, attributes, options);
 }
 
 export function withSpanContext<T>(span: SwarmSpan, fn: () => T): T {

package/src/slack/blocks.ts

@@ -375,6 +375,7 @@ export function buildBufferFlushBlocks(opts: {
 type TreeStatusIcon = TreeNode["status"] | "superseded";
 
 const STATUS_ICON: Record<TreeStatusIcon, string> = {
+  draft: "📎",
   backlog: "🗂️",
   unassigned: "📭",
   offered: "📨",

package/src/slack/handlers.ts

@@ -196,6 +196,13 @@ let cachedBotId: string | null = null;
 const swarmThreadRootCache = new Map<string, boolean>();
 const SWARM_THREAD_ROOT_CACHE_MAX = 1000;
 
+/** Reset Slack handler caches between tests that exercise production handlers. */
+export function resetSlackHandlerCachesForTesting(): void {
+  cachedBotUserId = null;
+  cachedBotId = null;
+  swarmThreadRootCache.clear();
+}
+
 /**
  * Pure check: does the given thread-root message belong to our own swarm bot?
  * Exported for testing.

package/src/tasks/sibling-awareness.ts

@@ -58,6 +58,7 @@ async function toSiblingTaskInfo(task: AgentTask): Promise<SiblingTaskInfo> {
     agentName: agent?.name ?? null,
     description: stripSiblingBlock(task.task),
     updatedAt: task.lastUpdatedAt,
+    createdAt: task.createdAt,
   };
 }
 

package/src/tasks/sibling-block.ts

@@ -18,9 +18,15 @@ export type SiblingTaskInfo = {
   agentId: string | null;
   agentName: string | null;
   description: string;
-  // Most recent change timestamp (ISO string). Used for relative-time render
-  // and for picking the "best" sibling to wire as parent.
+  // Most recent change timestamp (ISO string). Used for the "last active"
+  // relative-time render and for picking the "best" sibling to wire as parent.
+  // NOTE: this ticks on every progress event, so it is NOT a proxy for when
+  // the sibling (or the user input behind it) started.
   updatedAt: string;
+  // Creation timestamp (ISO string) — when the user input behind this sibling
+  // actually arrived. Optional so existing callers keep compiling; when it is
+  // absent we omit the "started" clause rather than guess from `updatedAt`.
+  createdAt?: string;
 };
 
 const DESCRIPTION_TRUNCATE = 200;
@@ -100,8 +106,15 @@ export function renderSiblingBlock(
       : s.agentId
         ? `agent:${s.agentId}`
         : "agent:unassigned";
-    const rel = formatRelativeTime(s.updatedAt, now);
-    lines.push(`- [${s.status}] task:${s.id} — ${agentLabel} — started ${rel} ago`);
+    // `updatedAt` advances on every progress event, so rendering it as
+    // "started" made a minutes-old sibling look seconds-old and invited the
+    // reader to conclude two unrelated user inputs were a double-submit.
+    // Report each timestamp under its own name instead.
+    const lastActive = `last active ${formatRelativeTime(s.updatedAt, now)} ago`;
+    const timing = s.createdAt
+      ? `started ${formatRelativeTime(s.createdAt, now)} ago, ${lastActive}`
+      : lastActive;
+    lines.push(`- [${s.status}] task:${s.id} — ${agentLabel} — ${timing}`);
     lines.push(`  "${truncateForBlock(s.description)}"`);
   }
   lines.push("</sibling_tasks_in_progress>");

package/src/tests/artifact-sdk.test.ts

@@ -9,6 +9,11 @@ import {
 } from "../artifact-sdk/server";
 import { getBasePrompt } from "../prompts/base-prompt";
 
+function restoreEnvValue(key: string, value: string | undefined): void {
+  if (value === undefined) delete process.env[key];
+  else process.env[key] = value;
+}
+
 // ─── Port allocation tests ──────────────────────────────────────────────
 
 describe("getAvailablePort", () => {
@@ -132,9 +137,9 @@ describe("createArtifactServer", () => {
   });
 
   afterAll(() => {
-    process.env.AGENT_ID = originalEnv.AGENT_ID;
-    process.env.API_KEY = originalEnv.API_KEY;
-    process.env.MCP_BASE_URL = originalEnv.MCP_BASE_URL;
+    restoreEnvValue("AGENT_ID", originalEnv.AGENT_ID);
+    restoreEnvValue("API_KEY", originalEnv.API_KEY);
+    restoreEnvValue("MCP_BASE_URL", originalEnv.MCP_BASE_URL);
   });
 
   describe("factory return shape", () => {
@@ -596,9 +601,9 @@ describe("artifact CLI command", () => {
         expect(output).toContain("https://test.lt.example.com");
       } finally {
         console.log = origLog;
-        process.env.MCP_BASE_URL = origEnv.MCP_BASE_URL;
-        process.env.API_KEY = origEnv.API_KEY;
-        process.env.AGENT_ID = origEnv.AGENT_ID;
+        restoreEnvValue("MCP_BASE_URL", origEnv.MCP_BASE_URL);
+        restoreEnvValue("API_KEY", origEnv.API_KEY);
+        restoreEnvValue("AGENT_ID", origEnv.AGENT_ID);
         mockServer.stop();
       }
     });
@@ -627,9 +632,9 @@ describe("artifact CLI command", () => {
         expect(output).toContain("No active artifacts");
       } finally {
         console.log = origLog;
-        process.env.MCP_BASE_URL = origEnv.MCP_BASE_URL;
-        process.env.API_KEY = origEnv.API_KEY;
-        process.env.AGENT_ID = origEnv.AGENT_ID;
+        restoreEnvValue("MCP_BASE_URL", origEnv.MCP_BASE_URL);
+        restoreEnvValue("API_KEY", origEnv.API_KEY);
+        restoreEnvValue("AGENT_ID", origEnv.AGENT_ID);
         mockServer.stop();
       }
     });
@@ -679,9 +684,9 @@ describe("artifact CLI command", () => {
         expect(output).toContain("No active artifacts");
       } finally {
         console.log = origLog;
-        process.env.MCP_BASE_URL = origEnv.MCP_BASE_URL;
-        process.env.API_KEY = origEnv.API_KEY;
-        process.env.AGENT_ID = origEnv.AGENT_ID;
+        restoreEnvValue("MCP_BASE_URL", origEnv.MCP_BASE_URL);
+        restoreEnvValue("API_KEY", origEnv.API_KEY);
+        restoreEnvValue("AGENT_ID", origEnv.AGENT_ID);
         mockServer.stop();
       }
     });
@@ -736,9 +741,9 @@ describe("artifact CLI command", () => {
         expect(output).toContain("stopped");
       } finally {
         console.log = origLog;
-        process.env.MCP_BASE_URL = origEnv.MCP_BASE_URL;
-        process.env.API_KEY = origEnv.API_KEY;
-        process.env.AGENT_ID = origEnv.AGENT_ID;
+        restoreEnvValue("MCP_BASE_URL", origEnv.MCP_BASE_URL);
+        restoreEnvValue("API_KEY", origEnv.API_KEY);
+        restoreEnvValue("AGENT_ID", origEnv.AGENT_ID);
         mockServer.stop();
       }
     });