pi-odd-worktree 0.0.0-stage → 0.1.0

package/tools/commands.test.js

@@ -0,0 +1,176 @@
+'use strict';
+// S4 commands: `/warp` and `/odd-list` are driven here through the registered
+// handlers. `/issues` has its own suite (tools/issues-command.test.js), where
+// the `gh` runner is injected. The warp case also proves the agent route end to
+// end: `worktree_warp` queues the move as `/warp @<token>` and that exact
+// argument is the handoff the command decodes.
+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 } = require('./fixtures/load-extension.js');
+
+const scratch = [];
+function track(dir) {
+  scratch.push(dir);
+  return dir;
+}
+
+const savedEnv = { ...process.env };
+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 HOOK_BIN = path.resolve(track(fs.mkdtempSync(path.join(os.tmpdir(), 'odd-cmd-hookbin-'))));
+fs.writeFileSync(path.join(HOOK_BIN, 'codegraph'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+const NO_HERDR = path.join(os.tmpdir(), 'odd-worktree-no-such-herdr-binary');
+
+function git(cwd, args) {
+  const out = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (out.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${out.stderr}`);
+  return out.stdout.trim();
+}
+
+function makeRepo() {
+  const dir = track(fs.mkdtempSync(path.join(os.tmpdir(), 'odd-cmd-repo-')));
+  git(dir, ['init', '-b', 'main']);
+  git(dir, ['config', 'user.email', 'test@example.test']);
+  git(dir, ['config', 'user.name', 'Test']);
+  fs.writeFileSync(path.join(dir, 'README.md'), '# fixture\n');
+  git(dir, ['add', 'README.md']);
+  git(dir, ['commit', '-m', 'init']);
+  return dir;
+}
+
+const notifications = [];
+function makeCtx(cwd, extra = {}) {
+  return {
+    cwd,
+    hasUI: false,
+    mode: 'tui',
+    sessionManager: { getSessionId: () => 'thread-1' },
+    ui: {
+      notify: (text, level) => { notifications.push([level, text]); },
+      ...extra,
+    },
+  };
+}
+
+function resultText(result) {
+  return (result.content || []).map((part) => (part && part.text) || '').join('\n');
+}
+
+let host;
+let commands;
+let tools;
+before(async () => {
+  process.env.HERDR_BIN_PATH = NO_HERDR;
+  process.env.GENTLE_WORKTREE_THREAD = 'thread-1';
+  process.env.PATH = `${HOOK_BIN}${path.delimiter}${savedEnv.PATH || ''}`;
+  const sent = [];
+  const loaded = await loadExtension({ sendUserMessage: (text, options) => { sent.push([text, options]); } });
+  host = loaded.host;
+  commands = loaded.commands;
+  tools = loaded.tools;
+  host.sent = sent;
+});
+
+describe('/warp', () => {
+  test('refuses more than one name and says which form to use', async () => {
+    notifications.length = 0;
+    await commands.get('warp').handler('feat-x principal', makeCtx(makeRepo()));
+    assert.deepEqual(notifications, [
+      ['error', 'worktree warp needs exactly one name: use /warp <name> (the flattened branch slug, or principal).'],
+    ]);
+  });
+
+  test('outside a repository asks for git init instead of opening the selector', async () => {
+    const loose = track(fs.mkdtempSync(path.join(os.tmpdir(), 'odd-cmd-loose-')));
+    notifications.length = 0;
+    await commands.get('warp').handler('', makeCtx(loose));
+    assert.deepEqual(notifications, [['info', `not a git repository: ${loose}; run 'git init' first`]]);
+  });
+
+  test('a warp outside a session reports that it needs a session, not a crash', async () => {
+    const repo = makeRepo();
+    notifications.length = 0;
+    await commands.get('warp').handler('feat-none', makeCtx(repo));
+    assert.deepEqual(notifications, [
+      ['error', 'worktree warp is only available as a session command: run /warp <name> from a Pi session'],
+    ]);
+  });
+
+  test('the agent tool queues the move as the /warp handoff the command reads', async () => {
+    const repo = makeRepo();
+    const ctx = makeCtx(repo);
+    const created = await tools.get('worktree_create').execute(
+      'call-1',
+      { branch: 'feat/warp-me', changes: 'none' },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.notEqual(created.isError, true, resultText(created));
+
+    host.sent.length = 0;
+    const queued = await tools.get('worktree_warp').execute(
+      'call-2',
+      { name: 'feat-warp-me' },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.notEqual(queued.isError, true, resultText(queued));
+    assert.match(resultText(queued), /^worktree warp: handoff queued/);
+    assert.equal(host.sent.length, 1);
+    const [message, options] = host.sent[0];
+    assert.deepEqual(options, { expandPromptTemplates: true });
+    assert.ok(message.startsWith('/warp @'), `the queued command is /warp (${message})`);
+
+    // The command accepts exactly that argument: the handoff is decoded (the
+    // session-control refusal is the NEXT gate, so nothing about the token is
+    // rejected) instead of falling through to the name path.
+    notifications.length = 0;
+    await commands.get('warp').handler(message.slice('/warp '.length), ctx);
+    assert.deepEqual(notifications, [
+      ['error', 'worktree warp is only available as a session command: run /warp <name> from a Pi session'],
+    ]);
+  });
+});
+
+describe('/odd-list', () => {
+  test('an empty checkout says there is nothing to read', async () => {
+    const repo = makeRepo();
+    notifications.length = 0;
+    await commands.get('odd-list').handler('', makeCtx(repo));
+    assert.deepEqual(notifications, [['info', 'No odd documents under odd/tasks/ in this checkout.']]);
+  });
+
+  test('lists odd/tasks documents through the degraded select menu', async () => {
+    const repo = makeRepo();
+    fs.mkdirSync(path.join(repo, 'odd', 'tasks'), { recursive: true });
+    fs.writeFileSync(path.join(repo, 'odd', 'tasks', 'feature.md'), '# Feature\n');
+    let offered = null;
+    notifications.length = 0;
+    await commands.get('odd-list').handler(
+      '',
+      makeCtx(repo, { select: async (title, options) => { offered = options; return options[0]; } }),
+    );
+    assert.deepEqual(offered, ['feature']);
+    assert.deepEqual(notifications, [['info', path.join(repo, 'odd', 'tasks', 'feature.md')]]);
+  });
+
+  test('an unknown option names the command that is valid', async () => {
+    notifications.length = 0;
+    await commands.get('odd-list').handler('nope', makeCtx(makeRepo()));
+    assert.deepEqual(notifications, [['error', 'Unknown option "nope". Use /odd-list.']]);
+  });
+});

package/tools/fixtures/gh-api-user.json

@@ -0,0 +1 @@
+{"login":"jonasotoaguilar","name":"Jonathan Soto"}

package/tools/fixtures/gh-issue-list.json

@@ -0,0 +1 @@
+[{"author":{"id":"U_kgDOBXYt8A","is_bot":false,"login":"jonasotoaguilar","name":"Jonathan Soto"},"body":"The GitHub repository was renamed from `jonasotoaguilar/herdr-gentle-agents` to `jonasotoaguilar/herdr-gentle-shell`, and the local `origin` already points at the new name.\n\nThe rename is deliberately partial. `herdr-gentle-agents` appears in 33 files, but most of those occurrences are contracts rather than names:\n\n- **Repository identity (update):** `package.json` metadata URLs, `README.md` and `DESIGN.md` links and badges, `docs/*.md` links, the repository slug `install.sh` downloads from, and the install command string the plugin version check prints.\n- **Contracts (keep byte-identical):** the state directory segment and plugin ids (`STATE_PLUGIN_ID`, `PLUGIN_ID`, `LEGACY_PLUGIN_ID`, `SIDEBAR_STATE_SEGMENT`, `SIDEBAR_LEGACY_PLUGIN_ID`), the managed-block markers `# BEGIN/# END herdr-gentle-agents (managed; do not edit)` already written into the user's Pi settings, state file names, `repo_key` values, the Herdr plugin directory name, and every test that pins them.\n\nRenaming a contract would orphan the installed state on disk and make the tooling stop recognising the managed block it wrote, which is why S15 of `odd/tasks/customize-command.md` forbids it.\n\nAcceptance: the full suite green, and every changed occurrence reported as a URL/identity reference with its reason, alongside every occurrence deliberately kept.","comments":[],"createdAt":"2026-10-18T04:21:27Z","labels":[],"number":76,"reactionGroups":[],"state":"OPEN","stateReason":"","title":"chore: update the repository references after the rename to herdr-gentle-shell","updatedAt":"2026-10-18T04:21:27Z","url":"https://github.com/jonasotoaguilar/herdr-gentle-shell/issues/76"}]

package/tools/fixtures/gh-issue-view.json

@@ -0,0 +1 @@
+{"author":{"id":"U_kgDOBXYt8A","is_bot":false,"login":"jonasotoaguilar","name":"Jonathan Soto"},"body":"The GitHub repository was renamed from `jonasotoaguilar/herdr-gentle-agents` to `jonasotoaguilar/herdr-gentle-shell`, and the local `origin` already points at the new name.\n\nThe rename is deliberately partial. `herdr-gentle-agents` appears in 33 files, but most of those occurrences are contracts rather than names:\n\n- **Repository identity (update):** `package.json` metadata URLs, `README.md` and `DESIGN.md` links and badges, `docs/*.md` links, the repository slug `install.sh` downloads from, and the install command string the plugin version check prints.\n- **Contracts (keep byte-identical):** the state directory segment and plugin ids (`STATE_PLUGIN_ID`, `PLUGIN_ID`, `LEGACY_PLUGIN_ID`, `SIDEBAR_STATE_SEGMENT`, `SIDEBAR_LEGACY_PLUGIN_ID`), the managed-block markers `# BEGIN/# END herdr-gentle-agents (managed; do not edit)` already written into the user's Pi settings, state file names, `repo_key` values, the Herdr plugin directory name, and every test that pins them.\n\nRenaming a contract would orphan the installed state on disk and make the tooling stop recognising the managed block it wrote, which is why S15 of `odd/tasks/customize-command.md` forbids it.\n\nAcceptance: the full suite green, and every changed occurrence reported as a URL/identity reference with its reason, alongside every occurrence deliberately kept.","comments":[],"createdAt":"2026-10-18T04:21:27Z","labels":[],"number":76,"reactionGroups":[],"state":"OPEN","stateReason":"","title":"chore: update the repository references after the rename to herdr-gentle-shell","updatedAt":"2026-10-18T04:21:27Z","url":"https://github.com/jonasotoaguilar/herdr-gentle-shell/issues/76"}

package/tools/fixtures/gh-label-list.json

@@ -0,0 +1 @@
+[{"color":"f143ab","description":"Barrier affecting people with disabilities","name":"accessibility"},{"color":"d73a4a","description":"Something isn't working","name":"bug"},{"color":"0075ca","description":"Improvements or additions to documentation","name":"documentation"},{"color":"cfd3d7","description":"This issue or pull request already exists","name":"duplicate"},{"color":"a2eeef","description":"New feature or request","name":"enhancement"},{"color":"7057ff","description":"Good for newcomers","name":"good first issue"},{"color":"008672","description":"Extra attention is needed","name":"help wanted"},{"color":"e4e669","description":"This doesn't seem right","name":"invalid"},{"color":"d876e3","description":"Further information is requested","name":"question"},{"color":"ffffff","description":"This will not be worked on","name":"wontfix"},{"color":"FBCA04","description":"Needs maintainer review","name":"status:needs-review"},{"color":"D73A4A","description":"Bug fix","name":"type:bug"},{"color":"A2EEEF","description":"New feature","name":"type:feature"},{"color":"0075CA","description":"Documentation only","name":"type:docs"},{"color":"5319E7","description":"Code refactoring","name":"type:refactor"},{"color":"BFDADC","description":"Build CI or tooling","name":"type:chore"},{"color":"B60205","description":"Breaking change","name":"type:breaking-change"},{"color":"B60205","description":"Maintainer-approved exception for an oversized review slice","name":"size:exception"},{"color":"0E8A16","description":"Maintainer-approved issue ready for implementation","name":"status:approved"}]

package/tools/fixtures/gh-repo-view.json

@@ -0,0 +1 @@
+{"nameWithOwner":"jonasotoaguilar/herdr-gentle-shell"}

package/tools/fixtures/load-extension.js

@@ -0,0 +1,66 @@
+'use strict';
+// Shared loader for the standalone extension: the extension is plain JS under
+// a .ts name, so a test copies it to a scratch .mjs with the two Pi package
+// imports stubbed and imports it with a fake `pi` object. The lib override
+// points the copied module at this package's own lib/ directory.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+
+const LIB_DIR = path.resolve(__dirname, '../../lib');
+const SRC = path.resolve(__dirname, '../../extensions/odd-worktree-tools.ts');
+
+const TYPE_STUB = [
+  'const Type = {',
+  '  Object: (props) => ({ type: "object", properties: props }),',
+  '  String: (opts) => ({ type: "string", ...(opts || {}) }),',
+  '  Number: (opts) => ({ type: "number", ...(opts || {}) }),',
+  '  Array: (items, opts) => ({ type: "array", items, ...(opts || {}) }),',
+  '  Boolean: (opts) => ({ type: "boolean", ...(opts || {}) }),',
+  '  Optional: (schema) => ({ ...schema, optional: true }),',
+  '};',
+].join('\n');
+
+// The stubbed source is read once per process; a test that asserts on the
+// source itself can read SRC directly.
+let cached = null;
+function stubbedSource() {
+  if (cached !== null) return cached;
+  const srcText = fs.readFileSync(SRC, 'utf8');
+  const stubbed = srcText
+    .replace('import { Type } from "@earendil-works/pi-ai";', TYPE_STUB)
+    .replace('import { defineTool } from "@earendil-works/pi-coding-agent";', 'const defineTool = (def) => def;');
+  if (stubbed === srcText) throw new Error('expected both Pi package import lines to be stubbed');
+  cached = stubbed;
+  return cached;
+}
+
+// Load the extension with the injected `pi` double. Returns the registered
+// commands and tools keyed by name, exactly as the host received them.
+async function loadExtension(pi) {
+  process.env.GENTLE_WORKTREE_LIB_DIR = LIB_DIR;
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'odd-worktree-ext-'));
+  try {
+    const copy = path.join(dir, 'odd-worktree-tools.mjs');
+    fs.writeFileSync(copy, stubbedSource());
+    const factory = (await import(pathToFileURL(copy).href)).default;
+    const commands = new Map();
+    const tools = new Map();
+    const messageRenderers = new Map();
+    const hooks = [];
+    const host = {
+      registerCommand: (name, handler) => { commands.set(name, handler); },
+      registerTool: (tool) => { tools.set(tool.name, tool); },
+      registerMessageRenderer: (type, renderer) => { messageRenderers.set(type, renderer); },
+      on: (event, handler) => { hooks.push([event, handler]); },
+      ...pi,
+    };
+    factory(host);
+    return { commands, tools, messageRenderers, hooks, host };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+module.exports = { LIB_DIR, SRC, loadExtension, stubbedSource };

package/tools/gh-issues-feedback.test.js

@@ -0,0 +1,359 @@
+'use strict';
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const gh = require('../lib/gh-issues.js');
+afterEach(() => gh.setGhRunner(null));
+const ok = (doc) => ({ status: 0, stdout: JSON.stringify(doc), stderr: '' });
+const field = (argv, name) => argv.find((value) => value.startsWith(`${name}=`))?.slice(name.length + 1);
+const node = (number) => ({ number, title: `Issue ${number}`, state: 'OPEN', author: { login: 'author' }, labels: { nodes: [] }, comments: { totalCount: 0 } });
+function runner(handler) {
+  const calls = [];
+  gh.setGhRunner(async (_bin, argv) => {
+    calls.push(argv);
+    if (argv[0] === 'repo') return ok({ nameWithOwner: 'owner/repo' });
+    return handler(argv);
+  });
+  return calls;
+}
+
+test('fresh pages preserve the server query, per-row cursor and requested capacity', async () => {
+  let round = 0;
+  const calls = runner((argv) => {
+    assert.equal(argv[0], 'api');
+    assert.match(field(argv, 'search'), /repo:owner\/repo/);
+    assert.match(field(argv, 'search'), /assignee:@me/);
+    assert.equal(field(argv, 'first'), '7');
+    assert.equal(field(argv, 'cursor'), 'previous');
+    return ok({ data: { search: { issueCount: 12, pageInfo: { hasNextPage: true, endCursor: 'next' }, edges: [{ cursor: 'next', node: { ...node(4), title: `Fresh ${++round}` } }] } } });
+  });
+  const params = { query: 'assignee:@me', after: 'previous', first: 7 };
+  const first = await gh.getIssuePage(params);
+  const second = await gh.getIssuePage(params);
+  assert.equal(first.ok, true);
+  assert.equal(first.issues[0].cursor, 'next');
+  assert.equal(first.total, 12);
+  assert.equal(first.hasNextPage, true);
+  assert.equal(second.issues[0].title, 'Fresh 2');
+  assert.equal(calls.filter((argv) => argv[0] === 'api').length, 2, 'each page request is fresh');
+});
+
+test('page budgets larger than one API page are fetched without dropping cursors', async () => {
+  const calls = runner((argv) => {
+    const after = field(argv, 'cursor');
+    const count = Number(field(argv, 'first'));
+    const start = after ? 101 : 1;
+    return ok({ data: { search: { issueCount: 160, pageInfo: { hasNextPage: start + count <= 160, endCursor: `c${start + count - 1}` }, edges: Array.from({ length: count }, (_, i) => ({ cursor: `c${start + i}`, node: node(start + i) })) } } });
+  });
+  const result = await gh.getIssuePage({ first: 145 });
+  assert.equal(result.ok, true);
+  assert.equal(result.issues.length, 145);
+  assert.equal(result.issues[144].cursor, 'c145');
+  assert.deepEqual(calls.filter((argv) => argv[0] === 'api').map((argv) => field(argv, 'first')), ['100', '45']);
+});
+
+test('invalid page inputs produce no subprocess calls', async () => {
+  const calls = runner(() => ok({}));
+  for (const first of [0, -1, 1.5, NaN, 1001]) assert.equal((await gh.getIssuePage({ first })).ok, false);
+  for (const params of [null, [], 'bad']) assert.equal((await gh.getIssuePage(params)).ok, false);
+  assert.equal(calls.length, 0);
+});
+
+test('GraphQL errors and malformed page cursors are failures, never fake empty pages', async () => {
+  runner(() => ok({ errors: [{ message: 'Forbidden' }] }));
+  assert.equal((await gh.getIssuePage({ first: 5 })).ok, false);
+  runner(() => ok({ data: { search: { issueCount: 1, pageInfo: { hasNextPage: true }, edges: [{ node: node(1) }] } } }));
+  assert.equal((await gh.getIssuePage({ first: 5 })).ok, false);
+});
+
+test('assignable users paginate and deduplicate actual repository candidates', async () => {
+  runner((argv) => {
+    const after = field(argv, 'cursor');
+    return ok({ data: { repository: { assignableUsers: { nodes: after ? [{ login: 'bob', name: 'Bob' }, { login: 'alice' }] : [{ login: 'alice', name: 'Alice' }], pageInfo: { hasNextPage: !after, endCursor: after ? null : 'users-next' } } } } });
+  });
+  const result = await gh.listAssignableUsers();
+  assert.equal(result.ok, true);
+  assert.deepEqual(result.users.map((user) => user.login), ['alice', 'bob']);
+});
+
+test('assignee toggles add and remove using fixed argv with confirmed triage rights', async () => {
+  const calls = runner((argv) => {
+    if (argv[0] === 'api') return ok({ data: { repository: { viewerPermission: 'TRIAGE' } } });
+    return { status: 0, stdout: '', stderr: '' };
+  });
+  const result = await gh.editAssignees(3, { add: ['alice', 'bob'], remove: ['charlie'] });
+  assert.equal(result.ok, true);
+  assert.deepEqual(calls.find((argv) => argv[0] === 'issue'), ['issue', 'edit', '3', '--add-assignee', 'alice', '--add-assignee', 'bob', '--remove-assignee', 'charlie']);
+});
+
+test('denied and unknown repository roles cannot issue an assignee mutation', async () => {
+  for (const role of ['READ', null, 'UNKNOWN_ROLE']) {
+    const calls = runner(() => ok({ data: { repository: { viewerPermission: role } } }));
+    const result = await gh.editAssignees(3, { add: ['alice'], remove: [] });
+    assert.equal(result.ok, false);
+    assert.equal(calls.some((argv) => argv[0] === 'issue'), false);
+  }
+});
+
+test('malformed assignee changes are rejected before any read or write', async () => {
+  const calls = runner(() => ok({}));
+  for (const args of [null, [], 'bad', { add: ['--help'] }, { remove: ['bad,user'] }, { add: 'alice' }, { add: ['alice'], remove: ['alice'] }]) {
+    assert.equal((await gh.editAssignees(3, args)).ok, false);
+  }
+  assert.equal((await gh.editAssignees(0, { add: ['alice'] })).ok, false);
+  assert.equal(calls.length, 0);
+});
+
+test('permission and relation metadata is explicit and omits absent project/PR data', async () => {
+  runner(() => ok({ data: { repository: { viewerPermission: 'TRIAGE', issue: { assignees: { nodes: [{ login: 'alice' }, { login: 'bob' }] }, projectItems: { nodes: [{ project: { title: 'Roadmap', url: 'https://example.invalid/project' } }] }, closedByPullRequestsReferences: { totalCount: 2 } } } } }));
+  const result = await gh.getIssueMetadata(3);
+  assert.equal(result.ok, true);
+  assert.deepEqual(result.permissions, { canEditLabels: true, canEditAssignees: true, canCreateLabels: false, canCloseIssues: true });
+  assert.deepEqual(result.assignees, ['alice', 'bob']);
+  assert.equal(result.projects[0].title, 'Roadmap');
+  assert.equal(result.linkedPullRequestCount, 2);
+  runner(() => ok({ data: { repository: { viewerPermission: 'READ', issue: { assignees: { nodes: [] }, projectItems: { nodes: [] }, closedByPullRequestsReferences: { totalCount: 0 } } } } }));
+  const empty = await gh.getIssueMetadata(3);
+  assert.equal(empty.permissions.canEditLabels, false);
+  assert.equal(empty.permissions.canCloseIssues, false);
+  assert.equal('projects' in empty, false);
+  assert.equal('linkedPullRequestCount' in empty, false);
+});
+
+test('project scope failures preserve confirmed triage rights, assignees and linked PRs', async () => {
+  runner((argv) => {
+    if (field(argv, 'query').includes('projectItems')) return ok({ errors: [{ message: 'read:project scope required' }] });
+    return ok({ data: { repository: { viewerPermission: 'WRITE', issue: { assignees: { nodes: [{ login: 'alice' }] }, closedByPullRequestsReferences: { totalCount: 2 } } } } });
+  });
+  const result = await gh.getIssueMetadata(3);
+  assert.equal(result.ok, true);
+  assert.equal(result.permissions.canEditAssignees, true);
+  assert.equal(result.permissions.canCreateLabels, true);
+  assert.deepEqual(result.assignees, ['alice']);
+  assert.equal(result.linkedPullRequestCount, 2);
+  assert.equal('projects' in result, false);
+  assert.match(result.metadataError, /read:project/);
+});
+
+test('assignee mutation failures are not converted to success', async () => {
+  runner((argv) => argv[0] === 'api' ? ok({ data: { repository: { viewerPermission: 'WRITE' } } }) : { status: 1, stdout: '', stderr: 'Forbidden' });
+  const result = await gh.editAssignees(3, { add: ['alice'], remove: [] });
+  assert.equal(result.ok, false);
+  assert.match(result.error, /Forbidden/);
+});
+
+// T2 (S2): the unfiltered `All` bucket reads the repository's own issue
+// CONNECTION, which is cursor-paged with no 1000-match search ceiling and
+// reports the exact total. `getIssuePage` (the typed-search path) keeps its
+// search semantics and its honest cap.
+const connection = (edges, { totalCount = edges.length, hasNextPage = false, endCursor = null } = {}) => ok({
+  data: {
+    repository: {
+      issues: { totalCount, pageInfo: { hasNextPage, endCursor }, edges },
+    },
+  },
+});
+const connectionRunner = (handler) => {
+  const calls = [];
+  gh.setGhRunner(async (_bin, argv) => {
+    calls.push(argv);
+    if (argv[0] === 'repo') return ok({ nameWithOwner: 'owner/repo' });
+    return handler(argv);
+  });
+  // A live view: the array fills as the call runs, after this returns.
+  return () => calls.filter((argv) => argv[0] === 'api');
+};
+
+test('unfiltered All reads the issue connection with an exact total and per-row cursors', async () => {
+  let seen = null;
+  const calls = connectionRunner((argv) => {
+    seen = field(argv, 'query');
+    assert.equal(field(argv, 'first'), '30');
+    assert.equal(field(argv, 'cursor'), undefined, 'a head read starts the connection');
+    return connection([
+      { cursor: 'c1', node: node(1) },
+      { cursor: 'c2', node: node(2) },
+      { cursor: 'c3', node: node(3) },
+    ], { totalCount: 1500, hasNextPage: true, endCursor: 'c3' });
+  });
+  const result = await gh.getIssueConnectionPage({ first: 30 });
+  assert.equal(result.ok, true);
+  assert.equal(calls().length, 1);
+  assert.doesNotMatch(seen, /search\(/, 'never the capped search API');
+  assert.match(seen, /issues\(states: \[OPEN\], first: \$first, after: \$cursor/);
+  assert.match(seen, /orderBy: \{field: UPDATED_AT, direction: DESC\}/, 'ordering belongs to the query');
+  assert.match(seen, /totalCount/);
+  assert.match(seen, /edges \{\s*cursor\s+node \{/, 'every edge carries its own cursor');
+  assert.equal(result.total, 1500, 'the exact server total, never a page length');
+  assert.equal(result.hasNextPage, true);
+  assert.deepEqual(result.issues.map((row) => row.cursor), ['c1', 'c2', 'c3']);
+  assert.deepEqual(result.issues.map((row) => row.number), [1, 2, 3]);
+  assert.equal(result.issues[0].state, 'open');
+  assert.equal(result.issues[0].body, '', 'the connection never asks for bodies');
+});
+
+test('more than 1000 issues page past the search cap through the connection', async () => {
+  const served = [];
+  const calls = connectionRunner((argv) => {
+    const after = field(argv, 'cursor');
+    const count = Number(field(argv, 'first'));
+    const start = (after ? Number(after.slice(1)) : 0) + 1;
+    const end = start + count - 1;
+    served.push(`${start}-${end}`);
+    return connection(
+      Array.from({ length: count }, (_, i) => ({ cursor: `c${start + i}`, node: node(start + i) })),
+      { totalCount: 1500, hasNextPage: end < 1500, endCursor: `c${end}` },
+    );
+  });
+  const head = await gh.getIssueConnectionPage({ first: 1000 });
+  assert.equal(head.ok, true, '1000 rows is a page size here, not a result cap');
+  assert.equal(head.issues.length, 1000);
+  assert.equal(head.total, 1500);
+  assert.equal(head.hasNextPage, true);
+  assert.equal(head.issues[999].cursor, 'c1000');
+  const tail = await gh.getIssueConnectionPage({ first: 500, after: head.issues[999].cursor });
+  assert.equal(tail.ok, true);
+  assert.equal(tail.issues.length, 500);
+  assert.equal(tail.issues[0].number, 1001, 'the continuation crosses the 1000-match search ceiling');
+  assert.equal(tail.issues[499].number, 1500);
+  assert.equal(tail.total, 1500);
+  assert.equal(tail.hasNextPage, false);
+  const requested = calls().map((argv) => field(argv, 'first'));
+  assert.equal(requested.length, 15, 'ten server pages for the head request, five for the continuation');
+  assert.deepEqual(requested.slice(0, 10), Array(10).fill('100'));
+  assert.deepEqual(requested.slice(10), Array(5).fill('100'));
+  assert.ok(calls()[10].includes('cursor=c1000'), 'the continuation resumes at the last delivered row');
+  assert.equal(served[0], '1-100');
+  assert.equal(served[9], '901-1000');
+  assert.equal(served[10], '1001-1100');
+});
+
+test('the state filter is explicit and never collapses closed into open', async () => {
+  const cases = [
+    ['open', 'states: [OPEN]'],
+    ['closed', 'states: [CLOSED]'],
+    ['all', 'states: [OPEN, CLOSED]'],
+    ['CLOSED', 'states: [CLOSED]'],
+  ];
+  for (const [state, literal] of cases) {
+    const queries = [];
+    connectionRunner((argv) => {
+      queries.push(field(argv, 'query'));
+      return connection([], { totalCount: 0 });
+    });
+    const result = await gh.getIssueConnectionPage({ first: 5, state });
+    assert.equal(result.ok, true);
+    assert.equal(queries.length, 1);
+    assert.ok(queries[0].includes(literal), `${state} asks for ${literal}`);
+    if (state.toLowerCase() === 'closed') assert.doesNotMatch(queries[0], /OPEN/, 'a closed read never widens to open');
+  }
+  const calls = connectionRunner(() => connection([]));
+  for (const state of ['archived', 'OPEN,CLOSED', 0, true]) {
+    const bad = await gh.getIssueConnectionPage({ first: 5, state });
+    assert.equal(bad.ok, false);
+    assert.match(bad.error, /invalid issue state/);
+  }
+  assert.equal(calls().length, 0, 'an unknown state never reaches a subprocess');
+});
+
+test('a connection request refuses search text instead of silently ignoring it', async () => {
+  const calls = connectionRunner(() => connection([]));
+  for (const query of ['assignee:@me', 'sort:created-asc', 'is:closed']) {
+    const result = await gh.getIssueConnectionPage({ first: 5, query });
+    assert.equal(result.ok, false);
+    assert.match(result.error, /no search text/);
+  }
+  assert.equal(calls().length, 0, 'a refused request never reaches a subprocess');
+  const blank = await gh.getIssueConnectionPage({ first: 5, query: '   ' });
+  assert.equal(blank.ok, true, 'blank text is no text');
+});
+
+test('invalid connection page inputs produce no subprocess calls', async () => {
+  const calls = connectionRunner(() => connection([]));
+  for (const first of [0, -1, 1.5, NaN, 1001]) assert.equal((await gh.getIssueConnectionPage({ first })).ok, false);
+  for (const after of ['', 5, {}, []]) assert.equal((await gh.getIssueConnectionPage({ first: 5, after })).ok, false);
+  for (const params of [null, [], 'bad']) assert.equal((await gh.getIssueConnectionPage(params)).ok, false);
+  assert.equal(calls().length, 0);
+});
+
+test('GraphQL errors, malformed connections and duplicate rows are failures, never fake pages', async () => {
+  const failures = [
+    [ok({ errors: [{ message: 'Forbidden' }] }), /Forbidden/],
+    [ok({ data: { repository: { issues: { pageInfo: { hasNextPage: false }, edges: [] } } } }), /invalid issue page/],
+    [ok({ data: { repository: { issues: { totalCount: -1, pageInfo: { hasNextPage: false }, edges: [] } } } }), /invalid issue page/],
+    [connection([{ node: node(1) }]), /invalid issue cursor or duplicate issue/],
+    [connection([{ cursor: 'c1', node: node(1) }, { cursor: 'c1', node: node(2) }]), /invalid issue cursor or duplicate issue/],
+    [connection([{ cursor: 'c1', node: node(1) }, { cursor: 'c2', node: node(1) }]), /invalid issue cursor or duplicate issue/],
+    [connection([], { totalCount: 4, hasNextPage: true, endCursor: null }), /did not advance/],
+  ];
+  for (const [response, pattern] of failures) {
+    runner(() => response);
+    const result = await gh.getIssueConnectionPage({ first: 5 });
+    assert.equal(result.ok, false, `expected a failure for ${pattern}`);
+    assert.match(String(result.error), pattern);
+  }
+  let round = 0;
+  runner(() => {
+    round += 1;
+    const start = (round - 1) * 100 + 1;
+    return connection(
+      Array.from({ length: 100 }, (_, i) => ({ cursor: `c${start + i}`, node: node(start + i) })),
+      { totalCount: 500, hasNextPage: true, endCursor: 'same' },
+    );
+  });
+  const stalled = await gh.getIssueConnectionPage({ first: 200 });
+  assert.equal(stalled.ok, false);
+  assert.match(String(stalled.error), /did not advance/);
+  runner(() => connection(
+    [{ cursor: 'c1', node: node(1) }, { cursor: 'c2', node: node(2) }],
+    { totalCount: 10, hasNextPage: true, endCursor: 'c2' },
+  ));
+  const oversized = await gh.getIssueConnectionPage({ first: 1 });
+  assert.equal(oversized.ok, false);
+  assert.match(String(oversized.error), /exceeded the requested issue page size/);
+});
+
+test('a failed continuation page is a failure, never a short page', async () => {
+  let round = 0;
+  runner(() => {
+    round += 1;
+    if (round === 1) return connection(Array.from({ length: 100 }, (_, i) => ({ cursor: `c${i + 1}`, node: node(i + 1) })), { totalCount: 260, hasNextPage: true, endCursor: 'c100' });
+    return { status: 1, stdout: '', stderr: 'API rate limit exceeded', error: null };
+  });
+  const result = await gh.getIssueConnectionPage({ first: 150 });
+  assert.equal(result.ok, false);
+  assert.match(String(result.error), /API rate limit exceeded/);
+  assert.equal('issues' in result, false, 'no partial page is handed out as data');
+});
+
+test('a short server page stops the fill and keeps the server hasNextPage', async () => {
+  let round = 0;
+  runner(() => {
+    round += 1;
+    if (round === 1) return connection(Array.from({ length: 100 }, (_, i) => ({ cursor: `c${i + 1}`, node: node(i + 1) })), { totalCount: 400, hasNextPage: true, endCursor: 'c100' });
+    return connection(Array.from({ length: 20 }, (_, i) => ({ cursor: `c${101 + i}`, node: node(101 + i) })), { totalCount: 400, hasNextPage: true, endCursor: 'c120' });
+  });
+  const result = await gh.getIssueConnectionPage({ first: 150 });
+  assert.equal(result.ok, true);
+  assert.equal(result.issues.length, 120, 'a short page is honored, never refilled');
+  assert.equal(result.issues[119].cursor, 'c120', 'the caller continues from the last delivered row');
+  assert.equal(result.hasNextPage, true);
+  assert.equal(result.total, 400);
+});
+
+test('the typed-search path keeps its search semantics and its honest cap', async () => {
+  const calls = runner((argv) => {
+    assert.match(field(argv, 'search'), /is:open/);
+    assert.match(field(argv, 'search'), /sort:updated-desc/);
+    return ok({ data: { search: { issueCount: 12, pageInfo: { hasNextPage: true, endCursor: 'next' }, edges: [{ cursor: 'next', node: node(4) }] } } });
+  });
+  const result = await gh.getIssuePage({ query: 'assignee:@me', first: 7 });
+  assert.equal(result.ok, true);
+  assert.equal(result.total, 12);
+  assert.equal(result.issues[0].cursor, 'next');
+  runner(() => ok({ data: { search: { issueCount: 1001, pageInfo: { hasNextPage: true, endCursor: 'next' }, edges: [{ cursor: 'next', node: node(4) }] } } }));
+  const capped = await gh.getIssuePage({ first: 7 });
+  assert.equal(capped.ok, false);
+  assert.equal(capped.truncated, true);
+  assert.match(String(capped.error), /1000/);
+  assert.equal(calls.filter((argv) => argv[0] === 'api').length, 1);
+});