@miadi/tide 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -55,20 +55,27 @@ prompt for a human to review and submit. `buildSendKeysPlan(...)` returns the ex
55
55
  pair without executing — used for the cockpit's inline command preview. The tmux binary is
56
56
  resolved via `TIDE_TMUX_BIN` -> `tmux` on `PATH`.
57
57
 
58
- ### herdr transport — `multiplexer: "herdr"` (unverified-live)
58
+ ### herdr transport — `multiplexer: "herdr"` (live-verified)
59
59
 
60
60
  `sendKeys(pane, message, { multiplexer: "herdr" })` dispatches to the herdr CLI transport
61
61
  (`src/herdr.ts`): `herdr pane send-text` types the text, `herdr pane send-keys … Enter` submits
62
62
  (`submit: false` skips it, same toggle as tmux). The result is the herdr variant of the
63
63
  `TideSendKeysResult` union from `@miadi/tide-contract` (`multiplexer: "herdr"`, herdr CLI argv).
64
- herdr pane ids (`"1-2"`) are compact and **non-durable** — pass `paneLabel` and the client
65
- re-resolves label → current id via `herdr pane list` before **every** action. Additional verbs:
66
- `runInHerdrPane`, `readHerdrPane` (recent-unwrapped text), `waitForHerdrOutput`,
67
- `waitForHerdrAgentStatus`, `listHerdrPanes/Workspaces/Tabs`. Binary resolution:
64
+ herdr pane ids (`"w1:p2"` as of herdr 0.7; legacy `"1-2"` accepted) are **session-scoped** —
65
+ they reset on herdr restart, and a stale id fails loudly with `pane_not_found`. Pass `paneLabel`
66
+ (set via `herdr pane rename`) and the client re-resolves label → current id via
67
+ `herdr pane list` before **every** action; duplicate labels throw rather than guess. Additional
68
+ verbs: `runInHerdrPane`, `readHerdrPane` (recent-unwrapped text), `renameHerdrPane` (sets the
69
+ durable label), `waitForHerdrOutput` (typed `TideHerdrWaitOutputResult`),
70
+ `waitForHerdrAgentStatus` (typed `TideHerdrAgentStatusEvent` — live hits print an event
71
+ envelope), `listHerdrPanes/Workspaces/Tabs`. `peek(pane, lines, { multiplexer: "herdr" })`
72
+ reads herdr scrollback through the stable peek verb. Binary resolution:
68
73
  `TIDE_HERDR_BIN` → `herdr` on `PATH`.
69
74
 
70
- > **Readiness: `unverified-live`.** The herdr transport is proven against injected command
71
- > runners in `test/herdr.test.ts` only; no live smoke inside a herdr instance has run yet.
75
+ > **Readiness: `live-verified`.** Smoked against a real herdr 0.7.4 instance (EP137
76
+ > herdr-smoke lane, 2026-07-16) — inventory parsing, send-text/send-keys, pane run, read,
77
+ > wait output (hit + timeout exit codes), agent-status, and label→id resolution — in
78
+ > addition to the injected-runner tests in `test/herdr.test.ts`.
72
79
 
73
80
  `getTerminals` and `detect` are the read-only surface behind `GET /api/tide/terminals`
74
81
  and `GET /api/tide/detect` — the typed half of operator-terminal triage and manual
@@ -81,7 +88,7 @@ is deferred to the runtime + a guarded route.
81
88
  |---|---|
82
89
  | One-shot CLI (`tide … --format json`, `execFile` arg-arrays, no shell) | **implemented** |
83
90
  | Daemon + Unix-domain-socket transport (`miadi.tide.daemon.v2`) | **implemented** (`src/socket.ts`) |
84
- | herdr CLI transport (`src/herdr.ts`, `multiplexer: "herdr"`) | **unverified-live** (runner-mocked tests only) |
91
+ | herdr CLI transport (`src/herdr.ts`, `multiplexer: "herdr"`) | **live-verified** (herdr 0.7.4, EP137 smoke + runner-mocked tests) |
85
92
  | Schema-first contract (`tide-api.schema.json` → generated types) | planned |
86
93
 
87
94
  ### How transport selection works
@@ -110,11 +117,13 @@ Newline-delimited JSON over a Unix socket. Request
110
117
  (mirrors the runtime's `get_config_dir()`). Binary resolution for the CLI fallback:
111
118
  `TIDE_BIN` → `which tide` → legacy `/home/jgi/anaconda3/bin/tide`.
112
119
 
113
- ## Operator-cockpit surface (next)
120
+ ## Operator-cockpit surface
114
121
 
115
- `describeTransport()` + `pingDaemon()` are the building blocks for a `GET /api/tide/health`
116
- endpoint so a Hermes/Ava/Miadi session can see *which transport is live and whether the daemon is
117
- answering* before it reads context or proposes a steer. See the foundations plan.
122
+ `describeTransport()` + `pingDaemon()` back the shipped `GET /api/tide/health` route, so a
123
+ Hermes/Ava/Miadi session can see *which transport is live and whether the daemon is answering*
124
+ before it reads context or proposes a steer. The cockpit routes (`steer`, `peek`, `detect`,
125
+ `terminals`) are still tmux-only — herdr reachability from `/api/tide/*` is tracked in
126
+ jgwill/Miadi#494.
118
127
 
119
128
  ## Tests
120
129
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miadi/tide",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "Typed client boundary for the ironsilk `tide` runtime. Daemon Unix-socket transport with CLI fallback.",
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -15,7 +15,7 @@
15
15
  "src"
16
16
  ],
17
17
  "dependencies": {
18
- "@miadi/tide-contract": "0.2.0"
18
+ "@miadi/tide-contract": "0.2.2"
19
19
  },
20
20
  "scripts": {
21
21
  "test": "d=$(mktemp -d \"${TMPDIR:-/tmp}/miadi-tide-test.XXXXXX\") && trap 'rm -rf \"$d\"' EXIT && ../../node_modules/.bin/tsc -p tsconfig.test.json --outDir \"$d\" && node --test \"$d\"/packages/tide/test/*.test.js"
package/src/client.ts CHANGED
@@ -41,7 +41,7 @@ import {
41
41
  TideDaemonError,
42
42
  } from "./socket"
43
43
  import { TideError } from "./errors"
44
- import { sendKeysViaHerdr } from "./herdr"
44
+ import { HERDR_PANE_ID_PATTERN, buildHerdrSendKeysPlan, readHerdrPane, sendKeysViaHerdr } from "./herdr"
45
45
  import type { HerdrCommandRunner } from "./herdr"
46
46
 
47
47
  const pExecFile = promisify(execFile)
@@ -204,8 +204,26 @@ export function detect(opts: DetectOptions = {}): Promise<TideDetectResult> {
204
204
  return runTideJson<TideDetectResult>(args, { timeoutMs: 8_000, ...opts })
205
205
  }
206
206
 
207
- /** Operator cockpit — read scrollback for a pane without attaching. `pane` is the numeric index (no `%`). */
208
- export function peek(pane: string, lines = 30, opts?: TideRunOptions): Promise<TidePeekResult> {
207
+ export interface PeekOptions extends TideRunOptions {
208
+ /** Absent or "tmux" keeps the historical tide-runtime peek; "herdr" reads via `herdr pane read`. */
209
+ multiplexer?: Multiplexer
210
+ /** herdr only: durable pane label, re-resolved to the current pane id at action time. */
211
+ paneLabel?: string
212
+ /** herdr only: injected command runner (tests). */
213
+ runner?: HerdrCommandRunner
214
+ }
215
+
216
+ /**
217
+ * Operator cockpit — read scrollback for a pane without attaching. tmux path:
218
+ * `pane` is the numeric index (no `%`). herdr path (`multiplexer: "herdr"`):
219
+ * `pane` is a herdr pane id (or pass `paneLabel`), and the recent-unwrapped
220
+ * text comes back split into `lines`.
221
+ */
222
+ export async function peek(pane: string, lines = 30, opts: PeekOptions = {}): Promise<TidePeekResult> {
223
+ if (opts.multiplexer === "herdr") {
224
+ const text = await readHerdrPane(pane, lines, opts)
225
+ return { multiplexer: "herdr", pane, lines: text.split("\n"), text }
226
+ }
209
227
  return runTideJson<TidePeekResult>(
210
228
  ["operator", "peek", `%${pane}`, "--lines", String(lines), "--format", "json"],
211
229
  { timeoutMs: 8_000, ...opts },
@@ -267,12 +285,12 @@ export interface SendKeysOptions extends TideRunOptions {
267
285
  /**
268
286
  * Terminal multiplexer to drive. Absent or "tmux" keeps the historical
269
287
  * direct `tmux send-keys` path unchanged; "herdr" dispatches to the herdr
270
- * CLI transport (herdr.ts — READINESS: unverified-live).
288
+ * CLI transport (herdr.ts — READINESS: live-verified on herdr 0.7.4).
271
289
  */
272
290
  multiplexer?: Multiplexer
273
291
  /**
274
292
  * herdr only: durable pane label, re-resolved to the current pane id at
275
- * action time (herdr ids are compact and non-durable).
293
+ * action time (herdr ids are session-scoped and reset on herdr restart).
276
294
  */
277
295
  paneLabel?: string
278
296
  /** herdr only: injected command runner (tests). */
@@ -320,6 +338,13 @@ export async function sendKeys(
320
338
  if (opts.multiplexer === "herdr") {
321
339
  return sendKeysViaHerdr(pane, message, opts)
322
340
  }
341
+ // herdr-only options on the tmux path would silently steer the raw tmux
342
+ // pane — the wrong-pane hazard labels exist to prevent. Fail loudly instead.
343
+ if (opts.paneLabel !== undefined || opts.runner !== undefined) {
344
+ throw new TideError(
345
+ `sendKeys: "paneLabel"/"runner" are herdr-only options — pass multiplexer: "herdr"`,
346
+ )
347
+ }
323
348
  const submit = opts.submit ?? true
324
349
  const plan = buildSendKeysPlan(pane, message, submit)
325
350
  const bin = resolveTmuxBin()
@@ -465,13 +490,21 @@ export async function listPendingApprovals(
465
490
  }
466
491
  }
467
492
 
468
- /** Build a steer plan with lane context (wraps buildSendKeysPlan, adds lane_id). */
493
+ /**
494
+ * Build a steer plan with lane context (adds lane_id). Dispatches on the
495
+ * pane-target format: contract-legal herdr targets like "w1:p2" (see
496
+ * `EpisodeLane.pane_target`) get a herdr plan — the tmux normalizer would
497
+ * otherwise mangle them into garbage like "%w1:p2". The two id grammars are
498
+ * disjoint (tmux: `%?digits`), so format detection is unambiguous.
499
+ */
469
500
  export function buildEpisodeSteerPlan(
470
501
  laneId: string,
471
502
  pane: string,
472
503
  message: string,
473
504
  submit = true,
474
- ): ReturnType<typeof buildSendKeysPlan> & { lane_id: string } {
475
- const plan = buildSendKeysPlan(pane, message, submit)
505
+ ): TideSendKeysResult & { lane_id: string } {
506
+ const plan = HERDR_PANE_ID_PATTERN.test(pane.trim())
507
+ ? buildHerdrSendKeysPlan(pane, message, submit)
508
+ : buildSendKeysPlan(pane, message, submit)
476
509
  return { ...plan, lane_id: laneId }
477
510
  }
package/src/herdr.ts CHANGED
@@ -14,18 +14,29 @@
14
14
  // wait agent-status <id> --status … --timeout ms (JSON)
15
15
  // workspace list | tab list --workspace <id> | pane list (JSON)
16
16
  //
17
- // herdr pane ids ("1-2") are compact and NON-DURABLE — they can change when
18
- // panes, tabs, or workspaces close. Every action therefore re-resolves
19
- // `paneLabel` → current pane id at action time (never cached) when a label is
20
- // provided.
17
+ // herdr pane ids are "w<N>:p<M>" (e.g. "w1:p2") as of herdr 0.7; the legacy
18
+ // dashed "1-2" form is still accepted for older releases. Live smoke against
19
+ // herdr 0.7.4 (EP137) showed ids are monotonic within a session — they do NOT
20
+ // compact or get reused when panes close, and a stale id fails loudly with
21
+ // {"error":{"code":"pane_not_found"}}. They are still session-scoped (a herdr
22
+ // restart resets them), so every action re-resolves `paneLabel` → current pane
23
+ // id at action time (never cached) when a label is provided; `pane rename`
24
+ // sets the `label` field that resolution matches on.
21
25
  //
22
- // READINESS: unverified-live — exercised against injected runners in
23
- // test/herdr.test.ts only; no live smoke inside a herdr instance has run yet.
26
+ // READINESS: live-verified — smoked against a real herdr 0.7.4 instance
27
+ // (EP137 herdr-smoke lane, 2026-07-16) in addition to the injected-runner
28
+ // tests in test/herdr.test.ts.
24
29
 
25
30
  import { execFile } from "node:child_process"
26
31
  import { promisify } from "node:util"
27
32
 
28
- import type { TideAgentStatus, TideHerdrSendKeysResult } from "@miadi/tide-contract"
33
+ import type {
34
+ TideAgentStatus,
35
+ TideHerdrAgentStatusEvent,
36
+ TideHerdrPaneInfo,
37
+ TideHerdrSendKeysResult,
38
+ TideHerdrWaitOutputResult,
39
+ } from "@miadi/tide-contract"
29
40
  import { TideError } from "./errors"
30
41
  import type { TideRunOptions } from "./client"
31
42
 
@@ -64,14 +75,40 @@ function makeRunner(opts: HerdrRunOptions): HerdrCommandRunner {
64
75
  }
65
76
  }
66
77
 
78
+ /**
79
+ * Detail line for a failed runner call WITHOUT echoing argv values: node's
80
+ * execFile error message embeds the full command line ("Command failed: herdr
81
+ * pane send-text <id> <text> …") — the very values these TideError messages
82
+ * redact (live EP137 finding; mocks never hit this because injected errors
83
+ * carry custom messages). Prefer the child's stderr (herdr's own diagnostic,
84
+ * e.g. its {"error":…} JSON), then the message with any "Command failed: …"
85
+ * line stripped, then exit metadata.
86
+ */
87
+ function describeRunnerError(err: unknown): string {
88
+ const e = err as Partial<{ stderr: unknown; code: unknown; signal: unknown }> | null
89
+ const stderr = typeof e?.stderr === "string" ? e.stderr.trim() : ""
90
+ if (stderr) return stderr
91
+ const raw = err instanceof Error ? err.message : String(err)
92
+ // A "Command failed:" message embeds the full argv — possibly across several
93
+ // lines when the steered text contains newlines — so discard it entirely
94
+ // rather than stripping just the first line.
95
+ const stripped = raw.startsWith("Command failed:") ? "" : raw.trim()
96
+ if (stripped) return stripped
97
+ const meta = [
98
+ e?.code != null ? `exit code ${String(e.code)}` : null,
99
+ typeof e?.signal === "string" && e.signal ? `killed by ${e.signal}` : null,
100
+ ].filter(Boolean)
101
+ return meta.length ? meta.join(", ") : "command failed"
102
+ }
103
+
67
104
  /** Run one herdr CLI command, wrapping failures in TideError. */
68
105
  async function runHerdr(args: string[], opts: HerdrRunOptions): Promise<HerdrCommandResult> {
69
106
  const runner = makeRunner(opts)
70
107
  try {
71
108
  return await runner(resolveHerdrBin(), args)
72
109
  } catch (err) {
73
- const msg = err instanceof Error ? err.message : String(err)
74
- throw new TideError(`herdr ${args.join(" ")} failed: ${msg}`, err)
110
+ const verb = args.length >= 2 ? `${args[0]} ${args[1]}` : "operation"
111
+ throw new TideError(`herdr ${verb} failed: ${describeRunnerError(err)}`, err)
75
112
  }
76
113
  }
77
114
 
@@ -85,27 +122,27 @@ function parseHerdrJson<T>(stdout: string, what: string): T {
85
122
 
86
123
  // ── Pane targets and label→id resolution ────────────────────────────────────
87
124
 
88
- export const HERDR_PANE_ID_PATTERN = /^[0-9]+-[0-9]+$/
125
+ // "w1:p2" is the live herdr 0.7 format; the dashed "1-2" form is legacy.
126
+ export const HERDR_PANE_ID_PATTERN = /^(w[0-9]+:p[0-9]+|[0-9]+-[0-9]+)$/
89
127
 
90
- /** Validate a herdr pane id (e.g. "1-2"). Unlike tmux there is no `%` prefix to add. */
128
+ /** Validate a herdr pane id (e.g. "w1:p2"). Unlike tmux there is no `%` prefix to add. */
91
129
  export function normalizeHerdrPaneTarget(pane: string): string {
92
130
  const trimmed = pane.trim()
93
131
  if (!HERDR_PANE_ID_PATTERN.test(trimmed)) {
94
132
  throw new TideError(
95
- `invalid herdr pane id "${pane}" (expected "<workspace>-<pane>", e.g. "1-2"); herdr ids are non-durable — pass paneLabel to resolve by label instead`,
133
+ `invalid herdr pane id "${pane}" (expected "w<workspace>:p<pane>", e.g. "w1:p2"); herdr ids are session-scoped — pass paneLabel to resolve by label instead`,
96
134
  )
97
135
  }
98
136
  return trimmed
99
137
  }
100
138
 
101
- /** One row from `herdr pane list`. Loosely typed pending a herdr JSON schema. */
102
- export interface HerdrPaneInfo {
103
- pane_id?: string
104
- label?: string
139
+ /**
140
+ * One row from `herdr pane list` — the covenant shape (tide-contract 0.2.2's
141
+ * `TideHerdrPaneInfo`) plus a `title` field tolerated for other herdr builds
142
+ * (live 0.7.4 rows never carry it; resolution matches it only as a fallback).
143
+ */
144
+ export interface HerdrPaneInfo extends TideHerdrPaneInfo {
105
145
  title?: string
106
- focused?: boolean
107
- agent_status?: TideAgentStatus | string
108
- [key: string]: unknown
109
146
  }
110
147
 
111
148
  export interface HerdrWorkspaceInfo {
@@ -156,13 +193,25 @@ export async function listHerdrTabs(workspace: string, opts: HerdrRunOptions = {
156
193
 
157
194
  /**
158
195
  * Resolve a durable pane label to the CURRENT herdr pane id via `pane list`.
159
- * Runs before every action when a label is given — herdr ids compact when
160
- * panes close, so a cached id may silently point at a different pane.
196
+ * Runs before every action when a label is given — herdr ids are
197
+ * session-scoped (a herdr restart resets them), so a cached id can go stale.
198
+ * Live 0.7.4: a stale id fails loudly with pane_not_found (ids are never
199
+ * reused within a session); `pane rename` sets the `label` field matched here.
161
200
  */
162
201
  export async function resolveHerdrPaneId(paneLabel: string, opts: HerdrRunOptions = {}): Promise<string> {
163
202
  const label = paneLabel.trim()
164
203
  const panes = await listHerdrPanes(opts)
165
- const match = panes.find((p) => p.label === label || p.title === label)
204
+ // Two passes: an explicit `pane rename` label always beats a title
205
+ // coincidence, regardless of pane order.
206
+ let matches = panes.filter((p) => p.label === label)
207
+ if (matches.length === 0) matches = panes.filter((p) => p.title === label)
208
+ if (matches.length > 1) {
209
+ const ids = matches.map((p) => p.pane_id ?? "?").join(", ")
210
+ throw new TideError(
211
+ `ambiguous herdr pane label "${label}" — matches panes ${ids}; rename panes to unique labels`,
212
+ )
213
+ }
214
+ const match = matches[0]
166
215
  if (!match?.pane_id) {
167
216
  throw new TideError(`no herdr pane labeled "${label}" in \`herdr pane list\``)
168
217
  }
@@ -191,17 +240,17 @@ export interface HerdrSendKeysOptions extends HerdrTargetOptions {
191
240
  }
192
241
 
193
242
  /**
194
- * Build the exact herdr CLI argv pair for a steer WITHOUT executing it. Pure —
195
- * the herdr counterpart of buildSendKeysPlan(). `pane` must already be a
196
- * resolved herdr pane id; label→id resolution happens in sendKeysViaHerdr().
243
+ * Assemble the steer plan for an ALREADY-TRUSTED target — no validation. Ids
244
+ * herdr itself just returned (label resolution) must pass through unchecked:
245
+ * re-validating them against HERDR_PANE_ID_PATTERN is the regression class
246
+ * that broke 0.2.0 when live 0.7 ids arrived.
197
247
  */
198
- export function buildHerdrSendKeysPlan(
199
- pane: string,
248
+ function makeHerdrSendKeysPlan(
249
+ target: string,
200
250
  message: string,
201
- submit = true,
251
+ submit: boolean,
202
252
  paneLabel?: string,
203
253
  ): TideHerdrSendKeysResult {
204
- const target = normalizeHerdrPaneTarget(pane)
205
254
  const plan: TideHerdrSendKeysResult = {
206
255
  multiplexer: "herdr",
207
256
  target,
@@ -214,6 +263,20 @@ export function buildHerdrSendKeysPlan(
214
263
  return plan
215
264
  }
216
265
 
266
+ /**
267
+ * Build the exact herdr CLI argv pair for a steer WITHOUT executing it. Pure —
268
+ * the herdr counterpart of buildSendKeysPlan(). `pane` is caller-supplied and
269
+ * therefore validated; label→id resolution happens in sendKeysViaHerdr().
270
+ */
271
+ export function buildHerdrSendKeysPlan(
272
+ pane: string,
273
+ message: string,
274
+ submit = true,
275
+ paneLabel?: string,
276
+ ): TideHerdrSendKeysResult {
277
+ return makeHerdrSendKeysPlan(normalizeHerdrPaneTarget(pane), message, submit, paneLabel)
278
+ }
279
+
217
280
  /**
218
281
  * Steer a herdr pane: type `message` via `herdr pane send-text`, then submit a
219
282
  * real Enter via `herdr pane send-keys … Enter` unless `submit: false`. Same
@@ -226,23 +289,25 @@ export async function sendKeysViaHerdr(
226
289
  message: string,
227
290
  opts: HerdrSendKeysOptions = {},
228
291
  ): Promise<TideHerdrSendKeysResult> {
292
+ // resolveTarget validates caller-supplied ids and trusts label-resolved ones.
229
293
  const target = await resolveTarget(pane, opts)
230
- const plan = buildHerdrSendKeysPlan(target, message, opts.submit ?? true, opts.paneLabel)
294
+ const plan = makeHerdrSendKeysPlan(target, message, opts.submit ?? true, opts.paneLabel)
231
295
  const runner = makeRunner(opts)
232
296
  const bin = resolveHerdrBin()
233
297
  try {
234
298
  await runner(bin, plan.literal_command)
235
299
  } catch (err) {
236
- const msg = err instanceof Error ? err.message : String(err)
237
- throw new TideError(`herdr pane send-text to ${plan.target} failed (typing literal text): ${msg}`, err)
300
+ throw new TideError(
301
+ `herdr pane send-text to ${plan.target} failed (typing literal text): ${describeRunnerError(err)}`,
302
+ err,
303
+ )
238
304
  }
239
305
  if (plan.submit_command) {
240
306
  try {
241
307
  await runner(bin, plan.submit_command)
242
308
  } catch (err) {
243
- const msg = err instanceof Error ? err.message : String(err)
244
309
  throw new TideError(
245
- `herdr pane send-keys to ${plan.target} failed (submitting Enter; literal text was typed but left unsubmitted): ${msg}`,
310
+ `herdr pane send-keys to ${plan.target} failed (submitting Enter; literal text was typed but left unsubmitted): ${describeRunnerError(err)}`,
246
311
  err,
247
312
  )
248
313
  }
@@ -252,6 +317,20 @@ export async function sendKeysViaHerdr(
252
317
 
253
318
  // ── Other transport verbs ───────────────────────────────────────────────────
254
319
 
320
+ /**
321
+ * `herdr pane rename <id> <label>` — set the durable label that label→id
322
+ * resolution matches. The one command the whole re-resolution design rests on:
323
+ * without a rename, live 0.7.4 pane rows carry no `label` field at all.
324
+ */
325
+ export async function renameHerdrPane(
326
+ pane: string,
327
+ label: string,
328
+ opts: HerdrTargetOptions = {},
329
+ ): Promise<void> {
330
+ const target = await resolveTarget(pane, opts)
331
+ await runHerdr(["pane", "rename", target, label], opts)
332
+ }
333
+
255
334
  /** `herdr pane run <id> <command>` — send the text and a real Enter in one request. */
256
335
  export async function runInHerdrPane(
257
336
  pane: string,
@@ -292,28 +371,39 @@ export async function waitForHerdrOutput(
292
371
  pane: string,
293
372
  match: string,
294
373
  opts: HerdrWaitOptions = {},
295
- ): Promise<unknown> {
374
+ ): Promise<TideHerdrWaitOutputResult> {
296
375
  const target = await resolveTarget(pane, opts)
297
376
  const waitMs = opts.waitTimeoutMs ?? 30_000
298
377
  const args = ["wait", "output", target, "--match", match]
299
378
  if (opts.regex) args.push("--regex")
300
379
  args.push("--timeout", String(waitMs))
301
- // Child-process timeout must outlive the herdr-side wait.
302
- const { stdout } = await runHerdr(args, { ...opts, timeoutMs: opts.timeoutMs ?? waitMs + 5_000 })
303
- return parseHerdrJson<unknown>(stdout, "wait output")
380
+ // Child-process timeout must outlive the herdr-side wait — even when the
381
+ // caller passed a smaller generic timeoutMs, which would otherwise SIGTERM
382
+ // herdr mid-wait.
383
+ const { stdout } = await runHerdr(args, {
384
+ ...opts,
385
+ timeoutMs: Math.max(opts.timeoutMs ?? 0, waitMs + 5_000),
386
+ })
387
+ return parseHerdrJson<TideHerdrWaitOutputResult>(stdout, "wait output")
304
388
  }
305
389
 
306
- /** `herdr wait agent-status <id> --status … --timeout …` — blocks until the agent reaches the status. JSON result. */
390
+ /**
391
+ * `herdr wait agent-status <id> --status … --timeout …` — blocks until the
392
+ * agent reaches the status. On a hit, herdr 0.7.4 prints an EVENT envelope
393
+ * ({"event":"pane.agent_status_changed","data":{pane_id, workspace_id,
394
+ * agent_status}}), not a result envelope; on timeout it exits 1 with plain
395
+ * text on stderr, which surfaces here as a TideError.
396
+ */
307
397
  export async function waitForHerdrAgentStatus(
308
398
  pane: string,
309
399
  status: TideAgentStatus,
310
400
  opts: HerdrWaitOptions = {},
311
- ): Promise<unknown> {
401
+ ): Promise<TideHerdrAgentStatusEvent> {
312
402
  const target = await resolveTarget(pane, opts)
313
403
  const waitMs = opts.waitTimeoutMs ?? 60_000
314
404
  const { stdout } = await runHerdr(
315
405
  ["wait", "agent-status", target, "--status", status, "--timeout", String(waitMs)],
316
- { ...opts, timeoutMs: opts.timeoutMs ?? waitMs + 5_000 },
406
+ { ...opts, timeoutMs: Math.max(opts.timeoutMs ?? 0, waitMs + 5_000) },
317
407
  )
318
- return parseHerdrJson<unknown>(stdout, "wait agent-status")
408
+ return parseHerdrJson<TideHerdrAgentStatusEvent>(stdout, "wait agent-status")
319
409
  }