orionfold-relay 0.24.1 → 0.25.1

package/dist/cli.js

@@ -1186,7 +1186,7 @@ var CURRENT_PLUGIN_API_VERSION, CAPABILITY_VALUES, ORIGIN_VALUES, PrimitivesBund
 var init_types = __esm({
   "src/lib/plugins/sdk/types.ts"() {
     "use strict";
-    CURRENT_PLUGIN_API_VERSION = "0.24";
+    CURRENT_PLUGIN_API_VERSION = "0.25";
     CAPABILITY_VALUES = ["fs", "net", "child_process", "env"];
     ORIGIN_VALUES = ["ainative-internal", "third-party"];
     PrimitivesBundleManifestSchema = z.object({
@@ -4614,6 +4614,19 @@ var init_history = __esm({
   }
 });
 
+// src/lib/http/self-base-url.ts
+function getSelfBaseUrl() {
+  const explicit = process.env.RELAY_SELF_BASE_URL || process.env.NEXTAUTH_URL || process.env.NEXT_PUBLIC_APP_URL;
+  if (explicit) return explicit;
+  const port = process.env.PORT || "3000";
+  return `http://127.0.0.1:${port}`;
+}
+var init_self_base_url = __esm({
+  "src/lib/http/self-base-url.ts"() {
+    "use strict";
+  }
+});
+
 // src/lib/workflows/delay.ts
 function parseDuration(input) {
   const match = input.match(DURATION_PATTERN);
@@ -7135,7 +7148,13 @@ function getWorkspaceContext() {
     gitBranch = execFileSync2("git", ["branch", "--show-current"], {
       cwd,
       encoding: "utf-8",
-      timeout: 3e3
+      timeout: 3e3,
+      // Route git's stderr to a pipe (captured on the thrown error, then
+      // discarded) instead of inheriting the console. Without this, a
+      // non-git cwd leaks a raw `fatal: not a git repository` to a
+      // customer's first-run log before the catch swallows the exit code.
+      // Mirrors src/lib/instance/git-ops.ts run().
+      stdio: ["ignore", "pipe", "pipe"]
     }).trim() || null;
   } catch {
   }
@@ -12134,7 +12153,7 @@ async function listPendingApprovalPayloads(limit = 20) {
     const isBatchProposal = row.type === "context_proposal_batch";
     const parsedInput = parseNotificationToolInput(row.toolInput);
     let effectiveWorkflowId = row.workflowId;
-    if (!row.taskId && row.toolName === "WorkflowCheckpoint" && row.toolInput) {
+    if (!row.taskId && (row.toolName === "WorkflowCheckpoint" || row.toolName === "AskUserQuestion") && row.toolInput) {
       try {
         const parsed = typeof row.toolInput === "string" ? JSON.parse(row.toolInput) : row.toolInput;
         effectiveWorkflowId = parsed.workflowId ?? null;
@@ -12963,7 +12982,7 @@ var init_registry6 = __esm({
     init_registry5();
     init_installer();
     init_schedule_spec();
-    SUPPORTED_API_VERSIONS = /* @__PURE__ */ new Set([CURRENT_PLUGIN_API_VERSION, "0.23"]);
+    SUPPORTED_API_VERSIONS = /* @__PURE__ */ new Set([CURRENT_PLUGIN_API_VERSION, "0.24"]);
     pluginCache = null;
     lastLoadedPluginIds = /* @__PURE__ */ new Set();
     PluginTableSchema = z16.object({
@@ -15275,7 +15294,7 @@ Guidelines for schema inference:
         try {
           const table = await getTable(args.tableId);
           if (!table) return err("Table not found");
-          const baseUrl = process.env.NEXTAUTH_URL || process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000";
+          const baseUrl = getSelfBaseUrl();
           return ok({
             url: `${baseUrl}/api/tables/${args.tableId}/export?format=${args.format}`,
             table: table.name,
@@ -15721,7 +15740,7 @@ Guidelines for schema inference:
   ];
 }
 function getBaseUrl() {
-  return process.env.NEXTAUTH_URL || process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000";
+  return getSelfBaseUrl();
 }
 var init_table_tools = __esm({
   "src/lib/chat/tools/table-tools.ts"() {
@@ -15732,6 +15751,7 @@ var init_table_tools = __esm({
     init_history();
     init_import();
     init_enrichment();
+    init_self_base_url();
   }
 });
 
@@ -24164,6 +24184,7 @@ ${step.prompt}`;
 }
 async function executeCheckpoint(workflowId, definition, state, parentTaskId, workflowRuntimeId) {
   let previousOutput = "";
+  let userAnswer = "";
   for (let i = 0; i < definition.steps.length; i++) {
     const step = definition.steps[i];
     state.currentStepIndex = i;
@@ -24177,8 +24198,27 @@ async function executeCheckpoint(workflowId, definition, state, parentTaskId, wo
         throw new Error(`Step "${step.name}" was denied approval`);
       }
     }
-    const contextPrompt = previousOutput ? `Previous step output:
-${previousOutput}
+    userAnswer = "";
+    if (step.requiresInput) {
+      state.stepStates[i].status = "waiting_approval";
+      state.status = "paused";
+      await updateWorkflowState(workflowId, state, "paused");
+      const question = step.inputPrompt ?? step.prompt;
+      userAnswer = await waitForInput(workflowId, step.name, question);
+      state.status = "running";
+      state.stepStates[i].status = "running";
+      await updateWorkflowState(workflowId, state, "active");
+    }
+    const contextParts = [];
+    if (previousOutput) {
+      contextParts.push(`Previous step output:
+${previousOutput}`);
+    }
+    if (userAnswer.trim()) {
+      contextParts.push(`User-provided input:
+${userAnswer}`);
+    }
+    const contextPrompt = contextParts.length > 0 ? `${contextParts.join("\n\n---\n\n")}
 
 ---
 
@@ -24200,6 +24240,14 @@ ${step.prompt}` : step.prompt;
       throw new Error(`Step "${step.name}" failed: ${result.error}`);
     }
     previousOutput = result.result ?? "";
+    const hasDependents = i < definition.steps.length - 1;
+    if (hasDependents && previousOutput.trim().length === 0) {
+      state.stepStates[i].status = "failed";
+      state.stepStates[i].error = "Step produced no usable output; halting dependent steps to avoid a false completion. The agent may have refused for missing context \u2014 check its output and re-run with the needed input.";
+      throw new Error(
+        `Step "${step.name}" produced no usable output \u2014 halting workflow to avoid cascading refusals`
+      );
+    }
   }
 }
 async function executeParallel(workflowId, definition, state, parentTaskId, workflowRuntimeId) {
@@ -24729,6 +24777,33 @@ ${previousOutput.slice(0, 500)}`,
   }).where(eq44(notifications.id, notificationId));
   return false;
 }
+async function waitForInput(workflowId, stepName, question, options) {
+  const notificationId = crypto.randomUUID();
+  await db.insert(notifications).values({
+    id: notificationId,
+    taskId: null,
+    type: "permission_required",
+    title: `Workflow needs input: ${stepName}`,
+    body: question.slice(0, 500),
+    toolName: "AskUserQuestion",
+    toolInput: JSON.stringify({ question, options, workflowId, stepName }),
+    createdAt: /* @__PURE__ */ new Date()
+  });
+  const pollInterval = 2e3;
+  for (; ; ) {
+    const [notification] = await db.select().from(notifications).where(eq44(notifications.id, notificationId));
+    if (notification?.response) {
+      try {
+        const parsed = JSON.parse(notification.response);
+        const answer = parsed?.updatedInput?.answer;
+        return typeof answer === "string" ? answer : "";
+      } catch {
+        return "";
+      }
+    }
+    await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+  }
+}
 async function updateWorkflowState(workflowId, state, status) {
   const [workflow] = await db.select().from(workflows).where(eq44(workflows.id, workflowId));
   if (!workflow) throw new Error(`Workflow ${workflowId} not found \u2014 cannot update state`);
@@ -25318,13 +25393,15 @@ async function fireAction(actionType, config, rowData, meta) {
 Trigger data: ${JSON.stringify(rowData, null, 2)}` : `Triggered by table row change.
 
 Data: ${JSON.stringify(rowData, null, 2)}`;
-    await fetch(`${getBaseUrl2()}/api/tasks`, {
+    await fetch(`${getSelfBaseUrl()}/api/tasks`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         title: config.title ?? "Triggered Task",
         description,
-        projectId: config.projectId ?? null
+        // createTaskSchema wants `string | undefined`, not null — sending null
+        // 400s the self-call and the task is never created. Omit when absent.
+        ...config.projectId ? { projectId: config.projectId } : {}
       })
     });
     return;
@@ -25350,7 +25427,7 @@ Data: ${JSON.stringify(rowData, null, 2)}`;
     return;
   }
   if (actionType === "run_workflow" && config.workflowId) {
-    await fetch(`${getBaseUrl2()}/api/workflows/${config.workflowId}/execute`, {
+    await fetch(`${getSelfBaseUrl()}/api/workflows/${config.workflowId}/execute`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -25368,14 +25445,12 @@ function deriveAppIdFromBlueprintId(blueprintId) {
   if (idx <= 0) return null;
   return blueprintId.slice(0, idx);
 }
-function getBaseUrl2() {
-  return process.env.NEXTAUTH_URL || process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000";
-}
 var init_trigger_evaluator = __esm({
   "src/lib/tables/trigger-evaluator.ts"() {
     "use strict";
     init_db();
     init_schema();
+    init_self_base_url();
   }
 });
 
@@ -25838,8 +25913,8 @@ import { execFileSync as execFileSync3 } from "child_process";
 import yaml12 from "js-yaml";
 import semver from "semver";
 function relayCoreVersion() {
-  if (semver.valid("0.24.1")) {
-    return "0.24.1";
+  if (semver.valid("0.25.1")) {
+    return "0.25.1";
   }
   try {
     const root = getAppRoot(import.meta.dirname, 3);
@@ -27487,6 +27562,11 @@ Falling back to development mode for this run \u2014 Relay still works, but slow
       RELAY_DATA_DIR: DATA_DIR,
       RELAY_LAUNCH_CWD: launchCwd2,
       PORT: String(actualPort),
+      // Origin for Relay's internal loopback self-calls (trigger dispatch,
+      // compose table tools). The server always listens on loopback even when
+      // bound to a non-loopback host, so self-calls target 127.0.0.1 + the real
+      // port — never :3000, never the LAN IP. Fixes issue #29.
+      RELAY_SELF_BASE_URL: buildSidecarUrl(actualPort, "127.0.0.1"),
       ...opts.safeMode ? { RELAY_SAFE_MODE: "true" } : {},
       // In dev mode, Next blocks cross-origin /_next/* dev-asset requests from
       // the LAN client's IP, breaking the app over the network (issue #13).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orionfold-relay",
-  "version": "0.24.1",
+  "version": "0.25.1",
   "description": "Orionfold Relay — a local-first, multi-agent orchestration runtime and builder scaffold for AI-native work.",
   "keywords": [
     "ai",

package/src/app/api/chat/conversations/route.ts

@@ -51,7 +51,10 @@ export async function POST(req: NextRequest) {
     );
   }
 
-  const validRuntimes = ["claude-code", "openai-codex-app-server"];
+  // "ollama" is first-class: getRuntimeForModel() returns it for local models,
+  // engine.ts routes it to sendOllamaMessage. Omitting it here 400'd the
+  // "Best privacy (local only)" tier's first chat/compose on a fresh install (#30).
+  const validRuntimes = ["claude-code", "openai-codex-app-server", "ollama"];
   if (!validRuntimes.includes(runtimeId)) {
     return NextResponse.json(
       { error: `Invalid runtimeId. Must be one of: ${validRuntimes.join(", ")}` },

package/src/components/apps/app-detail-actions.tsx

@@ -2,15 +2,9 @@
 
 import { useState, useTransition } from "react";
 import { useRouter } from "next/navigation";
-import { MoreHorizontal, Trash2 } from "lucide-react";
+import { Trash2 } from "lucide-react";
 import { toast } from "sonner";
 import { Button } from "@/components/ui/button";
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
 import { ConfirmDialog } from "@/components/shared/confirm-dialog";
 
 interface AppDetailActionsProps {
@@ -76,22 +70,15 @@ export function AppDetailActions({
 
   return (
     <>
-      <DropdownMenu>
-        <DropdownMenuTrigger asChild>
-          <Button variant="ghost" size="sm" aria-label="App actions">
-            <MoreHorizontal className="h-4 w-4" aria-hidden="true" />
-          </Button>
-        </DropdownMenuTrigger>
-        <DropdownMenuContent align="end">
-          <DropdownMenuItem
-            onClick={() => setConfirmOpen(true)}
-            className="text-destructive focus:text-destructive"
-          >
-            <Trash2 className="h-3.5 w-3.5 mr-2" aria-hidden="true" />
-            Delete app
-          </DropdownMenuItem>
-        </DropdownMenuContent>
-      </DropdownMenu>
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={() => setConfirmOpen(true)}
+        className="text-destructive hover:text-destructive"
+      >
+        <Trash2 className="h-3.5 w-3.5 mr-1.5" aria-hidden="true" />
+        Delete app
+      </Button>
 
       <ConfirmDialog
         open={confirmOpen}

package/src/components/apps/kit-view/kit-view.tsx

@@ -25,7 +25,14 @@ export function KitView({ model }: KitViewProps) {
       {model.kpis && <KpisSlotView tiles={model.kpis} />}
       {model.hero && <HeroSlotView slot={model.hero} />}
       {model.secondary && model.secondary.length > 0 && (
-        <SecondarySlotView slots={model.secondary} />
+        <div className="space-y-3">
+          {model.secondaryLead && (
+            <p className="text-sm text-muted-foreground">
+              {model.secondaryLead}
+            </p>
+          )}
+          <SecondarySlotView slots={model.secondary} />
+        </div>
       )}
       {model.activity && <ActivitySlotView slot={model.activity} />}
       {model.footer && <FooterSlotView slot={model.footer} />}

package/src/components/apps/kit-view/slots/header.tsx

@@ -22,8 +22,8 @@ interface HeaderSlotProps {
 export function HeaderSlotView({ slot, manifestPane }: HeaderSlotProps) {
   const { title, description, status, actions, cadenceChip, runNowBlueprintId, runNowVariables, periodChip, triggerSourceChip } = slot;
   return (
-    <div className="flex flex-col gap-1 sm:flex-row sm:items-center sm:justify-between">
-      <div className="min-w-0">
+    <div className="flex flex-col gap-1 sm:flex-row sm:items-center sm:justify-between sm:gap-4">
+      <div className="min-w-0 flex-1">
         <h1 className="text-xl font-semibold tracking-tight line-clamp-2" title={title}>
           {title}
         </h1>
@@ -33,7 +33,7 @@ export function HeaderSlotView({ slot, manifestPane }: HeaderSlotProps) {
           </p>
         )}
       </div>
-      <div className="flex flex-wrap items-center gap-2 mt-2 sm:mt-0">
+      <div className="flex flex-wrap items-center gap-2 mt-2 sm:mt-0 sm:flex-nowrap sm:shrink-0">
         {status && <StatusChip status={status} size="md" />}
         {cadenceChip && (
           <ScheduleCadenceChip

package/src/components/apps/kit-view/slots/manifest-sheet.tsx

@@ -2,7 +2,7 @@
 
 import type { ReactNode } from "react";
 import { useState } from "react";
-import { ChevronDown, FileText } from "lucide-react";
+import { ChevronRight, FileText } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import {
   Sheet,
@@ -36,7 +36,7 @@ export function ManifestSheet({ appName, body }: ManifestSheetProps) {
       >
         <FileText className="h-3.5 w-3.5 mr-1.5" aria-hidden="true" />
         View manifest
-        <ChevronDown className="h-3.5 w-3.5 ml-1" aria-hidden="true" />
+        <ChevronRight className="h-3.5 w-3.5 ml-1" aria-hidden="true" />
       </Button>
       <Sheet open={open} onOpenChange={setOpen}>
         <SheetContent side="right" className="w-full sm:max-w-2xl overflow-hidden flex flex-col">

package/src/components/apps/last-run-card.tsx

@@ -13,10 +13,11 @@ import {
   SheetTitle,
   SheetTrigger,
 } from "@/components/ui/sheet";
-import { ChevronDown, AlertCircle } from "lucide-react";
+import { ChevronDown, AlertCircle, Sparkles, RefreshCw } from "lucide-react";
 import { ErrorBoundary } from "@/components/shared/error-boundary";
+import { RunNowButton } from "@/components/apps/run-now-button";
 import type { TaskStatus } from "@/lib/constants/task-status";
-import type { RuntimeTaskSummary } from "@/lib/apps/view-kits/types";
+import type { BlueprintCard, RuntimeTaskSummary } from "@/lib/apps/view-kits/types";
 
 interface LastRunSummary {
   id: string;
@@ -94,6 +95,94 @@ function CompactVariant({ blueprintLabel, lastRun, runCount30d }: CompactProps)
   );
 }
 
+interface RunnableBlueprintCardProps {
+  card: BlueprintCard;
+  lastRun: LastRunSummary | null;
+  runCount30d: number;
+}
+
+/**
+ * FEAT-5/6: the runnable blueprint card on the app home. Renders the
+ * blueprint's name + one-line description + last-run status + a Run action.
+ * The "Start here" card is highlighted. Row-insert blueprints label their
+ * automatic trigger instead of offering a manual Run that fights the contract.
+ */
+export function RunnableBlueprintCard({
+  card,
+  lastRun,
+  runCount30d,
+}: RunnableBlueprintCardProps) {
+  const isRowInsert = card.trigger?.kind === "row-insert";
+  return (
+    <Card
+      className={
+        card.isPrimary
+          ? "surface-card border-primary ring-1 ring-primary/30"
+          : "surface-card"
+      }
+    >
+      <CardHeader className="pb-2 space-y-1.5">
+        {card.isPrimary && (
+          <Badge className="w-fit gap-1">
+            <Sparkles className="h-3 w-3" />
+            Start here
+          </Badge>
+        )}
+        <CardTitle className="text-sm font-medium">{card.name}</CardTitle>
+        {card.description && (
+          <p className="text-xs text-muted-foreground line-clamp-2">
+            {card.description}
+          </p>
+        )}
+      </CardHeader>
+      <CardContent className="space-y-3">
+        <div className="flex items-center gap-2 flex-wrap">
+          {lastRun ? (
+            <>
+              <Badge variant={statusVariant[lastRun.status]}>
+                {lastRun.status}
+              </Badge>
+              <span className="text-xs text-muted-foreground">
+                {formatAgo(lastRun.createdAt)}
+              </span>
+            </>
+          ) : (
+            <span className="text-xs text-muted-foreground">never run</span>
+          )}
+          <span className="text-xs text-muted-foreground">
+            · {runCount30d} {runCount30d === 1 ? "run" : "runs"} · 30d
+          </span>
+        </div>
+        {isRowInsert ? (
+          <p className="flex items-center gap-1.5 text-xs text-muted-foreground">
+            <RefreshCw className="h-3.5 w-3.5" />
+            Runs on its own when you add a row to the{" "}
+            {card.trigger?.tableName ?? "linked"} table
+          </p>
+        ) : (
+          <div className="space-y-1.5">
+            <RunNowButton
+              blueprintId={card.id}
+              variables={card.variables}
+              label="Run"
+            />
+            {/* FEAT-5.2: on the "Start here" card, tell a first-time user what
+                Run does. Only the primary card carries this hint, so the grid
+                stays scannable (progressive disclosure). */}
+            {card.isPrimary && (
+              <p className="text-xs text-muted-foreground">
+                {card.variables.length > 0
+                  ? "Run asks a few questions, then starts a workflow you can watch."
+                  : "Run starts a workflow you can watch as it works."}
+              </p>
+            )}
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+
 function HeroVariant({ task, previousRuns }: HeroProps) {
   const [sheetOpen, setSheetOpen] = useState(false);
 

package/src/components/apps/ledger-hero-panel.tsx

@@ -15,7 +15,8 @@ export function LedgerHeroPanel({ series, categories, period }: LedgerHeroPanelP
   if (series.length === 0 && categories.length === 0) {
     return (
       <div className="surface-card rounded-xl p-12 text-center text-muted-foreground border">
-        No data yet. Add transactions or click <strong>Run now</strong> to ingest a CSV.
+        No data yet. Click <strong>Run now</strong> to start this app&apos;s workflow.
+        Results show up here once it finishes.
       </div>
     );
   }

package/src/components/chat/chat-session-provider.tsx

@@ -297,7 +297,16 @@ export function ChatSessionProvider({ children }: { children: ReactNode }) {
           ...(opts?.title ? { title: opts.title } : {}),
         }),
       });
-      if (!res.ok) return null;
+      if (!res.ok) {
+        // Never swallow a create failure silently again (#30): a rejected
+        // runtime/model used to clear the composer with no signal at all.
+        const detail = await res
+          .json()
+          .then((b) => (b as { error?: string })?.error)
+          .catch(() => null);
+        toast.error(detail || "Couldn't start a chat with this model. Try another model.");
+        return null;
+      }
       const conversation = (await res.json()) as ConversationRow;
       setConversations((prev) => [conversation, ...prev]);
       // Set empty messages BEFORE activating so the conversation has an

package/src/components/settings/license-section.tsx

@@ -53,10 +53,15 @@ function daysUntil(iso: string): number {
 }
 
 function formatDate(iso: string): string {
+  // License dates are calendar dates stored as midnight-UTC instants
+  // (e.g. "2026-07-03T00:00:00Z"). Format in UTC so a customer in a
+  // behind-UTC timezone doesn't see the date shift one day earlier than
+  // the license file and their purchase email say.
   return new Date(iso).toLocaleDateString(undefined, {
     year: "numeric",
     month: "short",
     day: "numeric",
+    timeZone: "UTC",
   });
 }
 

package/src/components/workflows/shared/workflow-header.tsx

@@ -11,11 +11,74 @@ import {
   RotateCcw,
   Trash2,
   FolderKanban,
+  ArrowRight,
+  Inbox as InboxIcon,
+  Clock3,
+  Loader2,
 } from "lucide-react";
 import { workflowStatusVariant, patternLabels } from "@/lib/constants/status-colors";
 import { IconCircle, getWorkflowIconFromName } from "@/lib/constants/card-icons";
 import type { WorkflowStatusResponse } from "@/lib/workflows/types";
 
+/**
+ * FEAT-7/8: a status-aware signpost telling the user what to do next. After a
+ * blueprint instantiates a draft, "Execute" is not obvious — so `draft` gets a
+ * "click Execute to start" nudge. Once running/paused, activity lives on other
+ * surfaces (Inbox for approvals, the steps below for progress) — so those
+ * statuses point there. A paused HITL run must read as "waiting for you", not
+ * "stuck".
+ *
+ * Distinguishing the two kinds of `paused`: a delay pause carries `resumeAt`
+ * (it resumes on its own); a HITL pause (BUG-3) sets a step to
+ * `waiting_approval` and has no resumeAt (it waits for your answer → Inbox).
+ */
+export type Signpost = {
+  tone: "info" | "wait";
+  icon: "arrow" | "inbox" | "clock" | "spinner";
+  href?: string;
+  text: string;
+} | null;
+
+export function computeSignpost(data: WorkflowStatusResponse): Signpost {
+  const status = data.status;
+  if (status === "draft") {
+    return {
+      tone: "info",
+      icon: "arrow",
+      text: "Ready to go. Click Execute to start this workflow.",
+    };
+  }
+  // A live workflow is `active` at the top level (`running` is a step/run-state
+  // value; the loop arm may report it too — accept both).
+  if (status === "active" || status === "running") {
+    return {
+      tone: "info",
+      icon: "spinner",
+      text: "Working now. Watch the steps below as it goes.",
+    };
+  }
+  if (status === "paused") {
+    // A delay pause resumes on its own; the non-loop arm carries resumeAt.
+    const resumeAt =
+      "resumeAt" in data ? (data.resumeAt as number | null) : null;
+    if (resumeAt != null) {
+      return {
+        tone: "wait",
+        icon: "clock",
+        text: "Paused for a scheduled step. It resumes on its own.",
+      };
+    }
+    // Otherwise it is waiting for your answer (HITL checkpoint → Inbox).
+    return {
+      tone: "wait",
+      icon: "inbox",
+      href: "/inbox",
+      text: "Waiting for your approval. Answer it in your Inbox.",
+    };
+  }
+  return null;
+}
+
 /**
  * Pattern-agnostic header card for the workflow detail page. Renders the
  * workflow name, pattern label, project/run badges, status badge, and the
@@ -136,6 +199,57 @@ export function WorkflowHeader({
           )}
         </div>
       </div>
+      <SignpostBanner signpost={computeSignpost(data)} />
     </CardHeader>
   );
 }
+
+/**
+ * FEAT-7/8: renders the status-aware "what to do next" banner. `wait` tone
+ * (waiting on the user) is emphasized; `info` tone is quiet. When a signpost
+ * has an href, the whole banner is a link (e.g. paused HITL → /inbox).
+ */
+function SignpostBanner({ signpost }: { signpost: Signpost }) {
+  const router = useRouter();
+  if (!signpost) return null;
+
+  const Icon =
+    signpost.icon === "inbox"
+      ? InboxIcon
+      : signpost.icon === "clock"
+        ? Clock3
+        : signpost.icon === "spinner"
+          ? Loader2
+          : ArrowRight;
+
+  const tone =
+    signpost.tone === "wait"
+      ? "border-status-warning/40 bg-status-warning/10 text-foreground"
+      : "border-border bg-muted/40 text-muted-foreground";
+
+  const body = (
+    <div
+      className={`mt-3 flex items-center gap-2 rounded-lg border px-3 py-2 text-sm ${tone} ${
+        signpost.href ? "cursor-pointer hover:bg-accent transition-colors" : ""
+      }`}
+    >
+      <Icon
+        className={`h-4 w-4 shrink-0 ${
+          signpost.icon === "spinner" ? "animate-spin" : ""
+        }`}
+      />
+      <span>{signpost.text}</span>
+      {signpost.href && <ArrowRight className="h-3.5 w-3.5 ml-auto shrink-0" />}
+    </div>
+  );
+
+  if (signpost.href) {
+    const href = signpost.href;
+    return (
+      <div role="link" tabIndex={0} onClick={() => router.push(href)}>
+        {body}
+      </div>
+    );
+  }
+  return body;
+}