tmux-ide 2.6.0 → 2.7.0

package/packages/contracts/src/actions-errors.ts

@@ -0,0 +1,41 @@
+/**
+ * Wire codes for the v2 action dispatcher's error envelope. Codes are
+ * stable identifiers — never rename without a coordinated dashboard
+ * release. New codes go at the bottom of the union.
+ *
+ * The runtime class that throws these (`ActionError`, `TerminalCwdError`,
+ * etc.) lives in @tmux-ide/daemon's command-center/actions/errors.ts; the
+ * type lives here so dashboards and other UI clients can branch on the
+ * code without reaching into daemon-internal modules.
+ */
+export type ActionErrorCode =
+  | "project_not_found"
+  | "cwd_not_found"
+  | "cwd_not_directory"
+  | "cwd_stat_failed"
+  | "session_already_running"
+  | "session_not_running"
+  | "launch_failed"
+  | "stop_failed"
+  | "terminal_not_found"
+  | "validation_failed"
+  | "task_not_found"
+  | "goal_not_found"
+  | "milestone_not_found"
+  | "mission_not_set"
+  | "task_dependency_unmet"
+  | "task_already_assigned"
+  | "skill_invalid"
+  | "skill_not_found"
+  | "ide_yml_missing"
+  | "config_path_invalid"
+  | "config_validation_failed"
+  | "validation_assertion_not_found"
+  | "webhook_not_found"
+  | "webhook_test_failed"
+  | "remote_access_restart_failed"
+  | "shutdown_already_in_progress"
+  | "bad_request"
+  | "thread_not_found"
+  | "permission_request_not_found"
+  | "internal";

package/packages/contracts/src/domain.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// PaneInfo — live tmux pane metadata (from src/command-center/discovery.ts)
+// ---------------------------------------------------------------------------
+
+export const PaneInfoSchemaZ = z.object({
+  id: z.string(),
+  index: z.number(),
+  title: z.string(),
+  currentCommand: z.string(),
+  width: z.number(),
+  height: z.number(),
+  active: z.boolean(),
+  role: z
+    .enum(["lead", "teammate", "planner", "validator", "researcher", "widget", "shell"])
+    .nullable(),
+  name: z.string().nullable(),
+  type: z.string().nullable(),
+});
+
+// ---------------------------------------------------------------------------
+// SessionOverview — minimal session listing entry
+// ---------------------------------------------------------------------------
+
+export const SessionOverviewSchemaZ = z.object({
+  name: z.string(),
+  dir: z.string(),
+});
+
+// ---------------------------------------------------------------------------
+// Inferred types
+// ---------------------------------------------------------------------------
+
+export type PaneInfo = z.infer<typeof PaneInfoSchemaZ>;
+export type SessionOverview = z.infer<typeof SessionOverviewSchemaZ>;

package/packages/contracts/src/ide-config.ts

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import { AuthConfigSchema } from "./lib-internal/auth.ts";
+import { HQConfigSchema } from "./lib-internal/hq.ts";
+
+const sizeField = z
+  .string()
+  .regex(/^[1-9]\d*%$/)
+  .refine((v) => parseInt(v) <= 100);
+
+export const ThemeConfigSchema = z.object({
+  accent: z.string().optional(),
+  border: z.string().optional(),
+  bg: z.string().optional(),
+  fg: z.string().optional(),
+});
+
+export const PaneSchema = z.object({
+  title: z.string().optional(),
+  command: z.string().optional(),
+  type: z
+    .enum([
+      "explorer",
+      "changes",
+      "preview",
+      "tasks",
+      "costs",
+      "config",
+      "mission-control",
+      "sidebar",
+    ])
+    .optional(),
+  target: z.string().optional(),
+  dir: z.string().optional(),
+  size: sizeField.optional(),
+  focus: z.boolean().optional(),
+  env: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
+  role: z.enum(["lead", "teammate", "planner", "validator", "researcher"]).optional(),
+  task: z.string().optional(),
+  specialty: z.string().optional(),
+  skill: z.string().optional(),
+});
+
+export const RowSchema = z.object({
+  size: sizeField.optional(),
+  panes: z.array(PaneSchema).min(1),
+});
+
+export const WebhookConfigSchema = z.object({
+  url: z.string(),
+  events: z.array(z.string()).optional(),
+  secret: z.string().optional(),
+});
+
+export const OrchestratorYamlConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  port: z.number().int().positive().optional(),
+  auto_dispatch: z.boolean().optional(),
+  stall_timeout: z.number().optional(),
+  poll_interval: z.number().min(100).optional(),
+  master_pane: z.string().optional(),
+  before_run: z.string().optional(),
+  after_run: z.string().optional(),
+  dispatch_mode: z.enum(["tasks", "goals", "missions"]).optional(),
+  max_concurrent_agents: z.number().min(1).max(50).optional(),
+  widgets: z.boolean().optional(),
+  webhooks: z.array(WebhookConfigSchema).optional(),
+  services: z
+    .record(
+      z.string(),
+      z.object({
+        command: z.string(),
+        port: z.number().optional(),
+        healthcheck: z.string().optional(),
+      }),
+    )
+    .optional(),
+  research: z
+    .object({
+      enabled: z.boolean().optional(),
+      triggers: z
+        .object({
+          mission_start: z.boolean().optional(),
+          milestone_progress: z.number().min(0).optional(),
+          milestone_complete: z.boolean().optional(),
+          periodic_minutes: z.number().min(0).optional(),
+          retry_cluster: z.boolean().optional(),
+          stall_detected: z.boolean().optional(),
+          discovered_issue: z.boolean().optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+});
+
+export const TunnelConfigSchema = z.object({
+  provider: z.enum(["tailscale", "ngrok", "cloudflare"]),
+  auto_start: z.boolean().optional(),
+  port: z.number().int().positive().optional(),
+  domain: z.string().optional(),
+  authtoken: z.string().optional(),
+});
+
+export const CommandCenterConfigSchema = z.object({
+  port: z.number().optional(),
+  enabled: z.boolean().optional(),
+});
+
+export const DashboardConfigSchema = z.object({
+  port: z.number().int().positive().optional(),
+});
+
+/**
+ * The app nav-column sidebar sugar. `sidebar: true` injects a full-height left
+ * column (default width) at launch; `sidebar: { width: "30" }` sets its column
+ * width (in tmux cols, as a string to match the CLI/tmux world). `false` /
+ * omitted means no sidebar.
+ */
+export const SidebarConfigSchema = z.union([
+  z.boolean(),
+  z.object({ width: z.string().optional() }),
+]);
+
+export const IdeConfigSchema = z.object({
+  name: z.string().optional(),
+  before: z.string().optional(),
+  team: z
+    .object({
+      name: z.string(),
+      model: z.string().optional(),
+      permissions: z.array(z.string()).optional(),
+    })
+    .optional(),
+  rows: z.array(RowSchema).min(1),
+  sidebar: SidebarConfigSchema.optional(),
+  theme: ThemeConfigSchema.optional(),
+  orchestrator: OrchestratorYamlConfigSchema.optional(),
+  command_center: CommandCenterConfigSchema.optional(),
+  dashboard: DashboardConfigSchema.optional(),
+  auth: AuthConfigSchema.optional(),
+  tunnel: TunnelConfigSchema.optional(),
+  hq: HQConfigSchema.optional(),
+});
+
+export const PaneActionSchema = z.object({
+  targetPane: z.string(),
+  title: z.string().nullable(),
+  chdir: z.string().nullable(),
+  exports: z.array(z.string()),
+  command: z.string().nullable(),
+  widgetType: z.string().nullable(),
+  widgetTarget: z.string().nullable(),
+  paneRole: z.string().nullable(),
+  paneType: z.string().nullable(),
+});
+
+export const SessionStateSchema = z.object({
+  running: z.boolean(),
+  reason: z.string().nullable(),
+});
+
+export type ThemeConfig = z.infer<typeof ThemeConfigSchema>;
+export type Pane = z.infer<typeof PaneSchema>;
+export type Row = z.infer<typeof RowSchema>;
+export type OrchestratorYamlConfig = z.infer<typeof OrchestratorYamlConfigSchema>;
+export type SidebarConfig = z.infer<typeof SidebarConfigSchema>;
+export type CommandCenterConfig = z.infer<typeof CommandCenterConfigSchema>;
+export type DashboardConfig = z.infer<typeof DashboardConfigSchema>;
+export type IdeConfig = z.infer<typeof IdeConfigSchema>;
+export type PaneAction = z.infer<typeof PaneActionSchema>;
+export type SessionState = z.infer<typeof SessionStateSchema>;

package/packages/contracts/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @tmux-ide/contracts — shared Zod schemas for the daemon ↔ dashboard
+ * boundary. Dashboard, packages/daemon, and any future v2 surfaces all
+ * import from this single source of truth.
+ *
+ * Adding a schema? Put it in either `domain.ts` (runtime data: tasks,
+ * missions, sessions, …) or `ide-config.ts` (the on-disk ide.yml
+ * shape). Both files are re-exported wholesale below — no manual
+ * registration needed.
+ *
+ * The `lib-internal/` directory holds schema-only helpers (auth, hq)
+ * that ide-config depends on — they are exported transitively here
+ * so consumers don't have to deep-import.
+ */
+
+export * from "./lib-internal/auth.ts";
+export * from "./lib-internal/hq.ts";
+export * from "./ide-config.ts";
+export * from "./domain.ts";
+export * from "./tmux.ts";
+export * from "./workspace.ts";
+export * from "./actions-contract.ts";
+export * from "./actions-errors.ts";
+export * from "./terminals.ts";

package/packages/contracts/src/lib-internal/auth.ts

@@ -0,0 +1,13 @@
+// Based on VibeTunnel (MIT) — github.com/amantus-ai/vibetunnel
+import { z } from "zod";
+
+export const AuthConfigSchema = z.object({
+  /** Auth method: "none" disables auth (default), "ssh" enables SSH key challenge-response. */
+  method: z.enum(["none", "ssh"]).default("none"),
+  /** JWT secret — auto-generated if omitted. */
+  secret: z.string().optional(),
+  /** Token expiry in seconds (default 86400 = 24h). */
+  token_expiry: z.number().min(60).default(86400),
+});
+
+export type AuthConfig = z.infer<typeof AuthConfigSchema>;

package/packages/contracts/src/lib-internal/hq.ts

@@ -0,0 +1,38 @@
+// Based on VibeTunnel (MIT) — github.com/amantus-ai/vibetunnel
+//
+// Schemas + serializable interfaces only. The daemon-only `RemoteMachine`
+// runtime type (Date / Set fields) lives in @tmux-ide/daemon's lib/hq —
+// not here.
+import { z } from "zod";
+
+export interface HQConfig {
+  enabled: boolean;
+  role: "hq" | "remote";
+  hq_url?: string;
+  secret?: string;
+  heartbeat_interval?: number;
+  machine_name?: string;
+}
+
+export interface RegistrationPayload {
+  id: string;
+  name: string;
+  url: string;
+  token: string;
+}
+
+export const RegistrationPayloadSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  url: z.string().url(),
+  token: z.string().min(1),
+});
+
+export const HQConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  role: z.enum(["hq", "remote"]),
+  hq_url: z.string().url().optional(),
+  secret: z.string().optional(),
+  heartbeat_interval: z.number().min(1000).default(15000),
+  machine_name: z.string().optional(),
+});

package/packages/contracts/src/terminals.ts

@@ -0,0 +1,116 @@
+/**
+ * Multi-terminal registry contracts (G20-P1).
+ *
+ * A `Terminal` is a *named pool entry* — metadata about a PTY the
+ * daemon may or may not have spawned yet. The daemon's existing
+ * `/ws/pty/:id` endpoint owns the actual process lifecycle; this
+ * registry exists so the UI can persist tab labels + restore them
+ * across reloads, and so deterministic scope/script tabs collapse to
+ * the same id (re-opens land on the running scrollback).
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------
+
+export type TerminalKind = "shell" | "setup" | "run" | "teardown";
+
+export interface Terminal {
+  /** Deterministic id for scope/script tabs; UUID for ad-hoc tabs. */
+  id: string;
+  /** Session name the terminal belongs to. */
+  projectId: string;
+  /** Sub-grouping inside a session (mission id, dir hash, …). Free-form. */
+  scopeId: string;
+  /** Free-text display name. The tab strip renames this without changing id. */
+  name: string;
+  kind: TerminalKind;
+  createdAt: string;
+  updatedAt: string;
+  /** Set when the id was derived via `createScriptTerminalId` so the
+   *  client can show a "shared script" badge in the tab strip. */
+  scripted?: boolean;
+}
+
+/** Live runtime info — derived from the daemon's bridge registry, not
+ *  the JSON store. Combined with `Terminal` for the list endpoint. */
+export interface TerminalRuntime {
+  running: boolean;
+  cols?: number;
+  rows?: number;
+  /** Bytes available in the replay ring buffer when a client subscribes. */
+  replayBytes?: number;
+}
+
+export interface TerminalWithRuntime extends Terminal {
+  runtime: TerminalRuntime;
+}
+
+export interface TerminalListResponse {
+  terminals: TerminalWithRuntime[];
+}
+
+// ---------------------------------------------------------------------
+// Deterministic id
+// ---------------------------------------------------------------------
+
+/** Build a deterministic 32-char id from `(projectId, scopeId, kind,
+ *  script)`. Two different callers asking for "the run script terminal
+ *  for project X, scope Y, script Z" get the same id and land on the
+ *  same bridge — which means scrollback survives a browser reload. */
+export async function createScriptTerminalId(args: {
+  projectId: string;
+  scopeId?: string;
+  /** Backward-compat alias for `scopeId`. */
+  taskId?: string;
+  kind: TerminalKind;
+  script: string;
+}): Promise<string> {
+  const scope = args.scopeId ?? args.taskId;
+  if (!scope) {
+    throw new Error("createScriptTerminalId: scopeId (or taskId) is required");
+  }
+  const key = `${args.projectId}::${scope}::${args.kind}::${args.script}`;
+  const data = new TextEncoder().encode(key);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")
+    .slice(0, 32);
+}
+
+// ---------------------------------------------------------------------
+// Zod request schemas
+// ---------------------------------------------------------------------
+
+export const terminalKindSchema = z.enum(["shell", "setup", "run", "teardown"]);
+
+export const terminalCreateRequestSchema = z
+  .object({
+    scopeId: z.string().trim().min(1).max(256),
+    name: z.string().trim().min(1).max(120),
+    kind: terminalKindSchema.optional(),
+    /** Provide for script tabs to opt into deterministic id collapse. */
+    script: z.string().max(2048).optional(),
+    /** Explicit id wins. Used by the dashboard to reserve a known id
+     *  (e.g. the default shell tab derived from session.dir). */
+    id: z
+      .string()
+      .trim()
+      .min(8)
+      .max(64)
+      .regex(/^[A-Za-z0-9_-]+$/u, "id may only contain alphanumerics, '-', '_'")
+      .optional(),
+  })
+  .refine((v) => v.kind !== undefined || v.script === undefined, {
+    message: "script requires kind",
+    path: ["script"],
+  });
+export type TerminalCreateRequest = z.infer<typeof terminalCreateRequestSchema>;
+
+export const terminalRenameRequestSchema = z.object({
+  name: z.string().trim().min(1).max(120),
+});
+export type TerminalRenameRequest = z.infer<typeof terminalRenameRequestSchema>;

package/packages/contracts/src/tmux.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+
+/**
+ * Tmux state schemas — the canonical typed surface for tmux sessions,
+ * windows, panes, and pane addressing.
+ *
+ * Used by:
+ *   - packages/tmux-bridge — implementation that shells out to tmux.
+ *   - packages/daemon (session-monitor, discovery, command-center) —
+ *     materializes these shapes into the live runtime state.
+ *   - dashboard — consumes them via the typed REST/SSE clients.
+ *
+ * Adding a new addressing mode (e.g. byRegex) is intentionally a one-line
+ * discriminant change here; bridge resolvers must update in lockstep.
+ */
+
+export const TmuxPaneSchemaZ = z.object({
+  /** Stable tmux pane id (e.g. `%23`). */
+  id: z.string(),
+  /** Pane index within its window (zero-based). */
+  paneIndex: z.number().int().nonnegative(),
+  /** Window index within the session (zero-based). */
+  windowIndex: z.number().int().nonnegative(),
+  title: z.string().nullable(),
+  command: z.string().nullable(),
+  active: z.boolean(),
+});
+export type TmuxPane = z.infer<typeof TmuxPaneSchemaZ>;
+
+export const TmuxWindowSchemaZ = z.object({
+  index: z.number().int().nonnegative(),
+  name: z.string(),
+  panes: z.array(TmuxPaneSchemaZ),
+});
+export type TmuxWindow = z.infer<typeof TmuxWindowSchemaZ>;
+
+export const TmuxSessionSchemaZ = z.object({
+  name: z.string(),
+  windows: z.array(TmuxWindowSchemaZ),
+  /** Session creation time (epoch milliseconds). */
+  created: z.number().int().nonnegative(),
+  attached: z.boolean(),
+  /** Project directory the session was launched from, when known. */
+  projectDir: z.string().nullable(),
+});
+export type TmuxSession = z.infer<typeof TmuxSessionSchemaZ>;
+
+/**
+ * Discriminated union for addressing a pane. The bridge's resolver
+ * implements byId/byIndex/byTitle directly; byRole is resolved at the
+ * daemon layer (it requires reading the ide.yml-driven role mapping)
+ * and translated into a concrete address before reaching the bridge.
+ */
+export const TmuxPaneTargetSchemaZ = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("byId"), id: z.string() }),
+  z.object({ kind: z.literal("byIndex"), index: z.number().int().nonnegative() }),
+  z.object({ kind: z.literal("byTitle"), title: z.string() }),
+  z.object({ kind: z.literal("byRole"), role: z.string() }),
+]);
+export type TmuxPaneTarget = z.infer<typeof TmuxPaneTargetSchemaZ>;

package/packages/contracts/src/workspace.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+/**
+ * A workspace is a project the daemon is actively serving — identified by
+ * its tmux session name and bound to a project directory.
+ *
+ * The workspace registry replaces the historical single-session
+ * TMUX_IDE_SESSION env coupling, letting the daemon serve N projects in
+ * one process. Goal 12 of the t3-style consolidation; see T065.
+ */
+export const WorkspaceSchemaZ = z.object({
+  /** Stable workspace name (typically equal to tmux session name). */
+  name: z.string().min(1),
+  /** Tmux session this workspace maps to. */
+  sessionName: z.string().min(1),
+  /** Absolute project directory. */
+  projectDir: z.string().min(1),
+  /** Absolute path to the ide.yml driving this workspace. */
+  ideConfigPath: z.string().nullable(),
+  /** ISO timestamp of when the workspace was added. */
+  addedAt: z.string(),
+});
+export type Workspace = z.infer<typeof WorkspaceSchemaZ>;
+
+// ---------------------------------------------------------------------------
+// HTTP request / response shapes for /api/workspaces
+// ---------------------------------------------------------------------------
+
+export const WorkspaceListResponseSchemaZ = z.object({
+  workspaces: z.array(WorkspaceSchemaZ),
+});
+export type WorkspaceListResponse = z.infer<typeof WorkspaceListResponseSchemaZ>;
+
+export const AddWorkspaceRequestSchemaZ = z.object({
+  /** Absolute path to the project directory. */
+  projectDir: z.string().min(1),
+  /** Optional explicit workspace name. Auto-derived from basename when absent. */
+  name: z.string().min(1).optional(),
+  /** Optional override for the tmux session name (defaults to `name`). */
+  sessionName: z.string().min(1).optional(),
+  /** Optional ide.yml path the workspace was launched with. */
+  ideConfigPath: z.string().min(1).optional(),
+});
+export type AddWorkspaceRequest = z.infer<typeof AddWorkspaceRequestSchemaZ>;
+
+export const AddWorkspaceResponseSchemaZ = z.object({
+  workspace: WorkspaceSchemaZ,
+});
+export type AddWorkspaceResponse = z.infer<typeof AddWorkspaceResponseSchemaZ>;
+
+// ---------------------------------------------------------------------------
+// WebSocket event frames — fired on registry add/remove (including the
+// auto-reconcile loop that drops dead sessions). Kept here so dashboard /
+// daemon consumers share the exact discriminator strings.
+// ---------------------------------------------------------------------------
+
+export const WorkspaceAddedFrameSchemaZ = z.object({
+  type: z.literal("workspace.added"),
+  workspace: WorkspaceSchemaZ,
+});
+export type WorkspaceAddedFrame = z.infer<typeof WorkspaceAddedFrameSchemaZ>;
+
+export const WorkspaceRemovedFrameSchemaZ = z.object({
+  type: z.literal("workspace.removed"),
+  name: z.string(),
+});
+export type WorkspaceRemovedFrame = z.infer<typeof WorkspaceRemovedFrameSchemaZ>;

package/packages/daemon/dist/agent-explain.d.ts

@@ -1,4 +1,4 @@
-import { type DetectedState } from "./tui/detect/manifest.ts";
+import { type DetectedState, type ManifestConfidence } from "./tui/detect/manifest.ts";
 import { type AgentStatus, type InstantState } from "./tui/detect/classify.ts";
 export interface ExplainReport {
     pane: {
@@ -23,6 +23,13 @@ export interface ExplainReport {
         manifestId: string | null;
         matchedCommand: string;
         source: "hint" | "fast" | "tree" | "none";
+        /** The matched manifest's evidence confidence (null when nothing resolved). */
+        confidence: ManifestConfidence | null;
+        /**
+         * Executable-ish tokens seen in the pane's process subtree. Populated for
+         * the "no manifest matched" case so the report can say what it DID find.
+         */
+        subtree: string[];
     };
     states: Array<{
         state: DetectedState;

package/packages/daemon/dist/agent-explain.js

@@ -17,7 +17,7 @@ import { execFileSync } from "node:child_process";
 import { explain } from "./tui/detect/manifest.js";
 import { classifyInstant, parseAuthority, } from "./tui/detect/classify.js";
 import { getManifests } from "./tui/detect/manifest-loader.js";
-import { readProcessTable, resolveAgentCommand } from "./tui/detect/process-tree.js";
+import { describeSubtree, readProcessTable, resolveAgentCommand, } from "./tui/detect/process-tree.js";
 import { readPaneSnapshot } from "./tui/detect/snapshot.js";
 import { IdeError } from "./lib/errors.js";
 /** Working/blocked authority reports older than this are stale (mirrors classify.ts). */
@@ -91,6 +91,9 @@ export function buildReport(target) {
         hint: info.hintRaw,
     });
     const manifest = resolved.manifest;
+    // When nothing resolved, record what the process-tree DID see so `explain`
+    // can point the user at an `@agent_hint` target instead of a dead end.
+    const subtree = manifest ? [] : describeSubtree(table, info.pid);
     // Snapshot + per-state explanation.
     const snapshot = { ...readPaneSnapshot(info.id), title: info.title };
     const explained = manifest
@@ -119,6 +122,8 @@ export function buildReport(target) {
             manifestId: manifest?.id ?? null,
             matchedCommand: resolved.matchedCommand,
             source: resolved.source,
+            confidence: manifest ? (manifest.confidence ?? "conservative") : null,
+            subtree,
         },
         states: explained.checked,
         winner: explained.state,
@@ -168,8 +173,19 @@ export function renderReport(r, opts = {}) {
         out.push(`  ${label("hint")}      ${dim("(unset)")}`);
     }
     // Resolution
-    const mid = r.resolution.manifestId ?? dim("none");
-    out.push(`  ${label("manifest")}  ${mid}  ${dim(`via ${r.resolution.source}` + (r.resolution.matchedCommand ? ` "${r.resolution.matchedCommand}"` : ""))}`);
+    if (r.resolution.manifestId) {
+        const conf = r.resolution.confidence === "tuned"
+            ? c("\x1b[32m", "tuned")
+            : dim(r.resolution.confidence ?? "conservative");
+        out.push(`  ${label("manifest")}  ${r.resolution.manifestId}  ${dim(`via ${r.resolution.source}` + (r.resolution.matchedCommand ? ` "${r.resolution.matchedCommand}"` : ""))}  [${conf}]`);
+    }
+    else {
+        // No manifest matched — say so, and report what the process-tree DID see so
+        // the user can set an `@agent_hint` or add a manifest.
+        const saw = r.resolution.subtree.length > 0 ? r.resolution.subtree.join(", ") : r.pane.cmd || "(nothing)";
+        out.push(`  ${label("manifest")}  ${dim("none matched")} — ${dim(`process-tree saw: ${saw}`)}`);
+        out.push(`            ${dim("set `tmux set-option -p @agent_hint <agent>` to force one")}`);
+    }
     // Per-state rule results
     out.push("");
     out.push(bold("  state rules"));