@desplega.ai/agent-swarm 2.4.1 → 2.4.3

package/src/tests/status.test.ts

@@ -115,7 +115,6 @@ const ENV_KEYS_TO_RESET = [
   "GOOGLE_APPLICATION_CREDENTIALS",
   "AGENTMAIL_API_KEY",
   "AGENTMAIL_DISABLE",
-  "SWARM_VERIFY_TTL_MS",
   "ANONYMIZED_TELEMETRY",
 ];
 
@@ -314,7 +313,7 @@ describe("setup milestones", () => {
     expect(getMilestone(payload, "harness").state).toBe("verified");
   });
 
-  test("provider rollup counts every agent with a fresh passing report in verifiedWorkers", async () => {
+  test("provider rollup counts every agent with a passing report in verifiedWorkers", async () => {
     const verified = await createAgent({
       name: "w-verified",
       isLead: false,
@@ -376,7 +375,7 @@ describe("setup milestones", () => {
 
   // ─── Multi-provider fleet rollup ─────────────────────────────────────────
   describe("harness — multi-provider fleet aggregate", () => {
-    test("`verified` when every provider in the fleet has a fresh passing live test", async () => {
+    test("`verified` when every provider in the fleet has a passing live test", async () => {
       const a = await createAgent({
         name: "claude-w",
         isLead: false,
@@ -423,8 +422,30 @@ describe("setup milestones", () => {
 
       const m = getMilestone(await buildStatusPayload(), "harness");
       expect(m.state).toBe("configured");
-      expect(m.hint).toContain("claude");
-      expect(m.hint).toContain("codex");
+      // Only the provider that needs attention is listed.
+      expect(m.hint).toBe("codex: not live-tested");
+    });
+
+    test("an all-verified fleet carries no hint, however old the passing tests are", async () => {
+      const a = await createAgent({
+        name: "claude-w",
+        isLead: false,
+        status: "idle",
+        capabilities: [],
+      });
+      const b = await createAgent({
+        name: "codex-w",
+        isLead: false,
+        status: "idle",
+        capabilities: [],
+      });
+      const old = { ok: true, error: null, latency_ms: 12, testedAt: Date.now() - 6 * 3_600_000 };
+      await seedCredStatus(a.id, "claude", { ready: true, satisfiedBy: "env", liveTest: old });
+      await seedCredStatus(b.id, "codex", { ready: true, satisfiedBy: "file", liveTest: old });
+
+      const m = getMilestone(await buildStatusPayload(), "harness");
+      expect(m.state).toBe("verified");
+      expect(m.hint).toBeUndefined();
     });
 
     test("`unverified` when any provider in the fleet reports blocked credentials", async () => {
@@ -1062,6 +1083,135 @@ describe("computeHealth (Phase 2)", () => {
     expect(payload.health).toBe("degraded");
   });
 
+  test("`ok` when live workers' last passing live test is hours old", async () => {
+    const lead = await createAgent({
+      name: "lead-old",
+      isLead: true,
+      status: "idle",
+      capabilities: [],
+    });
+    const worker = await createAgent({
+      name: "worker-old",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+    await updateAgentActivity(lead.id);
+    await updateAgentActivity(worker.id);
+    const oldPass = { ok: true, error: null, latency_ms: 12, testedAt: Date.now() - 6 * 3_600_000 };
+    await seedCredStatus(lead.id, "claude", { ready: true, satisfiedBy: "env", liveTest: oldPass });
+    await seedCredStatus(worker.id, "claude", {
+      ready: true,
+      satisfiedBy: "env",
+      liveTest: oldPass,
+    });
+
+    const payload = await buildStatusPayload();
+    expect(getMilestone(payload, "workers").state).toBe("verified");
+    expect(getMilestone(payload, "harness").state).toBe("verified");
+    expect(payload.health).toBe("ok");
+  });
+
+  test("`degraded` when the provider's latest live test failed, even after an older pass", async () => {
+    const passed = await createAgent({
+      name: "worker-pass",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+    const failed = await createAgent({
+      name: "worker-fail",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+    await updateAgentActivity(passed.id);
+    await updateAgentActivity(failed.id);
+    await seedCredStatus(passed.id, "claude", {
+      ready: true,
+      satisfiedBy: "env",
+      liveTest: { ok: true, error: null, latency_ms: 12, testedAt: Date.now() - 60_000 },
+    });
+    await seedCredStatus(failed.id, "claude", {
+      ready: true,
+      satisfiedBy: "env",
+      liveTest: { ok: false, error: "HTTP 401", latency_ms: 12, testedAt: Date.now() },
+    });
+
+    const payload = await buildStatusPayload();
+    const harness = getMilestone(payload, "harness");
+    expect(harness.state).toBe("configured");
+    expect(harness.hint).toBe("claude: live test failed");
+    expect(payload.health).toBe("degraded");
+  });
+
+  test("an offline agent's newer failed live test does not override an online pass", async () => {
+    const online = await createAgent({
+      name: "worker-online",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+    const offline = await createAgent({
+      name: "worker-offline",
+      isLead: false,
+      status: "offline",
+      capabilities: [],
+    });
+    await updateAgentActivity(online.id);
+    await seedCredStatus(online.id, "claude", {
+      ready: true,
+      satisfiedBy: "env",
+      liveTest: { ok: true, error: null, latency_ms: 12, testedAt: Date.now() - 6 * 3_600_000 },
+    });
+    await seedCredStatus(offline.id, "claude", {
+      ready: true,
+      satisfiedBy: "env",
+      liveTest: { ok: false, error: "HTTP 401", latency_ms: 12, testedAt: Date.now() },
+    });
+
+    expect(await rollupCredStatusForProvider("claude")).toMatchObject({
+      state: "verified",
+      workers: 1,
+      reports: 1,
+    });
+    const harness = getMilestone(await buildStatusPayload(), "harness");
+    expect(harness.state).toBe("verified");
+    expect(harness.hint).toBeUndefined();
+  });
+
+  test("a provider reported only by offline agents does not degrade the harness", async () => {
+    const online = await createAgent({
+      name: "claude-online",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+    const offline = await createAgent({
+      name: "codex-offline",
+      isLead: false,
+      status: "offline",
+      capabilities: [],
+    });
+    await updateAgentActivity(online.id);
+    await seedCredStatus(online.id, "claude", {
+      ready: true,
+      satisfiedBy: "env",
+      liveTest: { ok: true, error: null, latency_ms: 12, testedAt: Date.now() },
+    });
+    await seedCredStatus(offline.id, "codex", {
+      ready: false,
+      missing: ["OPENAI_API_KEY"],
+      satisfiedBy: null,
+      liveTest: { ok: false, error: "HTTP 401", latency_ms: 12, testedAt: Date.now() },
+    });
+
+    const harness = getMilestone(await buildStatusPayload(), "harness");
+    expect(harness.state).toBe("verified");
+    expect(harness.hint).toBeUndefined();
+    expect((harness.providers ?? []).map((p) => p.provider)).toEqual(["claude"]);
+  });
+
   test("`ok` when workers are `configured` (heartbeat drift is a runtime concern, not setup health)", async () => {
     // Workers in `configured` state means agents exist but haven't posted a
     // heartbeat in the last 5 minutes. This is surfaced on /agents and the
@@ -1166,9 +1316,8 @@ describe("worker-reported live test drives harness.state", () => {
     expect(getMilestone(await buildStatusPayload(), "harness").state).toBe("verified");
   });
 
-  test("a stale live test (older than SWARM_VERIFY_TTL_MS) drops to `configured`", async () => {
+  test("an old passing live test keeps harness `verified`", async () => {
     process.env.HARNESS_PROVIDER = "claude";
-    process.env.SWARM_VERIFY_TTL_MS = "1000"; // 1s — anything older is stale
     const a = await createAgent({ name: "w-stl", isLead: false, status: "idle", capabilities: [] });
     await seedCredStatus(a.id, "claude", {
       ready: true,
@@ -1176,10 +1325,10 @@ describe("worker-reported live test drives harness.state", () => {
         ok: true,
         error: null,
         latency_ms: 80,
-        testedAt: Date.now() - 60_000, // 60s ago, well beyond TTL
+        testedAt: Date.now() - 24 * 3_600_000, // a day ago: workers only re-test on change
       },
     });
-    expect(getMilestone(await buildStatusPayload(), "harness").state).toBe("configured");
+    expect(getMilestone(await buildStatusPayload(), "harness").state).toBe("verified");
   });
 
   test("a failed live test still leaves harness `configured` if presence is ready", async () => {

package/src/tests/task-lineage.test.ts

@@ -0,0 +1,180 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import {
+  closeDb,
+  createAgent,
+  createTaskExtended,
+  getDbClient,
+  getTaskLineage,
+  initDb,
+  TASK_LINEAGE_LIMITS,
+} from "../be/db";
+
+const TEST_DB_PATH = "./test-task-lineage.sqlite";
+
+async function removeDb() {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(`${TEST_DB_PATH}${suffix}`);
+    } catch {}
+  }
+}
+
+describe("getTaskLineage", () => {
+  let agentId: string;
+
+  beforeAll(async () => {
+    await removeDb();
+    initDb(TEST_DB_PATH);
+    const agent = await createAgent({
+      id: crypto.randomUUID(),
+      name: "Lineage Test Agent",
+      isLead: false,
+      status: "idle",
+    });
+    agentId = agent.id;
+  });
+
+  /** A straight parentTaskId chain, root first. */
+  async function createChain(label: string, length: number) {
+    const chain = [await createTaskExtended(`${label} 0`, { agentId })];
+    for (let i = 1; i < length; i++) {
+      chain.push(
+        await createTaskExtended(`${label} ${i}`, { agentId, parentTaskId: chain[i - 1]!.id }),
+      );
+    }
+    return chain;
+  }
+
+  afterAll(async () => {
+    closeDb();
+    await removeDb();
+  });
+
+  test("unknown task: null", async () => {
+    expect(await getTaskLineage("no-such-task")).toBeNull();
+  });
+
+  test("from a grandchild: walks up to the root, then the whole tree", async () => {
+    const root = await createTaskExtended("root", { agentId });
+    const childA = await createTaskExtended("child a", { agentId, parentTaskId: root.id });
+    const childB = await createTaskExtended("child b", { agentId, parentTaskId: root.id });
+    const grandchild = await createTaskExtended("grandchild", {
+      agentId,
+      parentTaskId: childA.id,
+    });
+    const greatGrandchild = await createTaskExtended("great-grandchild", {
+      agentId,
+      parentTaskId: grandchild.id,
+    });
+    const unrelated = await createTaskExtended("unrelated", { agentId });
+
+    const lineage = await getTaskLineage(grandchild.id);
+    expect(lineage).not.toBeNull();
+    expect(lineage!.rootTaskId).toBe(root.id);
+    expect(lineage!.truncated).toBe(false);
+    expect(lineage!.tasks[0]!.id).toBe(root.id);
+    const ids = new Set(lineage!.tasks.map((t) => t.id));
+    expect(ids).toEqual(
+      new Set([root.id, childA.id, childB.id, grandchild.id, greatGrandchild.id]),
+    );
+    expect(ids.has(unrelated.id)).toBe(false);
+    expect(lineage!.tasks.find((t) => t.id === childA.id)!.parentTaskId).toBe(root.id);
+  });
+
+  test("a node cap keeps the path to the task and its own subtree, and says it cut", async () => {
+    const root = await createTaskExtended("wide root", { agentId });
+    const children = [];
+    for (let i = 0; i < 6; i++) {
+      children.push(await createTaskExtended(`fan-out ${i}`, { agentId, parentTaskId: root.id }));
+    }
+    const last = children[children.length - 1]!;
+    const leaf = await createTaskExtended("leaf under the last child", {
+      agentId,
+      parentTaskId: last.id,
+    });
+
+    const lineage = await getTaskLineage(last.id, { maxNodes: 3 });
+    expect(lineage!.truncated).toBe(true);
+    const ids = new Set(lineage!.tasks.map((t) => t.id));
+    expect(ids.has(root.id)).toBe(true);
+    expect(ids.has(last.id)).toBe(true);
+    expect(ids.has(leaf.id)).toBe(true);
+    expect(lineage!.tasks.length).toBeLessThanOrEqual(2 * 3 + 2);
+  });
+
+  test("a depth cap stops the walk down", async () => {
+    const root = await createTaskExtended("deep root", { agentId });
+    let parent = root;
+    for (let i = 0; i < 5; i++) {
+      parent = await createTaskExtended(`level ${i + 1}`, { agentId, parentTaskId: parent.id });
+    }
+    const lineage = await getTaskLineage(root.id, { maxDepth: 2 });
+    expect(lineage!.tasks).toHaveLength(3);
+    expect(lineage!.truncated).toBe(true);
+  });
+
+  test("a chain past the default depth cap says it cut", async () => {
+    const chain = await createChain("default-depth", 32);
+    const lineage = await getTaskLineage(chain[0]!.id);
+    expect(lineage!.tasks).toHaveLength(TASK_LINEAGE_LIMITS.maxDepth + 1);
+    expect(lineage!.truncated).toBe(true);
+  });
+
+  test("a chain that ends exactly at the depth cap is complete", async () => {
+    const chain = await createChain("exact-depth", 3);
+    const lineage = await getTaskLineage(chain[0]!.id, { maxDepth: 2 });
+    expect(lineage!.tasks).toHaveLength(3);
+    expect(lineage!.truncated).toBe(false);
+  });
+
+  test("every ancestor of the task survives a node cap of 1", async () => {
+    const chain = await createChain("path-node-cap", 5);
+    const leaf = chain[chain.length - 1]!;
+    const lineage = await getTaskLineage(leaf.id, { maxNodes: 1 });
+    expect(new Set(lineage!.tasks.map((t) => t.id))).toEqual(new Set(chain.map((t) => t.id)));
+    // Nothing in the tree is left out, so the result is complete.
+    expect(lineage!.truncated).toBe(false);
+    const ids = new Set(lineage!.tasks.map((t) => t.id));
+    for (const task of lineage!.tasks) {
+      if (task.id !== lineage!.rootTaskId) expect(ids.has(task.parentTaskId!)).toBe(true);
+    }
+  });
+
+  test("a deep focused path survives both caps, and a cut sibling still flags", async () => {
+    const chain = await createChain("deep-focus", 8);
+    const sibling = await createTaskExtended("off-path sibling", {
+      agentId,
+      parentTaskId: chain[1]!.id,
+    });
+    const leaf = chain[chain.length - 1]!;
+    const lineage = await getTaskLineage(leaf.id, { maxNodes: 1, maxDepth: 1 });
+    const ids = new Set(lineage!.tasks.map((t) => t.id));
+    for (const task of chain) expect(ids.has(task.id)).toBe(true);
+    expect(ids.has(sibling.id)).toBe(false);
+    expect(lineage!.truncated).toBe(true);
+  });
+
+  test("a fan-out exactly at the node cap is complete; one more child cuts", async () => {
+    const root = await createTaskExtended("cap root", { agentId });
+    for (let i = 0; i < 3; i++) {
+      await createTaskExtended(`cap child ${i}`, { agentId, parentTaskId: root.id });
+    }
+    const atCap = await getTaskLineage(root.id, { maxNodes: 4 });
+    expect(atCap!.tasks).toHaveLength(4);
+    expect(atCap!.truncated).toBe(false);
+    const overCap = await getTaskLineage(root.id, { maxNodes: 3 });
+    expect(overCap!.tasks).toHaveLength(3);
+    expect(overCap!.truncated).toBe(true);
+  });
+
+  test("a parentTaskId cycle ends at the ancestor cap instead of looping", async () => {
+    const a = await createTaskExtended("cycle a", { agentId });
+    const b = await createTaskExtended("cycle b", { agentId, parentTaskId: a.id });
+    await getDbClient().run("UPDATE agent_tasks SET parentTaskId = ? WHERE id = ?", [b.id, a.id]);
+
+    const lineage = await getTaskLineage(a.id, { maxAncestors: 5, maxDepth: 4 });
+    expect(lineage!.truncated).toBe(true);
+    expect(new Set(lineage!.tasks.map((t) => t.id))).toEqual(new Set([a.id, b.id]));
+  });
+});

package/src/tests/telemetry-init.test.ts

@@ -1,4 +1,8 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 import pkg from "../../package.json";
 import {
   _getInstallationIdForTests,
@@ -14,6 +18,7 @@ import {
   _resolveIntegrationProvider,
   _resolveIntegrationType,
   emitIntegrationConnected,
+  getTelemetryEnvironment,
   initTelemetry,
   telemetry,
   track,
@@ -686,8 +691,11 @@ describe("initTelemetry", () => {
     const originalFetch = globalThis.fetch;
     const originalNodeEnv = process.env.NODE_ENV;
     let captured: Record<string, unknown> | null = null;
+    let packageRoot: URL;
 
     beforeEach(() => {
+      packageRoot = pathToFileURL(`${mkdtempSync(join(tmpdir(), "telemetry-env-"))}/`);
+      process.env.NODE_ENV = "production";
       captured = null;
       globalThis.fetch = (async (_url: string, init?: { body?: string }) => {
         captured = init?.body ? JSON.parse(init.body) : null;
@@ -697,14 +705,59 @@ describe("initTelemetry", () => {
     });
 
     afterEach(() => {
+      rmSync(packageRoot, { recursive: true, force: true });
       globalThis.fetch = originalFetch;
       delete process.env.DESPLEGA_TELEMETRY_ENV;
       if (originalNodeEnv === undefined) delete process.env.NODE_ENV;
       else process.env.NODE_ENV = originalNodeEnv;
     });
 
+    test("track detects the real checkout through the default package root with an unprimed cache", async () => {
+      await initTelemetry(
+        "api-server",
+        async (key) => (key === "telemetry_installation_id" ? "install_checkout_env" : undefined),
+        async () => {},
+        { generateIfMissing: true },
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
+      expect(metadata.environment).toBe("development");
+    });
+
+    test("a .git directory marks a checkout as development", () => {
+      mkdirSync(new URL(".git", packageRoot));
+      expect(getTelemetryEnvironment(packageRoot)).toBe("development");
+      rmSync(new URL(".git", packageRoot), { recursive: true });
+      expect(getTelemetryEnvironment(packageRoot)).toBe("development");
+    });
+
+    test("a .git file marks a worktree as development", async () => {
+      await Bun.write(new URL(".git", packageRoot), "gitdir: /some/worktree");
+      expect(getTelemetryEnvironment(packageRoot)).toBe("development");
+    });
+
+    test("caches the checkout check across events", () => {
+      expect(getTelemetryEnvironment(packageRoot)).toBe("production");
+      mkdirSync(new URL(".git", packageRoot));
+      expect(getTelemetryEnvironment(packageRoot)).toBe("production");
+      process.env.DESPLEGA_TELEMETRY_ENV = "staging";
+      expect(getTelemetryEnvironment(packageRoot)).toBe("staging");
+    });
+
+    test("an unusable package root falls back to production without throwing", () => {
+      expect(getTelemetryEnvironment(new URL("data:text/plain,unavailable"))).toBe("production");
+    });
+
+    test("compiled binary paths default to production without throwing", () => {
+      expect(getTelemetryEnvironment(new URL("file:///$bunfs/root/"))).toBe("production");
+    });
+
     test("defaults to production even when NODE_ENV is development", async () => {
       process.env.NODE_ENV = "development";
+      expect(getTelemetryEnvironment(packageRoot)).toBe("production");
       await initTelemetry(
         "api-server",
         async (key) => (key === "telemetry_installation_id" ? "install_default_env" : undefined),
@@ -719,9 +772,11 @@ describe("initTelemetry", () => {
       expect(metadata.environment).toBe("production");
     });
 
-    test("uses DESPLEGA_TELEMETRY_ENV when set", async () => {
-      process.env.NODE_ENV = "production";
-      process.env.DESPLEGA_TELEMETRY_ENV = "development";
+    test("uses DESPLEGA_TELEMETRY_ENV over a git checkout and NODE_ENV=test", async () => {
+      mkdirSync(new URL(".git", packageRoot));
+      process.env.NODE_ENV = "test";
+      process.env.DESPLEGA_TELEMETRY_ENV = "staging";
+      expect(getTelemetryEnvironment(packageRoot)).toBe("staging");
       await initTelemetry(
         "api-server",
         async (key) => (key === "telemetry_installation_id" ? "install_explicit_env" : undefined),
@@ -733,11 +788,13 @@ describe("initTelemetry", () => {
       await new Promise((r) => setTimeout(r, 0));
 
       const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
-      expect(metadata.environment).toBe("development");
+      expect(metadata.environment).toBe("staging");
     });
 
-    test("preserves NODE_ENV=test when telemetry env is unset", async () => {
+    test("preserves NODE_ENV=test over a git checkout when telemetry env is unset", async () => {
+      mkdirSync(new URL(".git", packageRoot));
       process.env.NODE_ENV = "test";
+      expect(getTelemetryEnvironment(packageRoot)).toBe("test");
       await initTelemetry(
         "api-server",
         async (key) => (key === "telemetry_installation_id" ? "install_test_env" : undefined),

package/src/tests/user-token-rest-auth.test.ts

@@ -110,6 +110,44 @@ describe("normal REST API user-bound token auth", () => {
     expect(body.requestedByUserId).toBeUndefined();
   });
 
+  for (const caller of ["user", "operator", "agent"] as const) {
+    for (const explicit of [false, true]) {
+      test(`REST ${caller} follow-up ${explicit ? "keeps an explicit schema" : caller === "agent" ? "inherits the parent schema" : "does not inherit the parent schema"}`, async () => {
+        const user = await createUser({ name: "Schema follow-up user" });
+        const agent = await createAgent({ name: "Schema worker", status: "idle" });
+        const parentSchema = { type: "object", properties: { options: { type: "array" } } };
+        const explicitSchema = { type: "object", properties: { answer: { type: "string" } } };
+        const parent = await createTaskExtended("schema-carrying worker task", {
+          agentId: agent.id,
+          requestedByUserId: user.id,
+          outputSchema: parentSchema,
+        });
+        const token =
+          caller === "user" ? (await mintToken(user.id, "rest", ACTOR)).plaintext : API_KEY;
+        const res = await fetch(`http://localhost:${port}/api/tasks`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            ...(caller === "agent" ? { "X-Agent-ID": agent.id } : {}),
+          },
+          body: JSON.stringify({
+            task: "Continue the session",
+            parentTaskId: parent.id,
+            source: "ui",
+            ...(explicit ? { outputSchema: explicitSchema } : {}),
+          }),
+        });
+
+        expect(res.status).toBe(201);
+        const body = (await res.json()) as { id: string; outputSchema?: unknown };
+        expect(body.outputSchema).toEqual(
+          explicit ? explicitSchema : caller === "agent" ? parentSchema : undefined,
+        );
+      });
+    }
+  }
+
   test("global API key caller cannot spoof requestedByUserId via body — falls back to owned task context", async () => {
     const legitRequester = await createUser({ name: "Legit Requester" });
     const attacker = await createUser({ name: "Attacker" });

package/src/tools/app-rows.ts

@@ -53,6 +53,11 @@ function rowFilters(model: ModelDef, equals: Record<string, string | number | bo
         { path: `equals.${column}`, message: "Unknown or hidden column." },
       ]);
     }
+    if (declared?.kind === "json") {
+      throw new AppRowValidationError([
+        { path: `equals.${column}`, message: "json columns cannot be filtered" },
+      ]);
+    }
     if (!validValue(declared ?? { kind: SYSTEM_COLUMN_KINDS[column]! }, value)) {
       throw new AppRowValidationError([
         { path: `equals.${column}`, message: "Filter value must match the column kind." },

package/src/utils/env-flag.ts

@@ -53,3 +53,12 @@ export function isEnvFlagEnabled(
 ): boolean {
   return parseEnvFlag(env[key], defaultValue);
 }
+
+/**
+ * Whether the session-end summary is turned off via `SKIP_SESSION_SUMMARY`.
+ * Every harness (claude Stop hook, pi, opencode, codex) gates on this, so
+ * `1`/`true` skip and unset/empty/`0`/`false` keep the summary everywhere.
+ */
+export function isSessionSummarySkipped(env: NodeJS.ProcessEnv = process.env): boolean {
+  return isEnvFlagEnabled("SKIP_SESSION_SUMMARY", false, env);
+}

package/templates/skills/apps/SKILL.md

@@ -225,6 +225,7 @@ Each column is `{ "kind": ..., "required"?: boolean, "default"?: ..., "index"?:
 | `boolean` | Boolean; set `index: true` only when equality lookups need it. |
 | `date` | ISO-8601 string; never indexed. |
 | `enum` | String from the non-empty unique `enum` list; always indexed, without `index: true`. |
+| `json` | Any JSON value (object, array, nested) up to 256 KB serialized by default (`APPS_JSON_COLUMN_MAX_BYTES`); never indexed, and a named query cannot `filter` or `sort` on it. Not allowed for `userConfig` fields or element props. |
 
 `default` must match the column kind (and be one of the enum values). `required: true` rejects missing/null values unless a default supplies the value. `id`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` — and the sync envelope `source`, `syncedAt`, `stale` — are system columns and reserved names. An app created before the sync envelope that declared ordinary columns with these names surfaces `definitionError` after upgrade until they are renamed: patch in a fresh column with a `{from}` migration directive, then purge the old one. Rows always expose `id`/`createdAt`/`updatedAt`; `createdBy`/`updatedBy` record the acting principal (`user:<id>`, `agent:<id>`, `operator`, or `sync:<source>` for engine writes) and are system-managed on every row write.
 
@@ -321,7 +322,7 @@ A named query is:
 }
 ```
 
-`filter` is a strict AND of equality checks. A filter may target a declared model column or a system column (`id`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, and on synced models `source`, `syncedAt`, `stale`) — filtering on `id` is the universal way to select one row for a detail view, and `{ "stale": true }` selects rows a complete pull stopped confirming. A literal value must match the column's kind; date filters compare the stored raw ISO string, not parsed instants. Omit `limit` for the default 200 rows, or set an integer from 1 through 1000. `sort.column` is a model column, `createdAt`, `updatedAt`, or `syncedAt`; `dir` is `asc` or `desc`. Query runtime state is `{ data, loading, error }` under `/queries/<queryName>`.
+`filter` is a strict AND of equality checks. A filter may target a declared model column or a system column (`id`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, and on synced models `source`, `syncedAt`, `stale`) — filtering on `id` is the universal way to select one row for a detail view, and `{ "stale": true }` selects rows a complete pull stopped confirming. A literal value must match the column's kind; date filters compare the stored raw ISO string, not parsed instants. Omit `limit` for the default 200 rows, or set an integer from 1 through 1000. `sort.column` is a non-`json` model column, `createdAt`, `updatedAt`, or `syncedAt`; `dir` is `asc` or `desc`. Query runtime state is `{ data, loading, error }` under `/queries/<queryName>`.
 
 A filter value may instead be exactly `{ "$param": "<name>" }`. At execution, the caller supplies that name and the server coerces its value to the filtered column's kind before equality matching:
 
@@ -520,7 +521,7 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
 
 Table details:
 
-- `columns[]`: `{ key, label?, kind?, tones?: {value: badgeTone}, width?: number, pinned?: "left" or "right", align?: "start" or "end", truncate?: "end" or "middle", icon?, tooltip?: "<row field>", max?: number, onChange?: chain }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge`, `status`, `user`, `agent`, `relative`, `duration`, `progress`, `copy`, `switch`, or `link`; `string` and `enum` render as text. Pin id/actions columns so they survive horizontal scroll on narrow viewports.
+- `columns[]`: `{ key, label?, kind?, tones?: {value: badgeTone}, width?: number, pinned?: "left" or "right", align?: "start" or "end", truncate?: "end" or "middle", icon?, tooltip?: "<row field>", max?: number, onChange?: chain }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge`, `status`, `user`, `agent`, `relative`, `duration`, `progress`, `copy`, `switch`, `link`, or `json`; `string` and `enum` render as text, and `json` renders a truncated single-line `JSON.stringify` preview. Pin id/actions columns so they survive horizontal scroll on narrow viewports.
   - `status`: lifecycle values (`pending`, `in_progress`, `running`, `completed`, `failed`, `cancelled`, `paused`, `reviewing`, ...) render the dashboard status chip with its icon; other values use `tones` like `badge`.
   - `user` / `agent`: avatar plus name. `relative` (and `date`): smart time, exact time on hover. `duration`: milliseconds as `1m 23s`. `progress`: a bar against `max` (default 100). `copy`: the value plus a copy button. `link`: an http(s) URL opening in a new tab (other values render as text).
   - `switch`: a toggle. `onChange` runs with `$row` = the row with this column already set to the new value, e.g. `[{ "action": "app.mutate", "params": { "model": "m", "op": "update", "rowId": { "$row": "id" }, "values": { "enabled": { "$row": "enabled" } } } }]`. Without `onChange` the switch is read-only.
@@ -789,6 +790,7 @@ The tool returns `{ appId, url: "/apps/<id>" }`. Open that URL to verify the liv
 - Logged-in browser: a fresh dashboard has no connection and redirects to /setup. Seed the localStorage key `agent-swarm-connections` with `{connections:[{id,name,apiUrl,apiKey}],activeId}`. Build the value from an env var and pipe it to `agent-browser eval --stdin`, so the key never reaches a command line. Reload, then pick a user in the "Who are you?" dialog.
 - Apps scroll inside an inner canvas, so a full-page screenshot captures only the viewport. Scroll the canvas or raise the viewport height. For mobile, set a 375px-wide viewport before the screenshot.
 - App definitions: `GET /api/apps` and `GET /api/apps/<id>` with the API key as Bearer.
+- Follow-up edit to a live app: list in the brief the control numbers the edit must not move, and assert them from the backing script before publishing. Take a signed-in screenshot of each changed selector at 1440px wide, save the shots to agent-fs, critique, and repeat at least 3 times. If the backing script caches results, bump its version or force a fresh run so the shots show new data.
 
 
 ### Rows from agents and scripts