@flisk-sh/flisk 1.4.6 → 1.4.7

package/cli/dist/commands/logs.js

@@ -2,13 +2,16 @@
 // SPDX-License-Identifier: MIT
 import { Command } from "commander";
 import { STANDARD_PORTS } from "../utils/constants.js";
+import { getDeferredResourceNames } from "../utils/doctor-runtime.js";
 import { errorFactories, FliskError, runCommand, showErrorAndExit } from "../utils/errors.js";
 import { createMachineEnvelope } from "../utils/machine-output.js";
-import { readNativeLogLines } from "../utils/native-runtime.js";
+import { nativeServiceStates, readNativeLogLines } from "../utils/native-runtime.js";
 import { isNativeProject } from "../utils/native-service.js";
 import { findProjectRoot } from "../utils/paths.js";
 import { EnvUnreadableError, envSecretValues, redactSecrets, redactValue, } from "../utils/secret-redaction.js";
+import { deriveServiceStates } from "../utils/service-runtime-state.js";
 import { discoverResourcesFromRoot } from "../utils/services.js";
+import { unhealthyServiceNames } from "../utils/status-groups.js";
 import { isTiltAvailable, runTilt } from "../utils/tilt.js";
 import { DEFAULT_LOG_TAIL, isTiltConnectionFailure, isValidPort, isValidSince, isValidTail, MAX_LOG_TAIL, parseTiltLogLines, sinceMilliseconds, } from "../utils/tilt-logs.js";
 import { tiltUnreachableMessage } from "../utils/tilt-unreachable-message.js";
@@ -28,6 +31,38 @@ async function tiltResourceNames(port) {
         return null;
     }
 }
+/** Raw `tilt get uiresources` JSON, or null when Tilt cannot be read. */
+async function tiltResourcesJson(port) {
+    try {
+        const result = await runTilt("get", ["uiresources", "-o", "json", "--port", port], {
+            inheritStdio: false,
+        });
+        return result.exitCode === 0 ? result.stdout : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Failing or pending services among the project's, from the running Tilt; null when Tilt cannot be read. */
+async function tiltUnhealthyNames(projectRoot, port) {
+    const text = await tiltResourcesJson(port);
+    if (!text)
+        return null;
+    let resources = [];
+    try {
+        resources = discoverResourcesFromRoot(projectRoot);
+    }
+    catch {
+        // Without discovery there are no dependsOn edges; Tilt's own states still decide.
+    }
+    try {
+        const states = deriveServiceStates(text, Object.fromEntries(resources.map((r) => [r.name, r.config?.dependsOn ?? []])), getDeferredResourceNames(resources));
+        return unhealthyServiceNames(Object.keys(states).map((name) => ({ name })), states);
+    }
+    catch {
+        return null;
+    }
+}
 /** The project's services when every one declares `command` (they run as local processes), else null. */
 function nativeResources(projectRoot) {
     try {
@@ -45,6 +80,7 @@ export const logsCommand = new Command("logs")
     .option("-s, --service <names...>", "Only these services (Tilt resource names)")
     .option("--tail <n>", "Number of most recent lines to return", String(DEFAULT_LOG_TAIL))
     .option("--since <duration>", "Only logs newer than this duration, for example 30s, 5m, 1h")
+    .option("--unhealthy", "Only services that are failing or still starting", false)
     .option("--port <n>", "Tilt UI port (default: TILT_PORT or 10350)")
     .option("--json", "Output one JSON object and exit", false)
     .action(async (options) => {
@@ -78,6 +114,19 @@ export const logsCommand = new Command("logs")
         fail("USAGE", "--port must be a valid port number", 2);
     const tail = Number(options.tail);
     const services = options.service ?? [];
+    const reportAllHealthy = () => {
+        if (options.json) {
+            console.log(JSON.stringify(createMachineEnvelope({
+                services,
+                tail,
+                since: options.since ?? null,
+                lines: [],
+                unhealthy: [],
+            })));
+            return;
+        }
+        console.log("All services are healthy; nothing to show with --unhealthy.");
+    };
     const action = async () => {
         const projectRoot = findProjectRoot();
         if (!projectRoot) {
@@ -104,7 +153,15 @@ export const logsCommand = new Command("logs")
                 const error = errorFactories.unknownServices(unknown, known);
                 fail("UNKNOWN_SERVICE", error.message, error.exitCode, error.suggestions);
             }
-            const lines = readNativeLogLines(projectRoot, services.length > 0 ? services : known, {
+            let selected = services.length > 0 ? services : known;
+            if (options.unhealthy) {
+                const states = nativeServiceStates(projectRoot, known);
+                const bad = new Set(unhealthyServiceNames(resources, states));
+                selected = selected.filter((name) => bad.has(name));
+                if (selected.length === 0)
+                    return reportAllHealthy();
+            }
+            const lines = readNativeLogLines(projectRoot, selected, {
                 tail,
                 sinceMs: options.since === undefined ? undefined : sinceMilliseconds(options.since),
             });
@@ -130,14 +187,24 @@ export const logsCommand = new Command("logs")
                 fail("UNKNOWN_SERVICE", error.message, error.exitCode, suggestions);
             }
         }
+        let selectedServices = services;
+        if (options.unhealthy) {
+            const bad = await tiltUnhealthyNames(projectRoot, portText);
+            if (bad === null)
+                fail("TILT_NOT_RUNNING", tiltUnreachableMessage(portText));
+            selectedServices =
+                services.length > 0 ? services.filter((n) => bad?.includes(n)) : (bad ?? []);
+            if (selectedServices.length === 0)
+                return reportAllHealthy();
+        }
         const args = ["--port", portText, "--tail", String(tail)];
         if (options.since !== undefined)
             args.push("--since", options.since);
         if (options.json)
             args.push("--json");
         // `--` so a service name that starts with "-" is never read as a Tilt flag.
-        if (services.length > 0)
-            args.push("--", ...services);
+        if (selectedServices.length > 0)
+            args.push("--", ...selectedServices);
         const result = await runTilt("logs", args, { inheritStdio: false });
         if (result.exitCode !== 0) {
             const detail = result.stderr.trim();

package/cli/dist/commands/project.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import { Command } from "commander";
 import { generateMasterConfigs, readProjectConfig } from "../generator/template-engine.js";
+import { installAgentSkills } from "../utils/agent-skills.js";
 import { addYesOption } from "../utils/command-helpers.js";
 import { MASTER_CONFIG_FILES, PROJECT_JSON } from "../utils/constants.js";
 import { clearDiscoveryCache } from "../utils/discovery-context.js";
@@ -233,6 +234,7 @@ export const projectCommand = addYesOption(new Command("project"))
     .option("--force", "Overwrite existing configuration (dangerous)")
     .option("--config-file <path>", "Load project config from existing JSON file")
     .option("-q, --quiet", "Only print what fails; used by `flisk demo`", false)
+    .option("--no-agent-skills", "Do not write the Flisk agent skills (.claude/skills, .agents/skills) and AGENTS.md")
     .action(async (template, options) => {
     const { assertMachineReadyOrExit, detectRuntimePrerequisites, formatRuntimeNextSteps } = await import("../utils/cold-preflight.js");
     // Project setup only writes files: it must not need a running Docker daemon
@@ -493,6 +495,20 @@ export const projectCommand = addYesOption(new Command("project"))
         if (ignored.length > 0 && !quiet) {
             showSuccess(`Added to .gitignore: ${ignored.join(", ")}`);
         }
+        // A coding agent opened in the project then knows to build and run the app with Flisk.
+        // The project works without them, so a failure here is a warning, not an exit.
+        if (options.agentSkills !== false) {
+            try {
+                const skillFiles = installAgentSkills(projectRoot);
+                if (skillFiles.length > 0 && !quiet) {
+                    showSuccess("Added agent skills: .claude/skills, .agents/skills and AGENTS.md (start with flisk-build)");
+                }
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                console.log(chalk.yellow(`⚠️  Could not add the agent skills: ${reason}`));
+            }
+        }
         if (!quiet) {
             console.log(chalk.green("\n✅ Project configuration complete!"));
             showDetail("\nGenerated files in .flisk/.flisk-out/:", 0);

package/cli/dist/commands/resource.js

@@ -231,7 +231,9 @@ export function createPackageJson(name, type, frameworkId, prismaEnabled = false
             // vitest 5 peers on vite ^6.4.0 || ^7 || ^8; vite 5 makes `vitest run` fail at startup with
             // ERR_PACKAGE_PATH_NOT_EXPORTED ('./module-runner'), in every resource once it is hoisted.
             ...(isFrontend && !framework?.scripts ? { vite: "^6.4.1" } : {}),
-            ...(drizzleEnabled ? { "drizzle-kit": DRIZZLE_KIT_RANGE, "@types/pg": "^8.11.0" } : {}),
+            ...(drizzleEnabled ? { "drizzle-kit": DRIZZLE_KIT_RANGE } : {}),
+            // Both import 'pg' (src/db.ts, the agent's checkpoint store); without the types the image's `tsc` fails with TS7016.
+            ...(drizzleEnabled || isPostgresAgent ? { "@types/pg": "^8.11.0" } : {}),
             ...(framework?.devDependencies ?? {}),
             ...(backendFramework?.devDependencies ?? {}),
         },

package/cli/dist/commands/status.js

@@ -13,6 +13,7 @@ import { isNativeProject } from "../utils/native-service.js";
 import { findProjectRoot } from "../utils/paths.js";
 import { deriveServiceStates } from "../utils/service-runtime-state.js";
 import { groupSharedPostgres, readProjectName } from "../utils/shared-infra.js";
+import { groupServicesByStack, unhealthyServiceNames } from "../utils/status-groups.js";
 import { buildServicePorts, buildStackPorts } from "../utils/status-ports.js";
 import { isTiltAvailable, runTilt } from "../utils/tilt.js";
 import { getTiltPollingPort } from "../utils/tilt-startup.js";
@@ -24,6 +25,7 @@ export const statusCommand = new Command("status")
     .option("--stacks", "Show stack information (default)", true)
     .option("--resources", "Show all discovered resources", false)
     .option("--tilt", "Show tilt resource status", false)
+    .option("--unhealthy", "Show only services that are failing or still starting", false)
     .action(async (options) => {
     const action = async () => {
         // Discover first: outside a project this fails before any status line is printed.
@@ -155,9 +157,12 @@ export const statusCommand = new Command("status")
                     name: stack.name,
                     resourceCount: stack.resourceCount,
                     resources: stack.resources.map((resource) => resource.name),
+                    healthyCount: stack.resources.filter((resource) => serviceStates?.[resource.name]?.status === "ready").length,
                 })),
                 unassignedResources: discovery.unassignedResources.map((resource) => resource.name),
                 sharedInfra: sharedInfraGroup,
+                // Names of the failing or pending services, so a caller need not filter `resources` itself.
+                unhealthy: unhealthyServiceNames(discovery.resources, serviceStates),
             };
             console.log(JSON.stringify(createMachineEnvelope(data, errors)));
             if (errors.length > 0) {
@@ -168,27 +173,29 @@ export const statusCommand = new Command("status")
         }
         console.log(chalk.bold("Resources:"), `${discovery.resources.length} discovered`);
         console.log(chalk.bold("Stacks:"), `${discovery.stacks.length} defined`);
-        if (discovery.stacks.length > 0) {
+        const hasStates = serviceStates !== null && Object.keys(serviceStates).length > 0;
+        const unhealthyOnly = Boolean(options.unhealthy);
+        // With service states the grouped "Services:" section below replaces the plain per-stack counts.
+        if (!hasStates && !unhealthyOnly) {
             for (const stack of discovery.stacks) {
-                const resourcesInStack = stack.resources.length;
-                showDetail(`${stack.name}: ${formatCount(resourcesInStack, "resource")}`);
+                showDetail(`${stack.name}: ${formatCount(stack.resources.length, "resource")}`);
                 if (options.verbose) {
                     for (const resource of stack.resources) {
                         showDetail(`${resource.name}`, 6);
                     }
                 }
             }
-        }
-        if (discovery.unassignedResources.length > 0) {
-            console.log();
-            console.log(chalk.yellow(`${formatCount(discovery.unassignedResources.length, "resource")} not in any stack:`));
-            if (options.verbose) {
-                for (const resource of discovery.unassignedResources) {
-                    showDetail(`${resource.name}`);
+            if (discovery.unassignedResources.length > 0) {
+                console.log();
+                console.log(chalk.yellow(`${formatCount(discovery.unassignedResources.length, "resource")} not in any stack:`));
+                if (options.verbose) {
+                    for (const resource of discovery.unassignedResources) {
+                        showDetail(`${resource.name}`);
+                    }
                 }
             }
         }
-        if (sharedInfraGroup) {
+        if (sharedInfraGroup && !unhealthyOnly) {
             console.log();
             console.log(chalk.bold("Shared infrastructure:"));
             showDetail(`${sharedInfraGroup.name} (one instance, ${formatCount(sharedInfraGroup.databases.length, "database")})`);
@@ -196,21 +203,33 @@ export const statusCommand = new Command("status")
                 showDetail(`  ${database.name} (stack ${database.stack}): ${database.services.join(", ")}`);
             }
         }
-        if (serviceStates && Object.keys(serviceStates).length > 0) {
+        if (hasStates && serviceStates) {
+            const states = serviceStates;
             console.log();
-            console.log(chalk.bold("Services:"));
-            for (const resource of discovery.resources) {
-                const state = serviceStates[resource.name];
-                if (!state)
+            console.log(chalk.bold(unhealthyOnly ? "Unhealthy services:" : "Services:"));
+            const unhealthy = new Set(unhealthyServiceNames(discovery.resources, states));
+            if (unhealthyOnly && unhealthy.size === 0) {
+                showDetail(chalk.green("All services are healthy."));
+            }
+            for (const group of groupServicesByStack(discovery.stacks, discovery.unassignedResources, states)) {
+                const shown = group.resources.filter((resource) => states[resource.name] && (!unhealthyOnly || unhealthy.has(resource.name)));
+                if (unhealthyOnly && shown.length === 0)
                     continue;
-                const mark = state.status === "ready"
-                    ? chalk.green("✓")
-                    : state.status === "error"
-                        ? chalk.red("✗")
-                        : chalk.yellow("…");
-                const ports = buildServicePorts(resource, portPlan?.ingressHttp);
-                const urlPart = ports.url ? ` → ${ports.url}` : "";
-                showDetail(`${mark} ${resource.name}${urlPart}  ${state.status}${state.reason ? ` (${state.reason})` : ""}`);
+                const summary = `${group.healthy}/${group.total} healthy`;
+                showDetail(`${chalk.bold(group.name)}: ${group.healthy === group.total ? chalk.green(summary) : chalk.yellow(summary)}`);
+                for (const resource of shown) {
+                    const state = states[resource.name];
+                    if (!state)
+                        continue;
+                    const mark = state.status === "ready"
+                        ? chalk.green("✓")
+                        : state.status === "error"
+                            ? chalk.red("✗")
+                            : chalk.yellow("…");
+                    const ports = buildServicePorts(resource, portPlan?.ingressHttp);
+                    const urlPart = ports.url ? ` → ${ports.url}` : "";
+                    showDetail(`${mark} ${resource.name}${urlPart}  ${state.status}${state.reason ? ` (${state.reason})` : ""}`, 6);
+                }
             }
         }
         else if (discovery.resources.length > 0) {

package/cli/dist/commands/ui.js

@@ -7,6 +7,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { DetailPanel, FileTree, ResourceSelectInput, ResourceTable, ServiceIssues, TabBar, TUIHeader, } from "../components/index.js";
 import { TABS } from "../components/TabBar.js";
 import { createTUITheme, sectionTitle, TUIThemeContext, useTUITheme, } from "../components/ui-theme.js";
+import { fetchAgentOverview } from "../utils/agent-sessions.js";
 import { errorFactories, requireProjectRoot } from "../utils/errors.js";
 import { readSavedHostPortPlan } from "../utils/host-port-config.js";
 import { findProjectRoot, getPackageVersion } from "../utils/paths.js";
@@ -16,6 +17,7 @@ import { buildAdvertisedTargets } from "../utils/service-urls.js";
 import { clearMetadataCache, discoverResources, discoverStacks, getResourceMetadata, getStackMetadata, } from "../utils/services.js";
 import { singleFlight } from "../utils/single-flight.js";
 import { createStatusMessageController } from "../utils/status-message.js";
+import { buildServicePorts } from "../utils/status-ports.js";
 import { getListRowFromMouseY, getTerminalRuleWidth } from "../utils/terminal-layout.js";
 import { isTiltAvailable } from "../utils/tilt.js";
 import { loadTiltEvents, stripTerminalControls, TiltEventsLoadError, } from "../utils/tilt-events.js";
@@ -134,12 +136,45 @@ export const TUIApp = ({ animated = true }) => {
         });
         const poll = () => run(() => fetchServiceStates(services, tiltPort));
         void poll();
-        const timer = setInterval(() => void poll(), 5000);
+        // The agent panel rides on this same timer: the selected agent is read once per tick, never one loop per agent.
+        const timer = setInterval(() => {
+            void poll();
+            void agentPollRef.current();
+        }, 5000);
         return () => {
             cancelled = true;
             clearInterval(timer);
         };
     }, [services]);
+    // Readiness and sessions of the selected agent resource, read from the agent itself through its ingress route.
+    const [agentOverview, setAgentOverview] = useState(null);
+    const agentRoute = useMemo(() => {
+        const resource = services.find((s) => s.name === selectedService);
+        if (!resource || (resource.config?.appType ?? resource.type) !== "agent")
+            return null;
+        const url = buildServicePorts(resource, ingressPort).url;
+        return url ? { name: resource.name, url } : null;
+    }, [services, selectedService, ingressPort]);
+    const agentPollRef = useRef(async () => { });
+    useEffect(() => {
+        if (!agentRoute) {
+            agentPollRef.current = async () => { };
+            setAgentOverview(null);
+            return;
+        }
+        let cancelled = false;
+        const run = singleFlight((overview) => {
+            if (!cancelled)
+                setAgentOverview({ name: agentRoute.name, overview });
+        });
+        agentPollRef.current = () => run(() => fetchAgentOverview(agentRoute.url));
+        setAgentOverview(null);
+        void agentPollRef.current();
+        return () => {
+            cancelled = true;
+            agentPollRef.current = async () => { };
+        };
+    }, [agentRoute]);
     // Re-read service.json files from disk. An empty project is not an error:
     // it renders EmptyState. Only a failed discovery shows ErrorScreen.
     const refresh = useCallback(() => {
@@ -648,7 +683,11 @@ export const TUIApp = ({ animated = true }) => {
                                                                                 ? theme.info
                                                                                 : theme.success, children: [formatEventTime(event.occurredAt), " ", event.resourceName, " ", event.title] }), event.details && (_jsx(Text, { color: theme.muted, children: formatEventDetails(event.details, mainPanelWidth) }))] }, event.id))) })) : (_jsx(Text, { color: theme.muted, children: "No recent build events are available from Tilt yet." }))] }))] })), activeTab === "config" && (_jsxs(_Fragment, { children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, color: theme.muted, children: sectionTitle(theme, "Configuration") }) }), selectedServiceData ? (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: theme.accent, children: selectedServiceData.service.configPath }), _jsx(Box, { marginTop: 1, ...(theme.ascii
                                                             ? {}
-                                                            : { borderStyle: "single", borderColor: theme.border }), paddingX: 1, children: _jsx(Text, { color: theme.muted, wrap: "wrap", children: JSON.stringify(selectedServiceData.service.config, null, 2).slice(0, 1000) }) })] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: theme.muted, children: "Select a service to view configuration" }), _jsx(Box, { marginTop: 1, children: _jsx(ResourceSelectInput, { items: items, onSelect: handleSelect, highlightedIndex: highlightedIndex, isActive: !isSearching, maxVisibleItems: pageSize, width: mainPanelWidth, onLayout: handleListLayout }) })] }))] }))] }), showSidebar && (_jsx(Box, { marginLeft: 2, children: _jsx(DetailPanel, { stack: selectedStackData?.stack || null, service: selectedServiceData?.service || null, stackMetadata: selectedStackData?.metadata || null, visible: !!selectedStack || !!selectedService }) }))] }), _jsxs(Box, { ...(theme.ascii ? {} : { borderStyle: "single", borderColor: theme.border }), paddingX: 1, height: 3, flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { color: theme.accent, bold: true, children: [theme.bannerStart, " ", activeTab] }), _jsxs(Text, { color: theme.success, children: [theme.ascii ? "[+]" : "\u25cf", " ", services.filter((s) => s.stack).length, " in stack"] }), _jsxs(Text, { color: theme.warning, children: [theme.ascii ? "-" : "\u25cb", " ", services.filter((s) => !s.stack).length, " no stack"] })] }), _jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { color: theme.muted, children: ["Stacks: ", stacks.length] }), _jsxs(Text, { color: theme.muted, children: ["Services: ", services.length] }), _jsxs(Text, { color: theme.muted, children: [theme.ascii ? "Mouse" : "🖱️", " ", mouseEnabled ? "ON" : "OFF", theme.separator, theme.ascii ? "Info" : "ℹ️", " ", showTooltips ? "ON" : "OFF", theme.separator, _jsx(Text, { color: showEnabledOnly ? theme.success : theme.warning, children: showEnabledOnly
+                                                            : { borderStyle: "single", borderColor: theme.border }), paddingX: 1, children: _jsx(Text, { color: theme.muted, wrap: "wrap", children: JSON.stringify(selectedServiceData.service.config, null, 2).slice(0, 1000) }) })] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: theme.muted, children: "Select a service to view configuration" }), _jsx(Box, { marginTop: 1, children: _jsx(ResourceSelectInput, { items: items, onSelect: handleSelect, highlightedIndex: highlightedIndex, isActive: !isSearching, maxVisibleItems: pageSize, width: mainPanelWidth, onLayout: handleListLayout }) })] }))] }))] }), showSidebar && (_jsx(Box, { marginLeft: 2, children: _jsx(DetailPanel, { stack: selectedStackData?.stack || null, service: selectedServiceData?.service || null, stackMetadata: selectedStackData?.metadata || null, agent: agentRoute && selectedServiceData
+                                        ? agentOverview?.name === agentRoute.name
+                                            ? agentOverview.overview
+                                            : null
+                                        : undefined, visible: !!selectedStack || !!selectedService }) }))] }), _jsxs(Box, { ...(theme.ascii ? {} : { borderStyle: "single", borderColor: theme.border }), paddingX: 1, height: 3, flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { color: theme.accent, bold: true, children: [theme.bannerStart, " ", activeTab] }), _jsxs(Text, { color: theme.success, children: [theme.ascii ? "[+]" : "\u25cf", " ", services.filter((s) => s.stack).length, " in stack"] }), _jsxs(Text, { color: theme.warning, children: [theme.ascii ? "-" : "\u25cb", " ", services.filter((s) => !s.stack).length, " no stack"] })] }), _jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { color: theme.muted, children: ["Stacks: ", stacks.length] }), _jsxs(Text, { color: theme.muted, children: ["Services: ", services.length] }), _jsxs(Text, { color: theme.muted, children: [theme.ascii ? "Mouse" : "🖱️", " ", mouseEnabled ? "ON" : "OFF", theme.separator, theme.ascii ? "Info" : "ℹ️", " ", showTooltips ? "ON" : "OFF", theme.separator, _jsx(Text, { color: showEnabledOnly ? theme.success : theme.warning, children: showEnabledOnly
                                                     ? theme.ascii
                                                         ? "[+] enabled"
                                                         : "\u2713 enabled"

package/cli/dist/commands/up.js

@@ -12,7 +12,7 @@ import { STANDARD_PORTS } from "../utils/constants.js";
 import { getDeferredResourceNames, summarizeTiltBuildError } from "../utils/doctor-runtime.js";
 import { applyEnvFileSelection, assertEngineSupportsEnvFile, EnvFileError, envFileWarning, PROJECT_ENV_FILE_VAR, selectEnvFile, } from "../utils/env-selection.js";
 import { completeEnvFile } from "../utils/env-validator.js";
-import { errorFactories, FliskError, getErrorMessage, handleTiltFailure, requireProjectRoot, runCommand, showError, showErrorAndExit, withTiltCheck, } from "../utils/errors.js";
+import { errorFactories, FliskError, getErrorMessage, requireProjectRoot, runCommand, showError, showErrorAndExit, withTiltCheck, } from "../utils/errors.js";
 import { ensureSmokeRecordsIgnored } from "../utils/file-helpers.js";
 import { evaluateFliskVersionFloor } from "../utils/flisk-version.js";
 import { formatCount } from "../utils/formatting.js";
@@ -34,13 +34,15 @@ import { enforceServiceConfigGate, warnSchemaVersions } from "../utils/service-c
 import { appendHealthPath, resolveServiceUrl, resolveSubdomainBases, } from "../utils/service-urls.js";
 import { discoverResourcesStrict, discoverResourcesWithProblems, discoverStacks, getResourcesForStack, stackExists, warnAboutSkippedFiles, } from "../utils/services.js";
 import { buildSmokePlans, formatSmokeFailure, runSmokePlans, safeSmokeDeps, } from "../utils/smoke.js";
-import { buildStartupReport, formatStartupReport, isStartupStalled, } from "../utils/startup-report.js";
+import { buildStartupReport, formatStartupReport, isStartupStalled, machineProblemFixes, } from "../utils/startup-report.js";
 import { buildTiltUpArgs, runTilt } from "../utils/tilt.js";
 import { classifyTiltPorts } from "../utils/tilt-port-owner.js";
 import { stopTiltOnPort } from "../utils/tilt-process.js";
 import { parseTiltPort, resolveTiltPort, secondUpAction, stopTiltForUp, } from "../utils/tilt-startup.js";
+import { upFailureHints } from "../utils/up-hints.js";
 import { findUnknownServices, resolveOnlySelection } from "../utils/up-only.js";
-import { tiltGetUiResources, waitForTiltResourcesReady } from "../utils/up-readiness.js";
+import { createUpProgressReporter, fetchWithProgress, shouldRedrawUpProgress, } from "../utils/up-progress.js";
+import { tiltGetUiResources, tiltResourceLogs, waitForTiltResourcesReady, } from "../utils/up-readiness.js";
 import { enableDiscoveredStacks, writeDefaultProjectConfig } from "./project.js";
 export function formatUpSuccess(port, options = {}) {
     const { appUrls = [], serviceHealth = [], showLogsHint = serviceHealth.length > 0 } = options;
@@ -318,8 +320,11 @@ export const upCommand = new Command("up")
         options.quiet = true;
     const portSetting = parseTiltPort(process.env.TILT_PORT);
     if (!portSetting.ok) {
-        emit?.({ ok: false }, [{ code: "INVALID_TILT_PORT", message: portSetting.message }]);
-        showErrorAndExit(portSetting.message);
+        const suggestions = upFailureHints({ kind: "invalid-tilt-port" });
+        emit?.({ ok: false }, [
+            { code: "INVALID_TILT_PORT", message: portSetting.message, suggestions },
+        ]);
+        showErrorAndExit(portSetting.message, 1, suggestions);
     }
     const configuredTiltPort = portSetting.port;
     // First, before the host/Docker checks below: an old CLI must stop with one clear line, not a half-working stack.
@@ -441,7 +446,7 @@ export const upCommand = new Command("up")
     }
     if (!options.dryRun) {
         const { assertMachineReadyOrExit } = await import("../utils/cold-preflight.js");
-        await assertMachineReadyOrExit();
+        await assertMachineReadyOrExit({ hints: upFailureHints({ kind: "machine" }) });
     }
     const action = async () => {
         const foundRoot = options.dryRun ? requireProjectRoot() : findProjectRoot();
@@ -716,12 +721,16 @@ export const upCommand = new Command("up")
             let startedDependencies = dependencyNames;
             if (uiReady && emit) {
                 const deferred = getDeferredResourceNames(discoveredResources);
+                const dependsOn = Object.fromEntries(discoveredResources.map((r) => [r.name, r.config?.dependsOn ?? []]));
                 const readiness = await waitForTiltResourcesReady(port, {
                     deferred,
                     // Only what the caller named must be enabled. Dependencies are the Tiltfile's call (it skips some on purpose).
                     expected: options.only
                         ? options.only.filter((name) => !deferred.has(name))
                         : undefined,
+                    // As for the human output: stop as soon as everything left is blocked by a failure (for example init-networks),
+                    // instead of waiting out the whole timeout.
+                    isStalled: (text) => isStartupStalled(text, dependsOn, deferred),
                 });
                 if (readiness.ready) {
                     jsonReady = true;
@@ -735,11 +744,21 @@ export const upCommand = new Command("up")
                 }
                 else {
                     startupFailed = true;
-                    const detail = readiness.failures.map((f) => `${f.name}: ${f.message}`).join("; ");
+                    const fixes = await machineProblemFixes(readiness.failures, (name) => tiltResourceLogs(port, name));
+                    const detail = readiness.failures
+                        .map((f) => {
+                        const fix = fixes.get(f.name);
+                        return `${f.name}: ${f.message}${fix ? `. ${fix}` : ""}`;
+                    })
+                        .join("; ");
                     emit({ ok: false, tiltUrl: `http://localhost:${port}`, failures: readiness.failures }, [
                         {
                             code: readiness.timedOut ? "UP_TIMEOUT" : "UP_RESOURCE_FAILED",
                             message: `${readiness.timedOut ? "Timed out waiting for resources" : "Resources failed"}${detail ? ` (${detail})` : ""}. Tilt is still running; inspect it or run: flisk down`,
+                            suggestions: upFailureHints({
+                                kind: "services",
+                                failed: readiness.failures.map((failure) => failure.name),
+                            }),
                         },
                     ]);
                 }
@@ -749,10 +768,22 @@ export const upCommand = new Command("up")
             if (uiReady && !emit) {
                 const deferred = getDeferredResourceNames(discoveredResources);
                 const dependsOn = Object.fromEntries(discoveredResources.map((r) => [r.name, r.config?.dependsOn ?? []]));
+                const progress = createUpProgressReporter({
+                    write: (text) => process.stdout.write(text),
+                    redraw: shouldRedrawUpProgress({
+                        isTTY: process.stdout.isTTY,
+                        quiet: Boolean(options.quiet),
+                        env: process.env,
+                    }),
+                    deferred,
+                    columns: process.stdout.columns,
+                });
                 const readiness = await waitForTiltResourcesReady(port, {
                     deferred,
                     isStalled: (text) => isStartupStalled(text, dependsOn, deferred),
+                    fetchJson: fetchWithProgress(tiltGetUiResources, progress),
                 });
+                progress.finish();
                 if (!readiness.ready) {
                     startupFailed = true;
                     const resourcesJson = await tiltGetUiResources(port);
@@ -766,9 +797,13 @@ export const upCommand = new Command("up")
                             blocked: [],
                             starting: [],
                         };
-                    const reportLines = formatStartupReport(report, readiness.timedOut, (port) => findPortOccupant(port));
+                    const machineFixes = await machineProblemFixes(report.failed, (name) => tiltResourceLogs(port, name));
+                    const reportLines = formatStartupReport(report, readiness.timedOut, (port) => findPortOccupant(port), machineFixes);
                     if (reportLines.length > 0) {
-                        showError(reportLines.join("\n"));
+                        showError(reportLines.join("\n"), undefined, upFailureHints({
+                            kind: "services",
+                            failed: report.failed.map((failure) => failure.name),
+                        }));
                     }
                 }
             }
@@ -814,6 +849,7 @@ export const upCommand = new Command("up")
                         envFiles: envFileSelection ? [envFileSelection.path] : [],
                     }),
                 });
+                const smokeFailures = [];
                 for (const smokeResult of results) {
                     if (smokeResult.ok) {
                         if (!options.quiet)
@@ -821,13 +857,20 @@ export const upCommand = new Command("up")
                     }
                     else {
                         smokeFailed = true;
+                        smokeFailures.push(smokeResult.name);
                         showError(formatSmokeFailure(smokeResult));
                     }
                 }
                 if (smokeFailed) {
                     stopTiltOnPort(port);
+                    const suggestions = upFailureHints({ kind: "smoke", failed: smokeFailures });
+                    showError("A smoke check failed; Tilt was stopped", undefined, suggestions);
                     emit?.({ ok: false }, [
-                        { code: "UP_SMOKE_FAILED", message: "A smoke check failed; Tilt was stopped" },
+                        {
+                            code: "UP_SMOKE_FAILED",
+                            message: "A smoke check failed; Tilt was stopped",
+                            suggestions,
+                        },
                     ]);
                 }
             }
@@ -849,7 +892,7 @@ export const upCommand = new Command("up")
             process.exit(1);
         }
         if (result.exitCode !== 0) {
-            handleTiltFailure("up", result.exitCode);
+            showErrorAndExit(`tilt up failed with exit code ${result.exitCode}`, result.exitCode, upFailureHints({ kind: "tilt-exited" }));
         }
         if (startupFailed && result.exitCode === 0) {
             process.exit(1);

package/cli/dist/components/DetailPanel.js

@@ -1,10 +1,30 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Copyright (c) 2026 Flisk Landscape contributors
 // SPDX-License-Identifier: MIT
 import { Box, Text } from "ink";
+import { formatAge } from "../utils/agent-format.js";
 import { formatDate, getStatusColor, getStatusIcon } from "../utils/formatting.js";
 import { getTUIStatusColor, getTUIStatusIcon, useTUITheme } from "./ui-theme.js";
-export const DetailPanel = ({ stack, service, stackMetadata, visible, }) => {
+const MAX_LISTED_SESSIONS = 5;
+/** Readiness, session count, last activity and the newest sessions of an agent; `null` while the first poll is pending. */
+const AgentSection = ({ agent }) => {
+    const theme = useTUITheme();
+    const row = (label, value, color = theme.foreground) => (_jsxs(Box, { children: [_jsxs(Text, { color: theme.muted, children: [label, ": "] }), _jsx(Text, { color: color, children: value })] }));
+    let body;
+    if (agent === null) {
+        body = row("Agent", "checking...", theme.muted);
+    }
+    else if (agent.state === "not-running") {
+        body = row("Agent", "not running", theme.warning);
+    }
+    else {
+        const { sessions } = agent;
+        const newest = sessions?.sessions[0]?.lastActivity ?? null;
+        body = (_jsxs(_Fragment, { children: [row("Ready", agent.ready ? "yes" : "no", agent.ready ? theme.success : theme.warning), sessions ? (_jsxs(_Fragment, { children: [row("Sessions", String(sessions.total)), row("Last activity", formatAge(newest)), sessions.sessions.slice(0, MAX_LISTED_SESSIONS).map((s) => (_jsxs(Box, { children: [_jsx(Text, { color: theme.foreground, children: s.sessionId.slice(0, 18) }), _jsxs(Text, { color: theme.muted, children: [" ", formatAge(s.lastActivity), " ", s.status] })] }, s.sessionId))), sessions.total > MAX_LISTED_SESSIONS && (_jsxs(Text, { color: theme.muted, children: ["... ", sessions.total - MAX_LISTED_SESSIONS, " more"] }))] })) : (row("Sessions", "not available (agent has no /sessions)", theme.muted))] }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: theme.muted, underline: true, children: "Agent" }), body] }));
+};
+export const DetailPanel = ({ stack, service, stackMetadata, agent, visible, }) => {
     const theme = useTUITheme();
     if (!visible) {
         return _jsx(Box, { width: 0 });
@@ -13,7 +33,7 @@ export const DetailPanel = ({ stack, service, stackMetadata, visible, }) => {
         const title = theme.ascii
             ? `--- ${service.name.toUpperCase()} ---`
             : `\u250C\u2500 ${service.name.toUpperCase()} \u2500\u2510`;
-        return (_jsxs(Box, { width: 40, flexDirection: "column", borderStyle: theme.ascii ? undefined : "single", borderColor: theme.border, paddingX: 1, paddingY: 1, children: [_jsx(Box, { marginBottom: 1, justifyContent: "center", children: _jsx(Text, { color: theme.accent, bold: true, children: title }) }), _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: theme.muted, children: "Name: " }), _jsx(Text, { color: theme.foreground, children: service.name })] }), _jsxs(Box, { children: [_jsx(Text, { color: theme.muted, children: "Stack: " }), _jsx(Text, { color: theme.foreground, children: service.stack || "unknown" })] }), _jsxs(Box, { children: [_jsx(Text, { color: theme.muted, children: "Type: " }), _jsx(Text, { color: theme.warning, bold: theme.highContrast, children: (service.stack || "") === "platform" ? "PLATFORM" : "PRODUCT" })] })] }), _jsx(Box, { marginTop: 2, children: _jsxs(Text, { color: theme.muted, dimColor: theme.dimMuted, children: ["Press ", _jsx(Text, { color: theme.accent, children: "[Esc]" }), " to close"] }) })] }));
+        return (_jsxs(Box, { width: 40, flexDirection: "column", borderStyle: theme.ascii ? undefined : "single", borderColor: theme.border, paddingX: 1, paddingY: 1, children: [_jsx(Box, { marginBottom: 1, justifyContent: "center", children: _jsx(Text, { color: theme.accent, bold: true, children: title }) }), _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: theme.muted, children: "Name: " }), _jsx(Text, { color: theme.foreground, children: service.name })] }), _jsxs(Box, { children: [_jsx(Text, { color: theme.muted, children: "Stack: " }), _jsx(Text, { color: theme.foreground, children: service.stack || "unknown" })] }), _jsxs(Box, { children: [_jsx(Text, { color: theme.muted, children: "Type: " }), _jsx(Text, { color: theme.warning, bold: theme.highContrast, children: (service.stack || "") === "platform" ? "PLATFORM" : "PRODUCT" })] })] }), agent !== undefined && _jsx(AgentSection, { agent: agent }), _jsx(Box, { marginTop: 2, children: _jsxs(Text, { color: theme.muted, dimColor: theme.dimMuted, children: ["Press ", _jsx(Text, { color: theme.accent, children: "[Esc]" }), " to close"] }) })] }));
     }
     if (stack && stackMetadata) {
         const statusColor = getTUIStatusColor(theme, getStatusColor(stackMetadata.overallStatus));

package/cli/dist/mcp/tools.js

@@ -328,23 +328,26 @@ export function createFliskTools(run = runFliskCli, up = defaultUpDeps) {
         },
         {
             name: "get_agent_sessions",
-            description: "Inspect session checkpoints from a running AI agent resource. Set projectPath when the MCP server is not running from the project root.",
+            description: "List the sessions of a running AI agent resource (id, last activity, status, checkpoint size), or read one session's checkpoint when sessionId is set. Set projectPath when the MCP server is not running from the project root.",
             inputSchema: {
                 ...OBJECT({
                     projectPath: PROJECT_PATH,
                     resource: { type: "string", description: "Name of the agent resource" },
-                    sessionId: { type: "string", description: "Session ID to fetch (required)" },
+                    sessionId: {
+                        type: "string",
+                        description: "Session ID to read; omit it to list all sessions",
+                    },
                 }),
-                required: ["resource", "sessionId"],
+                required: ["resource"],
             },
             handler: viaCli((args) => {
                 const resource = optionalName(args.resource, "resource");
                 if (!resource)
                     throw new Error("resource is required");
                 const sessionId = optionalName(args.sessionId, "sessionId");
-                if (!sessionId)
-                    throw new Error("sessionId is required");
-                return ["agent", "sessions", resource, `--session-id=${sessionId}`, "--json"];
+                return sessionId
+                    ? ["agent", "sessions", resource, `--session-id=${sessionId}`, "--json"]
+                    : ["agent", "sessions", resource, "--json"];
             }),
         },
     ];

package/cli/dist/types/index.js

@@ -1,5 +1,3 @@
-// Copyright (c) 2026 Flisk Landscape contributors
-// SPDX-License-Identifier: MIT
 import { RESOURCE_DEFAULTS_FILE, TECH_STACK_FILE } from "../utils/constants.js";
 export const RESOURCE_CONFIG_APP_TYPES = [
     "backend",