herdr-gentle-shell 1.6.0 → 1.6.1

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/DESIGN.md CHANGED
@@ -405,7 +405,7 @@ gentle_done_v1 = sessionHash ":" expiry
405
405
  ; finish nobody looks at recedes at the cap. The consumer
406
406
  ; accepts no expiry beyond now+3600000 at read (the only
407
407
  ; token whose ceiling is not the 60 s TTL). A VIEWED finish
408
- ; recedes far sooner: the daemon starts one 5 s dwell
408
+ ; recedes far sooner: the daemon starts one 3 s dwell
409
409
  ; (DONE_VIEW_DWELL_MS) at the first frame that observes the
410
410
  ; pane focused and then renders `idle` (§5.2). That ledger
411
411
  ; of views is keyed by the token's absolute expiry and is
package/README.md CHANGED
@@ -381,7 +381,7 @@ it publishes is drawn at once, and the daemon caps each sleep at the nearest
381
381
  live `done` expiry and the nearest pending view-dwell deadline, so a row
382
382
  reaches `idle` on time instead of one poll later. `done` is held until viewed:
383
383
  a real finish stays `done` until the pane is first observed as the focused
384
- pane in the daemon's own snapshot, then one 5 s dwell (`DONE_VIEW_DWELL_MS`,
384
+ pane in the daemon's own snapshot, then one 3 s dwell (`DONE_VIEW_DWELL_MS`,
385
385
  consumer-side, not an override) and the recede to `idle`; a finish nobody
386
386
  looks at recedes at `GENTLE_DONE_UNSEEN_CAP_MS` (default 900000 ms = 15
387
387
  minutes, clamped [100, 3600000]), which is the finish token's expiry. A new
@@ -572,7 +572,14 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
572
572
  **normal panel**. Panel kind is decided from git, the pane Herdr names is
573
573
  verified to belong to its workspace and to sit in the requested path before
574
574
  Pi starts, and (unless `notify: false`) the caller is woken when that session
575
- really finishes. The other worktree tools and the ODD and issues panels live
575
+ really finishes. A worktree panel passes the target as both `--path` and
576
+ `--cwd`, because Herdr resolves the owning repository from `--cwd` rather
577
+ than from the process directory, so a worktree of another repository opens
578
+ too; and when Herdr still answers `worktree_not_found` for a path git proves
579
+ is a linked worktree, the panel opens as a normal one at the same path and
580
+ the result says which kind it opened (`panel: normal` plus a `fallback:`
581
+ row), while every other Herdr failure still aborts and opens nothing. The
582
+ other worktree tools and the ODD and issues panels live
576
583
  in `odd-worktree` now; the sidebar and Moshi switches stayed here and are
577
584
  reached through `/herdr-gentle:customize`. See
578
585
  [docs/herdr-session-open.md](docs/herdr-session-open.md).
@@ -5,7 +5,7 @@ The panel kind follows the path:
5
5
 
6
6
  | The path is | The panel opened |
7
7
  | --- | --- |
8
- | a linked Git worktree (a checkout whose `git rev-parse --git-dir` differs from its `--git-common-dir`) | **worktree panel** — `herdr worktree open --path <path>` |
8
+ | a linked Git worktree (a checkout whose `git rev-parse --git-dir` differs from its `--git-common-dir`) | **worktree panel** — `herdr worktree open --path <path> --cwd <path>` |
9
9
  | a repository's primary checkout, including `git init --separate-git-dir` | **normal panel** — `herdr workspace create --cwd <path>` |
10
10
  | any other existing directory, including a subdirectory of a checkout | **normal panel** — `herdr workspace create --cwd <path>` |
11
11
 
@@ -52,8 +52,15 @@ reply parsers), `lib/herdr-session-notifications.js` (finish subscription)
52
52
  - Worktree panel: `herdr worktree list --cwd <path>` first. A workspace
53
53
  already open for that checkout is reused; two different workspace ids
54
54
  claiming it fail closed. Otherwise `herdr worktree open --path <path>
55
- --no-focus`, and a failed open is re-checked against one fresh list rather
56
- than assumed to have done nothing.
55
+ --cwd <path> --no-focus`: the path travels twice because Herdr resolves
56
+ the owning repository from `--cwd`, not from the process directory, so a
57
+ worktree of another repository resolves instead of answering
58
+ `worktree_not_found`. A failed open is re-checked against one fresh list
59
+ rather than assumed to have done nothing, and only that
60
+ `worktree_not_found` code for a path git *still* proves is a linked
61
+ worktree falls back to a **normal panel** at the same path (`herdr
62
+ workspace create --cwd <path> --no-focus`), with the result saying so;
63
+ every other failure aborts and opens nothing.
57
64
  - Normal panel: `herdr workspace create --cwd <requested> --no-focus`, where
58
65
  `<requested>` is the caller's own spelling of the path.
59
66
  4. **Verify the pane before starting anything.** The pane Herdr names must
@@ -68,9 +75,12 @@ reply parsers), `lib/herdr-session-notifications.js` (finish subscription)
68
75
  6. **Subscribe to the finish** unless `notify: false` was passed.
69
76
 
70
77
  The result is compact, ordered `label: value` rows — `outcome`, `path`,
71
- `panel` (`worktree` or `normal`), `branch` (only for a Git checkout), `session`,
78
+ `panel` (`worktree` or `normal`, naming the kind really opened), `fallback`
79
+ (only when a worktree open fell back: `normal panel after herdr reported
80
+ worktree_not_found`), `branch` (only for a Git checkout), `session`,
72
81
  `workspace`, `pane`, `agent` — and the same facts ride in `details` as `path`,
73
- `kind` (`worktree` / `primary` / `generic`), `branch`, `paneId`, `workspaceId`,
82
+ `kind` (`worktree` / `primary` / `generic` / `normal` after a fallback),
83
+ `branch`, `fallback` (only when it happened), `paneId`, `workspaceId`,
74
84
  `sessionId`, `resumed`, `agentName`, `notify`.
75
85
 
76
86
  ## Parameters
@@ -50,7 +50,7 @@ tokens carrying private data are added here.
50
50
  finish token's expiry (`GENTLE_DONE_UNSEEN_CAP_MS`, producer-side, default
51
51
  900000 ms = 15 min, clamped [100, 3600000]); the daemon owns the earlier
52
52
  recede, because `focused` rides the same snapshot it already reads: the
53
- first frame that sees the pane focused starts one 5 s dwell
53
+ first frame that sees the pane focused starts one 3 s dwell
54
54
  (`DONE_VIEW_DWELL_MS`, a consumer constant, not an override) and the row
55
55
  then renders `idle`. A second look changes nothing, and the per-pane view
56
56
  ledger is daemon memory only, so a daemon restart while the token is still
@@ -762,7 +762,7 @@ const LOST_SETTLE_BEATS = 2;
762
762
  // `done`, so the producer mints the finish itself: one session-bound
763
763
  // `<hash>:<expiry>` token per finish at the settled-and-empty edge. Since T3
764
764
  // the expiry is the UNSEEN cap, not the visible dwell: the row holds `done`
765
- // until the human views the pane, then the consumer's own 5 s dwell and
765
+ // until the human views the pane, then the consumer's own 3 s dwell and
766
766
  // `idle`, and a pane nobody looks at recedes at the cap. The producer owns the
767
767
  // mint and the cap because it stamps the token; the consumer owns the recede
768
768
  // because `focused` rides the snapshot the daemon already reads. The finish
@@ -780,7 +780,7 @@ const DONE_UNSEEN_CAP_ENV = "GENTLE_DONE_UNSEEN_CAP_MS";
780
780
  // spell in which a stranded `subagent_run` keeps the native state non-terminal
781
781
  // and the `done` mint withheld, after which the terminal state lands. Its 5 s
782
782
  // default is the time the latch waits on a launch result that may never come;
783
- // the 5 s dwell after the human views a finish lives consumer-side
783
+ // the 3 s dwell after the human views a finish lives consumer-side
784
784
  // (`DONE_VIEW_DWELL_MS` in herdr-plugin/lib/gentle-tokens.js). Overridden
785
785
  // through GENTLE_HERDR_DONE_HOLD_MS, clamped to [1 s, 5 min].
786
786
  const DONE_HOLD_MS = 5000;
@@ -3749,7 +3749,7 @@ export default function (pi) {
3749
3749
  // pending launch, no live background job, and no human-wait, review, or
3750
3750
  // error leg — then republished with the SAME expiry so the unseen cap can
3751
3751
  // never be extended. The consumer holds `done` until the pane is viewed
3752
- // (its own 5 s dwell, then idle) and lets the token expire at the cap when
3752
+ // (its own 3 s dwell, then idle) and lets the token expire at the cap when
3753
3753
  // nobody ever looks. Any work appearing during the episode clears it on
3754
3754
  // that beat, so the row moves straight back to the role state. A session
3755
3755
  // that never worked never mints one. A live background job counts as
@@ -4,8 +4,14 @@
4
4
  //
5
5
  // It opens a Herdr panel running a Pi session AT A PATH:
6
6
  // * the path is a linked Git worktree -> a WORKTREE panel
7
- // (`herdr worktree open --path …`), reusing the workspace Herdr already
8
- // has for that checkout when there is one;
7
+ // (`herdr worktree open --path … --cwd …`), reusing the workspace Herdr
8
+ // already has for that checkout when there is one. The target is passed as
9
+ // `--cwd` as well because herdr resolves a worktree against the
10
+ // repository of the FOCUSED workspace, not against the process cwd, so a
11
+ // worktree of ANOTHER repository resolves instead of answering
12
+ // `worktree_not_found`. When herdr still answers `worktree_not_found` for
13
+ // a path git proves is a linked worktree, the panel falls back to a NORMAL
14
+ // one at the same path and the result says so;
9
15
  // * the path is a repository's primary checkout, any other directory, or a
10
16
  // subdirectory of a checkout -> a NORMAL panel
11
17
  // (`herdr workspace create --cwd …`).
@@ -181,12 +187,23 @@ async function executeSessionOpen(params, ctx, watcherOptions) {
181
187
  let paneId = null;
182
188
  let openedHere = false;
183
189
  const openCall = isWorktree ? "herdr worktree open" : "herdr workspace create";
190
+ // The panel kind that was really OPENED. A worktree panel can degrade to a
191
+ // normal panel on the one documented fallback, and both the rows and the
192
+ // details state the kind that was opened, never the one that was classified.
193
+ let openedKind = kind;
194
+ // The herdr error code that forced that fallback, or null. It is present
195
+ // only when a fallback really happened, so every existing result keeps its
196
+ // exact key order.
197
+ let fallbackCode = null;
184
198
 
185
199
  // One pane choice, used by the reuse path and by the create-then-list path.
186
200
  // Each refusal carries the details object the caller publishes, so every
187
201
  // refusal of this tool has the same key order: path, kind, branch, then the
188
202
  // pane before the workspace it belongs to.
189
- const paneRefusalBase = () => ({ path: target, kind, branch });
203
+ const paneRefusalBase = () => ({
204
+ path: target, kind: openedKind, branch,
205
+ ...(fallbackCode === null ? {} : { fallback: fallbackCode }),
206
+ });
190
207
  const choosePane = async (note) => {
191
208
  const panes = await runHerdr("pane-list", { workspace: workspaceId }, 60000);
192
209
  if (panes.status !== 0) {
@@ -214,22 +231,24 @@ async function executeSessionOpen(params, ctx, watcherOptions) {
214
231
  // Verify the pair a successful open/create reply names, before anything is
215
232
  // started in it: the pane belongs to the workspace, the pane's own workspace
216
233
  // (when reported) agrees, and its cwd is the requested path or inside it.
217
- const verifyOpenedPair = (pair) => {
234
+ // `call` names the call that really produced the panel, so a fallback reply
235
+ // is reported as the `herdr workspace create` it was.
236
+ const verifyOpenedPair = (pair, call = openCall) => {
218
237
  if (pair.workspaceId === null || pair.paneId === null) {
219
- return `herdr session open failed: '${openCall}' for ${target} succeeded but its output named no workspace/pane; no session was started`;
238
+ return `herdr session open failed: '${call}' for ${target} succeeded but its output named no workspace/pane; no session was started`;
220
239
  }
221
240
  if (!pair.paneId.startsWith(`${pair.workspaceId}:`)) {
222
- return `herdr session open failed: '${openCall}' named workspace '${pair.workspaceId}' but pane '${pair.paneId}', which does not belong to it; no session was started`;
241
+ return `herdr session open failed: '${call}' named workspace '${pair.workspaceId}' but pane '${pair.paneId}', which does not belong to it; no session was started`;
223
242
  }
224
243
  if (pair.paneWorkspace !== null && pair.paneWorkspace !== pair.workspaceId) {
225
- return `herdr session open failed: '${openCall}' named workspace '${pair.workspaceId}' but its root pane reports workspace '${pair.paneWorkspace}'; no session was started`;
244
+ return `herdr session open failed: '${call}' named workspace '${pair.workspaceId}' but its root pane reports workspace '${pair.paneWorkspace}'; no session was started`;
226
245
  }
227
246
  if (pair.paneCwd !== null) {
228
247
  const openedState = lib.checkoutState(pair.paneCwd, target);
229
248
  const openedReal = openedState.real !== null ? openedState.real : openedState.absolute;
230
249
  const inside = openedReal !== null && (openedReal === target || openedReal.startsWith(target + path.sep));
231
250
  if (!inside) {
232
- return `herdr session open failed: the pane '${pair.paneId}' '${openCall}' opened for ${target} has cwd ${pair.paneCwd}, outside ${target}; no session was started`;
251
+ return `herdr session open failed: the pane '${pair.paneId}' '${call}' opened for ${target} has cwd ${pair.paneCwd}, outside ${target}; no session was started`;
233
252
  }
234
253
  }
235
254
  return null;
@@ -271,10 +290,16 @@ async function executeSessionOpen(params, ctx, watcherOptions) {
271
290
  // it fails, one fresh list decides whether the workspace appeared anyway.
272
291
  // A worktree panel opens at the canonical checkout; a normal panel keeps the
273
292
  // spelling the caller asked for, which is what their shell will show.
274
- const opened = isWorktree
275
- ? await runHerdr("open", { path: target, noFocus: true }, 60000)
293
+ //
294
+ // The target travels as BOTH `--path` and `--cwd`: herdr resolves a
295
+ // worktree against the repository of the FOCUSED workspace unless `--cwd`
296
+ // names the resolution base, so only a target passed as `--cwd` can be
297
+ // resolved when its repository is not the focused one.
298
+ let reply = isWorktree
299
+ ? await runHerdr("open", { path: target, cwd: target, noFocus: true }, 60000)
276
300
  : await runHerdr("workspace-create", { cwd: requested, noFocus: true }, 60000);
277
- if (opened.status !== 0) {
301
+ let call = openCall;
302
+ if (reply.status !== 0) {
278
303
  if (isWorktree) {
279
304
  const relisted = await runHerdr("list", { cwd: target }, 60000);
280
305
  const retry = relisted.status === 0
@@ -283,17 +308,38 @@ async function executeSessionOpen(params, ctx, watcherOptions) {
283
308
  if (retry.id !== null) workspaceId = retry.id;
284
309
  }
285
310
  if (workspaceId === null) {
286
- return errorResult(
287
- `herdr session open failed: ${lib.herdrFailureText(openCall, opened.status, opened.stderr || opened.error)} for ${target}; no session was opened`,
288
- { path: target, kind, branch },
289
- );
311
+ // The ONE fallback (S3): herdr answered `worktree_not_found` for a path
312
+ // git still proves is a linked worktree, i.e. it could not resolve that
313
+ // worktree's repository. A normal panel at the same path still opens.
314
+ // Every other failure — and this code for a path that is no longer a
315
+ // linked worktree — keeps the abort below, so an unrelated error is
316
+ // never masked by a panel.
317
+ const code = isWorktree ? lib.herdrErrorCode(reply) : null;
318
+ if (code !== "worktree_not_found" || !(await lib.isLinkedWorktreePath(target))) {
319
+ return errorResult(
320
+ `herdr session open failed: ${lib.herdrFailureText(call, reply.status, reply.stderr || reply.error)} for ${target}; no session was opened`,
321
+ { path: target, kind, branch },
322
+ );
323
+ }
324
+ const fallback = await runHerdr("workspace-create", { cwd: target, noFocus: true }, 60000);
325
+ if (fallback.status !== 0) {
326
+ return errorResult(
327
+ `herdr session open failed: ${lib.herdrFailureText("herdr workspace create", fallback.status, fallback.stderr || fallback.error)} for ${target} after 'herdr worktree open' reported ${code}; no session was opened`,
328
+ { path: target, kind: "normal", branch, fallback: code },
329
+ );
330
+ }
331
+ reply = fallback;
332
+ call = "herdr workspace create";
333
+ openedKind = "normal";
334
+ fallbackCode = code;
290
335
  }
291
- } else {
292
- const pair = lib.openedWorkspace(opened.stdout);
293
- const refusal = verifyOpenedPair(pair);
336
+ }
337
+ if (reply.status === 0 && workspaceId === null) {
338
+ const pair = lib.openedWorkspace(reply.stdout);
339
+ const refusal = verifyOpenedPair(pair, call);
294
340
  if (refusal) {
295
341
  return errorResult(refusal, {
296
- path: target, kind, branch,
342
+ ...paneRefusalBase(),
297
343
  paneId: pair.paneId, workspaceId: pair.workspaceId,
298
344
  });
299
345
  }
@@ -303,7 +349,7 @@ async function executeSessionOpen(params, ctx, watcherOptions) {
303
349
  }
304
350
  if (paneId === null && workspaceId !== null) {
305
351
  const chosen = await choosePane(
306
- isWorktree
352
+ openedKind === "worktree"
307
353
  ? `; the workspace '${workspaceId}' was opened by this call and no session was started in it`
308
354
  : `; the workspace '${workspaceId}' was created by this call and no session was started in it`,
309
355
  );
@@ -320,7 +366,8 @@ async function executeSessionOpen(params, ctx, watcherOptions) {
320
366
  timeout: String(AGENT_START_TIMEOUT_MS), agentArgs: piArgs,
321
367
  }, AGENT_START_TIMEOUT_MS + 60000);
322
368
  const details = {
323
- path: target, kind, branch,
369
+ path: target, kind: openedKind, branch,
370
+ ...(fallbackCode === null ? {} : { fallback: fallbackCode }),
324
371
  paneId, workspaceId, sessionId, resumed, agentName, notify,
325
372
  };
326
373
  if (started.status !== 0) {
@@ -341,7 +388,7 @@ async function executeSessionOpen(params, ctx, watcherOptions) {
341
388
  try {
342
389
  notifications.startAgentSessionWatcher(
343
390
  {
344
- paneId, path: target, kind, branch, sessionId,
391
+ paneId, path: target, kind: openedKind, branch, sessionId,
345
392
  agentName, workspaceId, repoRoot: target,
346
393
  },
347
394
  watcherOptions,
@@ -301,9 +301,16 @@ function agentNameForPath(target, options = {}) {
301
301
  // `--flag=value`. Unknown operations or flags throw, and `--trust-repository`
302
302
  // is absent everywhere: trusting a repository is a human decision this tool
303
303
  // never takes. `--focus` stays out too — panels open with `--no-focus`.
304
+ //
305
+ // `open` accepts `cwd` beside `path` because herdr resolves a worktree against
306
+ // the repository of the FOCUSED workspace, not against the process cwd
307
+ // (herdr 0.9.5: `herdr worktree list` reported the focused workspace's repo
308
+ // from three different cwds, while `--cwd <worktree>` reported the worktree's
309
+ // own repo). Passing the target as `--cwd` is what makes a worktree of
310
+ // another repository resolvable.
304
311
  const HERDR_ALLOWLIST = {
305
312
  list: ['cwd'],
306
- open: ['path', 'noFocus'],
313
+ open: ['cwd', 'path', 'noFocus'],
307
314
  'workspace-create': ['cwd', 'noFocus'],
308
315
  'pane-list': ['workspace'],
309
316
  'agent-start': ['name', 'kind', 'pane', 'timeout', 'agentArgs'],
@@ -444,6 +451,54 @@ function herdrFailureText(call, status, reason) {
444
451
  return `'${call}' exited ${status} (${detail})`;
445
452
  }
446
453
 
454
+ // The `error.code` a failed herdr reply names, or null when it names none.
455
+ // Herdr prints `{"error":{"code":"…","message":"…"}}`; only the CODE is read
456
+ // (a message is prose, never a decision), and a reply carrying anything else —
457
+ // plain text, or JSON without an error code — reads as no code at all.
458
+ function herdrErrorCode(reply) {
459
+ const source = reply && typeof reply === 'object' ? reply : {};
460
+ for (const raw of [source.stderr, source.stdout]) {
461
+ if (typeof raw !== 'string') continue;
462
+ const text = raw.trim();
463
+ if (text.length === 0) continue;
464
+ const candidates = [text];
465
+ const first = text.indexOf('{');
466
+ const last = text.lastIndexOf('}');
467
+ if (first !== -1 && last > first) candidates.push(text.slice(first, last + 1));
468
+ for (const candidate of candidates) {
469
+ let doc = null;
470
+ try {
471
+ doc = JSON.parse(candidate);
472
+ } catch {
473
+ continue;
474
+ }
475
+ const code = doc && typeof doc === 'object' && doc.error && typeof doc.error === 'object'
476
+ && typeof doc.error.code === 'string' && doc.error.code.length > 0
477
+ ? doc.error.code
478
+ : null;
479
+ if (code !== null) return code;
480
+ }
481
+ }
482
+ return null;
483
+ }
484
+
485
+ // Whether `target` is STILL the checkout root of an existing linked worktree,
486
+ // re-probed from git at the moment a failed open would fall back (never
487
+ // remembered from the earlier classification): a path that vanished, stopped
488
+ // being a worktree, or stopped being that worktree's ROOT keeps today's abort
489
+ // behaviour instead of falling back. Root identity matters on its own: a plain
490
+ // directory recreated inside another linked worktree resolves to the ENCLOSING
491
+ // checkout, whose kind says nothing about this path.
492
+ async function isLinkedWorktreePath(target, opts = {}) {
493
+ const state = checkoutState(target, null);
494
+ if (!state.exists || !state.isDirectory) return false;
495
+ const real = canonicalPath(target) || (state.real !== null ? state.real : state.absolute);
496
+ if (typeof real !== 'string' || real.length === 0) return false;
497
+ const probe = await repoProbe(real, opts);
498
+ if (probe.error !== null || probe.repo === null || probe.repo.isLinkedWorktree !== true) return false;
499
+ return identityOf(probe.repo.root) === identityOf(real);
500
+ }
501
+
447
502
  // ---------------------------------------------------------------------------
448
503
  // Herdr replies
449
504
  // ---------------------------------------------------------------------------
@@ -629,6 +684,10 @@ function sessionOpenRows(details) {
629
684
  const target = cleanValue(details.path);
630
685
  if (target.length > 0) rows.push(`path: ${target}`);
631
686
  rows.push(`panel: ${details.kind === 'worktree' ? 'worktree' : 'normal'}`);
687
+ // A fallback is never silent: a normal panel created because herdr refused
688
+ // the worktree says so, and names the error code that made it happen.
689
+ const fallback = cleanValue(details.fallback);
690
+ if (fallback.length > 0) rows.push(`fallback: normal panel after herdr reported ${fallback}`);
632
691
  const branch = cleanValue(details.branch);
633
692
  if (branch.length > 0) rows.push(`branch: ${branch}`);
634
693
  const session = cleanValue(details.sessionId);
@@ -657,6 +716,8 @@ module.exports = {
657
716
  resolveHerdrBinary,
658
717
  isHerdrRefusal,
659
718
  herdrFailureText,
719
+ herdrErrorCode,
720
+ isLinkedWorktreePath,
660
721
  worktreeWorkspaceId,
661
722
  selectSessionPane,
662
723
  openedWorkspace,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "herdr-gentle-shell",
3
- "version": "1.6.0",
3
+ "version": "1.6.1",
4
4
  "description": "Pi package for Herdr sidebar states: the Pi extension sidecar that publishes session facts as Herdr pane-metadata tokens, the optional Moshi notification channel, and the Pi-side helpers the Herdr Gentle Shell plugin drives.",
5
5
  "keywords": [
6
6
  "pi-package",