throughline 0.10.7 → 0.10.9

package/CHANGELOG.md

@@ -10,6 +10,24 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.10.9] — 2026-09-01
+
+### Fixed
+
+- `handoff-context --supplement-file`は、capture済みsessionに会話本文がまだ無い場合でも、
+  同じprojectに束縛された補足記憶だけを9,500字予算内で返す。Cursorの初回Workspace
+  Trust直後など、session行だけが先に作られたBotも記憶付きで再起動できる。
+- Windowsの子プロセスとowner-only ACL処理を、工場標準のPowerShell 7へ統一した。
+  製品CIも現行の3環境（macOS・Linux workstation・Windows native）を直接検証する。
+
+## [0.10.8] — 2026-09-01
+
+### Added
+
+- `handoff-context`へ任意の`--supplement-file`を追加した。補足JSONは元sessionの
+  `project_path`と一致する場合だけ、長期記憶・RAGとして既存の9,500字枠へ合成する。
+  DBの所有権と既存の補足なし出力は変えない。
+
 ## [0.10.7] — 2026-09-01
 
 ### Added
@@ -1379,7 +1397,9 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.10.7...HEAD
+[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.10.9...HEAD
+[0.10.9]: https://github.com/kitepon/Throughline/compare/v0.10.8...v0.10.9
+[0.10.8]: https://github.com/kitepon/Throughline/compare/v0.10.7...v0.10.8
 [0.10.7]: https://github.com/kitepon/Throughline/compare/v0.10.6...v0.10.7
 [0.10.6]: https://github.com/kitepon/Throughline/compare/v0.10.5...v0.10.6
 [0.10.5]: https://github.com/kitepon/Throughline/compare/v0.10.4...v0.10.5

package/README.ja.md

@@ -390,7 +390,7 @@ v0.10.4以前には `self-update` が存在しない。該当版からの初回
 | `throughline runtime-errors snapshot --json` | boundedなlocal aggregateを読み取る（network I/Oなし） |
 | `throughline runtime-errors diagnostics --json` | collection/store状態をpathやraw errorなしで診断 |
 | `throughline handoff-preview --session <id>` | Codex 向け `throughline_handoff` JSON projection を表示 |
-| `throughline handoff-context --session <id> --json` | SessionStart と同じ引き継ぎ文脈を versioned JSON で取得。記憶行の `session_id` と `sessions.merged_into` は変更せず、同一端末内の別ベンダーランチャーから使える |
+| `throughline handoff-context --session <id> --json [--supplement-file <path>]` | SessionStartと同じ引き継ぎ文脈を取得。任意のproject束縛済み補足を、長期記憶・知識として同じ9,500字枠へ合成できる |
 | `throughline latest-session --project <absolute-path> --json` | 指定した1プロジェクトだけを対象に直近セッションIDを読み取る。既存DBをread-onlyで開き、記録がなければ`empty`を返す |
 | `throughline grok-continue --session <id>` | handoff-context を初手 user 文にした対話 Grok 席を立てる。cwd は源の `project_path`。ready でなければ spawn しない。`--rules` なし。macOS Terminal のみ |
 | `throughline codex-sidecar-diagnostics` | この project の `codex-sidecar` diagnostics status を確認 |
@@ -426,7 +426,10 @@ throughline handoff-context --session codex:<thread-id> --json
 ```
 
 成功時の`throughline.handoff_context.v1`は`schema`、`status`、`sessionId`、`context`だけを返す。
-`context`はSessionStartと同じ予算付き継承文脈で、DB作成・migration・baton消費・session merge・
+`context`はSessionStartと同じ予算付き継承文脈である。任意の`--supplement-file <path>`には
+`throughline.handoff_supplement.v1`、源sessionと同じ`projectPath`、`title`と`content`からなる
+`sections`を指定する。補足は会話記憶と同じ9,500字枠へ入り、別projectの補足は拒否する。
+DB作成・migration・baton消費・session merge・
 latest session推測・`sessions.merged_into`変更・L1/L2/L3 rowの所属変更は行わない。AItermは任意の
 別harness portable forkでこの境界を使う。Observer feedはcompleted-turn projectionであり代替ではない。
 

package/README.md

@@ -817,7 +817,7 @@ entry to the `tasks` array yourself:
 
 ## Commands
 
-**The current release is v0.10.7.** Throughline supports Claude Code, Codex,
+**The current release is v0.10.9.** Throughline supports Claude Code, Codex,
 Grok, and Cursor as documented host adapters. The versioned, read-only
 `handoff-context` boundary opens only an existing database and leaves baton
 state, session ownership, and memory rows unchanged. Factory diagnostics,
@@ -855,7 +855,7 @@ once with `npm install --global throughline@latest`, then run
 | `throughline runtime-errors reopen <fingerprint> --json` | Explicitly reopen a resolved aggregate without fabricating a new occurrence |
 | `throughline runtime-errors compact --json`    | Remove only acknowledged, resolved aggregates after retention; open or unacknowledged records remain |
 | `throughline handoff-preview --session <id>`   | Print a Codex-facing `throughline_handoff` JSON projection    |
-| `throughline handoff-context --session <id> --json` | Print the exact SessionStart inheritance context as versioned JSON without moving memory rows or changing `sessions.merged_into`; intended for local launchers that need portable cross-harness context |
+| `throughline handoff-context --session <id> --json [--supplement-file <path>]` | Print the SessionStart inheritance context without moving memory rows; an optional project-bound supplement adds long-term memory and knowledge inside the same 9,500-character budget |
 | `throughline latest-session --project <absolute-path> --json` | Read the latest session id strictly scoped to one project; opens the existing database read-only and returns `empty` when the project has no captured session |
 | `throughline grok-continue --session <id>` | Spawn a person-facing Grok seat whose first user text is the handoff-context body. cwd is the source session `project_path`. Does not spawn without ready context. No `--rules`. macOS Terminal only |
 | `throughline codex-capture --codex-thread-id <id>` | Capture active Codex rollout turns into a `codex:<thread_id>` DB session |
@@ -909,7 +909,24 @@ throughline handoff-context --session codex:<thread-id> --json
 
 The successful `throughline.handoff_context.v1` object contains only `schema`,
 `status`, `sessionId`, and `context`. The context is the same budgeted
-inheritance text used by SessionStart. The command does not create or migrate a
+inheritance text used by SessionStart. A launcher may append
+`--supplement-file <path>` with a `throughline.handoff_supplement.v1` JSON object:
+
+```json
+{
+  "schema": "throughline.handoff_supplement.v1",
+  "projectPath": "/absolute/bot/project",
+  "sections": [
+    { "title": "Long-term memory", "content": "..." },
+    { "title": "Relevant knowledge", "content": "..." }
+  ]
+}
+```
+
+The supplement is included only when `projectPath` matches the source session
+and shares the 9,500-character budget with conversation memory. If the captured
+session has no dialogue context yet, a valid project-bound supplement is returned
+by itself. The command does not create or migrate a
 database, consume a baton, merge sessions, infer a latest session, change
 `sessions.merged_into`, or reassign L1/L2/L3 rows. AIterm uses this boundary for
 its optional cross-harness portable fork; the Observer feed is a separate

package/bin/throughline.mjs

@@ -11,7 +11,7 @@
  *   throughline detail <時刻> # L2+L3 詳細取得 (Claude が Bash 経由で呼ぶ想定)
  *   throughline recall --l2|--l1 # 注入案内から辿る pull 用 read-only 記憶取得
  *   throughline handoff-preview # Codex-facing throughline_handoff JSON preview
- *   throughline handoff-context --session <id> --json # Read-only inheritance context JSON
+ *   throughline handoff-context --session <id> --json [--supplement-file <path>] # Read-only inheritance context JSON
  *   throughline latest-session --project <path> --json # Latest session strictly scoped to one project
  *   throughline grok-continue --session <id> # Spawn a Grok seat whose first user text is handoff-context
  *   throughline auditor-context --json # Read-only bounded auditor context JSON
@@ -236,9 +236,10 @@ Usage:
   throughline monitor           Multi-session token monitor (use --all, --session <id>)
   throughline detail <time>     Retrieve L2+L3 detail for a turn (e.g. 14:23:05 or 14:23-14:30)
   throughline handoff-preview   Print Codex-facing throughline_handoff JSON
-  throughline handoff-context --session <id> --json
+  throughline handoff-context --session <id> --json [--supplement-file <path>]
                               Print the exact inheritance context without
-                              changing database ownership
+                              changing database ownership; optionally include
+                              project-bound long-term memory and knowledge
   throughline latest-session --project <absolute-path> --json
                               Read the latest session id for exactly one project
   throughline grok-continue --session <id>

package/docs/04_public_release_plan.md

@@ -6,7 +6,7 @@
 
 ## 現行状態
 
-- release candidateのpackage版は `0.10.7`。tagとnpmの公開確認はpublish後に行う。
+- release candidateのpackage版は `0.10.9`。tagとnpmの公開確認はpublish後に行う。
 - Claude Code、Codex、Grok、Cursorをfirst-class hostとして扱う。
 - 現行DB schemaはv9。schemaの正本は [src/db.mjs](../src/db.mjs) の
   `CURRENT_VERSION`、二相handoffの判断は

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-    "version": "0.10.7",
+    "version": "0.10.9",
     "type": "module",
     "description": "Persistent memory hooks for Claude Code, Codex, Grok, and Cursor (/clear-safe context compression)",
     "keywords": [

package/src/cli/handoff-context.mjs

@@ -1,36 +1,96 @@
 import { DatabaseSync } from 'node:sqlite';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 
-import { buildBudgetedResumeContext } from '../resume-context.mjs';
+import { sameProjectPath } from '../project-path.mjs';
+import {
+  buildBudgetedResumeContext,
+  INJECTION_BUDGET_CHARS,
+} from '../resume-context.mjs';
 
 export const HANDOFF_CONTEXT_SCHEMA = 'throughline.handoff_context.v1';
+export const HANDOFF_SUPPLEMENT_SCHEMA = 'throughline.handoff_supplement.v1';
 
 export function parseArgs(argv = []) {
-  if (
-    argv.length !== 3 ||
+  const baseArgsInvalid =
+    (argv.length !== 3 && argv.length !== 5) ||
     argv[0] !== '--session' ||
     typeof argv[1] !== 'string' ||
     argv[1].length === 0 ||
-    argv[2] !== '--json'
-  ) {
+    argv[2] !== '--json';
+  const supplementArgsValid = argv.length === 3 || (
+    argv[3] === '--supplement-file' &&
+    typeof argv[4] === 'string' &&
+    argv[4].length > 0
+  );
+  if (baseArgsInvalid || !supplementArgsValid) {
     throw new TypeError('usage error');
   }
-  return { sessionId: argv[1] };
+  return {
+    sessionId: argv[1],
+    supplementFile: argv.length === 5 ? argv[4] : null,
+  };
+}
+
+export function renderHandoffSupplement(value, projectPath) {
+  if (
+    value?.schema !== HANDOFF_SUPPLEMENT_SCHEMA ||
+    !isAbsolute(value.projectPath) ||
+    !sameProjectPath(value.projectPath, projectPath) ||
+    !Array.isArray(value.sections) ||
+    value.sections.length === 0
+  ) {
+    throw new TypeError('invalid handoff supplement');
+  }
+
+  const sections = value.sections.map((section) => {
+    if (
+      typeof section?.title !== 'string' || section.title.length === 0 ||
+      typeof section?.content !== 'string' || section.content.length === 0
+    ) {
+      throw new TypeError('invalid handoff supplement section');
+    }
+    return `### ${section.title}\n${section.content}`;
+  });
+  return ['## このBotの長期記憶と関連知識', ...sections].join('\n\n');
 }
 
 export function readHandoffContext(sessionId, {
   dbPath = join(homedir(), '.throughline', 'throughline.db'),
+  supplementFile = null,
 } = {}) {
   if (!existsSync(dbPath)) return null;
 
   const db = new DatabaseSync(dbPath, { readOnly: true });
   try {
-    return buildBudgetedResumeContext(db, {
+    let supplementContext = null;
+    if (supplementFile) {
+      const row = db.prepare(
+        'SELECT project_path FROM sessions WHERE session_id = ?',
+      ).get(sessionId);
+      if (!row?.project_path) return null;
+      supplementContext = renderHandoffSupplement(
+        JSON.parse(readFileSync(supplementFile, 'utf8')),
+        row.project_path,
+      );
+    }
+
+    const separator = supplementContext ? '\n\n' : '';
+    const context = buildBudgetedResumeContext(db, {
       sessionId,
       isInheritance: true,
+      maxChars: INJECTION_BUDGET_CHARS - (supplementContext?.length ?? 0) - separator.length,
     })?.text ?? null;
+    if (!context && !supplementContext) return null;
+
+    const combined = supplementContext && context
+      ? `${supplementContext}${separator}${context}`
+      : supplementContext ?? context;
+    if (combined.length > INJECTION_BUDGET_CHARS) {
+      throw new RangeError('handoff context exceeds injection budget');
+    }
+    return combined;
   } finally {
     db.close();
   }
@@ -61,16 +121,19 @@ export function run(argv = [], {
   readContext = readHandoffContext,
 } = {}) {
   let sessionId;
+  let supplementFile;
   try {
-    ({ sessionId } = parseArgs(argv));
+    ({ sessionId, supplementFile } = parseArgs(argv));
   } catch {
-    stderr.write('Usage: throughline handoff-context --session <id> --json\n');
+    stderr.write(
+      'Usage: throughline handoff-context --session <id> --json [--supplement-file <path>]\n',
+    );
     return 2;
   }
 
   let context;
   try {
-    context = readContext(sessionId);
+    context = readContext(sessionId, { supplementFile });
   } catch {
     stderr.write('Throughline handoff context could not be read.\n');
     return 1;

package/src/cli/handoff-context.test.mjs

@@ -1,14 +1,14 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DatabaseSync } from 'node:sqlite';
 
-import { buildBudgetedResumeContext } from '../resume-context.mjs';
-import { readSessionProjectPath } from './handoff-context.mjs';
+import { buildBudgetedResumeContext, INJECTION_BUDGET_CHARS } from '../resume-context.mjs';
+import { parseArgs, readSessionProjectPath } from './handoff-context.mjs';
 
 const REPO_ROOT = fileURLToPath(new URL('../..', import.meta.url));
 const BIN_PATH = join(REPO_ROOT, 'bin/throughline.mjs');
@@ -132,6 +132,114 @@ test('handoff-context emits the exact inheritance context without changing DB ow
   }
 });
 
+test('handoff-context adds a project-bound supplement inside the shared budget', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-handoff-supplement-'));
+  try {
+    const { db, dbPath } = createFixture(home);
+    const before = ownershipSnapshot(db);
+    db.close();
+    const supplementFile = join(home, 'supplement.json');
+    writeFileSync(supplementFile, JSON.stringify({
+      schema: 'throughline.handoff_supplement.v1',
+      projectPath: '/work/project',
+      sections: [
+        { title: '長期記憶', content: 'オーナーとの約束を大切にしている' },
+        { title: '関連知識', content: 'BellTeamではBotごとにprojectを分離する' },
+      ],
+    }));
+
+    const result = runCli(home, [
+      'handoff-context', '--session', SESSION_ID, '--json',
+      '--supplement-file', supplementFile,
+    ]);
+    assert.equal(result.status, 0, result.stderr);
+    const context = JSON.parse(result.stdout).context;
+    assert.match(context, /このBotの長期記憶と関連知識/);
+    assert.match(context, /オーナーとの約束を大切にしている/);
+    assert.match(context, /BellTeamではBotごとにprojectを分離する/);
+    assert.match(context, /所有権を変えずに記憶を渡して/);
+    assert.ok(context.indexOf('長期記憶') < context.indexOf('直前の対話'));
+    assert.ok(context.length <= INJECTION_BUDGET_CHARS);
+
+    const verify = new DatabaseSync(dbPath, { readOnly: true });
+    assert.deepEqual(ownershipSnapshot(verify), before);
+    verify.close();
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('handoff-context returns a project-bound supplement when the captured session has no dialogue yet', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-handoff-supplement-only-'));
+  try {
+    const { db, dbPath } = createFixture(home);
+    db.exec('DELETE FROM details; DELETE FROM bodies; DELETE FROM skeletons;');
+    const before = ownershipSnapshot(db);
+    db.close();
+    const supplementFile = join(home, 'supplement.json');
+    writeFileSync(supplementFile, JSON.stringify({
+      schema: 'throughline.handoff_supplement.v1',
+      projectPath: '/work/project',
+      sections: [{ title: 'Botプロフィール', content: '名前はCursor確認担当' }],
+    }));
+
+    const result = runCli(home, [
+      'handoff-context', '--session', SESSION_ID, '--json',
+      '--supplement-file', supplementFile,
+    ]);
+    assert.equal(result.status, 0, result.stderr);
+    assert.deepEqual(JSON.parse(result.stdout), {
+      schema: 'throughline.handoff_context.v1',
+      status: 'ready',
+      sessionId: SESSION_ID,
+      context: '## このBotの長期記憶と関連知識\n\n### Botプロフィール\n名前はCursor確認担当',
+    });
+
+    const verify = new DatabaseSync(dbPath, { readOnly: true });
+    assert.deepEqual(ownershipSnapshot(verify), before);
+    verify.close();
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('handoff-context refuses a supplement from another bot project', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-handoff-supplement-scope-'));
+  try {
+    const { db } = createFixture(home);
+    db.close();
+    const supplementFile = join(home, 'supplement.json');
+    writeFileSync(supplementFile, JSON.stringify({
+      schema: 'throughline.handoff_supplement.v1',
+      projectPath: '/work/other-bot',
+      sections: [{ title: '長期記憶', content: 'B_PRIVATE_MEMORY' }],
+    }));
+
+    const result = runCli(home, [
+      'handoff-context', '--session', SESSION_ID, '--json',
+      '--supplement-file', supplementFile,
+    ]);
+    assert.equal(result.status, 1);
+    assert.doesNotMatch(result.stdout, /B_PRIVATE_MEMORY/);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('handoff-context accepts only the documented supplement argument shape', () => {
+  assert.deepEqual(parseArgs(['--session', 's', '--json']), {
+    sessionId: 's',
+    supplementFile: null,
+  });
+  assert.deepEqual(parseArgs([
+    '--session', 's', '--json', '--supplement-file', '/tmp/memory.json',
+  ]), {
+    sessionId: 's',
+    supplementFile: '/tmp/memory.json',
+  });
+  assert.throws(() => parseArgs(['--session', 's', '--supplement-file', '/tmp/memory.json', '--json']));
+});
+
 test('readSessionProjectPath returns the source session project', () => {
   const home = mkdtempSync(join(tmpdir(), 'tl-session-project-'));
   try {

package/src/cli/latest-session.test.mjs

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import test from 'node:test';
 
@@ -49,7 +49,7 @@ test('readyとemptyをJSONで返す', () => {
   assert.deepEqual(JSON.parse(stdout.read()), {
     schema: 'throughline.latest_session.v1',
     status: 'ready',
-    projectPath: '/bots/a',
+    projectPath: resolve('/bots/a'),
     sessionId: 'claude:abc',
     updatedAt: 'now',
   });

package/src/cli/self-update.mjs

@@ -1,6 +1,6 @@
 import { createRequire } from 'node:module';
 import { realpathSync } from 'node:fs';
-import { dirname, isAbsolute, join, win32 } from 'node:path';
+import { dirname, join, posix, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { spawnPortableSync } from '../os/portable-spawn-sync.mjs';
@@ -94,7 +94,7 @@ export function resolveGlobalCliPath(result, platform = process.platform) {
   if (!succeeded(result) || typeof result.stdout !== 'string') return null;
   const lines = result.stdout.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean);
   if (lines.length !== 1) return null;
-  const path = platform === 'win32' ? win32 : { isAbsolute, join };
+  const path = platform === 'win32' ? win32 : posix;
   if (!path.isAbsolute(lines[0])) return null;
   return path.join(lines[0], 'throughline', 'bin', 'throughline.mjs');
 }
@@ -110,7 +110,7 @@ export function validateSelfUpdateIdentity(value, {
   if (Object.keys(value).sort().join('\0') !== exact.sort().join('\0')) return false;
   if (value.schema !== SELF_UPDATE_IDENTITY_SCHEMA || value.version !== version ||
     typeof value.cliPath !== 'string') return false;
-  const path = platform === 'win32' ? win32 : { isAbsolute };
+  const path = platform === 'win32' ? win32 : posix;
   if (!path.isAbsolute(value.cliPath) || !path.isAbsolute(cliPath ?? '')) return false;
   try {
     const actual = canonicalizePath(value.cliPath);

package/src/cli/self-update.test.mjs

@@ -118,6 +118,7 @@ test('self-update delegates post-install work to the newly installed CLI', () =>
     env: { PATH: '/fixture/bin' },
     runner,
     packageVersion: '0.10.4',
+    platform: 'linux',
     nodePath: '/node',
     cliPath: '/old-throughline.mjs',
     canonicalizePath: fakeCanonicalizePath,
@@ -160,6 +161,7 @@ test('new CLI completes install, migration, and diagnostics in order', () => {
     },
     runner,
     packageVersion: '0.10.5',
+    platform: 'linux',
     nodePath: '/node',
     cliPath: '/throughline.mjs',
   }), 0);
@@ -257,6 +259,7 @@ test('old CLI help with exit 0 cannot satisfy the post-install protocol', () =>
     stderr: sink(),
     runner,
     packageVersion: '0.10.4',
+    platform: 'linux',
     nodePath: '/node',
     canonicalizePath: fakeCanonicalizePath,
   }), 1);
@@ -293,6 +296,7 @@ test('post-install non-JSON failure preserves child stderr as the cause', () =>
     stderr,
     runner,
     packageVersion: '0.10.4',
+    platform: 'linux',
     nodePath: '/node',
     canonicalizePath: fakeCanonicalizePath,
   }), 1);
@@ -330,6 +334,7 @@ test('post-install structured failure preserves its stage and stderr', () => {
     stderr,
     runner,
     packageVersion: '0.10.4',
+    platform: 'linux',
     nodePath: '/node',
     canonicalizePath: fakeCanonicalizePath,
   }), 7);

package/src/completed-turn-receipts.test.mjs

@@ -148,7 +148,7 @@ test('completed turn receipt: one Windows mutation spends ACL processes only on
   try {
     writeCompletedTurnReceipt(input(1), options);
     assert.equal(calls.length, 3, 'new directory, lock, and store each require one apply+verify process');
-    assert.ok(calls.every((call) => call.command === 'powershell.exe'));
+    assert.ok(calls.every((call) => call.command === 'pwsh.exe'));
     calls.length = 0;
 
     writeCompletedTurnReceipt(input(2), options);

package/src/docs-contract.test.mjs

@@ -1,6 +1,5 @@
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
 import { test } from 'node:test';
 import { fileURLToPath } from 'node:url';
 
@@ -8,6 +7,7 @@ import {
   extractMarkdownTargets,
   findMissingPackedTargets,
 } from '../scripts/verify-pack-markdown-links.mjs';
+import { spawnPortableSync } from './os/portable-spawn-sync.mjs';
 
 test('Markdown-only CI runs the product-owned documentation contract', () => {
   const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -36,7 +36,7 @@ test('Markdown-only CI runs the product-owned documentation contract', () => {
   );
 
   const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const result = spawnSync(npmCommand, ['run', 'verify:docs', '--silent'], {
+  const result = spawnPortableSync(npmCommand, ['run', 'verify:docs', '--silent'], {
     cwd: fileURLToPath(new URL('..', import.meta.url)),
     encoding: 'utf8',
   });

package/src/os/portable-spawn-sync.mjs

@@ -43,7 +43,7 @@ export function spawnPortableSync(command, args, options = {}) {
     return spawnSync(process.execPath, [resolved, ...args], spawnOptions);
   }
   if (extension === '.ps1') {
-    return spawnSync('powershell.exe', [
+    return spawnSync('pwsh.exe', [
       '-NoLogo',
       '-NoProfile',
       '-NonInteractive',

package/src/os/windows-acl-test-helper.mjs

@@ -16,9 +16,9 @@ $acl.SetOwner($sid); $acl.SetAccessRuleProtection($true,$false)
 $inherit=if($isDir){[System.Security.AccessControl.InheritanceFlags]'ContainerInherit,ObjectInherit'}else{[System.Security.AccessControl.InheritanceFlags]::None}
 $rule=New-Object System.Security.AccessControl.FileSystemAccessRule($sid,'FullControl',$inherit,[System.Security.AccessControl.PropagationFlags]::None,[System.Security.AccessControl.AccessControlType]::Allow)
 $acl.AddAccessRule($rule)
-if($isDir){[System.IO.Directory]::SetAccessControl($target,$acl)}else{[System.IO.File]::SetAccessControl($target,$acl)}
+Set-Acl -LiteralPath $target -AclObject $acl
 `;
-  const result = spawnSync('powershell.exe', [
+  const result = spawnSync('pwsh.exe', [
     '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script,
   ], {
     encoding: 'utf8',
@@ -39,7 +39,7 @@ export function verifyWindowsPrivateAcl(path, directory = false) {
 $ErrorActionPreference='Stop'
 $target=$env:THROUGHLINE_TEST_ACL_PATH; $isDir=$env:THROUGHLINE_TEST_ACL_DIRECTORY -eq '1'
 $sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
-$acl=if($isDir){[System.IO.Directory]::GetAccessControl($target)}else{[System.IO.File]::GetAccessControl($target)}
+$acl=Get-Acl -LiteralPath $target
 $owner=$acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value
 if($owner -ne $sid){exit 41}
 $rules=@($acl.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier]))
@@ -47,7 +47,7 @@ if($rules.Count -ne 1){exit 42}
 $rule=$rules[0]
 if($rule.IdentityReference.Value -ne $sid -or $rule.AccessControlType -ne 'Allow' -or $rule.IsInherited -or ($rule.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::FullControl) -ne [System.Security.AccessControl.FileSystemRights]::FullControl){exit 43}
 `;
-  const result = spawnSync('powershell.exe', [
+  const result = spawnSync('pwsh.exe', [
     '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script,
   ], {
     encoding: 'utf8',

package/src/os/windows-acl.mjs

@@ -33,7 +33,7 @@ export function verifyWindowsAcl(path, directory) {
 }
 
 function runWindowsAclScript(path, directory, script) {
-  const result = childProcess.spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+  const result = childProcess.spawnSync('pwsh.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
     env: { ...process.env, THROUGHLINE_ACL_PATH: path, THROUGHLINE_ACL_DIRECTORY: directory ? '1' : '0' },
     stdio: 'ignore', timeout: WINDOWS_ACL_TIMEOUT_MS, windowsHide: true,
   });
@@ -42,7 +42,7 @@ function runWindowsAclScript(path, directory, script) {
 
 const WINDOWS_ACL_VERIFY_SCRIPT = String.raw`
 $p=$env:THROUGHLINE_ACL_PATH; $isDir=$env:THROUGHLINE_ACL_DIRECTORY -eq '1'; $sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
-$acl=if($isDir){[System.IO.Directory]::GetAccessControl($p)}else{[System.IO.File]::GetAccessControl($p)}
+$acl=Get-Acl -LiteralPath $p
 $owner=$acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value
 if($owner -ne $sid){exit 41}; $rules=@($acl.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier])); if($rules.Count -ne 1){exit 42}
 $r=$rules[0]; if($r.IdentityReference.Value -ne $sid -or $r.AccessControlType -ne 'Allow' -or $r.IsInherited -or ($r.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::FullControl) -ne [System.Security.AccessControl.FileSystemRights]::FullControl){exit 43}
@@ -53,5 +53,5 @@ $p=$env:THROUGHLINE_ACL_PATH; $sid=[System.Security.Principal.WindowsIdentity]::
 $isDir=$env:THROUGHLINE_ACL_DIRECTORY -eq '1'; $acl=if($isDir){New-Object System.Security.AccessControl.DirectorySecurity}else{New-Object System.Security.AccessControl.FileSecurity}; $acl.SetAccessRuleProtection($true,$false)
 $flags=if($isDir){[System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'}else{[System.Security.AccessControl.InheritanceFlags]::None}
 $rule=New-Object System.Security.AccessControl.FileSystemAccessRule($sid,'FullControl',$flags,[System.Security.AccessControl.PropagationFlags]::None,[System.Security.AccessControl.AccessControlType]::Allow)
-$acl.SetOwner($sid); $acl.AddAccessRule($rule); if($isDir){[System.IO.Directory]::SetAccessControl($p,$acl)}else{[System.IO.File]::SetAccessControl($p,$acl)}
+$acl.SetOwner($sid); $acl.AddAccessRule($rule); Set-Acl -LiteralPath $p -AclObject $acl
 ` + WINDOWS_ACL_VERIFY_SCRIPT;

package/src/runtime-error-store.test.mjs

@@ -123,7 +123,7 @@ test('runtime error store: one Windows mutation spends ACL processes only on dis
 
   assert.equal(observeRuntimeError({ code: 'HOOK_CODEX_FAILED' }, options).status, 'recorded');
   assert.equal(calls.length, 3, 'new directory, lock, and store each require one apply+verify process');
-  assert.ok(calls.every((call) => call.command === 'powershell.exe'));
+  assert.ok(calls.every((call) => call.command === 'pwsh.exe'));
   calls.length = 0;
 
   assert.equal(observeRuntimeError({ code: 'HOOK_CODEX_FAILED' }, options).status, 'recorded');

package/src/test-env.mjs

@@ -15,8 +15,9 @@ process.env.NODE_NO_WARNINGS = '1';
 // app-server fixtures.  Run their .mjs bodies with this test runner's Node
 // executable, preserving the command arguments the production code sends.
 import childProcess from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { syncBuiltinESMExports } from 'node:module';
+import { basename, dirname, extname, join } from 'node:path';
 
 const { spawn: nativeSpawn, spawnSync: nativeSpawnSync } = childProcess;
 
@@ -25,6 +26,16 @@ function normalizeNodeFixture(command, args = []) {
     return [command, args];
   }
   if (command.endsWith('.mjs')) return [process.execPath, [command, ...args]];
+  const extension = extname(command).toLowerCase();
+  if (extension === '.cmd' || extension === '.bat') {
+    const sibling = join(dirname(command), `${basename(command, extension)}.ps1`);
+    if (existsSync(sibling)) {
+      return ['pwsh.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-File', sibling, ...args]];
+    }
+  }
+  if (extension === '.ps1') {
+    return ['pwsh.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-File', command, ...args]];
+  }
   try {
     const header = readFileSync(command, 'utf8').slice(0, 128);
     if (/^#!.*\bnode(?:\.exe)?\b/.test(header)) return [process.execPath, [command, ...args]];