kushi-agents 5.7.0 → 5.7.2

package/README.md

@@ -260,6 +260,7 @@ npx kushi-agents --clawpilot                       # Clawpilot only
 npx kushi-agents --vscode                          # VS Code Chat only
 
 # Install to BOTH at once (auto-detects what's present + targets both)
+# v5.7.1+: when run from inside a project dir, also refreshes <cwd>/.kushi/.
 npx kushi-agents --all-hosts
 
 # Uninstall

package/bin/cli.mjs

@@ -182,10 +182,16 @@ if (args.includes('--help') || args.includes('-h')) {
     --clawpilot       Install to ~/.copilot/m-skills/kushi/
     --vscode          Install to ~/.vscode/chat/skills/kushi/  (a.k.a. GitHub Copilot Chat)
     --all-hosts       Install to BOTH hosts
+    --no-workspace    Skip the auto workspace install (host install only)
     --uninstall [--clawpilot|--vscode|--all]
                       Cleanly remove the kushi install + skills-metadata.json entry
                       from the chosen host(s). Default = all detected hosts.
 
+    Note: when run from inside a project directory (any of: package.json, .git,
+    .kushi/, Evidence/, etc.), host installs ALSO refresh the workspace
+    .kushi/ install in cwd. One command covers both. Pass --no-workspace to
+    suppress, or run from a non-project directory.
+
   Workspace install (legacy / default when no host flag is given):
     --target vscode     Install to <cwd>/.kushi/ + update .vscode/settings.json   [default]
     --target clawpilot  Alias for --clawpilot (kept for back-compat)
@@ -274,6 +280,7 @@ if (wantsVscode || wantsAllHosts || wantsUninstall) {
     all,
     uninstall: wantsUninstall,
     profile: getFlag('--profile'),
+    includeWorkspace: !args.includes('--no-workspace'),
   }).catch((err) => {
     console.error(`\n  ${err.message}\n`);
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.7.0",
+  "version": "5.7.2",
   "description": "Install Kushi — multi-source project evidence agent with Comprehensive Structured Capture (CSC) into weekly-only files across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. Meetings retain a sibling verbatim/ audit folder. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {
@@ -43,7 +43,7 @@
   },
   "license": "MIT",
   "scripts": {
-    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs src/sanitize-workiq-input.test.mjs src/detect-vertex-repo.test.mjs src/vertex-validate.test.mjs src/emit-vertex.e2e.test.mjs src/config-root-resolve.test.mjs src/forbidden-workiq-phrasings.test.mjs src/multi-host-install.test.mjs src/eval-aggregator.test.mjs src/eval-runner.test.mjs src/skill-creator.test.mjs src/skill-checker.test.mjs src/hooks-dispatcher.test.mjs src/parallel-refresh.test.mjs src/otel-emit.test.mjs src/teach.test.mjs src/schema-evolve.test.mjs src/global-wiki.test.mjs src/promote.test.mjs src/doctor.test.mjs src/setup-wizard.test.mjs src/cli-no-args.test.mjs src/cli-no-args-tty.test.mjs src/per-user-files.test.mjs src/layout-portable.test.mjs src/profile-coverage.test.mjs plugin/runners/test/unit/*.test.mjs",
+    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs src/sanitize-workiq-input.test.mjs src/detect-vertex-repo.test.mjs src/vertex-validate.test.mjs src/emit-vertex.e2e.test.mjs src/config-root-resolve.test.mjs src/forbidden-workiq-phrasings.test.mjs src/multi-host-install.test.mjs src/eval-aggregator.test.mjs src/eval-runner.test.mjs src/skill-creator.test.mjs src/skill-checker.test.mjs src/hooks-dispatcher.test.mjs src/parallel-refresh.test.mjs src/otel-emit.test.mjs src/teach.test.mjs src/schema-evolve.test.mjs src/global-wiki.test.mjs src/promote.test.mjs src/doctor.test.mjs src/setup-wizard.test.mjs src/cli-no-args.test.mjs src/cli-no-args-tty.test.mjs src/per-user-files.test.mjs src/layout-portable.test.mjs src/profile-coverage.test.mjs src/get-kushi-config.test.mjs plugin/runners/test/unit/*.test.mjs",
     "test:runners": "node --test plugin/runners/test/unit/*.test.mjs",
     "test:runners:integration": "node --test plugin/runners/test/integration/*.test.mjs",
     "test:integration:bootstrap": "node src/bootstrap-dryrun.integration.test.mjs",

package/plugin/learnings/cross-cutting.md

@@ -4,6 +4,65 @@ Newest on top. Format defined in [`README.md`](./README.md). Use this file when
 
 ---
 
+### 2026-05-29 — `[switch]` parameter collides with same-name local var in PowerShell
+
+**Symptom**: Calling `.\.kushi\lib\Get-KushiConfig.ps1 -Name 'm365-auth' -Raw` threw at the **call site**:
+
+```
+Get-KushiConfig.ps1: Cannot convert the "{ ...full file contents... }" value of type "System.String" to type "System.Management.Automation.SwitchParameter".
+```
+
+The error wrapped the entire file content as the failed-coercion value — confusing, because the user's invocation only passed `-Name '...' -Raw` (no positional value).
+
+**Root cause**: PowerShell variables are **case-insensitive**. The script declared `[switch] $Raw` as a parameter, then used a local `$raw = Get-Content -LiteralPath $resolved -Raw` to read the file. Those are the *same variable*. The string assignment to the typed switch parameter triggered SwitchParameter coercion, which fails on any non-empty string. Crucially, the error is reported at the *call site* (the `&` invocation line), not at the assignment line — so the symptom looked like a parameter-binding bug.
+
+**Fix shipped (v5.7.2, 2026-05-29)**: Renamed the local var to `$rawText` everywhere in `Get-KushiConfig.ps1`. Audited all other `[switch]` params in `plugin/lib/*.ps1` for the same collision pattern — none found.
+
+**Why it wasn't caught**: 280 unit tests cover only `.mjs` runners. `Get-KushiConfig.ps1` and other shipped `.ps1` libs had **zero** automated test coverage. Added `src/get-kushi-config.test.mjs` (3 tests) that installs kushi into a temp dir and invokes the live shipped script via `pwsh`, asserting no SwitchParameter coercion error in stderr. Now wired into `npm test` (283 tests).
+
+**Lesson**: Any `.ps1` file shipped to users needs *integration* tests that invoke the real script via `pwsh`, not just unit tests of the JS that calls it. Avoid using `[switch]` parameter names that collide with common local variable names (`$raw`, `$path`, `$name`, `$content`) — PS case-insensitivity makes the collision invisible until something assigns a value.
+
+---
+
+### 2026-05-29 — Two issues that silently broke `bootstrap` end-to-end on Windows
+
+**Symptom**: After v5.7.0 shipped the auto-chain (bootstrap → discover → refresh), users ran the chain on Windows and saw discover return `skipped_reason: EINVAL` for every source, then refresh exit 0 with zero pulls. The runner *appeared* to be working — `status: ok`, no error message — but no boundaries were filled.
+
+**Root causes** (two stacked):
+
+1. **Node 20.12+ refuses to spawn `.cmd`/`.bat` files without `shell:true`** (CVE-2024-27980 hardening). `lib/workiq.mjs` was using `spawn(exe, args, { shell: false })` and the Windows workiq distribution ships as a `workiq.cmd` shim. Every spawn returned `EINVAL` immediately. The runner caught it and recorded `skipped_reason: EINVAL` per-source, but didn't escalate — it looked like 7 individual source-not-available skips, not one runtime-level failure.
+2. **`resolveWorkiqBin()` only checked `~/.copilot/bin/workiq.cmd`**. Users who installed WorkIQ via `npm i -g @microsoft/workiq` had it at `C:\Users\<u>\AppData\Roaming\npm\workiq.cmd` — invisible to kushi, even though `workiq --version` worked fine in their shell.
+
+**Fixes shipped (v5.7.1, 2026-05-29)**:
+
+1. **`lib/workiq.mjs` `runProcess()` routes `.cmd`/`.bat` through `cmd.exe`** with `windowsVerbatimArguments: true`. Verbatim args preserve quoting in long CSC prompts.
+2. **`resolveWorkiqBin()` searches PATH first** (with `PATHEXT`-aware `whichSync`), falls back to `~/.copilot/bin/`. So `npm`-installed workiq is now picked up automatically.
+3. **Lesson for future runners**: a per-source `skipped_reason` in JSON output isn't a substitute for a top-level error. If every source returns the SAME error code, that's a runtime failure, not 7 missing-source signals. Consider adding a `runtime_error` envelope check in discover that flips the top-level `status` to `error` if ≥N sources skip with the same `EXXX` code.
+
+**Discovered during**: Soak test of v5.7.0 in `kushi-wp` workspace — discover printed `{"status":"ok",...}` with all 7 sources `skipped_reason: EINVAL`, refresh ran clean, but no boundary was actually filled. Symptom looked like "WorkIQ has nothing for this project" until the user ran `node -e "spawn(...)"` to repro the EINVAL.
+
+---
+
+### 2026-05-29 — Two-command install (`--all-hosts` then workspace) is the wrong default
+
+**Symptom**: User runs:
+
+```
+npx kushi-agents@latest --all-hosts --profile full
+cd <repo-root>-wp
+npx kushi-agents@latest --profile full
+```
+
+…and asks: *"this is weird running both. is there a better way?"*
+
+**Root cause**: The CLI dispatched on the presence of host flags. `--all-hosts` took the `runMultiHost()` code path which did host-only installs. `npx kushi-agents` (no flag) took the legacy `main.mjs` workspace-install path. The two paths were mutually exclusive, even though the user's mental model was *"install Kushi everywhere"* — both globally and in the current repo.
+
+**Fix shipped (v5.7.1)**: After the host loop in `runMultiHost()`, detect if cwd is a recognized project (uses the existing `findProjectMarker()` from `main.mjs` — `.git`, `package.json`, `.kushi/`, `Evidence/`, etc.). If yes, also call `main({ target: 'vscode', yes: true, force: true })` to refresh the workspace install. Suppress with `--no-workspace`. From a non-project directory, prints `Workspace install skipped` and only does host install.
+
+**Result**: `npx kushi-agents@latest --all-hosts --profile full` from inside a repo now does the entire install in one shot. Help text + `docs/getting-started/install.md` updated to recommend the unified form first; legacy two-command form preserved in a `<details>` block for users on shared dev machines.
+
+---
+
 ### 2026-05-29 — `bootstrap → "fill the templates" → refresh` is the wrong default
 
 **Symptom**: User runs `bootstrap Northwind`. Runner scaffolds folders + empty `boundaries.yml` + empty `integrations.yml`. SKILL.md tells the agent to reply *"now fill these two files and run refresh"*. User runs `refresh` immediately; refresh emits a configuration-blocked report and exits 0 with zero pulls. User's reaction: *"we know we need to fill them, why did the tool stop and ask? is this not a methodical do?"*

package/plugin/lib/Get-KushiConfig.ps1

@@ -180,12 +180,12 @@ Run ``npx kushi-agents@latest`` (vscode) or ``npx kushi-agents@latest --clawpilo
 
 if ($Path) { return $resolved }
 
-$raw = Get-Content -LiteralPath $resolved -Raw
+$rawText = Get-Content -LiteralPath $resolved -Raw
 
 if (-not $AllowPlaceholders) {
   $sentinelHit = $false
   foreach ($s in $script:Sentinels) {
-    if ($raw -like "*$s*") { $sentinelHit = $true; break }
+    if ($rawText -like "*$s*") { $sentinelHit = $true; break }
   }
   if ($sentinelHit) {
     throw @"
@@ -195,16 +195,16 @@ Edit the file with your actual values, or pass -AllowPlaceholders to bypass this
   }
 }
 
-if ($Raw) { return $raw }
+if ($Raw) { return $rawText }
 
 $parsed = switch ($ext) {
   'json' {
-    $raw | ConvertFrom-Json -Depth 100
+    $rawText | ConvertFrom-Json -Depth 100
   }
   { $_ -in 'yml','yaml' } {
     if (Get-Module -ListAvailable -Name 'powershell-yaml') {
       Import-Module powershell-yaml -ErrorAction Stop
-      ConvertFrom-Yaml -Yaml $raw
+      ConvertFrom-Yaml -Yaml $rawText
     } else {
       Write-Warning "powershell-yaml not installed; required-field validation skipped. Install with: Install-Module powershell-yaml -Scope CurrentUser"
       $null
@@ -223,5 +223,5 @@ Edit the file with your actual values, or pass -AllowPlaceholders to bypass this
   }
 }
 
-if ($null -eq $parsed) { return $raw }
+if ($null -eq $parsed) { return $rawText }
 return $parsed

package/plugin/runners/lib/workiq.mjs

@@ -4,15 +4,45 @@
 import { spawn } from 'node:child_process';
 import { platform } from 'node:os';
 import path from 'node:path';
-import { promises as fs } from 'node:fs';
+import { promises as fs, existsSync } from 'node:fs';
 
 /** Resolve the workiq binary for the current platform. */
 export function resolveWorkiqBin(explicit = process.env.KUSHI_WORKIQ_BIN) {
-  if (explicit) return explicit;
+  if (explicit) {
+    if (path.isAbsolute(explicit)) return explicit;
+    const found = whichSync(explicit);
+    return found || explicit;
+  }
+  // 1. Try PATH first (npm-installed workiq lands in AppData\Roaming\npm).
+  const onPath = whichSync(platform() === 'win32' ? 'workiq.cmd' : 'workiq');
+  if (onPath) return onPath;
+  // 2. Fallback to Clawpilot-managed location.
   if (platform() === 'win32') return path.join(process.env.USERPROFILE || '', '.copilot', 'bin', 'workiq.cmd');
   return path.join(process.env.HOME || '', '.copilot', 'bin', 'workiq');
 }
 
+function whichSync(name) {
+  const PATH = process.env.PATH || process.env.Path || '';
+  const sep = platform() === 'win32' ? ';' : ':';
+  const exts = platform() === 'win32'
+    ? (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')
+    : [''];
+  const hasExt = /\.[a-zA-Z0-9]{1,5}$/.test(name);
+  for (const dir of PATH.split(sep)) {
+    if (!dir) continue;
+    if (hasExt) {
+      const candidate = path.join(dir, name);
+      if (existsSync(candidate)) return candidate;
+      continue;
+    }
+    for (const ext of exts) {
+      const candidate = path.join(dir, name + ext);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
 /**
  * Ask WorkIQ a question. Returns the raw stdout text and any parsed CSC blocks.
  *
@@ -86,7 +116,20 @@ async function pathExists(p) { try { await fs.access(p); return true; } catch {
 
 function runProcess(exe, args, { timeoutMs, env }) {
   return new Promise((resolve, reject) => {
-    const child = spawn(exe, args, { env, shell: false });
+    // Node 20.12+ refuses to spawn .cmd/.bat on Windows without shell:true
+    // (CVE-2024-27980). Detect and route through cmd.exe explicitly with
+    // verbatim args so quoting in the prompt survives intact.
+    const isWinShim = platform() === 'win32' && /\.(cmd|bat)$/i.test(exe);
+    const spawnOpts = { env, shell: false };
+    let spawnExe = exe;
+    let spawnArgs = args;
+    if (isWinShim) {
+      const quoted = [exe, ...args].map(quoteForCmd).join(' ');
+      spawnExe = process.env.ComSpec || 'cmd.exe';
+      spawnArgs = ['/d', '/s', '/c', quoted];
+      spawnOpts.windowsVerbatimArguments = true;
+    }
+    const child = spawn(spawnExe, spawnArgs, spawnOpts);
     let stdout = '';
     let stderr = '';
     let timeoutTimer = null;
@@ -102,3 +145,10 @@ function runProcess(exe, args, { timeoutMs, env }) {
     child.on('close', code => { if (timeoutTimer) clearTimeout(timeoutTimer); resolve({ stdout, stderr, exitCode: code ?? 0 }); });
   });
 }
+
+function quoteForCmd(s) {
+  if (s === '' || /[\s"&|<>^()]/.test(s)) {
+    return '"' + String(s).replace(/"/g, '""') + '"';
+  }
+  return String(s);
+}

package/src/get-kushi-config.test.mjs

@@ -0,0 +1,69 @@
+// Regression tests for plugin/lib/Get-KushiConfig.ps1.
+//
+// History: v5.7.1 had a SwitchParameter coercion bug. The script's
+// [switch] $Raw parameter collided with a local $raw = Get-Content variable
+// (PowerShell variables are case-insensitive). Assigning a string into the
+// typed switch parameter caused "Cannot convert String to SwitchParameter"
+// at the call site whenever the script was invoked from outside its own
+// scope.
+//
+// These tests install kushi into a temp dir, then invoke the live shipped
+// Get-KushiConfig.ps1 with various flag combinations and assert that the
+// invocation succeeds with no error stream output.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(HERE, '..');
+
+function makeTmp(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function freshInstall() {
+  const cwd = makeTmp('kushi-getconfig-');
+  const r = spawnSync(process.execPath, [path.join(REPO, 'bin', 'cli.mjs'), '--profile', 'full', '--skip-workiq-check', '--yes'], {
+    cwd, encoding: 'utf-8', shell: false,
+  });
+  assert.equal(r.status, 0, `installer failed: ${r.stderr || r.stdout}`);
+  return cwd;
+}
+
+function pwsh(cwd, args) {
+  return spawnSync('pwsh', ['-NoProfile', '-Command', ...args], {
+    cwd, encoding: 'utf-8', shell: false,
+  });
+}
+
+test('Get-KushiConfig.ps1 -Name m365-auth -Raw does not raise SwitchParameter coercion error', () => {
+  const cwd = freshInstall();
+  const script = path.join(cwd, '.kushi', 'lib', 'Get-KushiConfig.ps1');
+  const r = pwsh(cwd, [`& '${script}' -Name 'm365-auth' -Raw -AllowPlaceholders | Out-Null; if ($?) { 'OK' } else { 'FAIL' }`]);
+  assert.equal(r.status, 0, `pwsh exited ${r.status}; stderr=${r.stderr}`);
+  assert.match(r.stdout, /OK/, `expected OK, got stdout=${r.stdout} stderr=${r.stderr}`);
+  assert.doesNotMatch(r.stderr, /SwitchParameter/i, `SwitchParameter coercion error leaked: ${r.stderr}`);
+});
+
+test('Get-KushiConfig.ps1 -Name project-evidence -AllowPlaceholders -Raw works on fresh install', () => {
+  const cwd = freshInstall();
+  const script = path.join(cwd, '.kushi', 'lib', 'Get-KushiConfig.ps1');
+  const r = pwsh(cwd, [`& '${script}' -Name 'project-evidence' -AllowPlaceholders -Raw | Out-Null; if ($?) { 'OK' } else { 'FAIL' }`]);
+  assert.equal(r.status, 0, `pwsh exited ${r.status}; stderr=${r.stderr}`);
+  assert.match(r.stdout, /OK/, `expected OK, got stdout=${r.stdout} stderr=${r.stderr}`);
+  assert.doesNotMatch(r.stderr, /SwitchParameter/i, `SwitchParameter coercion error leaked: ${r.stderr}`);
+});
+
+test('Get-KushiConfig.ps1 -Path returns absolute resolved path', () => {
+  const cwd = freshInstall();
+  const script = path.join(cwd, '.kushi', 'lib', 'Get-KushiConfig.ps1');
+  const r = pwsh(cwd, [`& '${script}' -Name 'm365-auth' -Path`]);
+  assert.equal(r.status, 0, `pwsh exited ${r.status}; stderr=${r.stderr}`);
+  assert.match(r.stdout, /m365-auth\.json/, `expected resolved path, got stdout=${r.stdout}`);
+  assert.doesNotMatch(r.stderr, /SwitchParameter/i);
+});

package/src/main.mjs

@@ -394,7 +394,7 @@ function warnIfNotProjectRoot(projectRoot) {
  * @param {string} dir
  * @returns {{ name: string, kind: 'code'|'engagement', type: 'file'|'dir' } | null}
  */
-function findProjectMarker(dir) {
+export function findProjectMarker(dir) {
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });

package/src/multi-host.mjs

@@ -37,6 +37,7 @@ import {
 import { copyAssets } from './copy-assets.mjs';
 import { installRunnerDeps } from './install-runner-deps.mjs';
 import { seedConfig } from './seed-config.mjs';
+import { findProjectMarker } from './main.mjs';
 import {
   resolveProfile,
   makeIncludeFilter,
@@ -275,6 +276,40 @@ export async function runMultiHost(opts) {
       results.push(installHost(t.id, { home, force: true, profile: opts.profile }));
     }
   }
+
+  // Unified install (v5.7.1+): when the user upgrades hosts AND is sitting in
+  // a project directory, also refresh the workspace `.kushi/` install in cwd.
+  // This collapses the historical two-command dance:
+  //   npx kushi-agents@latest --all-hosts --profile full
+  //   cd <repo> && npx kushi-agents@latest --profile full
+  // into a single invocation. Suppress with `--no-workspace`. Skipped on
+  // uninstall and when cwd is not a recognized project (no marker, empty dir,
+  // or just plain files).
+  if (!opts.uninstall && opts.includeWorkspace !== false) {
+    const cwd = opts.cwd || process.cwd();
+    const marker = findProjectMarker(cwd);
+    if (marker) {
+      console.log('');
+      console.log(`  Workspace install detected (${marker.kind}: ${marker.name}) — installing into ${cwd}/.kushi/ ...`);
+      try {
+        const { main } = await import('./main.mjs');
+        await main({
+          target: 'vscode',
+          yes: true,
+          force: true,
+          profile: opts.profile,
+          skipWorkiqCheck: true,
+        });
+      } catch (err) {
+        console.error(`  Workspace install failed: ${err.message}`);
+      }
+    } else {
+      console.log('');
+      console.log('  Workspace install skipped — current directory is not a recognized project.');
+      console.log('  (cd into a repo or engagement folder and re-run, or pass --no-workspace to silence.)');
+    }
+  }
+
   console.log('');
   console.log(`  Done. ${results.length} host(s) processed.\n`);
   return results;