heyspex 0.2.2 → 0.2.4

package/scripts/copilot-statusline.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// HeySpex status line for GitHub Copilot CLI.
+//
+// Wired by `hs setup copilot --statusline` as `statusLine.command` in
+// <COPILOT_HOME or ~/.copilot>/settings.json. Copilot pipes session status JSON on
+// stdin and shows the first stdout line.
+//
+// This file is only a thin input adapter. All segment logic (model, repo > branch,
+// pinned epic, claimed/relevant spec) is the Claude Code renderer's build() in
+// scripts/claude-statusline/statusline-command.mjs, called with host:'copilot'
+// (no Claude glyph, no Haiku label, no transcript scan, cache-only pin read).
+//
+// Contract: exit 0 always; never print an error or stack trace; on any failure or a
+// hard 1.5 s budget overrun print the minimal "HeySpex" line. Plain ASCII-safe
+// output (marker is "[HS]" unless HEYSPEX_STATUSLINE_GLYPH=1 and the font is installed).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { build } from './claude-statusline/statusline-command.mjs';
+import { isMainModule } from './lib/shared-path-helpers.mjs';
+
+export const FALLBACK_LINE = 'HeySpex';
+const STDIN_TIMEOUT_MS = 500;
+const HARD_BUDGET_MS = 1500;
+
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const str = (v) => (typeof v === 'string' && v.trim() ? v : null);
+
+/** Copilot statusLine JSON -> the Claude-shaped session object build() reads. Never throws. */
+export function adaptCopilotSession(input) {
+  const j = input && typeof input === 'object' ? input : {};
+  const cw = j.context_window && typeof j.context_window === 'object' ? j.context_window : {};
+  const dir = str(j.workspace?.current_dir) ?? str(j.cwd);
+  const used = num(cw.current_context_used_percentage) ?? num(cw.used_percentage);
+  const inTok = num(cw.total_input_tokens);
+  const outTok = num(cw.total_output_tokens);
+  const context_window = {};
+  // Zero tokens means "no API call yet" in Copilot; render nothing rather than "0 tok".
+  if (inTok !== null && inTok + (outTok ?? 0) > 0) {
+    context_window.total_input_tokens = inTok;
+    context_window.total_output_tokens = outTok ?? 0;
+  }
+  if (used !== null) context_window.remaining_percentage = 100 - used;
+  return {
+    session_id: str(j.session_id),
+    cwd: dir,
+    workspace: { current_dir: dir },
+    model: { display_name: str(j.model?.display_name) ?? str(j.model?.id) },
+    context_window,
+  };
+}
+
+/** Nearest dir at or above `start` holding .git or heyspex.yaml; else `start`. */
+export function findRoot(start) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'heyspex.yaml'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) return path.resolve(start);
+    dir = up;
+  }
+}
+
+/** `hs mode off` honoured like the Claude line: env first, then <root>/<dot>heyspex/mode.json. */
+function modeIsOff(root) {
+  try {
+    const raw = String(process.env.HEYSPEX_MODE ?? '').trim().toLowerCase();
+    if (raw) return ['off', '0', 'false', 'disabled', 'disable', 'no'].includes(raw);
+    return JSON.parse(fs.readFileSync(path.join(root, '.heyspex', 'mode.json'), 'utf8'))?.mode === 'off';
+  } catch {
+    return false;
+  }
+}
+
+/** Render one line for raw stdin text. Returns '' when HeySpex is switched off. Never throws. */
+export async function renderLine(raw) {
+  try {
+    let parsed = null;
+    try { parsed = raw && raw.trim() ? JSON.parse(raw) : null; } catch { parsed = null; }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return FALLBACK_LINE;
+    const session = adaptCopilotSession(parsed);
+    const root = findRoot(session.cwd ?? process.cwd());
+    if (modeIsOff(root)) return '';
+    const line = await build(root, session, { host: 'copilot' });
+    return (line ?? '').split(/\r?\n/)[0].trim() || FALLBACK_LINE;
+  } catch {
+    return FALLBACK_LINE;
+  }
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve('');
+    const chunks = [];
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(Buffer.concat(chunks).toString('utf8'));
+    };
+    const timer = setTimeout(finish, STDIN_TIMEOUT_MS);
+    try {
+      process.stdin.on('data', (c) => chunks.push(Buffer.from(c)));
+      process.stdin.on('end', finish);
+      process.stdin.on('error', finish);
+    } catch {
+      finish();
+    }
+  });
+}
+
+async function main() {
+  const hard = setTimeout(() => {
+    try { process.stdout.write(`${FALLBACK_LINE}\n`); } catch { /* ignore */ }
+    process.exit(0);
+  }, HARD_BUDGET_MS);
+  const line = await renderLine(await readStdin());
+  clearTimeout(hard);
+  if (line) process.stdout.write(`${line}\n`);
+  process.exit(0);
+}
+
+if (isMainModule(import.meta.url)) {
+  main().catch(() => {
+    try { process.stdout.write(`${FALLBACK_LINE}\n`); } catch { /* ignore */ }
+    process.exit(0);
+  });
+}

package/scripts/dev-server-status.mjs

@@ -37,7 +37,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import http from 'node:http';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { isMainModule } from './lib/shared-path-helpers.mjs';
 
 // The runnable form of a HeySpex command on THIS machine — `hs …` when the bin
 // is on PATH, else an absolute-path `node "<install>/bin/hs.mjs" …`. Never an
@@ -722,7 +723,7 @@ export function summarizeStatus(status) {
 
 // ---- CLI entrypoint --------------------------------------------------------
 
-const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly = isMainModule(import.meta.url);
 if (invokedDirectly) {
   const asJson = process.argv.includes('--json');
   getDevServerStatus()

package/scripts/dev-server-stop.mjs

@@ -23,7 +23,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { isMainModule } from './lib/shared-path-helpers.mjs';
 
 import { getDevServerStatus, summarizeStatus } from './dev-server-status.mjs';
 
@@ -276,7 +277,7 @@ export async function stopDevServer({ vaultRoot, forcePorts = false, dryRun = fa
   };
 }
 
-const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly = isMainModule(import.meta.url);
 if (invokedDirectly) {
   const asJson = process.argv.includes('--json');
   const dryRun = process.argv.includes('--dry-run');

package/scripts/hs-capture-cli.mjs

@@ -22,7 +22,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { randomUUID } from "node:crypto";
-import { pathToFileURL } from "node:url";
+import { isMainModule } from "./lib/shared-path-helpers.mjs";
 
 import { resolveConsoleUrl, DEFAULT_CONSOLE_URL } from "./lib/console-url-resolver.mjs";
 import { heyspexHome } from "./lib/heyspex-home.mjs";
@@ -318,7 +318,7 @@ async function main() {
 // Guard so this module can be `import`ed (e.g. by hs-capture-cli.test.mjs)
 // without running main() — bin/hs.mjs spawns this file as a child process
 // with the file path as argv[1], so this only fires under that spawn.
-if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+if (isMainModule(import.meta.url)) {
   main().catch((err) => {
     process.stderr.write(`hs capture: ${err.message}\n`);
     process.exit(1);

package/scripts/hs-settings.mjs

@@ -25,7 +25,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-import { pathToFileURL } from 'node:url';
+import { isMainModule } from './lib/shared-path-helpers.mjs';
 
 import {
   listConfigLeaves,
@@ -328,7 +328,7 @@ function main(argv) {
 // helpers (buildListEntries, isHeyspexPlatformVault, …).
 const isMain = (() => {
   try {
-    return import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
+    return isMainModule(import.meta.url);
   } catch {
     return false;
   }

package/scripts/hs-view.mjs

@@ -23,7 +23,8 @@
  */
 import { spawn } from 'node:child_process';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { isMainModule } from './lib/shared-path-helpers.mjs';
 
 import { getDevServerStatus } from './dev-server-status.mjs';
 import { resolveConsoleUrl, DEFAULT_CONSOLE_URL } from './lib/console-url-resolver.mjs';
@@ -488,7 +489,7 @@ async function main() {
 
 // Run only as the CLI entry point. Without this guard, importing the module —
 // which is how `resolveWindowWidth` is tested — would spawn a browser window.
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+if (isMainModule(import.meta.url)) {
   main().catch((err) => {
     process.stderr.write(`hs view: ${err?.message || err}\n`);
     process.exitCode = 1;

package/scripts/install-copilot-hooks.mjs

@@ -12,12 +12,15 @@
 //   node scripts/install-copilot-hooks.mjs --print    # agent-facing instructions to stdout
 //   --target <dir>   repo to set up (default: cwd's repo root, walking up to .git / heyspex.yaml)
 //   --json           (with --check) machine-readable report
+//   --statusline     install ONLY the HeySpex status line: merges `statusLine` into <COPILOT_HOME or ~/.copilot>/settings.json
+//                    (backup kept; a foreign statusLine is left alone unless --force). With --uninstall removes only ours.
+//   --force          (with --statusline) replace a non-HeySpex statusLine
 //
 // Single-source rule: the plugin OR the repo hooks file, never both (every hook would fire twice).
 //
 // Exit codes:
-//   0  success / nothing to do / `copilot` missing (commands printed for the user to run)
-//   1  failure: plugin route could not complete, --check found a problem, unexpected error
+//   0  success / nothing to do
+//   1  failure: no Copilot CLI found (nothing installed), plugin route could not complete, --check found a problem, unexpected error
 //   2  refused: --hooks while the heyspex plugin is installed for Copilot, or bad arguments
 //
 // Never prints a stack trace; every path ends with a next step.
@@ -29,9 +32,11 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import { detectDoubleFire, invokedDirectly, renderGithubHooksText } from './lib/customer-kit.mjs';
+import { COPILOT_PREREQUISITE, copilotHomeDir, parsePluginList, resolveCopilotCli } from './lib/copilot-cli.mjs';
 
 export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export const HOOKS_REL = ['.github', 'hooks', 'heyspex.json'];
+export const STATUSLINE_REL = ['scripts', 'copilot-statusline.mjs'];
 const FALLBACK = { marketplace: 'heyspex-marketplace', plugin: 'heyspex' };
 
 const fsDeps = {
@@ -72,10 +77,12 @@ export function findRepoRoot(start) {
 }
 
 function parseArgs(argv) {
-  const a = { hooks: false, check: false, uninstall: false, print: false, json: false, target: null, bad: null };
+  const a = { hooks: false, statusline: false, force: false, check: false, uninstall: false, print: false, json: false, target: null, bad: null };
   for (let i = 0; i < argv.length; i++) {
     const x = argv[i];
     if (x === '--hooks') a.hooks = true;
+    else if (x === '--statusline') a.statusline = true;
+    else if (x === '--force') a.force = true;
     else if (x === '--check') a.check = true;
     else if (x === '--uninstall') a.uninstall = true;
     else if (x === '--print') a.print = true;
@@ -89,35 +96,46 @@ function parseArgs(argv) {
   return a;
 }
 
-function copilotRun(args) {
+/**
+ * Run the resolved Copilot CLI (PATH first, then the Copilot app's bundled copy, see lib/copilot-cli.mjs).
+ * A `.cmd`/`.bat` shim on Windows needs a shell; a real `copilot.exe` is spawned directly.
+ */
+function copilotRun(cli, args) {
+  if (!cli) return { status: 127, out: '', missing: true };
   try {
-    // Windows needs a shell to resolve copilot.cmd; args are constants or the package path, so quote the latter.
-    const win = process.platform === 'win32';
-    const argv = win ? args.map((x) => (/[\s&()^]/.test(x) ? `"${x}"` : x)) : args;
-    const r = spawnSync('copilot', argv, { encoding: 'utf8', shell: win, timeout: 120000 });
+    const shim = process.platform === 'win32' && /\.(cmd|bat)$/i.test(cli.path);
+    const quote = (x) => (/[\s&()^]/.test(x) ? `"${x}"` : x);
+    const r = spawnSync(shim ? quote(cli.path) : cli.path, shim ? args.map(quote) : args, { encoding: 'utf8', shell: shim, timeout: 120000, env: process.env });
     return { status: r.error ? 127 : (r.status ?? 1), out: `${r.stdout ?? ''}${r.stderr ?? ''}`, missing: !!r.error };
   } catch {
     return { status: 127, out: '', missing: true };
   }
 }
 
-function copilotOnPath() {
-  const r = copilotRun(['--version']);
-  return !r.missing && r.status === 0;
+/** Resolve the CLI once and confirm it runs; returns { path, source, version? } or null. */
+function locateCopilot() {
+  const cli = resolveCopilotCli();
+  if (!cli) return null;
+  const r = copilotRun(cli, ['--version']);
+  return !r.missing && r.status === 0 ? cli : null;
 }
 
+const describeCli = (cli) => (cli ? `${cli.path} (${cli.source === 'app' ? 'Copilot app' : 'PATH'})` : 'not found');
+
 const q = (s) => `'${s.replace(/'/g, "''")}'`;
 const nextCommand = () => 'npx heyspex setup copilot';
 
 /** Is the heyspex plugin installed for Copilot? Combines detectDoubleFire evidence with `copilot plugin list`. */
-function pluginEvidence(targetRoot, copilotAvailable) {
-  const df = detectDoubleFire({ targetRoot, home: os.homedir(), deps: fsDeps });
+function pluginEvidence(targetRoot, cli) {
+  const copilotHome = copilotHomeDir();
+  const df = detectDoubleFire({ targetRoot, home: os.homedir(), copilotHome, deps: fsDeps });
   // Only Copilot-side evidence counts: a Claude Code plugin install (~/.claude) is not a Copilot install.
-  const evidence = df.plugin === true ? df.evidence.filter((e) => /[/\\]\.copilot[/\\]/.test(e)) : [];
+  const evidence = df.plugin === true ? df.evidence.filter((e) => e.includes(copilotHome)) : [];
   let plugin = evidence.length > 0;
-  if (copilotAvailable) {
-    const r = copilotRun(['plugin', 'list']);
-    if (r.status === 0 && /heyspex/i.test(r.out)) {
+  if (cli) {
+    const r = copilotRun(cli, ['plugin', 'list']);
+    const listed = parsePluginList(r.out);
+    if (r.status === 0 && listed.enabled) {
       plugin = true;
       evidence.push('`copilot plugin list` names heyspex');
     }
@@ -139,6 +157,80 @@ function hooksFileState(target) {
   return { file, exists: true, ours, current: raw.replace(/\r\n/g, '\n') === renderGithubHooksText() };
 }
 
+// ---- status line (opt-in) ---------------------------------------------------------------------------
+
+export const STATUSLINE_REFRESH_SECS = 30;
+const settingsPath = () => path.join(copilotHomeDir(), 'settings.json');
+
+/** The statusLine command: node + the INSTALLED script, quoted so paths with spaces survive cmd.exe and sh. */
+export function statuslineCommand(pkgRoot = PACKAGE_ROOT, platform = process.platform) {
+  const script = path.join(pkgRoot, ...STATUSLINE_REL);
+  return platform === 'win32' ? `node "${script}"` : `node '${script.replace(/'/g, "'\\''")}'`;
+}
+
+export const isOurStatusLine = (sl) => !!sl && typeof sl === 'object' && typeof sl.command === 'string' && /copilot-statusline\.mjs/.test(sl.command);
+
+/** { file, exists, json, statusLine, error } for <COPILOT_HOME>/settings.json. */
+export function readCopilotSettings(file = settingsPath()) {
+  const raw = fsDeps.readFile(file);
+  if (raw === null) return { file, exists: false, json: {}, statusLine: null, error: null };
+  try {
+    const json = raw.trim() ? JSON.parse(raw) : {};
+    if (!json || typeof json !== 'object' || Array.isArray(json)) throw new Error('not a JSON object');
+    return { file, exists: true, json, statusLine: json.statusLine ?? null, error: null };
+  } catch (e) {
+    return { file, exists: true, json: null, statusLine: null, error: e?.message ?? String(e) };
+  }
+}
+
+function backupSettings(file) {
+  const bak = `${file}.heyspex-bak`;
+  if (!fs.existsSync(bak)) fs.copyFileSync(file, bak);
+  return bak;
+}
+
+function writeSettings(file, json) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(json, null, 2)}
+`, 'utf8');
+}
+
+function doStatusline(a, out, err) {
+  const script = path.join(PACKAGE_ROOT, ...STATUSLINE_REL);
+  const st = readCopilotSettings();
+  if (a.uninstall) {
+    if (st.error) { err(`hs setup copilot --statusline --uninstall: ${st.file} is not valid JSON (${st.error}); not touching it.`); return 1; }
+    if (!st.statusLine) { out(`no statusLine in ${st.file}; nothing to remove`); return 0; }
+    if (!isOurStatusLine(st.statusLine)) { out(`left the statusLine in ${st.file} alone: it is not the HeySpex one`); return 0; }
+    backupSettings(st.file);
+    const { statusLine: _drop, ...rest } = st.json;
+    writeSettings(st.file, rest);
+    out(`removed the HeySpex statusLine from ${st.file} (other keys kept; backup ${st.file}.heyspex-bak)`);
+    return 0;
+  }
+  if (!fs.existsSync(script)) {
+    err(`hs setup copilot --statusline: ${script} not found. The heyspex package looks incomplete; run \`npm install heyspex@latest\` and retry.`);
+    return 1;
+  }
+  if (st.error) { err(`hs setup copilot --statusline: ${st.file} is not valid JSON (${st.error}); fix or move it, then re-run. Nothing was changed.`); return 1; }
+  if (st.statusLine && !isOurStatusLine(st.statusLine) && !a.force) {
+    err(`hs setup copilot --statusline: ${st.file} already has a non-HeySpex statusLine (${JSON.stringify(st.statusLine.command ?? st.statusLine)}); not overwriting it.`);
+    err('Re-run with --force to replace it (a backup is kept).');
+    return 2;
+  }
+  const next = { type: 'command', command: statuslineCommand(), refreshInterval: STATUSLINE_REFRESH_SECS };
+  if (JSON.stringify(st.statusLine) === JSON.stringify(next)) {
+    out(`already current: statusLine in ${st.file}`);
+  } else {
+    if (st.exists) out(`backup: ${backupSettings(st.file)}`);
+    writeSettings(st.file, { ...st.json, statusLine: next });
+    out(`${st.statusLine ? 'updated' : 'wrote'} statusLine in ${st.file}`);
+  }
+  if (/[\\/]_npx[\\/]/.test(PACKAGE_ROOT)) out('WARNING: this ran from the npx cache, which can be pruned. Run it from a project that has heyspex installed (npm install heyspex) so the path stays valid.');
+  out('Next: restart Copilot (or /restart); the status line renders in interactive sessions only.');
+  return 0;
+}
+
 function manualCommands(spec) {
   return [
     `copilot plugin marketplace add ${q(PACKAGE_ROOT)}`,
@@ -161,8 +253,8 @@ function doPrint(out) {
 
 function doCheck(a, target, out) {
   const spec = resolvePluginSpec(PACKAGE_ROOT);
-  const hasCopilot = copilotOnPath();
-  const ev = pluginEvidence(target, hasCopilot);
+  const cli = locateCopilot();
+  const ev = pluginEvidence(target, cli);
   const hooks = hooksFileState(target);
   const route = ev.plugin && hooks.exists ? 'both' : ev.plugin ? 'plugin' : hooks.exists ? 'hooks' : 'none';
   const problems = [];
@@ -171,7 +263,12 @@ function doCheck(a, target, out) {
   if (route === 'hooks' && !hooks.ours) problems.push('.github/hooks/heyspex.json is not a HeySpex file');
   if (route === 'hooks' && hooks.ours && !hooks.current) problems.push('.github/hooks/heyspex.json is stale; re-run `npx heyspex setup copilot --hooks`');
   if (route === 'none') problems.push(`no route active; run \`${nextCommand()}\` (plugin) or \`${nextCommand()} --hooks\``);
-  const report = { route, plugin: ev.plugin, pluginEvidence: ev.evidence, hooksFile: hooks.exists, hooksFilePath: hooks.file, hooksCurrent: hooks.current, marketplaceManifest: spec.present, marketplacePath: spec.manifest, copilotOnPath: hasCopilot, problems };
+  if (!cli && route === 'none') problems.push(`Copilot CLI not found (not on PATH, no Copilot app copy). ${COPILOT_PREREQUISITE}`);
+  const sl = readCopilotSettings();
+  const slState = sl.error ? 'unreadable' : !sl.statusLine ? 'absent' : isOurStatusLine(sl.statusLine) ? 'heyspex' : 'foreign';
+  const slScriptOk = fs.existsSync(path.join(PACKAGE_ROOT, ...STATUSLINE_REL));
+  if (slState === 'heyspex' && !slScriptOk) problems.push('statusLine points at a HeySpex script that is missing from this package; re-run `npx heyspex setup copilot --statusline`');
+  const report = { statusLine: slState, settingsPath: sl.file, route, plugin: ev.plugin, pluginEvidence: ev.evidence, hooksFile: hooks.exists, hooksFilePath: hooks.file, hooksCurrent: hooks.current, marketplaceManifest: spec.present, marketplacePath: spec.manifest, copilotCli: cli, copilotHome: copilotHomeDir(), problems };
   if (a.json) out(JSON.stringify(report, null, 2));
   else {
     out(`hs setup copilot --check (target ${target})`);
@@ -179,7 +276,9 @@ function doCheck(a, target, out) {
     out(`  plugin installed: ${ev.plugin ? 'yes' : 'no'}${ev.evidence.length ? ` (${ev.evidence.join('; ')})` : ''}`);
     out(`  hooks file: ${hooks.exists ? `present${hooks.ours ? '' : ' (not HeySpex)'}${hooks.current ? ', current' : ', stale'}` : 'absent'}`);
     out(`  marketplace manifest in package: ${spec.present ? 'present' : 'MISSING'}`);
-    out(`  copilot CLI on PATH: ${hasCopilot ? 'yes' : 'no'}`);
+    out(`  copilot CLI: ${describeCli(cli)}`);
+    out(`  statusLine: ${slState}${slState === 'heyspex' ? ` (${sl.statusLine.command})` : slState === 'foreign' ? ` (${JSON.stringify(sl.statusLine.command ?? sl.statusLine)}; not ours)` : slState === 'absent' ? ' (opt in: `npx heyspex setup copilot --statusline`)' : ` (${sl.error})`} in ${sl.file}`);
+    if (process.env.COPILOT_HOME) out(`  COPILOT_HOME: ${copilotHomeDir()}`);
     for (const p of problems) out(`  PROBLEM: ${p}`);
     if (!problems.length) out('  ok');
   }
@@ -187,7 +286,7 @@ function doCheck(a, target, out) {
 }
 
 function doHooks(target, out, err) {
-  const ev = pluginEvidence(target, copilotOnPath());
+  const ev = pluginEvidence(target, locateCopilot());
   if (ev.plugin) {
     err(`hs setup copilot --hooks refused: the heyspex plugin is already installed for Copilot (${ev.evidence.join('; ')}).`);
     err('Plugin OR hooks, never both (every hook would fire twice). Remove the plugin first: `copilot plugin uninstall heyspex`.');
@@ -222,20 +321,23 @@ function doPlugin(target, out, err) {
     out(`WARNING: ${hooks.file} already exists. Plugin OR hooks, never both (every hook would fire twice). Remove it with \`npx heyspex setup copilot --uninstall\` after the plugin is installed.`);
   }
   const cmds = manualCommands(spec.spec);
-  if (!copilotOnPath()) {
-    out('`copilot` is not on PATH. Install GitHub Copilot CLI, then run these two commands:');
-    for (const c of cmds) out(`  ${c}`);
-    out('Then /restart in Copilot and verify with `copilot plugin list` and `npx heyspex doctor`.');
-    return 0;
+  const cli = locateCopilot();
+  if (!cli) {
+    err('hs setup copilot: GitHub Copilot CLI not found (not on PATH, and no Copilot app copy under %LOCALAPPDATA%\\github-copilot-sdk\\cli). Nothing was installed.');
+    err(COPILOT_PREREQUISITE);
+    err('Then re-run `npx heyspex setup copilot`, or run these two commands by hand:');
+    for (const c of cmds) err(`  ${c}`);
+    return 1;
   }
-  const add = copilotRun(['plugin', 'marketplace', 'add', PACKAGE_ROOT]);
+  out(`using Copilot CLI: ${describeCli(cli)}`);
+  const add = copilotRun(cli, ['plugin', 'marketplace', 'add', PACKAGE_ROOT]);
   if (add.status !== 0 && !/already/i.test(add.out)) {
     err(`copilot plugin marketplace add failed:\n${add.out.trim().slice(-600)}`);
     err('Run these by hand and report the output:');
     for (const c of cmds) err(`  ${c}`);
     return 1;
   }
-  const inst = copilotRun(['plugin', 'install', spec.spec]);
+  const inst = copilotRun(cli, ['plugin', 'install', spec.spec]);
   if (inst.status !== 0 && !/already/i.test(inst.out)) {
     err(`copilot plugin install failed:\n${inst.out.trim().slice(-600)}`);
     err('Run this by hand and report the output:');
@@ -247,16 +349,29 @@ function doPlugin(target, out, err) {
   return 0;
 }
 
-function doUninstall(target, out) {
+function doUninstall(target, out, err) {
   const hooks = hooksFileState(target);
   if (!hooks.exists) out(`no hooks file at ${hooks.file}`);
   else if (!hooks.ours) out(`left ${hooks.file} alone: it is not a HeySpex-only file`);
   else { fs.rmSync(hooks.file, { force: true }); out(`removed ${hooks.file}`); }
   const cmd = 'copilot plugin uninstall heyspex';
-  if (copilotOnPath()) {
-    const r = copilotRun(['plugin', 'uninstall', 'heyspex']);
-    out(r.status === 0 ? `ran \`${cmd}\`` : `\`${cmd}\` did not complete (it may not be installed): ${r.out.trim().slice(-200)}`);
-  } else out(`To remove the plugin, run: ${cmd}`);
+  const cli = locateCopilot();
+  if (cli) {
+    const r = copilotRun(cli, ['plugin', 'uninstall', 'heyspex']);
+    out(r.status === 0 ? `ran \`${cmd}\` via ${describeCli(cli)}` : `\`${cmd}\` did not complete (it may not be installed): ${r.out.trim().slice(-200)}`);
+    // A plugin loaded from a local marketplace is only DISABLED by `plugin uninstall` (it stays
+    // in `plugin list`), so drop the marketplace we registered too.
+    const mk = copilotRun(cli, ['plugin', 'marketplace', 'remove', resolvePluginSpec(PACKAGE_ROOT).marketplace]);
+    if (mk.status === 0) out(`removed marketplace ${resolvePluginSpec(PACKAGE_ROOT).marketplace}`);
+    return 0;
+  }
+  // No CLI: only an error when a plugin install is actually on record and could not be removed.
+  if (pluginEvidence(target, null).plugin) {
+    err(`hs setup copilot --uninstall: the heyspex plugin is installed for Copilot but no Copilot CLI was found to remove it. ${COPILOT_PREREQUISITE}`);
+    err(`Then run: ${cmd}`);
+    return 1;
+  }
+  out(`no heyspex plugin found for Copilot; nothing more to remove (to be sure, run: ${cmd})`);
   return 0;
 }
 
@@ -267,13 +382,14 @@ export function main(argv = process.argv.slice(2), io = {}) {
     const a = parseArgs(argv);
     if (a.bad) {
       err(`hs setup copilot: ${a.bad}`);
-      err('usage: hs setup copilot [--hooks] [--check [--json]] [--uninstall] [--print] [--target <dir>]');
+      err('usage: hs setup copilot [--hooks] [--statusline [--force]] [--check [--json]] [--uninstall] [--print] [--target <dir>]');
       return 2;
     }
     if (a.print) return doPrint(out);
     const target = a.target ? path.resolve(a.target) : findRepoRoot(process.env.HS_SETUP_TARGET?.trim() || process.cwd());
     if (a.check) return doCheck(a, target, out);
-    if (a.uninstall) return doUninstall(target, out);
+    if (a.statusline) return doStatusline(a, out, err);
+    if (a.uninstall) return doUninstall(target, out, err);
     if (a.hooks) return doHooks(target, out, err);
     return doPlugin(target, out, err);
   } catch (e) {

package/scripts/lib/copilot-cli.mjs

@@ -0,0 +1,108 @@
+// copilot-cli.mjs - find the GitHub Copilot CLI and its settings dir (HS-GLR5).
+//
+// `copilot` is not always on PATH: the Copilot Windows app ships the real CLI at
+// %LOCALAPPDATA%\github-copilot-sdk\cli\<version>\copilot.exe (the version folder changes on
+// every app update) and never adds it to PATH. Resolution order:
+//   1. `copilot` on PATH (npm -g @github/copilot, winget, brew ...)
+//   2. Windows only: the NEWEST %LOCALAPPDATA%\github-copilot-sdk\cli\<version>\copilot.exe
+// (macOS / Linux have no confirmed app-bundled location, so PATH is the only route there.)
+//
+// Pure + injectable (exists / listDir / env / platform) so it is unit-testable without a Copilot.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** What a user should install when no Copilot CLI can be found. Shown by setup, --check and the docs. */
+export const COPILOT_PREREQUISITE =
+  'GitHub Copilot CLI is required: install the GitHub Copilot app (auto-detected), or `npm install -g @github/copilot`, or `winget install GitHub.Copilot`.';
+
+const realDeps = {
+  exists: (p) => {
+    try { return fs.statSync(p).isFile(); } catch { return false; }
+  },
+  listDir: (p) => {
+    try { return fs.readdirSync(p); } catch { return []; }
+  },
+};
+
+/**
+ * Compare two Copilot version-folder names like `1.0.99-2` numerically, never lexically
+ * (`1.0.100` > `1.0.99`, `1.0.99-10` > `1.0.99-2`). A missing `-N` suffix counts as 0.
+ * Returns negative / 0 / positive like Array.sort.
+ */
+export function compareCopilotVersions(a, b) {
+  const parts = (v) => {
+    const [core, ...rest] = String(v).split('-');
+    const nums = core.split('.').map((x) => Number.parseInt(x, 10)).map((n) => (Number.isFinite(n) ? n : 0));
+    const suffix = Number.parseInt(rest.join('-'), 10);
+    return [...nums, Number.isFinite(suffix) ? suffix : 0];
+  };
+  const pa = parts(a);
+  const pb = parts(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+/** First `copilot` executable found on PATH, or null. Windows also tries .exe / .cmd / .bat. */
+export function findCopilotOnPath({ env = process.env, platform = process.platform, exists = realDeps.exists } = {}) {
+  const pathVar = env.PATH ?? env.Path ?? env.path ?? '';
+  const names = platform === 'win32' ? ['copilot.exe', 'copilot.cmd', 'copilot.bat'] : ['copilot'];
+  for (const dir of pathVar.split(path.delimiter).map((d) => d.trim().replace(/^"|"$/g, '')).filter(Boolean)) {
+    for (const n of names) {
+      const full = path.join(dir, n);
+      if (exists(full)) return full;
+    }
+  }
+  return null;
+}
+
+/** Newest app-bundled CLI under `<localAppData>\github-copilot-sdk\cli\<version>\copilot.exe`, or null. */
+export function findAppBundledCopilot({ localAppData, exists = realDeps.exists, listDir = realDeps.listDir } = {}) {
+  if (!localAppData) return null;
+  const root = path.join(localAppData, 'github-copilot-sdk', 'cli');
+  const versions = listDir(root)
+    .filter((v) => exists(path.join(root, v, 'copilot.exe')))
+    .sort(compareCopilotVersions);
+  const newest = versions.at(-1);
+  return newest ? { path: path.join(root, newest, 'copilot.exe'), version: newest } : null;
+}
+
+/**
+ * Resolve the Copilot CLI. Returns `{ path, source: 'path' | 'app', version? }` or null.
+ */
+export function resolveCopilotCli(opts = {}) {
+  const env = opts.env ?? process.env;
+  const platform = opts.platform ?? process.platform;
+  const exists = opts.exists ?? realDeps.exists;
+  const listDir = opts.listDir ?? realDeps.listDir;
+  const onPath = findCopilotOnPath({ env, platform, exists });
+  if (onPath) return { path: onPath, source: 'path' };
+  if (platform === 'win32') {
+    const app = findAppBundledCopilot({ localAppData: env.LOCALAPPDATA, exists, listDir });
+    if (app) return { ...app, source: 'app' };
+  }
+  return null;
+}
+
+/**
+ * Read `copilot plugin list` output for the heyspex plugin. A plugin loaded from a local
+ * marketplace is only DISABLED by `copilot plugin uninstall` and stays in the list marked
+ * `(disabled)`, so "listed" is not "installed": returns `{ listed, enabled }`.
+ */
+export function parsePluginList(out) {
+  const lines = String(out ?? '').split(/\r?\n/).filter((l) => /heyspex@/i.test(l));
+  return { listed: lines.length > 0, enabled: lines.some((l) => !/\(disabled\)|\[disabled\]/i.test(l)) };
+}
+
+/**
+ * Copilot's settings/state dir: `COPILOT_HOME` when set (Copilot's own override, see
+ * `copilot help environment`), else `<home>/.copilot`.
+ */
+export function copilotHomeDir({ env = process.env, home = os.homedir() } = {}) {
+  const override = typeof env.COPILOT_HOME === 'string' ? env.COPILOT_HOME.trim() : '';
+  return override ? path.resolve(override) : path.join(home, '.copilot');
+}