jackherd 1.14.0 → 1.15.0

package/src/plans/layout.ts

@@ -2,6 +2,7 @@ import { TONE, TONE_ROLE } from '../config/tones'
 import { CONTEXT_LEVEL, type ContextLevel, type ContextReading, contextLabel } from '../context'
 import type { LaneProgress, PhaseProgress } from '../plan-format'
 import { currentPhase, isPhaseOpen, phaseLabel } from '../plan-format'
+import { ellipsize } from '../plan-format/terminal-text'
 import type { WaitingItem } from '../plan-format/waiting'
 import { boundedMemo } from '../shared/bounded-memo'
 import {
@@ -32,6 +33,7 @@ import {
   type WatchHealth,
 } from '../watch/plan-badges'
 import type { UnplannedTask } from './active-tasks'
+import type { SubagentLine } from './activity-read'
 import { type AgentOf, clickHint } from './click-hint'
 import { type CoordinatorView, coordinatorShortName, coordinatorText } from './coordinator-row'
 import { type Frame, indented, joinFrames, narrower, rowFrame, spaced, textFrame, unpainted } from './frame'
@@ -98,7 +100,7 @@ import { shownWithMore } from './shown-with-more'
 import { askedCheckOf } from './source-asked'
 import { type SourceBlock, type SourceSummary, sourceItems, sourceSummaries } from './source-rows'
 import { chevronOf, LESS_MARK, NO_AGENT_SYMBOL, statusSymbol, statusWord, TURN_MARK } from './symbols'
-import { BADGE_TEXTS, type BadgeTexts, checksText, laneMarkText, TEXTS } from './texts'
+import { BADGE_TEXTS, type BadgeTexts, checksText, foldedChecksText, laneMarkText, TEXTS } from './texts'
 import { paintOfRole, paintOfTone, toneOfRole } from './tones'
 import {
   allBlockRows,
@@ -142,8 +144,13 @@ export type LaneView = {
   sentFiles?: SentChip[]
   /** What a resting lane waits on, from its report (`restNote`); absent or null while it works or asks nothing. */
   restNote?: string | null
+  /** The last action of the lane's agent and of its running subagents, from their logs; absent without a source. */
+  activity?: LaneActivity
 }
 
+/** `lane` is null while the agent's log holds no action; the lines show only while the lane works. */
+export type LaneActivity = { lane: string | null; subagents: readonly SubagentLine[] }
+
 /** `watch` is the health of the watcher the badges come from, absent when it was not read. */
 export type OverviewView = {
   title: string
@@ -652,15 +659,23 @@ const markTone = ({ feedback, changesRequested }: PullRequestBadges): BadgeTone
   return feedback > 0 ? BADGE_TONE.amber : BADGE_TONE.grey
 }
 
+/** The check state behind a folded badge in the colour of its state, a draft dim; empty without checks. */
+const foldedChecksMark = (pullRequest: PullRequest): string => {
+  const text = foldedChecksText(pullRequest)
+  if (!text) return ''
+  return ` ${pullRequest.draft ? paint.dim(text) : CHECKS_PAINT[pullRequest.checks](text)}`
+}
+
 /**
  * `↗ #<n>` as a badge linked to the pull request, with `💬 <n>` while it has feedback since its last push and `✋`
- * while changes are requested; dark red then, else amber with feedback, else grey.
+ * while changes are requested; dark red then, else amber with feedback, else grey. Its check state follows outside
+ * the badge, so a red check stays red beside the tone of the feedback.
  */
 const pullRequestMark = (pullRequest: PullRequest, badges: WatchBadges): string => {
   const found = badges[String(pullRequest.number)] ?? NO_BADGES
   const feedback = found.feedback > 0 ? ` 💬 ${found.feedback}` : ''
   const text = `↗ #${pullRequest.number}${feedback}${found.changesRequested ? ' ✋' : ''}`
-  return linkedBox(pullRequest.url, text, markTone(found))
+  return `${linkedBox(pullRequest.url, text, markTone(found))}${foldedChecksMark(pullRequest)}`
 }
 
 /** `📡 <n>` in amber while tickets of the lane are new, linked to the first of them; nothing otherwise. */
@@ -883,6 +898,34 @@ const pullRequestsFrame = (view: LaneView, context: LaneContext): Frame => {
   )
 }
 
+const ACTIVITY_MARK = '↳'
+const SUBAGENT_ACTIVITY_INDENT = '  '
+/** How long a subagent's name may grow before its action, so a narrow pane cuts the name and keeps the action. */
+const SUBAGENT_NAME_CELLS = 28
+
+/** One dim line of activity behind `indent`, cut to `width`; the cut is made before the paint, on plain text. */
+const activityLine = (indent: string, text: string, width: number): string =>
+  paint.dim(fit(`${indent}${ACTIVITY_MARK} ${text}`, width))
+
+/**
+ * The last action of a working lane's agent and of each of its running subagents, one dim line each, under the lane
+ * line in the column of its children. None while the lane does not work, or without a source for it.
+ */
+const activityLines = ({ activity, status }: LaneView, width: number): string[] => {
+  if (!activity || status.agent !== AGENT_STATUS.working) return []
+  const indent = ' '.repeat(LANE_HEAD_CELLS)
+  return [
+    ...(activity.lane === null ? [] : [activityLine(indent, activity.lane, width)]),
+    ...activity.subagents.map(({ label, description, line }) =>
+      activityLine(
+        `${indent}${SUBAGENT_ACTIVITY_INDENT}`,
+        `${ellipsize(description ?? label, SUBAGENT_NAME_CELLS)}: ${line}`,
+        width,
+      ),
+    ),
+  ]
+}
+
 /**
  * The lane line is a row of its own; an open lane continues after a blank line with its session, links, pull requests
  * and phases (`openLaneFrame`), indented to the column of the lane's name.
@@ -906,7 +949,9 @@ const laneBlock = (
   }
   const open = isLaneOpen(state, view.progress.lane.name, view.status.agent)
   const lines = laneLines(view, open, { width, taskStyle }, columns, reason)
-  const row = rowFrame(laneKey(view.progress.lane.name), lines, [], context)
+  const lane = rowFrame(laneKey(view.progress.lane.name), lines, [], context)
+  const activity = activityLines(view, width)
+  const row = activity.length > 0 ? joinFrames([lane, textFrame(activity)]) : lane
   if (!open) return row
   const inner = narrower(context, LANE_HEAD_CELLS)
   const head = {

package/src/plans/live.ts

@@ -2,13 +2,14 @@ import { existsSync, type FSWatcher, watch } from 'node:fs'
 import { basename, dirname } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { terminalSafe } from '../plan-format/terminal-text'
-import { runHerdr } from '../terminal/herdr'
+import { herdrRunnerAsync } from '../terminal/herdr'
 import { enterTerminal, reportCrash, terminalRestore } from '../terminal/lifetime'
 import { openInBrowser } from '../terminal/open'
 import { crashEnd } from '../terminal/restore'
 import { closeWaiting } from '../waiting/command'
 import { isWatcherRunning } from '../watch/watcher-lock'
-import { askCoordinator } from './ask-coordinator'
+import { ASKING_NOTICE, type AskDependencies, askCoordinator } from './ask-coordinator'
+import type { AskTarget } from './ask-target'
 import { errorText } from './error-text'
 import { focusedScreen } from './focus-overlay'
 import { noPullRequests } from './github'
@@ -438,6 +439,17 @@ const openPlan = (live: Live, snapshot: Snapshot, address: string) => {
   live.notice = reason === null ? texts.pageOpened(page.path) : texts.pageNotOpenedReason(reason)
 }
 
+/**
+ * Asks the coordinator without holding the herd still: the answer replaces the footer line when it arrives, unless
+ * another click has set the footer in the meantime.
+ */
+const askAndShow = async (live: Live, target: AskTarget, dependencies: AskDependencies) => {
+  const answer = await askCoordinator(target, dependencies)
+  if (live.notice !== ASKING_NOTICE) return
+  live.notice = answer
+  redraw(live)
+}
+
 /**
  * What a hit on a row of a block of the herd does: expands or folds it, asks the coordinator to put a question or a board row
  * (the result shows in the footer) or opens its address (a failure shows there). An appointment row only ever expands.
@@ -452,11 +464,12 @@ const applyBlockClick = (live: Live, outcome: BlockClick): void => {
   }
   if ('ask' in outcome) {
     const { root, settings } = live.source
-    live.notice = askCoordinator(outcome.ask, {
+    live.notice = ASKING_NOTICE
+    void askAndShow(live, outcome.ask, {
       language: settings.responseLanguage,
       adapter: settings.adapter,
       repository: basename(root),
-      run: runHerdr,
+      run: herdrRunnerAsync(process.env),
     })
     return
   }

package/src/plans/plan-panes.ts

@@ -1,8 +1,18 @@
 import { basename } from 'node:path'
 import { HERD_COMMAND, HERD_COMMAND_WORDS } from './herd-command'
 
-/** One herdr pane as `herd --ensure` sees it: where it is, whether an agent runs in it, its foreground commands. */
-export type PaneState = { pane: string; tab: string; cwd: string; agent: boolean; foreground: string[][] }
+/**
+ * One herdr pane as `herd --ensure` sees it: where it is, whether an agent runs in it, its foreground commands, and
+ * its name (`label`), which herdr keeps across a restart; null without one.
+ */
+export type PaneState = {
+  pane: string
+  tab: string
+  cwd: string
+  agent: boolean
+  foreground: string[][]
+  label: string | null
+}
 
 /** Runs a command in a free shell pane, or splits a pane to the right and runs it in the new one. */
 export type PaneAction = { kind: 'run' | 'split'; pane: string; command: string }
@@ -23,7 +33,7 @@ export type PlanPaneInput = {
 
 export type PlanPaneResult = { actions: PaneAction[]; notes: string[] }
 
-type ListedPane = { pane_id: string; tab_id: string; cwd: string; agent?: unknown }
+type ListedPane = { pane_id: string; tab_id: string; cwd: string; agent?: unknown; label?: unknown }
 
 const isListedPane = (value: unknown): value is ListedPane => {
   if (typeof value !== 'object' || value === null) return false
@@ -42,6 +52,7 @@ export const paneListOf = (json: string): Omit<PaneState, 'foreground'>[] => {
     tab: each.tab_id,
     cwd: each.cwd,
     agent: typeof each.agent === 'string',
+    label: typeof each.label === 'string' ? each.label : null,
   }))
 }
 
@@ -106,6 +117,13 @@ export const isPlanView = (foreground: readonly (readonly string[])[], lane: str
 export const isIdleShell = ({ agent, foreground }: PaneState): boolean =>
   !agent && foreground.length > 0 && foreground.every((argv) => SHELLS.has(programOf(argv)))
 
+/**
+ * A restored pane whose shell is still starting: nothing in the foreground yet, or a shell first (its prompt may run
+ * `git` beside it). Another program there, an editor or a pager, would take the command as its input.
+ */
+const isStartingShell = ({ agent, foreground }: PaneState): boolean =>
+  !agent && (foreground.length === 0 || SHELLS.has(programOf(foreground[0])))
+
 /**
  * The coordinator's pane: the agent herdr lists under the coordinator's name, else the calling pane when an agent
  * in the main checkout runs there, else the only agent in the main checkout. Two agents there and no name: none.
@@ -158,7 +176,8 @@ export const splitPaneOf = (json: string): string => {
 }
 
 /**
- * What one view needs in the tab of `anchor`: nothing when a pane there shows it, a run in a free shell whose
+ * What one view needs in the tab of `anchor`: nothing when a pane there shows it, a run in the pane without an agent
+ * that carries the view's name (restored by herdr, its shell may still be starting), else in a free shell whose
  * directory `isHome` accepts (the pane the view ran in before a restart), else a split of the anchor pane.
  */
 const actionFor = (
@@ -170,7 +189,8 @@ const actionFor = (
 ): PaneAction | null => {
   const tab = panes.filter((each) => each.tab === anchor.tab)
   if (tab.some((each) => isPlanView(each.foreground, lane))) return null
-  const free = tab.find((each) => isHome(each.cwd) && isIdleShell(each))
+  const named = tab.find((each) => each.label === herdLabel(lane) && isStartingShell(each))
+  const free = named ?? tab.find((each) => isHome(each.cwd) && isIdleShell(each))
   return free ? { kind: 'run', pane: free.pane, command } : { kind: 'split', pane: anchor.pane, command }
 }
 

package/src/plans/snapshot.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
 import type { ContextReading } from '../context'
+import { ASSISTANT_ENTRY_MARK } from '../context/log-vocabulary'
 import { coordinatorSettings } from '../context/options'
 import { type AgentLogReader, contextOfAgent } from '../context/report'
 import { agentLog, defaultProjectsDirectory } from '../context/session-log'
@@ -25,6 +26,7 @@ import type { SourceTicket, WatchBadges, WatchHealth } from '../watch/plan-badge
 import { readWatchReading } from '../watch/plan-badges-read'
 import type { SourceStatus } from '../watch/source-statuses'
 import { assignSignals, laneOfDirectory, type UnplannedTask } from './active-tasks'
+import { activityLineOf, type LaneSubagents } from './activity-read'
 import { type BoardRowsReader, boardRowsOf } from './board-rows'
 import { type CoordinatorView, coordinatorAgentOf, coordinatorTaskOf } from './coordinator-row'
 import {
@@ -70,7 +72,6 @@ import { createSliceGate, type SliceGate } from './slice-gate'
 import { withSourcePrefix } from './source-prefix'
 import type { HerdSource, SourceBlock } from './source-rows'
 import { type KeptStatus, logMark, pacedStatus, type WorktreeStatus } from './status-pace'
-import type { SubagentActivity } from './subagents'
 import { readSubagentActivitySliced, subagentSourceOf } from './subagents-read'
 import { boardTexts } from './texts'
 import { type UnlistedLane, unlistedLanes, unlistedSprintLane } from './unlisted-lanes'
@@ -91,7 +92,7 @@ export type Source = {
   /** The log lines of an agent's chat, null without one; defaults to reading them from `~/.claude/projects`. */
   readAgentLog?: AgentLogReader
   /** The worktrees subagents of the coordinator work in; defaults to reading them from `~/.claude/projects`. */
-  readSubagents?: (root: string, worktreeDirectory: string) => Map<string, SubagentActivity>
+  readSubagents?: (root: string, worktreeDirectory: string) => Map<string, LaneSubagents>
   /** What agents report doing (Claude's task lists, `jh task`); defaults to reading `~/.claude/projects` and `.jackherd/tasks/`. */
   readSignals?: (root: string, worktreeDirectory: string, now: number) => TaskSignal[]
 }
@@ -152,7 +153,7 @@ type LaneSources = {
   sprintDirectory: string
   agents: LaneAgent[]
   /** What subagents of the coordinator do in each worktree; a herdr agent in the worktree comes first. */
-  subagents: Map<string, SubagentActivity>
+  subagents: Map<string, LaneSubagents>
   /** The agents' log reader, asking once per agent however often the read is used in one snapshot. */
   readLog: AgentLogReader
   pullRequests: PullRequestState
@@ -200,9 +201,6 @@ type Decorations = {
   restNoteOf: (lane: string) => string | null
 }
 
-/** What every answer line of a session log holds; the fill is read from answers only. */
-const ANSWER_MARK = '"type":"assistant"'
-
 const answerLines = new WeakMap<readonly string[], string[]>()
 
 /**
@@ -212,7 +210,7 @@ const answerLines = new WeakMap<readonly string[], string[]>()
 const answerLinesOf = (lines: readonly string[]): string[] => {
   const kept = answerLines.get(lines)
   if (kept) return kept
-  const found = lines.filter((line) => line.includes(ANSWER_MARK))
+  const found = lines.filter((line) => line.includes(ASSISTANT_ENTRY_MARK))
   answerLines.set(lines, found)
   return found
 }
@@ -263,6 +261,17 @@ const pacedGitStatus = (sources: LaneSources, name: string, agent: LaneAgent | u
   return pacedStatus(statuses, { worktree, stamp: worktreeStamp(worktree, activity), now }, read)
 }
 
+/**
+ * The last action of a lane's agent and of its running subagents, from the logs read for the lane anyway; absent
+ * while neither has one, so a lane without a source shows nothing.
+ */
+const activityOf = (sources: LaneSources, name: string, agent: LaneAgent | undefined): Pick<LaneView, 'activity'> => {
+  const lines = agent ? sources.readLog(agent) : null
+  const lane = lines ? activityLineOf(lines) : null
+  const subagents = sources.subagents.get(name)?.lines ?? []
+  return lane === null && subagents.length === 0 ? {} : { activity: { lane, subagents } }
+}
+
 /** What a lane's worktree and agent say, listed in the sprint or not: git state, pull requests, context. */
 const runningState = async (sources: LaneSources, name: string, agent: LaneAgent | undefined) => {
   const { source, pullRequests } = sources
@@ -275,6 +284,7 @@ const runningState = async (sources: LaneSources, name: string, agent: LaneAgent
       status: { agent: agent?.status ?? subagent?.status ?? null, ...gitStatus },
       pullRequests: gitStatus.branch ? (pullRequests.byBranch.get(gitStatus.branch) ?? []) : [],
       context: contextOf(agent, source, sources.readLog),
+      ...activityOf(sources, name, agent),
     },
   }
 }
@@ -462,7 +472,7 @@ const readSubagents = async (
   { root, settings, readSubagents: read }: Source,
   worktrees: string,
   gate: SliceGate,
-): Promise<Map<string, SubagentActivity>> => {
+): Promise<Map<string, LaneSubagents>> => {
   try {
     if (read) return read(root, worktrees)
     return await readSubagentActivitySliced(subagentSourceOf(root, worktrees, settings.skillPrefix), gate.pass)

package/src/plans/subagents-read.ts

@@ -6,11 +6,11 @@ import { boundedMemo } from '../shared/bounded-memo'
 import { stampOf } from '../shared/stat-cache'
 import { DEFAULT_SKILL_PREFIX } from '../sync/init'
 import { readApprovalRequests } from '../watch/approvals'
+import { type LaneSubagents, withSubagentLines } from './activity-read'
 import {
   type RunningSubagent,
   runningSubagents,
   SUBAGENT_STALE_MINUTES,
-  type SubagentActivity,
   type SubagentLog,
   subagentsByLane,
 } from './subagents'
@@ -174,11 +174,12 @@ export const readSubagentActivitySliced = async (
   source: SubagentSource,
   pass: () => Promise<void>,
   now: number = Date.now(),
-): Promise<Map<string, SubagentActivity>> => {
+): Promise<Map<string, LaneSubagents>> => {
   const logs: SubagentLog[] = []
   for (const directory of allSessionDirectories(source.projects, source.root, now, source.worktreeDirectory)) {
     await pass()
     logs.push(...logsInSession(directory, now))
   }
-  return subagentsByLane(runningOf(logs, source, now), source.worktreeDirectory)
+  const running = runningOf(logs, source, now)
+  return withSubagentLines(subagentsByLane(running, source.worktreeDirectory), running, logs, source.worktreeDirectory)
 }

package/src/plans/subagents.ts

@@ -1,3 +1,4 @@
+import { CONTENT_BLOCK_TYPE } from '../context/log-vocabulary'
 import { keptLogEntry } from '../context/session-log'
 import { MS_PER_MINUTE } from '../plan-format/clock'
 import { terminalSafe } from '../plan-format/terminal-text'
@@ -64,7 +65,7 @@ const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/
 const toolCallTexts = (entry: Record<string, unknown>): string[] => {
   const content = isRecord(entry.message) && Array.isArray(entry.message.content) ? entry.message.content : []
   return content.flatMap((block) => {
-    if (!isRecord(block) || block.type !== 'tool_use' || !isRecord(block.input)) return []
+    if (!isRecord(block) || block.type !== CONTENT_BLOCK_TYPE.toolUse || !isRecord(block.input)) return []
     return [block.input.file_path, block.input.path, block.input.command].filter(
       (value): value is string => typeof value === 'string',
     )

package/src/plans/texts.ts

@@ -88,6 +88,8 @@ export type PlanTexts = {
   phaseTally: (done: number, total: number) => string
   herd: HerdTexts
   checks: Record<ChecksState, string>
+  /** Behind a folded lane's badge of a draft, in place of its check state. */
+  foldedDraft: string
   hint: string
   /** The help behind `?`: marks and keys with their meaning; the rules behind them stand in the README. */
   legend: LegendSection[]
@@ -186,9 +188,10 @@ export const TEXTS: PlanTexts = {
   checks: {
     [CHECKS.passed]: '✓ checks',
     [CHECKS.failed]: '✗ checks',
-    [CHECKS.pending]: '… checks',
+    [CHECKS.pending]: 'checks running',
     [CHECKS.none]: 'no checks',
   },
+  foldedDraft: 'draft',
   hint: '↑↓ select  →← open  s html  q quit  ? help',
   legend: [
     {
@@ -302,6 +305,29 @@ export const laneMarkText = (lane: { unlisted?: boolean }): string | null => (la
 /** The most red checks the checks column names; the rest is counted. */
 export const NAMED_CHECKS = 3
 
+/** The most characters of the red check a folded lane's badge names; a longer name ends in `…`. */
+export const FOLDED_CHECK_NAME_LENGTH = 8
+
+const cutCheckName = (name: string): string =>
+  name.length > FOLDED_CHECK_NAME_LENGTH ? `${name.slice(0, FOLDED_CHECK_NAME_LENGTH - 1)}…` : name
+
+/**
+ * The check state behind a folded lane's pull request badge, in the words of `TEXTS.checks` (`✓ checks`,
+ * `checks running`): `✗ test +1` names the first red check, cut to `FOLDED_CHECK_NAME_LENGTH`, and counts the others;
+ * nothing without checks, and `draft` for a draft, whose checks were mostly skipped.
+ */
+export const foldedChecksText = ({
+  checks,
+  failedChecks,
+  draft,
+}: Pick<PullRequest, 'checks' | 'failedChecks' | 'draft'>): string => {
+  if (draft) return TEXTS.foldedDraft
+  if (checks === CHECKS.none) return ''
+  const [first, ...rest] = failedChecks
+  if (checks !== CHECKS.failed || first === undefined) return TEXTS.checks[checks]
+  return `✗ ${cutCheckName(first)}${rest.length > 0 ? ` +${rest.length}` : ''}`
+}
+
 /**
  * The words of a pull request's check state: `✗ test, lint` names the red checks (at most `NAMED_CHECKS`, then
  * `+<n>`), every other state and a red one without names is the fixed word of `PLAN_TEXTS.checks`.

package/src/settled/send.ts

@@ -1,17 +1,80 @@
+import { z } from 'zod'
 import { TERMINAL_ADAPTER, type TerminalAdapter } from '../config'
 import { errorText } from '../plans/error-text'
-import type { HerdrRunner } from '../terminal/herdr'
+import { parseJsonOrNull } from '../shared/parse-json'
+import type { HerdrAsyncRunner, HerdrRunner } from '../terminal/herdr'
+import { AGENT_STATUS } from '../terminal/types'
 
 /** Hands a text to a lane's agent; returns the error text, or null when the agent took it. */
 export type LaneSender = (lane: string, message: string) => string | null
 
+/** As `LaneSender`, for a caller that must not hold the event loop while herdr answers. */
+export type AsyncLaneSender = (lane: string, message: string) => Promise<string | null>
+
+/** How long herdr itself waits for a working state before it reports `agent_prompt_stalled`. */
+export const HERDR_STALL_WINDOW_MS = 5_000
+
+/** Longer than herdr's own stall window, so a stalled paste is reported as stalled and not as a timeout. */
+export const PROMPT_CONFIRM_TIMEOUT_MS = 10_000
+
+/** The error codes of `herdr agent prompt --wait` that mean the agent never started working. */
+const HERDR_PROMPT_ERROR = { stalled: 'agent_prompt_stalled', timeout: 'timeout' } as const
+
+const herdrErrorSchema = z
+  .object({ error: z.object({ code: z.string(), message: z.string().optional() }).loose() })
+  .loose()
+
+type HerdrError = z.infer<typeof herdrErrorSchema>['error']
+
+/** What came before herdr's JSON (the command's name), and the error in it. */
+type ParsedHerdrError = { prefix: string; error: HerdrError }
+
+const notWorking = (reason: string): string => `the agent did not start working after the prompt (${reason})`
+
+const PROMPT_FAILURE_TEXT: Record<string, string> = {
+  [HERDR_PROMPT_ERROR.stalled]: notWorking(
+    `herdr: the text sits as a paste, nothing happened within ${HERDR_STALL_WINDOW_MS / 1000} s`,
+  ),
+  [HERDR_PROMPT_ERROR.timeout]: notWorking(`herdr: no working state within ${PROMPT_CONFIRM_TIMEOUT_MS / 1000} s`),
+}
+
+const NO_TERMINAL = `no terminal to reach the lane (terminal.adapter is ${TERMINAL_ADAPTER.none})`
+
 /**
  * `herdr agent prompt <lane> <text>`, the way the coordinator prompts a lane: the text as one argument of the
  * process, so no shell expands its backticks or `$(…)`.
  */
-export const promptArguments = (lane: string, message: string): string[] => ['agent', 'prompt', lane, message]
+export const promptArguments = (lane: string, message: string): string[] => [
+  'agent',
+  'prompt',
+  lane,
+  message,
+  '--wait',
+  '--until',
+  AGENT_STATUS.working,
+  '--timeout',
+  String(PROMPT_CONFIRM_TIMEOUT_MS),
+]
 
-const NO_TERMINAL = `no terminal to reach the lane (terminal.adapter is ${TERMINAL_ADAPTER.none})`
+/** The `{"error": …}` herdr prints after the command's name, or null for any other text. */
+const herdrErrorOf = (text: string): ParsedHerdrError | null => {
+  const start = text.indexOf('{')
+  const parsed = start < 0 ? null : herdrErrorSchema.safeParse(parseJsonOrNull(text.slice(start)))
+  if (!parsed?.success) return null
+  return { prefix: text.slice(0, start).replace(/:\s*$/, ''), error: parsed.data.error }
+}
+
+const unknownFailureText = ({ prefix, error }: ParsedHerdrError): string =>
+  [prefix, error.code, error.message].filter((part) => part !== undefined && part !== '').join(': ')
+
+/** Turns the text of a failed `herdr agent prompt` into one that says what happened; unknown text stays as it is. */
+export const promptFailureText = (text: string): string => {
+  const parsed = herdrErrorOf(text)
+  if (parsed === null) return text
+  return PROMPT_FAILURE_TEXT[parsed.error.code] ?? unknownFailureText(parsed)
+}
+
+const sendFailureText = (error: unknown): string => promptFailureText(errorText(error))
 
 /** The sender for the configured terminal; without one (`none`) every send fails with the reason. */
 export const laneSenderFor =
@@ -22,6 +85,19 @@ export const laneSenderFor =
       run(promptArguments(lane, message))
       return null
     } catch (error) {
-      return errorText(error)
+      return sendFailureText(error)
+    }
+  }
+
+/** As `laneSenderFor`, awaiting herdr instead of holding the event loop for up to `PROMPT_CONFIRM_TIMEOUT_MS`. */
+export const laneSenderForAsync =
+  (adapter: TerminalAdapter, run: HerdrAsyncRunner): AsyncLaneSender =>
+  async (lane, message) => {
+    if (adapter === TERMINAL_ADAPTER.none) return NO_TERMINAL
+    try {
+      await run(promptArguments(lane, message))
+      return null
+    } catch (error) {
+      return sendFailureText(error)
     }
   }

package/src/shared/parse-json.ts

@@ -0,0 +1,8 @@
+/** The parsed value of `text`, or null when it is not JSON. */
+export const parseJsonOrNull = (text: string): unknown => {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}

package/src/sync/command.ts

@@ -11,8 +11,9 @@ import {
   usageError,
 } from './command-context'
 import { errorMessage } from './error-message'
+import { readForeignSkills } from './foreign-skills'
 import { dailyUpdateNotice, defaultUpdateCheck, lockedVersion, syncNeeded, type UpdateCheck } from './if-changed'
-import { SYNC_EXIT } from './report'
+import { foreignSkillLines, SYNC_EXIT } from './report'
 import { migrateGlobalSettings } from './settings-migration'
 import { runGlobalSync, runSync } from './sync'
 
@@ -101,6 +102,20 @@ const syncGlobalIfChanged = async (context: CommandContext, accept: string[], ch
   return exitCode
 }
 
+const syncProject = (context: CommandContext, accept: string[], dryRun: boolean): Promise<number> =>
+  runWithKit(
+    context,
+    'sync',
+    async (kit) => {
+      const result = await runSync({ projectRoot: context.projectRoot, home: context.home, kit, accept, check: dryRun })
+      const foreignLines = foreignSkillLines(result, readForeignSkills(context.projectRoot))
+      const foreign = foreignLines.length > 0 ? [foreignLines.join('\n')] : []
+      const dryRunNote = dryRun ? [`${CLI_NAME} sync ${CHECK_FLAG}: nothing is written`] : []
+      return { notes: [...dryRunNote, ...foreign], result }
+    },
+    dryRun,
+  )
+
 export const runSyncCommand = async (
   args: string[],
   context: CommandContext = defaultContext(),
@@ -113,15 +128,7 @@ export const runSyncCommand = async (
   if (global) return syncGlobal(context, accept)
   if (isConfigWithoutInstall(context.projectRoot, existsSync))
     return usageError(context, notInstalledLine(context.projectRoot))
-  return runWithKit(
-    context,
-    'sync',
-    async (kit) => ({
-      notes: dryRun ? [`${CLI_NAME} sync ${CHECK_FLAG}: nothing is written`] : [],
-      result: await runSync({ projectRoot: context.projectRoot, home: context.home, kit, accept, check: dryRun }),
-    }),
-    dryRun,
-  )
+  return syncProject(context, accept, dryRun)
 }
 
 export const run = (args: string[]): Promise<number> => runSyncCommand(args)

package/src/sync/foreign-skills.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { z } from 'zod'
+import { SKILLS_DIRECTORY } from '../claude/paths'
+
+/** Written by `npx skills add` into the project root; only the skill names are read. */
+export const SKILLS_LOCK_FILE = 'skills-lock.json'
+
+const skillsLockSchema = z.object({ skills: z.record(z.string(), z.unknown()) }).loose()
+
+const SKILL_ENTRY_FILE = 'SKILL.md'
+const SKILL_ENTRY = new RegExp(`(?:^|/)${SKILLS_DIRECTORY}/([^/]+)/${SKILL_ENTRY_FILE.replace('.', '\\.')}$`)
+
+/** The kit path (relative to `.claude/`) of a skill's entry file. */
+export const skillEntryPath = (name: string): string => `${SKILLS_DIRECTORY}/${name}/${SKILL_ENTRY_FILE}`
+
+/** The skill an entry file path belongs to, from a kit path or a project path; undefined for any other file. */
+export const skillNameOfEntry = (path: string): string | undefined => SKILL_ENTRY.exec(path)?.[1]
+
+/** The skill names `skills-lock.json` lists; anything that is not that file's shape is the empty set. */
+export const parseForeignSkills = (value: unknown): ReadonlySet<string> => {
+  const parsed = skillsLockSchema.safeParse(value)
+  return new Set(parsed.success ? Object.keys(parsed.data.skills) : [])
+}
+
+/** The foreign skills of a project: the empty set when the lock file is missing, unreadable or invalid. */
+export const readForeignSkills = (root: string): ReadonlySet<string> => {
+  try {
+    return parseForeignSkills(JSON.parse(readFileSync(join(root, SKILLS_LOCK_FILE), 'utf8')))
+  } catch {
+    return new Set()
+  }
+}
+
+/** Of the kit paths (relative to `.claude/`), the names of the skills whose entry file a foreign skill sits on. */
+export const foreignSkillNamesOf = (kitPaths: readonly string[], foreign: ReadonlySet<string>): string[] =>
+  kitPaths.flatMap((path) => {
+    const name = skillNameOfEntry(path)
+    return name !== undefined && foreign.has(name) ? [name] : []
+  })