@flisk-sh/flisk 1.4.5 → 1.4.7

package/README.md

@@ -114,13 +114,13 @@ flisk resource shop-web --type frontend --stack shop --yes
 flisk up shop
 ```
 
-You get an orders API and a storefront behind one local gateway, with Postgres and live reload. You need Docker, [Tilt](https://docs.tilt.dev/install.html), Node.js 22.12+, and [Bun](https://bun.sh/) 1.2+; `flisk doctor` checks your machine. Prefer to answer questions instead? `npm init create-microservices my-project` asks what to create. See the [quick start](#quick-start) for every option.
+You get an orders API and a storefront behind one local gateway, with Postgres and live reload. You need Docker, [Tilt](https://docs.tilt.dev/install.html), Node.js 22.12+, and [Bun](https://bun.sh/) 1.2+; `flisk doctor` checks your machine. A simpler app needs none of those: give each service a `command` and [run it as local processes](docs/run-without-docker.md). Prefer to answer questions instead? `npm init create-microservices my-project` asks what to create. See the [quick start](#quick-start) for every option.
 
 <div align="center">
 
 <p><strong><a href="#quick-start">Quick start</a> · <a href="#why-flisk-cli">Why Flisk</a> · <a href="#examples">Examples</a> · <a href="#installation">Installation</a> · <a href="#faq">FAQ</a> · <a href="#docs">Documentation</a></strong></p>
 
-[Website](https://flisk.sh/) · [Quickstart](https://flisk.sh/docs/quickstart/) · [Examples](https://flisk.sh/docs/examples/) · [Awesome Flisk](https://github.com/flisk-sh/awesome-tdk-framework) · [Demo](https://flisk-sh.github.io/flisk-demo-animation/) · [Report a bug](https://github.com/flisk-sh/flisk/issues)
+[Website](https://flisk.sh/) · [Quickstart](https://flisk.sh/docs/quickstart/) · [Examples](https://flisk.sh/docs/examples/) · [Awesome Flisk](https://github.com/flisk-sh/awesome-flisk-framework) · [Demo](https://flisk-sh.github.io/flisk-demo-animation/) · [Report a bug](https://github.com/flisk-sh/flisk/issues)
 
 <a id="readme-languages"></a>
 
@@ -245,7 +245,7 @@ flisk up shop
 Agents get durable checkpoint volumes that survive `flisk down`, sticky session routing via `x-session-id`, graceful SIGTERM drain during hot reloads, a Docker health check on `/health`, and application-level readiness checks on `/ready`. See the [AI agents guide](docs/agents/ai-agents.md) and [honest comparison with agent frameworks](docs/compare-honest.md#ai-agent-frameworks-and-workflow-engines-libfx-langgraph-mastra-vercel-workflows-temporal).
 
 
-**What Flisk is:** a local development runtime. Define each service in `service.json` and run `flisk up`. Docker runs the containers, Tilt live-updates them while you code, and Flisk writes the configuration both use. No local Kubernetes is needed.
+**What Flisk is:** a local development runtime. Define each service in `service.json` and run `flisk up`. A service with a `command` runs as a local process, with nothing else installed. When you need a database, one gateway URL, or the container you deploy, Docker runs the containers, Tilt live-updates them while you code, and Flisk writes the configuration both use. No local Kubernetes is needed.
 
 **What Flisk is not:** a deploy tool or a Compose file. Production deployment stays with Helm, Argo CD, or Kustomize.
 
@@ -337,19 +337,42 @@ Get a running local stack in **3 commands**. Works on macOS, Linux, and Windows
 
 ### Prerequisites (install once)
 
-| Tool | Version | Install | Install path |
-|------|---------|---------|--------------|
-| **Docker** | Engine 25+, Compose 2.20.2+ | [docker.com](https://www.docker.com/products/docker-desktop/) | All paths |
-| **Tilt** | 0.25+ | `curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh \| bash` | All paths |
-| **Node.js** | 22.12+ | [nodejs.org](https://nodejs.org/) | npm path (`npm install -g @flisk-sh/flisk`) |
-| **Bun** | 1.2+ | `curl -fsSL https://bun.sh/install \| bash` | Bun path (`bun add -g @flisk-sh/flisk`) |
+| Tool | Version | Install | Needed for |
+|------|---------|---------|------------|
+| **Your app's runtime** | whatever your app uses | Node.js, Python, Go, Bun, ... | Every path: it runs your code |
+| **Node.js** | 22.12+ | [nodejs.org](https://nodejs.org/) | npm install (`npm install -g @flisk-sh/flisk`) |
+| **Docker** | Engine 25+, Compose 2.20.2+ | [docker.com](https://www.docker.com/products/docker-desktop/) | Docker + Tilt path only |
+| **Tilt** | 0.25+ | `curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh \| bash` | Docker + Tilt path only |
+| **Bun** | 1.2+ | `curl -fsSL https://bun.sh/install \| bash` | Bun install (`bun add -g @flisk-sh/flisk`), or generated JavaScript services |
 
-> **Conditional prerequisites**: Node.js is only required when you install Flisk via npm (`npm install -g @flisk-sh/flisk`). Bun is only required when you install via Bun or your project has generated JavaScript services. Docker and Tilt are required for every path.
+> **Two paths.** A project whose services each declare a `command` runs them as local processes: you need only Flisk and your app's runtime ([simplest path](#simplest-path-no-docker)). Docker and Tilt are needed for the Docker + Tilt path: databases such as Postgres, one gateway URL for every service, and running the same container you deploy. `flisk doctor` checks only what your project uses.
 
 > **Windows?** Use WSL2 Ubuntu. See the [Windows & WSL2 guide](docs/wsl2.md) for the recommended setup.
 
 ---
 
+### Simplest path: no Docker
+
+For an app made of services you can start with one command each (an API, a website, a worker), put a `service.json` next to each one:
+
+```json
+{ "schemaVersion": 1, "appName": "api", "appType": "backend", "command": "node server.js", "port": 4000, "healthCheckPath": "/health" }
+```
+
+```json
+{ "schemaVersion": 1, "appName": "web", "appType": "frontend", "command": "node server.js", "port": 3000, "dependsOn": ["api"] }
+```
+
+Then start everything from the project folder:
+
+```bash
+flisk up
+```
+
+Flisk starts the API, waits until it answers, starts the website, prints both URLs, prefixes each line of output with the service name, and restarts a service that crashes. Ctrl+C or `flisk down` stops them. No Docker, no Tilt, no generated files. See [Run your app without Docker](docs/run-without-docker.md) for every field, and for when to switch to the Docker + Tilt path.
+
+---
+
 ### Fastest path: one-command demo (no manual steps)
 
 ```bash
@@ -596,11 +619,11 @@ Runnable examples show Flisk on real stacks. Start with the smallest one:
 | [one-backend-helm](examples/one-backend-helm/README.md) | Working alongside Helm |
 | [byo](examples/byo/README.md) | Bringing your own existing resources |
 | [byo-jobs](examples/byo-jobs/README.md) | Bring-your-own jobs |
-| [tdk-example](examples/tdk-example/README.md) | A full multi-service stack |
+| [flisk-example](examples/flisk-example/README.md) | A full multi-service stack |
 
 ## Use Flisk with your AI agent
 
-The repository ships five agent skills for common Flisk work under [`.agents/skills`](.agents/skills): `flisk-doctor` (environment checks), `flisk-up` (preview and start a stack), `flisk-resource` (create a service), `flisk-status` (health and URLs), and `flisk-troubleshoot` (fixing `flisk` and Tilt errors). Agents working in this repo also follow [AGENTS.md](AGENTS.md). Use these skills to let your agent check your setup and explain failures instead of guessing at Docker or Tilt configuration.
+The repository ships agent skills for common Flisk work under [`.agents/skills`](.agents/skills): `flisk-build` (turn "build me a shop" into Flisk steps, check every URL, and report them), `flisk-recipe-starters` (start from a working restaurant, SaaS, store, AI agent or user-management app), recipes for a shop, a SaaS with login and billing, an AI agent with MCP tools and a database, and a blog (`flisk-recipe-shop`, `flisk-recipe-saas`, `flisk-recipe-ai-agent`, `flisk-recipe-blog`), `flisk-doctor` (environment checks), `flisk-up` (preview and start a stack), `flisk-resource` (create a service), `flisk-status` (health and URLs), and `flisk-troubleshoot` (fixing `flisk` and Tilt errors). More prompts to copy, by category (spreadsheets, recruiting, product management, shops, AI agents), are in the [prompt gallery](docs/recipes/build-with-your-agent.md). Agents working in this repo also follow [AGENTS.md](AGENTS.md). Use these skills to let your agent check your setup and explain failures instead of guessing at Docker or Tilt configuration.
 
 ## Installation
 
@@ -648,7 +671,7 @@ Set `FLISK_DEBUG=1` before running `flisk up --verbose` to include Starlark debu
 - [Generated service files and drift checks](docs/generated-files.md)
 - [Runnable one-backend example](examples/one-backend/README.md)
 - [Runnable Python backend example](examples/one-backend-python/README.md)
-- [Full multi-service example](examples/tdk-example/README.md)
+- [Full multi-service example](examples/flisk-example/README.md)
 - [Features and license limits](docs/FEATURES.md)
 - [Tool comparison: docker-compose, Tilt, Skaffold, DevSpace, kind](docs/comparison.md)
 - [Honest comparison and known limits](docs/compare-honest.md)
@@ -686,7 +709,7 @@ On native Windows, `flisk --version`, `flisk doctor`, and `flisk up --dry-run` a
 
 Core stays free. Premium is a separate key for the extras above; no key required to run `flisk up`.
 
-**Ecosystem map:** examples, articles, related tools, and notes live in [awesome-tdk-framework](https://github.com/flisk-sh/awesome-tdk-framework). Star this repo (`flisk`) if the CLI is what you run; use the awesome list to browse the rest.
+**Ecosystem map:** examples, articles, related tools, and notes live in [awesome-flisk-framework](https://github.com/flisk-sh/awesome-flisk-framework). Star this repo (`flisk`) if the CLI is what you run; use the awesome list to browse the rest.
 
 <p align="center">
 

package/cli/dist/agent-runtimes/custom.js

@@ -24,6 +24,13 @@ interface Checkpoint {
   messages: Array<{ role: 'user' | 'agent'; content: string; at: string }>;
 }
 
+// One row of GET /sessions: what is stored, not what is in it, so listing never reads a whole conversation.
+interface SessionSummary {
+  sessionId: string;
+  lastActivity: string;
+  checkpointBytes: number;
+}
+
 let client: Client | null = null;
 let initialized = false;
 
@@ -69,6 +76,17 @@ const store = {
       return { sessionId, messages: [] };
     }
   },
+  async list(): Promise<SessionSummary[]> {
+    const c = await getClient();
+    const res = await c.query(
+      'SELECT session_id, updated_at, octet_length(messages::text) AS bytes FROM flisk_agent_sessions',
+    );
+    return res.rows.map((row: { session_id: string; updated_at: Date; bytes: number }) => ({
+      sessionId: row.session_id,
+      lastActivity: new Date(row.updated_at).toISOString(),
+      checkpointBytes: Number(row.bytes),
+    }));
+  },
   async save(checkpoint: Checkpoint): Promise<void> {
     const c = await getClient();
     await c.query(
@@ -100,6 +118,9 @@ async function runTurn(checkpoint: Checkpoint, input: string): Promise<string> {
 
 let draining = false;
 let inFlight = 0;
+// Turns in flight per session, so GET /sessions can tell an active session from an idle one.
+const activeTurns = new Map<string, number>();
+const SESSION_LIST_LIMIT = 500;
 
 function sendJson(res: ServerResponse, status: number, body: unknown) {
   res.statusCode = status;
@@ -139,12 +160,19 @@ const server = createServer(async (req, res) => {
       }
       const body = await readJson(req);
       const input = String(body.input ?? '');
-      const checkpoint = await store.load(sessionId);
-      checkpoint.messages.push({ role: 'user', content: input, at: new Date().toISOString() });
-      const reply = await runTurn(checkpoint, input);
-      checkpoint.messages.push({ role: 'agent', content: reply, at: new Date().toISOString() });
-      await store.save(checkpoint);
-      return sendJson(res, 200, { sessionId, reply, turns: checkpoint.messages.length / 2 });
+      activeTurns.set(sessionId, (activeTurns.get(sessionId) ?? 0) + 1);
+      try {
+        const checkpoint = await store.load(sessionId);
+        checkpoint.messages.push({ role: 'user', content: input, at: new Date().toISOString() });
+        const reply = await runTurn(checkpoint, input);
+        checkpoint.messages.push({ role: 'agent', content: reply, at: new Date().toISOString() });
+        await store.save(checkpoint);
+        return sendJson(res, 200, { sessionId, reply, turns: checkpoint.messages.length / 2 });
+      } finally {
+        const left = (activeTurns.get(sessionId) ?? 1) - 1;
+        if (left > 0) activeTurns.set(sessionId, left);
+        else activeTurns.delete(sessionId);
+      }
     }
 
     if (url.pathname === '/session' && req.method === 'GET') {
@@ -154,6 +182,17 @@ const server = createServer(async (req, res) => {
       return sendJson(res, 200, { sessionId, turns: checkpoint.messages.length / 2, messages: checkpoint.messages });
     }
 
+    // Read-only list of the stored sessions, most recent first. status is 'active' while this instance runs a turn
+    // for the session, otherwise 'idle'. total counts every stored session, also those past the limit.
+    if (url.pathname === '/sessions' && req.method === 'GET') {
+      const all = (await store.list()).sort((a, b) => b.lastActivity.localeCompare(a.lastActivity));
+      const sessions = all.slice(0, SESSION_LIST_LIMIT).map((s) => ({
+        ...s,
+        status: activeTurns.has(s.sessionId) ? 'active' : 'idle',
+      }));
+      return sendJson(res, 200, { sessions, total: all.length });
+    }
+
     return sendJson(res, 404, { error: 'not_found' });
   } catch (error) {
     console.error('[agent] request failed:', error);
@@ -189,7 +228,7 @@ process.on('SIGINT', () => shutdown('SIGINT'));
 `;
     }
     return `import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
-import { mkdirSync, readFileSync, renameSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 
 // Contract with Flisk (see docs/agents/ai-agents.md):
@@ -208,6 +247,13 @@ interface Checkpoint {
   messages: Array<{ role: 'user' | 'agent'; content: string; at: string }>;
 }
 
+// One row of GET /sessions: what is stored, not what is in it, so listing never reads a whole conversation.
+interface SessionSummary {
+  sessionId: string;
+  lastActivity: string;
+  checkpointBytes: number;
+}
+
 // Session store. files: one JSON checkpoint per session, written atomically (temp file, then rename), so a kill
 // mid-write leaves the previous checkpoint intact.
 const store = {
@@ -223,6 +269,20 @@ const store = {
     const file = join(STATE_DIR, sessionId + '.json');
     return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : { sessionId, messages: [] };
   },
+  list(): SessionSummary[] {
+    if (!existsSync(STATE_DIR)) return [];
+    // Only finished checkpoints: an in-progress write is still a .tmp file.
+    return readdirSync(STATE_DIR)
+      .filter((file) => file.endsWith('.json'))
+      .flatMap((file) => {
+        try {
+          const stat = statSync(join(STATE_DIR, file));
+          return [{ sessionId: file.slice(0, -'.json'.length), lastActivity: stat.mtime.toISOString(), checkpointBytes: stat.size }];
+        } catch {
+          return []; // removed between the directory read and the stat
+        }
+      });
+  },
   save(checkpoint: Checkpoint): void {
     mkdirSync(STATE_DIR, { recursive: true });
     const file = join(STATE_DIR, checkpoint.sessionId + '.json');
@@ -241,6 +301,9 @@ async function runTurn(checkpoint: Checkpoint, input: string): Promise<string> {
 
 let draining = false;
 let inFlight = 0;
+// Turns in flight per session, so GET /sessions can tell an active session from an idle one.
+const activeTurns = new Map<string, number>();
+const SESSION_LIST_LIMIT = 500;
 
 function sendJson(res: ServerResponse, status: number, body: unknown) {
   res.statusCode = status;
@@ -280,12 +343,19 @@ const server = createServer(async (req, res) => {
       }
       const body = await readJson(req);
       const input = String(body.input ?? '');
-      const checkpoint = await store.load(sessionId);
-      checkpoint.messages.push({ role: 'user', content: input, at: new Date().toISOString() });
-      const reply = await runTurn(checkpoint, input);
-      checkpoint.messages.push({ role: 'agent', content: reply, at: new Date().toISOString() });
-      await store.save(checkpoint);
-      return sendJson(res, 200, { sessionId, reply, turns: checkpoint.messages.length / 2 });
+      activeTurns.set(sessionId, (activeTurns.get(sessionId) ?? 0) + 1);
+      try {
+        const checkpoint = await store.load(sessionId);
+        checkpoint.messages.push({ role: 'user', content: input, at: new Date().toISOString() });
+        const reply = await runTurn(checkpoint, input);
+        checkpoint.messages.push({ role: 'agent', content: reply, at: new Date().toISOString() });
+        await store.save(checkpoint);
+        return sendJson(res, 200, { sessionId, reply, turns: checkpoint.messages.length / 2 });
+      } finally {
+        const left = (activeTurns.get(sessionId) ?? 1) - 1;
+        if (left > 0) activeTurns.set(sessionId, left);
+        else activeTurns.delete(sessionId);
+      }
     }
 
     if (url.pathname === '/session' && req.method === 'GET') {
@@ -295,6 +365,17 @@ const server = createServer(async (req, res) => {
       return sendJson(res, 200, { sessionId, turns: checkpoint.messages.length / 2, messages: checkpoint.messages });
     }
 
+    // Read-only list of the stored sessions, most recent first. status is 'active' while this instance runs a turn
+    // for the session, otherwise 'idle'. total counts every stored session, also those past the limit.
+    if (url.pathname === '/sessions' && req.method === 'GET') {
+      const all = (await store.list()).sort((a, b) => b.lastActivity.localeCompare(a.lastActivity));
+      const sessions = all.slice(0, SESSION_LIST_LIMIT).map((s) => ({
+        ...s,
+        status: activeTurns.has(s.sessionId) ? 'active' : 'idle',
+      }));
+      return sendJson(res, 200, { sessions, total: all.length });
+    }
+
     return sendJson(res, 404, { error: 'not_found' });
   } catch (error) {
     console.error('[agent] request failed:', error);

package/cli/dist/commands/agent.js

@@ -1,57 +1,64 @@
 // Copyright (c) 2026 Flisk Landscape contributors
 // SPDX-License-Identifier: MIT
-import * as http from "node:http";
 import chalk from "chalk";
 import { Command } from "commander";
+import { formatAge } from "../utils/agent-format.js";
+import { agentSessionListRequest, agentSessionRequest, fetchAgent, parseAgentSessionList, } from "../utils/agent-sessions.js";
 import { createDiscoveryContext } from "../utils/discovery-context.js";
 import { errorFactories, FliskError, runCommand } from "../utils/errors.js";
+import { formatBytes } from "../utils/formatting.js";
 import { getHostPortPlan } from "../utils/host-port-config.js";
 import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
 import { findProjectRoot } from "../utils/paths.js";
 import { buildServicePorts } from "../utils/status-ports.js";
-const SESSION_REQUEST_TIMEOUT_MS = 10_000;
-/** GET with node:http because fetch silently drops a custom Host header, which is what Traefik routes on. */
-export function httpGet(url, headers, timeoutMs) {
-    return new Promise((resolve, reject) => {
-        // One signal covers the connection and the body read, so a hung agent cannot block the CLI.
-        const req = http.get(url, { headers, signal: AbortSignal.timeout(timeoutMs) }, (res) => {
-            const chunks = [];
-            res.on("data", (chunk) => chunks.push(chunk));
-            res.on("end", () => {
-                const status = res.statusCode ?? 0;
-                resolve({
-                    ok: status >= 200 && status < 300,
-                    status,
-                    text: Buffer.concat(chunks).toString("utf-8"),
-                });
-            });
-            res.on("error", reject);
-        });
-        req.on("error", reject);
-    });
-}
-/**
- * Agent containers publish no host port; the only way in is the Traefik route that `flisk status` prints as `url`
- * (for example http://api.<project>.localhost:8080/api/bot). `*.localhost` does not resolve everywhere (glibc without
- * systemd-resolved), so connect to loopback and keep the route's host in the Host header, which is all Traefik matches on.
- */
-export function agentSessionRequest(routeUrl, sessionId) {
-    const route = new URL(routeUrl);
-    const headers = { "x-session-id": sessionId };
-    if (route.hostname.endsWith(".localhost")) {
-        headers.host = route.host;
-        route.hostname = "127.0.0.1";
+export { formatAge } from "../utils/agent-format.js";
+export { agentSessionRequest, httpGet } from "../utils/agent-sessions.js";
+const WATCH_INTERVAL_MS = 2_000;
+/** The plain-text table `flisk agent sessions <resource>` prints, one line per session. */
+export function formatSessionTable(list, now = Date.now()) {
+    if (list.sessions.length === 0)
+        return ["No sessions yet."];
+    const rows = list.sessions.map((s) => [
+        s.sessionId,
+        formatAge(s.lastActivity, now),
+        s.status,
+        s.checkpointBytes === null ? "-" : formatBytes(s.checkpointBytes),
+    ]);
+    const header = ["SESSION", "LAST ACTIVITY", "STATUS", "CHECKPOINT"];
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    const line = (cells) => cells
+        .map((c, i) => (i === cells.length - 1 ? c : c.padEnd(widths[i])))
+        .join("  ")
+        .trimEnd();
+    const lines = [line(header), ...rows.map(line)];
+    if (list.total > list.sessions.length) {
+        lines.push(`... ${list.total - list.sessions.length} more not shown`);
     }
-    return { url: `${route.origin}${route.pathname.replace(/\/$/, "")}/session`, headers };
+    return lines;
 }
 export const agentCommand = new Command("agent").description("Inspect and operate AI agent resources");
 agentCommand
     .command("sessions <resource>")
-    .description("Inspect session checkpoints from a running AI agent resource")
-    .option("--session-id <id>", "Session ID to fetch (required)")
+    .description("List the sessions of a running AI agent resource, or inspect one session's checkpoint")
+    .option("--session-id <id>", "Session ID to fetch; without it, list all sessions")
+    .option("--watch", "Refresh the output every 2 seconds until interrupted", false)
     .option("--json", "Output one JSON object and exit", false)
     .action(async (resourceName, options) => {
+    // JSON mode prints its envelope and exits 1; human mode throws, and runCommand prints the message and hints.
+    const fail = ({ code, message, hints }) => {
+        if (options.json) {
+            console.log(JSON.stringify(createMachineEnvelope(null, [{ code, message }])));
+            process.exit(1);
+        }
+        throw new FliskError(message, hints);
+    };
     const action = async () => {
+        if (options.watch && options.json) {
+            fail({
+                code: "USAGE",
+                message: "--watch refreshes a table on the terminal and cannot be combined with --json.",
+            });
+        }
         const root = findProjectRoot();
         if (!root) {
             const error = errorFactories.notInProject();
@@ -62,112 +69,126 @@ agentCommand
         const discovery = createDiscoveryContext();
         const resource = discovery.resources.find((r) => r.name === resourceName);
         if (!resource) {
-            const msg = `Resource "${resourceName}" not found in project.`;
-            if (options.json) {
-                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "UNKNOWN_RESOURCE", message: msg }])));
-                process.exit(1);
-            }
-            throw new FliskError(msg);
+            fail({
+                code: "UNKNOWN_RESOURCE",
+                message: `Resource "${resourceName}" not found in project.`,
+            });
+            return;
         }
         const appType = resource.config?.appType ?? resource.type;
         if (appType !== "agent") {
-            const msg = `Resource "${resourceName}" is of type "${appType}", not "agent".`;
-            if (options.json) {
-                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "NOT_AN_AGENT", message: msg }])));
-                process.exit(1);
-            }
-            throw new FliskError(msg);
+            fail({
+                code: "NOT_AN_AGENT",
+                message: `Resource "${resourceName}" is of type "${appType}", not "agent".`,
+            });
         }
         const port = resource.port;
         if (!port) {
-            const msg = `Agent "${resourceName}" has no assigned port.`;
-            if (options.json) {
-                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "NO_PORT", message: msg }])));
-                process.exit(1);
-            }
-            throw new FliskError(msg);
-        }
-        // The agent runtime keys GET /session by x-session-id and has no list endpoint, so a missing id
-        // would only come back as a confusing 400. Fail before any request. Checked after resource
-        // validation so UNKNOWN_RESOURCE, NOT_AN_AGENT and NO_PORT keep their precedence.
-        const sessionId = typeof options.sessionId === "string" ? options.sessionId.trim() : "";
-        if (!sessionId) {
-            const msg = `--session-id is required: the agent "${resourceName}" returns the checkpoint of one session.`;
-            if (options.json) {
-                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "SESSION_ID_REQUIRED", message: msg }])));
-                process.exit(1);
-            }
-            throw new FliskError(msg, [`Run: flisk agent sessions ${resourceName} --session-id <id>`]);
+            fail({ code: "NO_PORT", message: `Agent "${resourceName}" has no assigned port.` });
         }
         const portPlan = root
             ? await getHostPortPlan(root, { inspectDocker: false }).catch(() => null)
             : null;
         const routeUrl = buildServicePorts(resource, portPlan?.ingressHttp).url;
         if (!routeUrl) {
-            const msg = `Agent "${resourceName}" has no ingress route to reach it through.`;
-            if (options.json) {
-                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "NO_ROUTE", message: msg }])));
-                process.exit(1);
-            }
-            throw new FliskError(msg);
+            fail({
+                code: "NO_ROUTE",
+                message: `Agent "${resourceName}" has no ingress route to reach it through.`,
+            });
+            return;
         }
-        const request = agentSessionRequest(routeUrl, sessionId);
-        // Nothing answered, or Traefik answered for a missing backend: either way the agent is not up.
-        const notRunning = () => {
-            const msg = `Agent "${resourceName}" is not responding at ${routeUrl}. Is the stack running?`;
-            if (options.json) {
-                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "AGENT_NOT_RUNNING", message: msg }])));
-                process.exit(1);
+        // With an id: the one checkpoint that GET /session returns. Without: the list from GET /sessions.
+        const sessionId = typeof options.sessionId === "string" ? options.sessionId.trim() : "";
+        const notRunning = {
+            code: "AGENT_NOT_RUNNING",
+            message: `Agent "${resourceName}" is not responding at ${routeUrl}. Is the stack running?`,
+            hints: ["Start the stack with: flisk up"],
+        };
+        const requestFailed = (reply) => ({
+            code: "AGENT_REQUEST_FAILED",
+            message: `Agent returned ${reply.status}: ${reply.detail}`,
+        });
+        /** One request and its rendering: the data for --json, or the lines a human sees. */
+        const load = async () => {
+            if (sessionId) {
+                const reply = await fetchAgent(agentSessionRequest(routeUrl, sessionId));
+                if (reply.kind === "not-running")
+                    return { ok: false, failure: notRunning };
+                if (reply.kind === "not-found") {
+                    const detail = reply.body?.error;
+                    return {
+                        ok: false,
+                        failure: requestFailed({
+                            kind: "error",
+                            status: 404,
+                            detail: typeof detail === "string" ? detail : JSON.stringify(reply.body),
+                        }),
+                    };
+                }
+                if (reply.kind === "error")
+                    return { ok: false, failure: requestFailed(reply) };
+                return {
+                    ok: true,
+                    data: { agent: resourceName, port, session: reply.body },
+                    lines: [
+                        chalk.bold(`Sessions for ${resourceName}:`),
+                        JSON.stringify(reply.body, null, 2),
+                    ],
+                };
+            }
+            const reply = await fetchAgent(agentSessionListRequest(routeUrl));
+            if (reply.kind === "not-running")
+                return { ok: false, failure: notRunning };
+            // The agent answered, but not for /sessions: it was scaffolded before the list endpoint existed.
+            const list = reply.kind === "ok" ? parseAgentSessionList(reply.body) : null;
+            if (reply.kind === "not-found" || (reply.kind === "ok" && !list)) {
+                return {
+                    ok: false,
+                    failure: {
+                        code: "SESSION_LIST_UNSUPPORTED",
+                        message: `Agent "${resourceName}" does not serve GET /sessions; it was created before Flisk could list agent sessions.`,
+                        hints: [
+                            `Read one session with: flisk agent sessions ${resourceName} --session-id <id>`,
+                            "Or copy the /sessions handler from a new scaffold (flisk resource <name> --type agent) into the agent's src/index.ts",
+                        ],
+                    },
+                };
             }
-            throw new FliskError(msg, ["Start the stack with: flisk up"]);
+            if (reply.kind === "error")
+                return { ok: false, failure: requestFailed(reply) };
+            const sessions = list;
+            return {
+                ok: true,
+                data: { agent: resourceName, port, sessions: sessions.sessions, total: sessions.total },
+                lines: [chalk.bold(`Sessions for ${resourceName}:`), ...formatSessionTable(sessions)],
+            };
         };
-        let res;
-        let bodyText;
-        try {
-            const reply = await httpGet(request.url, request.headers, SESSION_REQUEST_TIMEOUT_MS);
-            res = reply;
-            bodyText = reply.text;
-        }
-        catch {
-            return notRunning();
-        }
-        let body = {};
-        try {
-            body = bodyText ? JSON.parse(bodyText) : {};
-        }
-        catch {
-            body = { raw: bodyText };
-        }
-        // Traefik answers 502/503/504 when the route has no live container and a plain-text 404 when it has no route at
-        // all. An agent's own errors are JSON, so a non-JSON 404 is the gateway, not the agent.
-        const gatewayText = typeof body === "object" && body !== null && "raw" in body;
-        if (!res.ok &&
-            ([502, 503, 504].includes(res.status) || (res.status === 404 && gatewayText))) {
-            return notRunning();
-        }
-        if (!res.ok) {
-            const detail = body?.error ?? bodyText;
+        if (!options.watch) {
+            const result = await load();
+            if (!result.ok) {
+                fail(result.failure);
+                return;
+            }
             if (options.json) {
-                console.log(JSON.stringify(createMachineEnvelope(null, [
-                    {
-                        code: "AGENT_REQUEST_FAILED",
-                        message: `Agent returned ${res.status}: ${detail}`,
-                    },
-                ])));
-                process.exit(1);
+                console.log(JSON.stringify(createMachineEnvelope(result.data)));
+                return;
             }
-            throw new FliskError(`Agent error (${res.status}): ${detail}`);
-        }
-        if (options.json) {
-            console.log(JSON.stringify(createMachineEnvelope({
-                agent: resourceName,
-                port,
-                session: body,
-            })));
+            for (const line of result.lines)
+                console.log(line);
             return;
         }
-        console.log(chalk.bold(`Sessions for ${resourceName}:`));
-        console.log(JSON.stringify(body, null, 2));
+        // --watch: redraw on a timer. A failed refresh (the agent restarting, say) is shown and retried, not fatal.
+        for (;;) {
+            const result = await load();
+            const lines = result.ok
+                ? result.lines
+                : [chalk.red(result.failure.message), ...(result.failure.hints ?? [])];
+            process.stdout.write("\x1b[2J\x1b[H");
+            for (const line of lines)
+                console.log(line);
+            console.log(chalk.dim(`\nRefreshing every ${WATCH_INTERVAL_MS / 1000}s. Ctrl+C to stop.`));
+            await new Promise((resolve) => setTimeout(resolve, WATCH_INTERVAL_MS));
+        }
     };
     if (options.json) {
         try {