harnery 0.32.0 → 0.33.0

package/src/commands/claude-desktop.ts

@@ -1,12 +1,16 @@
 import type { Command } from "commander";
-import type { EmitContext } from "../commander.ts";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { monorepoRoot } from "../core/agents/index.ts";
 import {
   applyMirror,
+  applyTidy,
   type DesktopAccount,
   findDesktopDataDirs,
   listAccounts,
   planMirror,
+  planTidy,
   readCliAccount,
+  readDesktopLifecycleIndex,
 } from "../lib/claude-desktop.ts";
 
 /**
@@ -24,12 +28,14 @@ import {
  * desktop app picks the copies up, and opening one resumes with full
  * history.
  */
-export function registerClaudeDesktopCommand(program: Command, emit: EmitContext): void {
+export function registerClaudeDesktopCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
   const cmd = program
     .command("claude-desktop")
-    .description(
-      "Claude desktop-app session index: list accounts/sessions, mirror sessions across accounts",
-    )
+    .description("Claude desktop-app session index: list, mirror, and archive completed sessions")
     .action(() => {
       const dirs = requireDataDirs(emit, undefined);
       for (const dir of dirs) {
@@ -184,6 +190,101 @@ export function registerClaudeDesktopCommand(program: Command, emit: EmitContext
         }
       },
     );
+
+  cmd
+    .command("tidy")
+    .description(
+      "Archive desktop sidebar entries whose mapped Harnery lifecycle is done. " +
+        "Dry-run by default; --yes applies atomic entry updates.",
+    )
+    .option("--data-dir <path>", "Explicit desktop-app data directory")
+    .option(
+      "--account <uuid-prefix>",
+      "Only entries under accounts matching this UUID prefix (repeatable)",
+      collect,
+      [] as string[],
+    )
+    .option(
+      "--include-legacy-prefix",
+      "Also archive unmatched historical entries whose title starts with [DONE]",
+    )
+    .option("--yes", "Apply the archive plan (default is dry-run)")
+    .action(
+      async (opts: {
+        dataDir?: string;
+        account: string[];
+        includeLegacyPrefix?: boolean;
+        yes?: boolean;
+      }) => {
+        const dirs = requireDataDirs(emit, opts.dataDir);
+        const coordRoot =
+          context?.resolveCoordRoot?.() ?? context?.repoRoot ?? monorepoRoot() ?? process.cwd();
+        const lifecycle = await readDesktopLifecycleIndex(coordRoot);
+
+        for (const dir of dirs) {
+          const plan = planTidy(listAccounts(dir), lifecycle, {
+            accounts: opts.account,
+            includeLegacyPrefix: opts.includeLegacyPrefix,
+          });
+          const planned = plan.actions.map((action) => ({
+            account_uuid: action.entry.accountUuid,
+            cli_session_id: action.entry.cliSessionId,
+            title: action.entry.title,
+            source: action.source,
+            lifecycle_updated_at: action.lifecycle?.updatedAt ?? null,
+            file: action.entry.file,
+          }));
+          const skipped = plan.skipped
+            .map((skip) => ({
+              account_uuid: skip.entry.accountUuid,
+              cli_session_id: skip.entry.cliSessionId,
+              title: skip.entry.title,
+              reason: skip.reason,
+              lifecycle: skip.lifecycle?.state ?? null,
+            }))
+            .filter((skip) => skip.reason !== "already_archived");
+          const skippedByReason = Object.fromEntries(
+            [
+              "already_archived",
+              "blocked_title",
+              "lifecycle_active",
+              "lifecycle_blocked",
+              "unmatched",
+            ].map((reason) => [
+              reason,
+              plan.skipped.filter((skip) => skip.reason === reason).length,
+            ]),
+          );
+
+          if (!opts.yes) {
+            emit.data({
+              data_dir: dir,
+              dry_run: true,
+              planned,
+              skipped,
+              skipped_by_reason: skippedByReason,
+              hint: plan.actions.length > 0 ? "re-run with --yes to archive" : "nothing to archive",
+            });
+            continue;
+          }
+
+          const result = applyTidy(plan);
+          emit.data({
+            data_dir: dir,
+            dry_run: false,
+            archived: result.archived,
+            already_archived: result.alreadyArchived,
+            planned,
+            skipped,
+            skipped_by_reason: skippedByReason,
+            hint:
+              result.archived > 0
+                ? "fully quit the Claude desktop app (tray icon, not the X) and relaunch to refresh the sidebar"
+                : "nothing to archive",
+          });
+        }
+      },
+    );
 }
 
 function collect(value: string, previous: string[]): string[] {

package/src/commands/doctor.ts

@@ -21,7 +21,14 @@ import { BUILTIN_ADAPTER_IDS } from "../core/adapters/index.ts";
 import { resolveBinName, ripgrepAutoInstall } from "../core/config.ts";
 import { ADAPTER_SPECS, type AdapterId } from "../core/hooks/adapter/events.ts";
 import { loadAdapterWiring, summarizeAdapterWiring } from "../core/hooks/adapter/wiring.ts";
-import { inspectCodexWslBridge } from "../core/hooks/codex-wsl-bridge.ts";
+import {
+  type CodexHookAuthorizationResult,
+  probeCodexHookAuthorization,
+} from "../core/hooks/codex-authorization.ts";
+import {
+  type CodexWslBridgeStatus,
+  inspectCodexWslBridge,
+} from "../core/hooks/codex-wsl-bridge.ts";
 import {
   ADAPTER_BINARIES,
   ADAPTER_INSTALL_HINTS,
@@ -34,7 +41,7 @@ import { findRg, installRg, managedRgPath, rgInstallSupported } from "../lib/too
 
 type Severity = "ok" | "warn" | "fail";
 
-interface Check {
+export interface Check {
   name: string;
   severity: Severity;
   detail: string;
@@ -66,7 +73,7 @@ export function registerDoctorCommand(program: Command, emit: EmitContext): void
           emit.text(`ripgrep install failed: ${(err as Error).message}\n`);
         }
       }
-      const checks = runChecks();
+      const checks = await runChecks();
       const requiredFailed = checks.some((c) => c.severity === "fail");
 
       if (opts.json) {
@@ -99,13 +106,15 @@ export function registerDoctorCommand(program: Command, emit: EmitContext): void
     });
 }
 
-export function runChecks(): Check[] {
-  const codexWslBridge = checkCodexWslBridge();
+export async function runChecks(): Promise<Check[]> {
+  const codexWslStatus = inspectCodexWslBridge();
+  const codexWslBridge = checkCodexWslBridge(codexWslStatus);
   // Probe the adapter CLIs before the hook check runs, not in output order:
   // an unwired adapter only matters if its CLI is actually installed, and
   // probing once here keeps that join to one spawn per CLI.
   const workflow = BUILTIN_ADAPTER_IDS.map((id) => ({ id, ...checkWorkflowAdapter(id) }));
   const installed = workflow.filter((w) => w.installed).map((w) => w.id as AdapterId);
+  const codexAuthorization = await checkCodexHookAuthorization(installed, codexWslStatus);
   return [
     checkNode(),
     checkGit(),
@@ -113,6 +122,7 @@ export function runChecks(): Check[] {
     checkRipgrep(),
     checkHarneryDir(),
     checkAdapterHooks(installed),
+    ...(codexAuthorization ? [codexAuthorization] : []),
     checkGitHookRegions(),
     ...(codexWslBridge ? [codexWslBridge] : []),
     ...workflow.map((w) => w.check),
@@ -153,8 +163,7 @@ function checkGitHookRegions(): Check {
   }
 }
 
-function checkCodexWslBridge(): Check | null {
-  const status = inspectCodexWslBridge();
+function checkCodexWslBridge(status: CodexWslBridgeStatus | null): Check | null {
   if (!status) return null;
   return {
     name: "codex:WSL bridge",
@@ -166,6 +175,49 @@ function checkCodexWslBridge(): Check | null {
   };
 }
 
+export function codexAuthorizationCheck(result: CodexHookAuthorizationResult): Check {
+  const reviewHint =
+    "terminal UI: run `/hooks`; Codex Desktop: open Settings > Hooks; after approval, start a fresh task";
+  if (result.status === "runnable") {
+    return { name: "codex:hook authorization", severity: "ok", detail: result.detail };
+  }
+  if (result.status === "review_required" || result.status === "disabled") {
+    return {
+      name: "codex:hook authorization",
+      severity: "warn",
+      detail: result.detail,
+      hint: reviewHint,
+    };
+  }
+  return {
+    name: "codex:hook authorization",
+    severity: "warn",
+    detail: `authorization unverified: ${result.detail}`,
+    hint: reviewHint,
+  };
+}
+
+async function checkCodexHookAuthorization(
+  installedAdapters: AdapterId[],
+  codexWslStatus: CodexWslBridgeStatus | null,
+): Promise<Check | null> {
+  const root = findCoordProjectRoot();
+  if (!root || !summarizeAdapterWiring(root).wired.includes("codex")) return null;
+
+  if (codexWslStatus) {
+    return {
+      name: "codex:hook authorization",
+      severity: "warn",
+      detail:
+        "unverified from WSL; the Windows-native Codex runtime owns this workspace's trust state",
+      hint: "run the host's Windows bridge doctor, or open Codex Desktop Settings > Hooks; start a fresh task after approval",
+    };
+  }
+  if (!installedAdapters.includes("codex")) return null;
+
+  return codexAuthorizationCheck(await probeCodexHookAuthorization({ cwd: root }));
+}
+
 function checkRipgrep(): Check {
   const found = findRg();
   if (found) {

package/src/commands/init.ts

@@ -175,6 +175,8 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
             `${removed} legacy hook(s) in ${rel(projectRoot, settingsPath)} (${already} already present)`,
         );
       }
+      const authorizationReview = codexHookReviewAction(adapter);
+      if (authorizationReview) actions.push(authorizationReview);
 
       // ── 3. agent-facing instructions block + skills ────────────────────────
       // A misconfigured host addendum aborts here rather than half-writing: the
@@ -202,6 +204,15 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
     });
 }
 
+export function codexHookReviewAction(adapter: AdapterId): string | null {
+  if (adapter !== "codex") return null;
+  return (
+    "! Codex authorizes hook commands separately. Before starting work, review them in " +
+    "the terminal UI with `/hooks` or in Codex Desktop under Settings > Hooks. " +
+    "After approval, start a fresh task so SessionStart can run."
+  );
+}
+
 /**
  * Merge agent-hook entries into a adapter settings object in place, idempotently.
  * Preserves every existing hook; rewrites events already wired to

package/src/commands/instructions.ts

@@ -0,0 +1,129 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import { countTokens } from "gpt-tokenizer/model/gpt-4o";
+import type { EmitContext } from "../commander.ts";
+import { monorepoRoot } from "../core/agents/index.ts";
+import type { Adapter } from "../core/hooks/events/schema.ts";
+import {
+  buildInstructionBundle,
+  type InstructionBundleComponent,
+} from "../lib/instructions/bundle.ts";
+
+interface ManifestOptions {
+  adapter: string;
+  format: string;
+  output?: string;
+}
+
+export function registerInstructionsCommand(program: Command, emit: EmitContext): void {
+  const command = program
+    .command("instructions")
+    .description(
+      "Inspect and version the repo-authored instruction bundle loaded by each adapter.",
+    );
+
+  command
+    .command("manifest [paths...]")
+    .description("Emit a machine-readable bundle manifest for one or more working paths")
+    .option("--adapter <adapter>", "claude-code, cursor, codex, or all", "all")
+    .option("--format <type>", "Output format: json or table", "json")
+    .option("-o, --output <file>", "Write the complete JSON manifest to a file")
+    .action((paths: string[], options: ManifestOptions) => {
+      if (options.format === "json") emit.config({ format: "json" });
+      const coordRoot = monorepoRoot() ?? process.cwd();
+      const adapters = parseAdapters(options.adapter);
+      const profiles = (paths.length > 0 ? paths : [process.cwd()]).flatMap((path) =>
+        adapters.map((adapter) =>
+          enrichBundle(
+            buildInstructionBundle({ coordRoot, cwd: resolve(path), adapter }),
+            coordRoot,
+          ),
+        ),
+      );
+
+      const manifest = {
+        ok: true,
+        schema_version: 1,
+        generated_at: new Date().toISOString(),
+        source_commit: gitHead(coordRoot),
+        tokenizer: "o200k_base",
+        coord_root: ".",
+        profile_count: profiles.length,
+        profiles,
+      };
+      if (options.output) {
+        const output = resolve(options.output);
+        writeFileSync(output, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+        emit.data({
+          ok: true,
+          output,
+          schema_version: manifest.schema_version,
+          generated_at: manifest.generated_at,
+          source_commit: manifest.source_commit,
+          profile_count: manifest.profile_count,
+        });
+      } else {
+        emit.data(manifest);
+      }
+    });
+}
+
+function parseAdapters(value: string): Adapter[] {
+  if (value === "all") return ["claude-code", "cursor", "codex"];
+  if (value === "claude-code" || value === "cursor" || value === "codex") return [value];
+  throw new Error(`unsupported adapter '${value}' (expected claude-code, cursor, codex, or all)`);
+}
+
+function enrichBundle(bundle: ReturnType<typeof buildInstructionBundle>, coordRoot: string) {
+  const components = bundle.components.map((component) => enrichComponent(component, coordRoot));
+  const canonicalSources = bundle.canonical_sources.map((component) =>
+    enrichComponent(component, coordRoot),
+  );
+  return {
+    ...bundle,
+    coord_root: ".",
+    components,
+    canonical_sources: canonicalSources,
+    totals: totals(components),
+    canonical_source_totals: totals(canonicalSources),
+  };
+}
+
+function enrichComponent(component: InstructionBundleComponent, coordRoot: string) {
+  const bytes = readFileSync(resolve(coordRoot, component.path));
+  const text = bytes.includes(0) ? null : bytes.toString("utf8");
+  return {
+    ...component,
+    chars: text?.length ?? null,
+    tokens: text === null ? null : countTokens(text),
+  };
+}
+
+function totals(components: ReturnType<typeof enrichComponent>[]) {
+  const roles = ["always_loaded", "just_in_time", "runtime_config"] as const;
+  return {
+    files: components.length,
+    bytes: components.reduce((sum, component) => sum + component.bytes, 0),
+    tokens: components.reduce((sum, component) => sum + (component.tokens ?? 0), 0),
+    by_role: Object.fromEntries(
+      roles.map((role) => {
+        const selected = components.filter((component) => component.role === role);
+        return [
+          role,
+          {
+            files: selected.length,
+            bytes: selected.reduce((sum, component) => sum + component.bytes, 0),
+            tokens: selected.reduce((sum, component) => sum + (component.tokens ?? 0), 0),
+          },
+        ];
+      }),
+    ),
+  };
+}
+
+function gitHead(root: string): string | null {
+  const result = spawnSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" });
+  return result.status === 0 ? result.stdout.trim() : null;
+}

package/src/commands/presence.ts

@@ -175,7 +175,13 @@ export function registerPresenceCommand(program: Command, emit: EmitContext): vo
         for (const a of m.agents) {
           const task = a.task ? `  "${a.task.slice(0, 70)}"` : "";
           const files = a.files_touched?.length ? `  [${a.files_touched.length} files]` : "";
-          emit.text(`  agent-${a.name ?? a.instance_id.slice(0, 8)}${task}${files}\n`);
+          const lifecycle =
+            a.task_state === "blocked" && a.task_state_reason
+              ? `${a.task_state}: ${a.task_state_reason}`
+              : a.task_state;
+          emit.text(
+            `  agent-${a.name ?? a.instance_id.slice(0, 8)}${task}${files}  activity=${a.activity} lifecycle=${lifecycle}\n`,
+          );
         }
       }
     });

package/src/core/agents/canonical-emit.ts

@@ -37,11 +37,11 @@ export function resolveEmitRoot(start: string = process.cwd()): string | null {
   return resolveCoordRoot(start);
 }
 
-export function emitCanonical(input: CanonicalEmitInput): void {
+export function emitCanonical(input: CanonicalEmitInput): boolean {
   const root = resolveEmitRoot();
-  if (!root) return;
+  if (!root) return false;
   const binary = coordBinPath("agent-coord", root);
-  if (!binary) return;
+  if (!binary) return false;
   try {
     const args = [
       "emit-event",
@@ -71,9 +71,11 @@ export function emitCanonical(input: CanonicalEmitInput): void {
     if (result.error || result.status !== 0) {
       const why = result.error ? result.error.message : `exit ${result.status}`;
       process.stderr.write(`emitCanonical: ${input.type} emit failed (${why})\n`); // lint-ok-emission: soft-fail diagnostic promised by the module doc; silent drops cost blocked turns
+      return false;
     }
+    return true;
   } catch {
-    /* never break the caller */
+    return false;
   }
 }
 

package/src/core/agents/cli.ts

@@ -620,9 +620,13 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
   const sessionNameNudge = args["session-name-nudge"] === "true";
   const taskNudge = args["task-nudge"] === "true";
   const statusFooterNudge = args["status-footer-nudge"] === "true";
+  // Value is the adapter id; a bare flag (parsed as "true") still enables the
+  // reminder with the adapter-neutral wording.
+  const turnRitualNudge =
+    args["turn-ritual-nudge"] === "true" ? "generic" : args["turn-ritual-nudge"];
   if (!instanceId) {
     process.stderr.write(
-      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--session-name-nudge] [--task-nudge] [--status-footer-nudge]\n",
+      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--session-name-nudge] [--task-nudge] [--status-footer-nudge] [--turn-ritual-nudge <adapter>]\n",
     );
     return 2;
   }
@@ -635,6 +639,7 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
     sessionNameNudge,
     taskNudge,
     statusFooterNudge,
+    turnRitualNudge,
   });
   process.stdout.write(text);
   return 0;

package/src/core/agents/coord-client.ts

@@ -75,16 +75,27 @@ export interface Heartbeat {
   task?: string;
   /** UTC ISO-8601 timestamp when task was last set/cleared. Used by adapters without Stop enforcement to compute staleness. 2026-05-24. */
   task_updated_at?: string | null;
+  /** Current evidence-derived activity axis. */
+  activity?: "unknown" | "working" | "needs_input" | "idle";
+  activity_updated_at?: string;
+  activity_source?: string;
+  /** Explicit task lifecycle axis. */
+  task_state?: "active" | "blocked" | "done";
+  task_state_updated_at?: string;
+  task_state_reason?: string;
   /** Session name built on the first non-empty set-task; its presence means "this session has been named". 2026-08-09. */
   suggested_session_name?: string;
   /** Stamped by turn.stop once the suggested name is seen in assistant reply text. 2026-08-09. */
   session_name_seen_at?: string;
+  /** Which suggested name the latest sighting covered. */
+  session_name_seen_for?: string;
   /** Auto-generated per-turn summary written by the Stop hook via Haiku. 2026-05-23. */
   turn_summary?: string | null;
   /** UTC ISO-8601 timestamp when turn_summary was last refreshed. */
   turn_summary_updated_at?: string | null;
   /** Hook client: `claude-code` (default) or `cursor`. Cursor Phase 1. */
   platform?: string;
+  workflow_run_id?: string;
 }
 
 /**

package/src/core/agents/index.ts

@@ -12,3 +12,4 @@
 export * from "./canonical-emit.js";
 export * from "./coord-client.js";
 export * from "./session-events.js";
+export * from "./state/session-state.js";

package/src/core/agents/render/prompt-context.ts

@@ -45,6 +45,7 @@ import { join } from "node:path";
 import { coordEnv } from "../../../lib/env.ts";
 import { endOfTurnStatusCommand, resolveBinName } from "../../config.ts";
 import { type RemoteMachine, readRemoteMachines } from "../../presence/index.ts";
+import type { AgentActivity, TaskState } from "../state/session-state.ts";
 import { formatPendingCouncils } from "./session-context.ts";
 
 interface HeartbeatRow {
@@ -59,8 +60,12 @@ interface HeartbeatRow {
   files_touched?: string[];
   platform?: string;
   task?: string;
+  activity?: AgentActivity;
+  task_state?: TaskState;
+  task_state_reason?: string;
   task_updated_at?: string;
   suggested_session_name?: string;
+  session_name_seen_for?: string;
   turn_summary?: string;
   workflow_run_id?: string;
 }
@@ -79,6 +84,12 @@ export interface PromptContextOpts {
   /** When true, append the non-deduplicated Codex status-footer reminder.
    * The caller enables this only for human-facing Codex sessions. */
   statusFooterNudge?: boolean;
+  /** Adapter id whose Stop hook ENFORCES the end-of-turn ritual (task_set +
+   * status check). When set, append a fresh per-prompt reminder of that
+   * contract so the model satisfies it before ending the turn instead of
+   * being bounced into a retry. Not hash-deduped, same rationale as the
+   * status footer. */
+  turnRitualNudge?: string;
 }
 
 /**
@@ -98,6 +109,7 @@ export function renderPromptContext(opts: PromptContextOpts): string {
     sessionNameNudge,
     taskNudge,
     statusFooterNudge,
+    turnRitualNudge,
   } = opts;
   const sections: string[] = [];
 
@@ -130,9 +142,41 @@ export function renderPromptContext(opts: PromptContextOpts): string {
     if (statusMsg) sections.push(statusMsg);
   }
 
+  // 5. Adapters whose Stop hook ENFORCES the turn ritual get a fresh reminder
+  // on every prompt. Reminding before the reply is drafted is far cheaper than
+  // the bounce-and-retry the Stop hook otherwise forces: enforcement-only
+  // compliance was measured missing on a double-digit share of turns. Not
+  // hash-deduped for the same reason as the Codex footer.
+  if (turnRitualNudge) {
+    const ritualMsg = renderTurnRitualReminder(coordRoot, instanceId, turnRitualNudge);
+    if (ritualMsg) sections.push(ritualMsg);
+  }
+
   return sections.join("\n\n");
 }
 
+function renderTurnRitualReminder(
+  coordRoot: string,
+  selfInstanceId: string,
+  adapter: string,
+): string {
+  const hb = readHeartbeat(join(coordRoot, ".harnery", "active", `${selfInstanceId}.json`));
+  if (!hb || hb.kind === "subagent" || hb.kind === "transient" || hb.workflow_run_id) return "";
+
+  const bin = resolveBinName(coordRoot);
+  const statusCommand = endOfTurnStatusCommand(coordRoot);
+  // Claude Code renders the status box only if the reply carries it; Cursor
+  // shows the box inline on its own, so it is never asked for a second copy.
+  const paste =
+    adapter === "claude-code"
+      ? " and paste its output verbatim in a fenced code block at the end of your reply"
+      : "";
+  return (
+    `Turn ritual (Stop-enforced): on any turn that uses tools, run \`${bin} agents set-task "<short focus>"\` at some point during the turn (required every turn, even when the focus is unchanged; pass an empty string when there is no meaningful focus), then make \`${statusCommand}\` your final tool call${paste}. ` +
+    "A turn that ends without these is bounced by the Stop hook and costs a retry."
+  );
+}
+
 function renderStatusFooterReminder(coordRoot: string, selfInstanceId: string): string {
   const hb = readHeartbeat(join(coordRoot, ".harnery", "active", `${selfInstanceId}.json`));
   if (!hb || hb.kind === "subagent" || hb.kind === "transient" || hb.workflow_run_id) return "";
@@ -179,15 +223,21 @@ function computeFocusNudgeIfChanged(
   let message = "";
   let nudgeKind = "";
 
-  if (opts.sessionNameNudge && !hb.suggested_session_name) {
+  if (
+    opts.sessionNameNudge &&
+    (!hb.suggested_session_name ||
+      (hb.session_name_seen_for !== undefined &&
+        hb.suggested_session_name !== hb.session_name_seen_for))
+  ) {
     // Keyed on "a name was ever produced", not task_updated_at: a bare clear
     // as the first declaration must not end the naming window.
     needsNudge = true;
     nudgeKind = "session-name";
-    message =
-      `This session has no name yet: run \`${bin} agents set-task "<2-5 word session topic>"\` as your first tool call. ` +
-      "When it returns `first_of_session: true`, reproduce its `suggested_session_name` value by itself inside a fenced code block at the very top of your reply so the operator can one-click-copy it as the session/tab title. " +
-      "Then continue with the task; that `set-task` also satisfies this turn's focus declaration.";
+    message = hb.suggested_session_name
+      ? `This session's lifecycle changed its suggested name. Reproduce this value by itself inside a fenced code block at the very top of your reply so the operator can one-click-copy it as the session/tab title: ${hb.suggested_session_name}`
+      : `This session has no name yet: run \`${bin} agents set-task "<2-5 word session topic>"\` as your first tool call. ` +
+        "When it returns `first_of_session: true`, reproduce its `suggested_session_name` value by itself inside a fenced code block at the very top of your reply so the operator can one-click-copy it as the session/tab title. " +
+        "Then continue with the task; that `set-task` also satisfies this turn's focus declaration.";
   } else if (opts.taskNudge && !taskValue) {
     needsNudge = true;
     nudgeKind = "task-unset";
@@ -269,6 +319,9 @@ function computePeerTableIfChanged(
       started_at: p.started_at ?? null,
       files_touched: Array.from(p.files_touched ?? []).sort(),
       platform: p.platform ?? null,
+      activity: p.activity ?? "unknown",
+      task_state: p.task_state ?? "active",
+      task_state_reason: p.task_state_reason ?? null,
     }))
     .sort((a, b) => (a.instance_id ?? "").localeCompare(b.instance_id ?? ""));
   // Remote basis: machine + per-agent identity/task/files (published_at is
@@ -279,6 +332,9 @@ function computePeerTableIfChanged(
       instance_id: a.instance_id,
       name: a.name ?? null,
       task: a.task ?? null,
+      activity: a.activity,
+      task_state: a.task_state,
+      task_state_reason: a.task_state_reason ?? null,
       files_touched: Array.from(a.files_touched ?? []).sort(),
     })),
   }));
@@ -493,6 +549,7 @@ function renderSubtable(
 
 function formatRow(r: HeartbeatRow & { display_files: string[] }, nowSec: number): string {
   const taskPart = r.task ? ` "${r.task.slice(0, 60)}"` : "";
+  const statePart = formatState(r);
   // Fall back started_at → last_heartbeat; if neither is a valid timestamp,
   // show "age unknown" rather than the epoch-derived "20608d ago" ghost.
   const startedSec = parseIsoSec(r.started_at) ?? parseIsoSec(r.last_heartbeat);
@@ -503,7 +560,15 @@ function formatRow(r: HeartbeatRow & { display_files: string[] }, nowSec: number
   // Prefer a short instance_id over a bare "unknown" so an incomplete row is
   // still identifiable.
   const label = r.name ?? (r.instance_id ? r.instance_id.slice(0, 8) : "unknown");
-  return `  - agent-${label}${taskPart}   (${ageFrom}, ${filesPart}${lastActivity})${turnSummary}`;
+  return `  - agent-${label}${taskPart}   (${statePart}, ${ageFrom}, ${filesPart}${lastActivity})${turnSummary}`;
+}
+
+function formatState(r: HeartbeatRow): string {
+  const activity = r.activity ?? "unknown";
+  const lifecycle = r.task_state ?? "active";
+  const reason =
+    lifecycle === "blocked" && r.task_state_reason ? `: ${r.task_state_reason.slice(0, 80)}` : "";
+  return `activity=${activity}, lifecycle=${lifecycle}${reason}`;
 }
 
 function fmtFiles(files: string[]): string {