pi-odd-worktree 1.1.1 → 1.2.0

package/lib/worktree-warp-busy.js

@@ -0,0 +1,119 @@
+'use strict';
+// S4: a warp waits for THIS session's own background work.
+//
+// Gentle Shell publishes one presence header per live Pi session, carrying that
+// session's agent-task counters (`counts.{running,queued,waiting,finished}`) and
+// a heartbeat. This module reads that store through the SAME bounded reader the
+// checkout-deletion guard uses, hashes this session's id with the same sha256,
+// and keeps only ITS freshest header. Nothing else is read: no transcript, no
+// prompt, no activity payload.
+//
+// WHAT IT DOES NOT COVER. Background jobs (`bash_background`, `monitor`) live in
+// gentle-shell's in-memory job registry (lib/background-jobs.ts) and leave no
+// durable, session-attributable state on disk, and the Pi host exposes no API
+// for them. This module therefore never claims to see a job: the refusal text
+// names agent tasks only.
+//
+// FAILURE MODE. Best effort, like the close guard: an absent or unreadable
+// store answers `unavailable` and blocks nothing. Only a fresh header that
+// reports running or queued work makes a session busy.
+
+const { readGentlePresence, hashSessionId, PRESENCE_FRESH_MS } = require('./worktree-session-guard.js');
+
+// How long the command front waits for the published counters to drain before
+// it refuses, and how often it re-reads. Overridable so a session can shorten
+// or lengthen its own wait; the default keeps a warp from stalling a turn.
+const DEFAULT_WAIT_MS = 60000;
+const POLL_MS = 2000;
+const MAX_WAIT_MS = 600000;
+
+const isCount = (value) => Number.isSafeInteger(value) && value >= 0;
+
+function waitBudgetMs(env) {
+  const source = env && typeof env === 'object' ? env : {};
+  const raw = source.ODD_WORKTREE_WARP_BUSY_WAIT_MS;
+  if (raw === undefined || raw === null || raw === '') return DEFAULT_WAIT_MS;
+  const parsed = Number.parseInt(String(raw), 10);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) return DEFAULT_WAIT_MS;
+  return Math.min(parsed, MAX_WAIT_MS);
+}
+
+function idleActivity(status) {
+  return { status, running: 0, queued: 0, waiting: 0, label: null, heartbeat: null, busy: false };
+}
+
+// This session's own counters, or an idle/unavailable answer. Never rejects.
+async function sessionActivity(options = {}) {
+  const opts = options && typeof options === 'object' ? options : {};
+  const hash = hashSessionId(opts.sessionId);
+  if (hash === null) return idleActivity('unknown');
+  let read;
+  try {
+    read = await readGentlePresence({ env: opts.env, now: opts.now });
+  } catch {
+    return idleActivity('unavailable');
+  }
+  if (!read || read.status !== 'ok') return idleActivity(read && read.status === 'unavailable' ? 'unavailable' : 'unknown');
+  let freshest = null;
+  for (const entry of Array.isArray(read.entries) ? read.entries : []) {
+    if (!entry || entry.sessionHash !== hash || entry.recent !== true) continue;
+    if (!entry.counts || !isCount(entry.counts.running) || !isCount(entry.counts.queued) || !isCount(entry.counts.waiting)) continue;
+    if (freshest === null || entry.heartbeat > freshest.heartbeat) freshest = entry;
+  }
+  if (freshest === null) return idleActivity('ok');
+  const running = freshest.counts.running;
+  const queued = freshest.counts.queued;
+  return {
+    status: 'ok',
+    running,
+    queued,
+    waiting: freshest.counts.waiting,
+    label: typeof freshest.label === 'string' ? freshest.label : null,
+    heartbeat: freshest.heartbeat,
+    busy: running > 0 || queued > 0,
+  };
+}
+
+// The one sentence both fronts use. It names the counters it actually read and
+// says plainly that background jobs are not visible to it.
+function busyText(activity) {
+  const running = activity && isCount(activity.running) ? activity.running : 0;
+  const queued = activity && isCount(activity.queued) ? activity.queued : 0;
+  const parts = [];
+  if (running > 0) parts.push(`${running} running`);
+  if (queued > 0) parts.push(`${queued} queued`);
+  const workload = parts.length > 0 ? parts.join(' and ') : 'no';
+  const label = activity && typeof activity.label === 'string' && activity.label.length > 0
+    ? ` on "${activity.label}"`
+    : '';
+  return `this session still has ${workload} agent task(s)${label}: the warp waits for them to finish (as of the last published heartbeat); background jobs are not visible here, so confirm they finished too`;
+}
+
+// Poll until this session has no running or queued agent task, or the budget
+// runs out. `read` and `sleep` are injected so a test never waits for real.
+async function waitForSessionActivity(options = {}) {
+  const opts = options && typeof options === 'object' ? options : {};
+  const read = typeof opts.read === 'function' ? opts.read : () => sessionActivity({ sessionId: opts.sessionId, env: opts.env });
+  const sleep = typeof opts.sleep === 'function' ? opts.sleep : (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  const budget = isCount(opts.waitMs) ? opts.waitMs : waitBudgetMs(opts.env);
+  const poll = isCount(opts.pollMs) && opts.pollMs > 0 ? opts.pollMs : POLL_MS;
+  let activity = await read();
+  let waited = 0;
+  while (activity && activity.busy === true && waited < budget) {
+    const step = Math.min(poll, budget - waited);
+    if (step <= 0) break;
+    await sleep(step);
+    waited += step;
+    activity = await read();
+  }
+  return { activity, waited, waitedOut: !!(activity && activity.busy === true) };
+}
+
+module.exports = {
+  DEFAULT_WAIT_MS,
+  MAX_WAIT_MS,
+  busyText,
+  sessionActivity,
+  waitBudgetMs,
+  waitForSessionActivity,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-odd-worktree",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Pi package for odd-worktree: the Agent Worktree tools (create, list, close, warp), the /warp worktree panel, the /odd-list ODD viewer, and the /issues GitHub issue reader. Works in Pi alone; Herdr is optional.",
   "keywords": [
     "pi-package",

package/tools/herdr-free-create.test.js

@@ -0,0 +1,161 @@
+'use strict';
+// S1/S2: no creation path reaches a Herdr binary.
+//
+// The package no longer resolves or builds Herdr argv at all, so this suite pins
+// the claim two ways: a `herdr` sentinel FIRST on PATH records any argv it is
+// given (an empty log is the assertion), and a source scan proves no file
+// outside the git seam builds Herdr argv or resolves the binary. Both creation
+// fronts are exercised because they share one creation helper.
+const { test, describe, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { loadExtension, SRC, LIB_DIR } = require('./fixtures/load-extension.js');
+
+const savedEnv = { ...process.env };
+const scratch = [];
+const track = (entry) => { scratch.push(entry); return entry; };
+after(() => {
+  for (const key of Object.keys(process.env)) if (!(key in savedEnv)) delete process.env[key];
+  for (const [key, value] of Object.entries(savedEnv)) process.env[key] = value;
+  for (const dir of scratch) { try { fs.rmSync(dir, { recursive: true, force: true }); } catch {} }
+});
+
+const BIN = track(fs.mkdtempSync(path.join(os.tmpdir(), 'no-herdr-bin-')));
+const HERDR_LOG = path.join(BIN, 'calls.log');
+fs.writeFileSync(
+  path.join(BIN, 'herdr'),
+  '#!/bin/sh\nprintf "%s\\n" "$*" >> "$HERDR_LOG"\nexit 1\n',
+  { mode: 0o755 },
+);
+fs.writeFileSync(path.join(BIN, 'codegraph'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+
+function herdrCalls() {
+  try {
+    return fs.readFileSync(HERDR_LOG, 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
+const resetHerdr = () => fs.writeFileSync(HERDR_LOG, '');
+
+function git(cwd, args) {
+  const out = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (out.status !== 0) throw new Error(`git ${args.join(' ')}: ${out.stderr}`);
+  return out.stdout.trim();
+}
+
+function makeRepo() {
+  const dir = track(fs.mkdtempSync(path.join(os.tmpdir(), 'no-herdr-repo-')));
+  git(dir, ['init', '-b', 'main']);
+  git(dir, ['config', 'user.email', 'no-herdr@example.test']);
+  git(dir, ['config', 'user.name', 'No Herdr']);
+  fs.writeFileSync(path.join(dir, 'README.md'), '# fixture\n');
+  git(dir, ['add', 'README.md']);
+  git(dir, ['commit', '-m', 'init']);
+  return fs.realpathSync(dir);
+}
+
+const resultText = (result) => (result.content || []).map((part) => (part && part.text) || '').join('\n');
+
+function ctxFor(repo, notes, ui) {
+  return {
+    cwd: repo,
+    hasUI: true,
+    mode: 'tui',
+    sessionManager: { getSessionId: () => 'no-herdr-session' },
+    ui: { confirm: async () => true, notify: (text, level) => notes.push([level, text]), ...(ui || {}) },
+  };
+}
+
+// `/warp` create: the selector's create action, the create panel's answer, then
+// the closing selector. Only those answers are scripted.
+function warpCreateUi(panelAnswer) {
+  let call = 0;
+  return {
+    custom: async () => {
+      call += 1;
+      if (call === 1) return { create: true };
+      if (call === 2) return panelAnswer;
+      return undefined;
+    },
+  };
+}
+
+let tools;
+let commands;
+before(async () => {
+  process.env.PATH = `${BIN}${path.delimiter}${savedEnv.PATH || ''}`;
+  process.env.GENTLE_WORKTREE_THREAD = 'no-herdr-session';
+  ({ tools, commands } = await loadExtension({}));
+});
+
+describe('no creation path invokes Herdr', () => {
+  for (const existing of [false, true]) {
+    const kind = existing ? 'an existing' : 'a new';
+
+    test(`worktree_create never invokes Herdr for ${kind} branch`, async () => {
+      resetHerdr();
+      const repo = makeRepo();
+      const branch = existing ? 'feat/adopted' : 'feat/fresh';
+      if (existing) git(repo, ['branch', branch]);
+      const result = await tools.get('worktree_create').execute(
+        'no-herdr-tool',
+        { branch, changes: 'none' },
+        undefined,
+        undefined,
+        ctxFor(repo, []),
+      );
+      assert.notEqual(result.isError, true, resultText(result));
+      assert.equal(result.details.branchCreated, !existing);
+      assert.equal(herdrCalls(), '', `Herdr was invoked: ${herdrCalls()}`);
+      assert.doesNotMatch(resultText(result), /herdr (workspace|association)/i, 'no Herdr workspace is reported');
+    });
+
+    test(`/warp create never invokes Herdr for ${kind} branch`, async () => {
+      resetHerdr();
+      const repo = makeRepo();
+      const name = existing ? 'adopted' : 'fresh';
+      if (existing) git(repo, ['branch', `feat/${name}`]);
+      const notes = [];
+      await commands.get('warp').handler('', ctxFor(repo, notes, warpCreateUi({ ok: true, type: 'feat', name })));
+      const target = path.join(path.dirname(repo), `${path.basename(repo)}-worktrees`, `feat-${name}`);
+      assert.ok(fs.existsSync(target), `the /warp create made no checkout (notifications: ${JSON.stringify(notes)})`);
+      assert.equal(herdrCalls(), '', `Herdr was invoked: ${herdrCalls()}`);
+      for (const [, text] of notes) assert.doesNotMatch(text, /herdr (workspace|association)/i, `Herdr reported: ${text}`);
+    });
+  }
+
+  test('a refused create writes nothing and never invokes Herdr', async () => {
+    resetHerdr();
+    const repo = makeRepo();
+    const before = git(repo, ['branch', '--format=%(refname:short)']);
+    const result = await tools.get('worktree_create').execute(
+      'no-herdr-bad',
+      { branch: 'bad..name', changes: 'none' },
+      undefined,
+      undefined,
+      ctxFor(repo, []),
+    );
+    assert.equal(result.isError, true);
+    assert.match(resultText(result), /^invalid branch name/);
+    assert.equal(git(repo, ['branch', '--format=%(refname:short)']), before);
+    assert.equal(herdrCalls(), '', `Herdr was invoked: ${herdrCalls()}`);
+  });
+
+  // S1 is an AUDIT claim: no source file outside the git seam reaches a Herdr
+  // binary. Pinned as text so a reintroduced call cannot hide in a helper.
+  test('no source file outside lib/worktree-git.js calls a Herdr binary', () => {
+    const files = [
+      SRC,
+      ...fs.readdirSync(LIB_DIR).filter((name) => name.endsWith('.js')).map((name) => path.join(LIB_DIR, name)),
+    ].filter((file) => !file.endsWith(`${path.sep}worktree-git.js`));
+    for (const file of files) {
+      const source = fs.readFileSync(file, 'utf8');
+      assert.doesNotMatch(source, /herdrArgv\s*\(/, `${file} builds Herdr argv`);
+      assert.doesNotMatch(source, /resolveHerdrBinary\s*\(/, `${file} resolves the Herdr binary`);
+    }
+  });
+});