From e15a6168d2c8d69ae004feff822c89b2adc78c36 Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Sun, 5 Jul 2026 04:31:22 +0800 Subject: [PATCH 01/53] Support durable JSONL persistence on Windows --- docs/rfc/INDEX.md | 1 + ...026-07-05-windows-jsonl-durable-publish.md | 33 ++++ .../session-persistence-jsonl/README.md | 4 +- .../session-persistence-jsonl/package.json | 1 + .../session-persistence-jsonl/src/index.ts | 128 +++++++++---- .../session-persistence-jsonl/src/win32.ts | 150 ++++++++++++++++ .../tests/jsonl.spec.ts | 39 ++++ .../tests/win32.spec.ts | 168 ++++++++++++++++++ pnpm-lock.yaml | 144 +++++++++++++++ pnpm-workspace.yaml | 2 + 10 files changed, 636 insertions(+), 34 deletions(-) create mode 100644 docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md create mode 100644 packages/session-persistence/session-persistence-jsonl/src/win32.ts create mode 100644 packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index ab39d4f314..32f11b744a 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -150,6 +150,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Prompt variables and tool-guidance ownership](implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) | 2026-07-05 | | [Every LLM request is reconstructable from the session log](implemented/architecture/2026-07-05-reconstructable-requests.md) | 2026-07-05 | | [Subagent provider-lifecycle events — `subagent/provider-added` / `subagent/provider-removed`](implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md) | 2026-07-05 | +| [Windows-native durable JSONL publication](implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md) | 2026-07-05 | | [A shared timeout/deadline primitive, with hard-kill left to each capability](implemented/architecture/2026-07-06-timeout-deadline-library.md) | 2026-07-06 | | [Tool result retention library](implemented/architecture/2026-07-06-tool-result-retention-library.md) | 2026-07-06 | | [Tool-call timeout policy as a plugin](implemented/architecture/2026-07-07-tool-call-timeout-policy.md) | 2026-07-07 | diff --git a/docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md b/docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md new file mode 100644 index 0000000000..909f75132f --- /dev/null +++ b/docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md @@ -0,0 +1,33 @@ +# RFC: Windows-native durable JSONL publication + +Status: implemented + +## Problem + +`dsh-session-persistence-jsonl` publishes a session log lazily on the first append. The POSIX protocol writes a temp file, fsyncs it, links it to the final name, fsyncs the parent directory, and then removes the temp link. The parent-directory fsync is part of the durability contract: a crash after the namespace change must not lose the committed final name while leaving callers believing the session log materialized. + +Windows has atomic namespace operations, but Node does not expose a POSIX-equivalent parent-directory fsync contract there. Treating Windows directory sync failures as success would silently weaken a durable backend. The Windows path therefore needs a different publication primitive rather than a conditional inside the POSIX `syncDir` helper. + +## Decision + +The JSONL backend forks inside `materialize()` before any namespace mutation. Shared code computes the session directory, final log path, and initial JSONL bytes; POSIX and Windows then run separate publication protocols. + +POSIX keeps the existing protocol: create the root and cwd bucket with parent directory fsyncs, write and fsync a temp file, publish with `link()` so an existing final log is never overwritten, fsync the bucket directory, then remove the redundant temp hard link. + +Windows creates missing directories through a durable staging publish: create a random sibling directory, then publish it to the final directory name with `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` without `MOVEFILE_REPLACE_EXISTING` or `MOVEFILE_COPY_ALLOWED`. File materialization writes and fsyncs the temp log, then publishes that temp file to the final path with the same write-through `MoveFileExW` call and no replacement. `koffi` is the minimal Win32 bridge for this API surface; its install script is allowed in `pnpm-workspace.yaml` because the package ships the native loader and prebuilt platform modules. + +## Alternatives considered + +**Ignore Windows directory-sync failures.** Rejected because it reports a first append as durable without forcing the published namespace entry to stable storage. + +**Use `CreateHardLinkW`.** Rejected because hard links are filesystem-dependent, do not publish directories, and expose no write-through option. + +**Use replacement or transactional APIs.** `ReplaceFileW` has replacement semantics that conflict with same-id collision rejection, and Transactional NTFS is not recommended for new application designs. + +## Consequences + +The backend keeps one external contract across platforms: first append either publishes a complete log at the final name or fails without overwriting an existing log. The platform split is an implementation detail; `SessionPersistence` APIs and on-disk JSONL format do not change. + +Windows tests exercise the real Win32 publish path on native Windows. Power-loss behavior remains an API-contract property rather than something unit tests can prove; the testable invariants are that directory fsync is not called on Windows materialization, final-path collisions fail, temp logs are fsync'd before publication, and the resulting log loads normally. + +Append and repair still use ordinary file-handle fsyncs on both platforms. A failed append closes its append-only handle, reopens the log read/write, truncates it to the pre-append size, and fsyncs the rollback because Windows rejects `ftruncate` on append-only handles. diff --git a/packages/session-persistence/session-persistence-jsonl/README.md b/packages/session-persistence/session-persistence-jsonl/README.md index 43f4443107..097ad04b67 100644 --- a/packages/session-persistence/session-persistence-jsonl/README.md +++ b/packages/session-persistence/session-persistence-jsonl/README.md @@ -23,7 +23,7 @@ The JSONL durable session-persistence backend — a concrete `SessionPersistence ## Durability and crash semantics -- **Lazy materialization.** `create(meta)` writes nothing; on the first `append`, the backend writes and `fsync`s a temporary file, publishes it without overwrite via a hard link, then `fsync`s the directory. A created-but-never-appended session leaves nothing on disk and is absent from `list`. +- **Lazy materialization.** `create(meta)` writes nothing; the `.jsonl` (header + first batch) is written atomically on the first `append`: POSIX uses temp-write + file `fsync` + `link` + parent-directory `fsync`; Windows uses temp-write + file `fsync` + `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` and creates missing directories through the same write-through publish pattern. A created-but-never-appended session leaves nothing on disk and is absent from `list`. - **Append-only.** Committed events (at or below a flushed `turn/end`) are never rewritten. Subsequent appends are line appends at EOF + `fsync`. - **Crash recovery — preserve valid tail work.** `load` keeps the contiguous valid prefix of an interrupted final turn. It truncates from the first unparsable or sequence-gapped uncommitted record, then appends the synthetic tool, step, and turn closers required by the shared [persistence contract](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md); the same defect at or before the last committed `turn/end` rejects. - **Contiguous-seq.** `append` rejects a batch whose first `seq` does not continue the stored log, and rejects non-JSON-serializable `event.data` naming the offending event type. @@ -45,4 +45,4 @@ The plugin buffers frozen session events and drains them on flush or disposal. A - **Only the current `SESSION_FORMAT_VERSION` (v0) loads** — the on-disk format is pre-release/unstable: a breaking format change is absorbed at v0 and non-current logs are rejected; there is no migration. - **Nothing deletes session files** — logs accumulate under `root` until removed externally (the seam has no deletion surface). - **Single-process assumption** — per-session serialization and the write cursor live in this process; two processes appending to the same `root` are not coordinated. -- **Initial materialization requires hard-link support** — first append uses `link()` so same-id races fail instead of overwriting a committed log; a filesystem that cannot create hard links cannot host this backend. +- **POSIX materialization requires hard-link support** — its first append uses `link()` so same-id races fail instead of overwriting a committed log; Windows uses write-through rename without replacement. diff --git a/packages/session-persistence/session-persistence-jsonl/package.json b/packages/session-persistence/session-persistence-jsonl/package.json index ddb9f2af4d..2644e14efc 100644 --- a/packages/session-persistence/session-persistence-jsonl/package.json +++ b/packages/session-persistence/session-persistence-jsonl/package.json @@ -27,6 +27,7 @@ "cordis": "^4.0.0-rc.7" }, "dependencies": { + "koffi": "^3.1.0", "schemastery": "^3.18.0" }, "devDependencies": { diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts index 0c8a2ee3ef..ac1c07860e 100644 --- a/packages/session-persistence/session-persistence-jsonl/src/index.ts +++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts @@ -19,6 +19,7 @@ import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-se import { encodeSegment, eventLine, logPath, parseHeaderMeta, scanLog, sessionDir, toHeaderLine, } from './format.ts' +import { ensureDurableDirectoryWin32, publishNewFileWin32 } from './win32.ts' /** Plugin config: where the JSONL backend keeps its session logs (`root` is required — no default). */ export interface Config { @@ -160,33 +161,35 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi // --- materialization / append / repair (file mechanics) --- - /** Atomically write the header line + first batch (temp-write, fsync, collision-safe hard-link publish). */ + /** Atomically write the header line + first batch (temp-write, fsync, publish). */ private async materialize(meta: SessionHeader, events: readonly SessionEvent[]): Promise { const dir = sessionDir(this.root, meta.cwd) - await mkdir(this.root, { recursive: true, mode: 0o700 }) - await this.syncDir(dirname(this.root)) - await mkdir(dir, { recursive: true, mode: 0o700 }) - await this.syncDir(this.root) const finalPath = logPath(this.root, meta.cwd, meta.id) - // Materialization is the first write; an existing log is an id collision. - /* v8 ignore next 3 -- createCore guards collisions before materialize; this is a TOCTOU backstop */ - if (await this.exists(finalPath)) { - throw new Error(`refusing to materialize "${meta.id}": a log already exists on disk (load/resume it instead)`) + const content = this.initialLogContent(meta, events) + /* v8 ignore next -- native Windows coverage exercises this platform dispatch; Linux covers the POSIX peer */ + if (process.platform === 'win32') { + await this.materializeWin32(dir, finalPath, meta.id, content) + } else { + await this.materializePosix(dir, finalPath, meta.id, content) } + } + + private initialLogContent(meta: SessionHeader, events: readonly SessionEvent[]): string { const header = JSON.stringify(toHeaderLine(meta)) const body = events.map(eventLine).join('\n') - const content = header + '\n' + body + '\n' + return header + '\n' + body + '\n' + } - const tmp = `${finalPath}.${randomBytes(6).toString('hex')}.tmp` - const handle = await open(tmp, 'wx', 0o600) - try { - await handle.writeFile(content) - await handle.sync() - } finally { - await handle.close() - } - // Publish with link()+unlink(): unlike rename(), link fails if another - // process materialized the same id first. + private async materializePosix(dir: string, finalPath: string, id: SessionId, content: string): Promise { + await mkdir(this.root, { recursive: true, mode: 0o700 }) + await this.syncDirPosix(dirname(this.root)) + await mkdir(dir, { recursive: true, mode: 0o700 }) + await this.syncDirPosix(this.root) + await this.rejectExistingLog(finalPath, id) + const tmp = await this.writeSyncedTempFile(finalPath, content) + // Publish via link()+unlink(), NOT rename(): link fails with EEXIST if the + // final path already exists, so two processes materializing the same id + // concurrently cannot clobber each other. rename() would silently overwrite. let linked = false try { await link(tmp, finalPath) @@ -197,10 +200,13 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi /* v8 ignore next -- link failure is the TOCTOU/IO race guarded above; not reachable in test */ if (!linked) await rm(tmp, { force: true }) } - // The published link becomes crash-durable only after its directory fsync. - await this.syncDir(dir) - // Best-effort temp cleanup: the log is already published and durable, so a failure to - // remove the (now-redundant) temp hard link must not reject the append. + // link() succeeded — the log is published. fsync the directory so the new + // entry survives a power loss: the new link is not crash-durable until the + // parent directory's metadata is synced. + await this.syncDirPosix(dir) + // Best-effort temp cleanup: the log is already published and durable, so a + // failure to remove the (now-redundant) temp hard link must NOT reject the + // append. Swallow only the rm failure; nothing else of consequence runs here. try { await rm(tmp, { force: true }) } catch { @@ -208,8 +214,47 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } } - /** fsync a directory so a just-created or published entry inside it is crash-durable. */ - private async syncDir(dir: string): Promise { + /* v8 ignore start -- native Windows coverage exercises this integration path */ + private async materializeWin32(dir: string, finalPath: string, id: SessionId, content: string): Promise { + await ensureDurableDirectoryWin32(this.root) + await ensureDurableDirectoryWin32(dir) + await this.rejectExistingLog(finalPath, id) + const tmp = await this.writeSyncedTempFile(finalPath, content) + try { + await publishNewFileWin32(tmp, finalPath) + } catch (error) { + await rm(tmp, { force: true }) + throw error + } + } + /* v8 ignore stop */ + + private async rejectExistingLog(finalPath: string, id: SessionId): Promise { + // Never publish over an existing committed log: materialize is the FIRST + // write of a session the backend believes is new. A file here means a + // different session shares this id on disk — reject loudly. (createCore + // already guards the create path, so this is unreachable-in-practice TOCTOU + // defense.) + /* v8 ignore next 3 -- createCore guards collisions before materialize; this is a TOCTOU backstop */ + if (await this.exists(finalPath)) { + throw new Error(`refusing to materialize "${id}": a log already exists on disk (load/resume it instead)`) + } + } + + private async writeSyncedTempFile(finalPath: string, content: string): Promise { + const tmp = `${finalPath}.${randomBytes(6).toString('hex')}.tmp` + const handle = await open(tmp, 'wx', 0o600) + try { + await handle.writeFile(content) + await handle.sync() + } finally { + await handle.close() + } + return tmp + } + + /** fsync a POSIX directory so a just-created/renamed entry is crash-durable. */ + private async syncDirPosix(dir: string): Promise { const handle = await open(dir, 'r') try { await handle.sync() @@ -226,17 +271,37 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi private async appendLines(meta: SessionHeader, events: readonly SessionEvent[]): Promise { const path = logPath(this.root, meta.cwd, meta.id) const handle = await open(path, 'a') + let closed = false + const closeAppendHandle = async (): Promise => { + if (closed) return + closed = true + await handle.close() + } + try { const { size: before } = await handle.stat() try { await handle.writeFile(events.map(eventLine).join('\n') + '\n') await handle.sync() } catch (error) { - // Roll back whatever bytes landed so a retry starts from a clean EOF. - await handle.truncate(before) - await handle.sync() + try { + await closeAppendHandle() + await this.rollbackAppend(path, before) + } catch (rollbackError) { + throw new AggregateError([error, rollbackError], `failed to roll back append to "${path}"`) + } throw error } + } finally { + await closeAppendHandle() + } + } + + private async rollbackAppend(path: string, size: number): Promise { + const handle = await open(path, 'r+') + try { + await handle.truncate(size) + await handle.sync() } finally { await handle.close() } @@ -322,9 +387,8 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi await handle.close() return true } catch (error) { - // Only ENOENT means absent. A permission/I/O error must surface, not be - // collapsed to `false` — otherwise load() reports "not found" and collision - // checks proceed under a false absence assumption. + // Only ENOENT means absent. A permission/I/O error must surface rather + // than letting load or collision checks proceed under false absence. if (isENOENT(error)) return false throw error } diff --git a/packages/session-persistence/session-persistence-jsonl/src/win32.ts b/packages/session-persistence/session-persistence-jsonl/src/win32.ts new file mode 100644 index 0000000000..143f230ea3 --- /dev/null +++ b/packages/session-persistence/session-persistence-jsonl/src/win32.ts @@ -0,0 +1,150 @@ +/** + * Windows durable namespace helpers for the JSONL backend. + * + * POSIX publishes a newly-created log by creating a directory entry and then + * fsyncing the parent directory. Windows does not expose that parent-directory + * fsync contract through Node, so the Windows path uses the native durable + * namespace primitive instead: create a staging object in the target directory + * and publish it with `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` without + * replacement or cross-volume copy fallback. + * + * @module dsh-session-persistence-jsonl/win32 + */ + +import { mkdtemp, rm, stat } from 'node:fs/promises' +import { basename, join, parse, resolve, toNamespacedPath } from 'node:path' + +type MoveFileExW = (existing: string, replacement: string, flags: number) => boolean +type GetLastError = () => number + +interface Win32Bindings { + moveFileExW: MoveFileExW + getLastError: GetLastError +} + +interface Win32ErrnoException extends NodeJS.ErrnoException { + win32Code: number + dest: string +} + +const MOVEFILE_WRITE_THROUGH = 0x00000008 +const ERROR_FILE_NOT_FOUND = 2 +const ERROR_PATH_NOT_FOUND = 3 +const ERROR_ACCESS_DENIED = 5 +const ERROR_NOT_SAME_DEVICE = 17 +const ERROR_FILE_EXISTS = 80 +const ERROR_INVALID_NAME = 123 +const ERROR_ALREADY_EXISTS = 183 + +let bindings: Win32Bindings | undefined + +/** Load the small Win32 surface lazily so non-Windows processes never load Koffi. */ +async function win32(): Promise { + if (bindings !== undefined) return bindings + const koffi = (await import('koffi')).default + const kernel32 = koffi.load('kernel32.dll') + bindings = { + moveFileExW: kernel32.func('__stdcall', 'MoveFileExW', 'bool', ['str16', 'str16', 'uint']) as MoveFileExW, + getLastError: kernel32.func('__stdcall', 'GetLastError', 'uint', []) as GetLastError, + } + return bindings +} + +function errnoCode(win32Code: number): string { + switch (win32Code) { + case ERROR_FILE_NOT_FOUND: + case ERROR_PATH_NOT_FOUND: + return 'ENOENT' + case ERROR_ACCESS_DENIED: + return 'EACCES' + case ERROR_NOT_SAME_DEVICE: + return 'EXDEV' + case ERROR_FILE_EXISTS: + case ERROR_ALREADY_EXISTS: + return 'EEXIST' + case ERROR_INVALID_NAME: + return 'EINVAL' + default: + return 'EIO' + } +} + +function win32Error(syscall: string, win32Code: number, path: string, dest: string): Win32ErrnoException { + const code = errnoCode(win32Code) + const error = new Error(`${syscall} ${code} (Win32 ${win32Code}): ${path} -> ${dest}`) as Win32ErrnoException + error.code = code + error.errno = win32Code + error.syscall = syscall + error.path = path + error.dest = dest + error.win32Code = win32Code + return error +} + +function isENOENT(error: unknown): boolean { + return (error as NodeJS.ErrnoException | null)?.code === 'ENOENT' +} + +function isEEXIST(error: unknown): boolean { + return (error as NodeJS.ErrnoException | null)?.code === 'EEXIST' +} + +async function assertDirectory(path: string): Promise { + try { + const info = await stat(path) + if (info.isDirectory()) return true + const error = new Error(`path exists but is not a directory: ${path}`) as NodeJS.ErrnoException + error.code = 'ENOTDIR' + error.path = path + throw error + } catch (error) { + if (isENOENT(error)) return false + throw error + } +} + +/** + * Publish `existing` at `replacement` with Windows write-through rename + * semantics. The destination must not already exist; the move must stay within + * the volume (no copy fallback flag is set). + * @param existing - the synced staging path to move. + * @param replacement - the final path, which must not already exist. + */ +export async function publishNewFileWin32(existing: string, replacement: string): Promise { + const api = await win32() + const ok = api.moveFileExW(toNamespacedPath(existing), toNamespacedPath(replacement), MOVEFILE_WRITE_THROUGH) + if (!ok) throw win32Error('MoveFileExW', api.getLastError(), existing, replacement) +} + +/** + * Create `target` and its missing ancestors with durable Windows namespace + * publication. Each missing directory is first created as a random staging + * sibling, then moved to its final name with `MOVEFILE_WRITE_THROUGH`; races + * with another creator are accepted only after verifying the winner is a + * directory. + * @param target - the absolute directory path to create durably when absent. + */ +export async function ensureDurableDirectoryWin32(target: string): Promise { + const absolute = resolve(target) + const root = parse(absolute).root + await assertDirectory(root) + + const segments = absolute.slice(root.length).split(/[\\/]+/).filter(part => part.length > 0) + let current = root + for (const segment of segments) { + const next = join(current, segment) + if (!await assertDirectory(next)) await createLeafDirectoryWin32(current, next) + current = next + } +} + +async function createLeafDirectoryWin32(parent: string, target: string): Promise { + const staging = await mkdtemp(join(parent, `.dsh-mkdir-${basename(target)}-`)) + try { + await publishNewFileWin32(staging, target) + } catch (error) { + await rm(staging, { recursive: true, force: true }) + if (isEEXIST(error) && await assertDirectory(target)) return + throw error + } +} diff --git a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts index 4b279e3c6e..e7a65d3c8f 100644 --- a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts +++ b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts @@ -336,6 +336,45 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7]) }) + it('reports both the append failure and a failed rollback', async () => { + const m = meta('rollback-failure') + await ctx.sessionPersistence.create(m) + await ctx.sessionPersistence.append(m.id, oneTurnLog()) + + const path = logPath(root, undefined, m.id) + const handle = await (await import('node:fs/promises')).open(path, 'r') + const proto = Object.getPrototypeOf(handle) as { sync: () => Promise } + await handle.close() + const realSync = proto.sync + let failed = false + const syncSpy = vi.spyOn(proto, 'sync').mockImplementation(async function (this: unknown) { + if (!failed) { failed = true; throw new Error('simulated append fsync failure') } + return realSync.call(this) + }) + const backend = ctx.sessionPersistence as unknown as { + rollbackAppend: (path: string, size: number) => Promise + } + const realRollback = backend.rollbackAppend.bind(backend) + backend.rollbackAppend = () => Promise.reject(new Error('simulated rollback failure')) + + try { + await ctx.sessionPersistence.append(m.id, [ + { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + ] as SessionEvent[]) + throw new Error('expected append to reject') + } catch (error) { + expect(error).toBeInstanceOf(AggregateError) + const aggregate = error as AggregateError + expect(aggregate.message).toContain(`failed to roll back append to "${path}"`) + expect(aggregate.errors).toHaveLength(2) + expect(aggregate.errors[0]).toMatchObject({ message: 'simulated append fsync failure' }) + expect(aggregate.errors[1]).toMatchObject({ message: 'simulated rollback failure' }) + } finally { + backend.rollbackAppend = realRollback + syncSpy.mockRestore() + } + }) + it('load returns a meta copy: mutating it does not corrupt backend pathing', async () => { const m = meta('meta-copy', '/proj') await ctx.sessionPersistence.create(m) diff --git a/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts new file mode 100644 index 0000000000..760eb3d455 --- /dev/null +++ b/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts @@ -0,0 +1,168 @@ +/** + * Unit tests for the Windows durable namespace helper with a mocked kernel32 + * binding. The real JSONL suite exercises the helper on native Windows; these + * tests keep the Win32 error mapping and race handling covered on every host. + */ + +import { afterEach, describe, expect, it, vi } from 'vitest' +import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs' +import { mkdtemp, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' + +const MOVEFILE_WRITE_THROUGH = 0x00000008 +const ERROR_FILE_NOT_FOUND = 2 +const ERROR_PATH_NOT_FOUND = 3 +const ERROR_ACCESS_DENIED = 5 +const ERROR_NOT_SAME_DEVICE = 17 +const ERROR_FILE_EXISTS = 80 +const ERROR_INVALID_NAME = 123 +const ERROR_ALREADY_EXISTS = 183 + +type MoveFileExW = (existing: string, replacement: string, flags: number, setLastError: (code: number) => void) => boolean + +const roots: string[] = [] + +function stripNamespace(path: string): string { + if (path.startsWith('\\\\?\\UNC\\')) return `\\\\${path.slice('\\\\?\\UNC\\'.length)}` + if (path.startsWith('\\\\?\\')) return path.slice('\\\\?\\'.length) + return path +} + +async function tempRoot(): Promise { + const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-win32-')) + roots.push(dir) + return dir +} + +async function importWithMove(moveFileExW: MoveFileExW): Promise { + vi.resetModules() + vi.doMock('koffi', () => { + let lastError = 0 + const setLastError = (code: number): void => { lastError = code } + const move: MoveFileExW = (existing, replacement, flags, setError) => { + const ok = moveFileExW(existing, replacement, flags, setError) + lastError = ok ? 0 : lastError + return ok + } + return { + default: { + load: () => ({ + func: (_convention: string, name: string) => { + if (name === 'MoveFileExW') return (existing: string, replacement: string, flags: number) => { + const ok = move(existing, replacement, flags, setLastError) + return ok + } + return () => lastError + }, + }), + }, + } + }) + return import('../src/win32.ts') +} + +async function importWithError(code: number): Promise { + vi.resetModules() + vi.doMock('koffi', () => ({ + default: { + load: () => ({ + func: (_convention: string, name: string) => { + if (name === 'MoveFileExW') return () => false + return () => code + }, + }), + }, + })) + return import('../src/win32.ts') +} + +async function importWithFilesystemMove(): Promise { + return importWithMove((existing, replacement, flags, setLastError) => { + expect(flags).toBe(MOVEFILE_WRITE_THROUGH) + const from = stripNamespace(existing) + const to = stripNamespace(replacement) + if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return false } + if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return false } + renameSync(from, to) + return true + }) +} + +afterEach(async () => { + vi.doUnmock('koffi') + vi.resetModules() + for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }) +}) + +describe('Windows durable namespace helpers', () => { + it('publishes a new file with write-through MoveFileExW semantics', async () => { + const { publishNewFileWin32 } = await importWithFilesystemMove() + const root = await tempRoot() + const tmp = join(root, 'log.tmp') + const final = join(root, 'log.jsonl') + await writeFile(tmp, 'content') + + await publishNewFileWin32(tmp, final) + expect(existsSync(tmp)).toBe(false) + expect(readFileSync(final, 'utf8')).toBe('content') + }) + + it('maps Win32 publish failures to Node-style errno codes', async () => { + const cases = [ + [ERROR_FILE_NOT_FOUND, 'ENOENT'], + [ERROR_PATH_NOT_FOUND, 'ENOENT'], + [ERROR_ACCESS_DENIED, 'EACCES'], + [ERROR_NOT_SAME_DEVICE, 'EXDEV'], + [ERROR_FILE_EXISTS, 'EEXIST'], + [ERROR_ALREADY_EXISTS, 'EEXIST'], + [ERROR_INVALID_NAME, 'EINVAL'], + [9999, 'EIO'], + ] as const + for (const [win32Code, code] of cases) { + const { publishNewFileWin32 } = await importWithError(win32Code) + await expect(publishNewFileWin32('from', 'to')).rejects.toMatchObject({ code, win32Code, path: 'from', dest: 'to' }) + } + }) + + it('creates missing directories through staging siblings and tolerates an already-created race', async () => { + const root = await tempRoot() + const raced = join(root, 'raced') + const { ensureDurableDirectoryWin32 } = await importWithMove((existing, replacement, flags, setLastError) => { + expect(flags).toBe(MOVEFILE_WRITE_THROUGH) + const from = stripNamespace(existing) + const to = stripNamespace(replacement) + if (to === raced) { + mkdirSync(to) + setLastError(ERROR_ALREADY_EXISTS) + return false + } + if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return false } + if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return false } + renameSync(from, to) + return true + }) + + await ensureDurableDirectoryWin32(join(root, 'a', 'b')) + expect(existsSync(join(root, 'a', 'b'))).toBe(true) + await ensureDurableDirectoryWin32(join(root, 'a', 'b')) + await ensureDurableDirectoryWin32(raced) + expect(existsSync(raced)).toBe(true) + }) + + it('surfaces directory publication failures other than an existing-target race', async () => { + const { ensureDurableDirectoryWin32 } = await importWithError(ERROR_ACCESS_DENIED) + const root = await tempRoot() + + await expect(ensureDurableDirectoryWin32(join(root, 'denied'))).rejects.toMatchObject({ code: 'EACCES' }) + }) + + it('rejects a non-directory component instead of treating it as missing', async () => { + const { ensureDurableDirectoryWin32 } = await importWithFilesystemMove() + const root = await tempRoot() + const blocked = join(root, 'blocked') + writeFileSync(blocked, 'x') + + await expect(ensureDurableDirectoryWin32(join(blocked, 'child'))).rejects.toMatchObject({ code: 'ENOTDIR' }) + }) +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9810a9a61e..9e6532f466 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1259,6 +1259,9 @@ importers: packages/session-persistence/session-persistence-jsonl: dependencies: + koffi: + specifier: ^3.1.0 + version: 3.1.1 schemastery: specifier: ^3.18.0 version: 3.18.0 @@ -3453,6 +3456,81 @@ packages: '@jridgewell/trace-mapping@0.3.31': resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==} + '@koromix/koffi-darwin-arm64@3.1.1': + resolution: {integrity: sha512-+Dl0zQDh1Wb55AWOn9hp7K30qgkODvrvN+ZNkFOh81Q0oFX/rpJQtocgjAuYk2zFAcajSeVDumkcHMPwnKSXzA==} + cpu: [arm64] + os: [darwin] + + '@koromix/koffi-darwin-x64@3.1.1': + resolution: {integrity: sha512-cDFAKn1qdZBFLrp7dAc9QUDw3l4xAhTJbOdPWWb0LxssVicUdHcRCLZGrDsmPW2tpH6LGNNeLgqRpAoD2Mo8iA==} + cpu: [x64] + os: [darwin] + + '@koromix/koffi-freebsd-arm64@3.1.1': + resolution: {integrity: sha512-zaP7FJISI/scQW9Wa5QicY3a09WmtKBWSbmC+5nfCqPzwWe7Hx2so74Er7mPsDfCiMMR0Ya+evKbJQDkfyXicg==} + cpu: [arm64] + os: [freebsd] + + '@koromix/koffi-freebsd-ia32@3.1.1': + resolution: {integrity: sha512-7GejVb688TLM8rbjfc0oezJrATxZc0dn801xWEDJekN2DgmRXu7HquGqWQ6z3NeSq7ZxEggz4T3xtlbCysQapA==} + cpu: [ia32] + os: [freebsd] + + '@koromix/koffi-freebsd-x64@3.1.1': + resolution: {integrity: sha512-XLiCFP9OFCyOoGTjAimtDKLhzhfo34WcP1ShVWxRzNCWDGjfz8BYjwd69cp/cDSUXZbxamqs4+/6vmkePq9wxA==} + cpu: [x64] + os: [freebsd] + + '@koromix/koffi-linux-arm64@3.1.1': + resolution: {integrity: sha512-HA9xINK7G4dRAkpfnBWD9VfuyIBgW1SuK+KPHjksUwRMOnhgqP8J/JqgrAzdzcDiefGBkqEacIP776OUwz7knQ==} + cpu: [arm64] + os: [linux] + + '@koromix/koffi-linux-ia32@3.1.1': + resolution: {integrity: sha512-jG7IFytmP8K5Qtbx0ro0ZeuX3JjSsLxmYhq+nmXDdrtOAlxIsWGynuiDLS6Jk3vOchVii2m6Y2f/L3GLG2fG5A==} + cpu: [ia32] + os: [linux] + + '@koromix/koffi-linux-loong64@3.1.1': + resolution: {integrity: sha512-CIsT1cNnih8FuU52Me/IVlJBpH28SQfoDeYPctJswgJzaARktusF7m4MUbtR1PBDjuquCVM4/vFyNdOzfPonvA==} + cpu: [loong64] + os: [linux] + + '@koromix/koffi-linux-riscv64@3.1.1': + resolution: {integrity: sha512-9D6RmqeKsSvs3U6jILJU9PcAjMwKKyn7yLxNBb5k6z9PCoUoGJ3/BrhXAX0qjrLLwEiIpP/hS/40RuXvH8Lc3Q==} + cpu: [riscv64] + os: [linux] + + '@koromix/koffi-linux-x64@3.1.1': + resolution: {integrity: sha512-pyTcX5fePeYbt7TZAwRby69wdlRx3PT+g15ra5IYdat/Pgh3qAKEYeZ+uu7WpPGOy43p/oSRqqZoa2kORzozlA==} + cpu: [x64] + os: [linux] + + '@koromix/koffi-openbsd-ia32@3.1.1': + resolution: {integrity: sha512-iPnPzvG2HOfdzaiG1drdkt86sAqmTPDv9mAf+5gL7mRzkeeQC88EVGboRy7eXwdXn7R+v0ntA3iQxdHrBn6yXw==} + cpu: [ia32] + os: [openbsd] + + '@koromix/koffi-openbsd-x64@3.1.1': + resolution: {integrity: sha512-/Xqc3R0SVoMCYjMPZnJ9bULtRo364+dKmnQhfDrI83tSpxUHRw7HRNf12vBeL+hPgKxSBjtMpWfQ/ZIyVyLFag==} + cpu: [x64] + os: [openbsd] + + '@koromix/koffi-win32-arm64@3.1.1': + resolution: {integrity: sha512-JhqHauEwQvdcWUERxrV5HH/DT9W7hY1A1eU6/o8tB+yck+D3kt5elpRDBt9KjpW6h+vHPy3V0sjDvO0CXyabTA==} + cpu: [arm64] + os: [win32] + + '@koromix/koffi-win32-ia32@3.1.1': + resolution: {integrity: sha512-ZRuyYmlGS/rCc966qqs0qREXDW4FRdul7rDF1VgSWHbVmdc196PUgUT+blq/GjZgTwqzeEXtMRgM+cU8krHjvA==} + cpu: [ia32] + os: [win32] + + '@koromix/koffi-win32-x64@3.1.1': + resolution: {integrity: sha512-KqHPmvj6QILhNyI/To8QSihHsijeVGIYYPBOUnXEpcnH2LuLbargY4Hd6dDeTN3Z90uUUxN+1FWz1UnhVzFOiA==} + cpu: [x64] + os: [win32] + '@mermaid-js/parser@1.2.0': resolution: {integrity: sha512-oYPyv8A4As1yH5Bx+04iQEQxXuIQDe0GKCNSRgao6z8AM9jixXIfP0vsppRLvGf+nKIOb9/LdpWA4YuJiVvESA==} @@ -5662,6 +5740,9 @@ packages: engines: {node: ^20.19.0 || >=22.12.0} hasBin: true + koffi@3.1.1: + resolution: {integrity: sha512-mRX6AMeeKCxSOeOopqAcLAl5jcNvge7NAG8l7rF/8gGJATI0tdHFYjteIdE0mGOtWdsrJOij+PjnP8Q9c1gwgA==} + layout-base@1.0.2: resolution: {integrity: sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==} @@ -7842,6 +7923,51 @@ snapshots: '@jridgewell/resolve-uri': 3.1.2 '@jridgewell/sourcemap-codec': 1.5.5 + '@koromix/koffi-darwin-arm64@3.1.1': + optional: true + + '@koromix/koffi-darwin-x64@3.1.1': + optional: true + + '@koromix/koffi-freebsd-arm64@3.1.1': + optional: true + + '@koromix/koffi-freebsd-ia32@3.1.1': + optional: true + + '@koromix/koffi-freebsd-x64@3.1.1': + optional: true + + '@koromix/koffi-linux-arm64@3.1.1': + optional: true + + '@koromix/koffi-linux-ia32@3.1.1': + optional: true + + '@koromix/koffi-linux-loong64@3.1.1': + optional: true + + '@koromix/koffi-linux-riscv64@3.1.1': + optional: true + + '@koromix/koffi-linux-x64@3.1.1': + optional: true + + '@koromix/koffi-openbsd-ia32@3.1.1': + optional: true + + '@koromix/koffi-openbsd-x64@3.1.1': + optional: true + + '@koromix/koffi-win32-arm64@3.1.1': + optional: true + + '@koromix/koffi-win32-ia32@3.1.1': + optional: true + + '@koromix/koffi-win32-x64@3.1.1': + optional: true + '@mermaid-js/parser@1.2.0': dependencies: '@chevrotain/types': 11.1.2 @@ -10072,6 +10198,24 @@ snapshots: yaml: 2.9.0 zod: 4.4.3 + koffi@3.1.1: + optionalDependencies: + '@koromix/koffi-darwin-arm64': 3.1.1 + '@koromix/koffi-darwin-x64': 3.1.1 + '@koromix/koffi-freebsd-arm64': 3.1.1 + '@koromix/koffi-freebsd-ia32': 3.1.1 + '@koromix/koffi-freebsd-x64': 3.1.1 + '@koromix/koffi-linux-arm64': 3.1.1 + '@koromix/koffi-linux-ia32': 3.1.1 + '@koromix/koffi-linux-loong64': 3.1.1 + '@koromix/koffi-linux-riscv64': 3.1.1 + '@koromix/koffi-linux-x64': 3.1.1 + '@koromix/koffi-openbsd-ia32': 3.1.1 + '@koromix/koffi-openbsd-x64': 3.1.1 + '@koromix/koffi-win32-arm64': 3.1.1 + '@koromix/koffi-win32-ia32': 3.1.1 + '@koromix/koffi-win32-x64': 3.1.1 + layout-base@1.0.2: {} layout-base@2.0.1: {} diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 8f93814899..2de5578f5d 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -31,6 +31,8 @@ allowBuilds: '@google/genai': false protobufjs: false node-addon-require-builtin: false + # JSONL durability calls MoveFileExW with write-through publication on Windows. + koffi: true # The Landlock launcher family is our own sibling-repo release, consumed # fresh (hours old at each coordinated bump) — the release-age quarantine From 5ed34b66ce0d688a2440b42a25db99a7c71330de Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Wed, 8 Jul 2026 12:45:31 +0800 Subject: [PATCH 02/53] fix(acp-snapshot): make path-separator tests platform-neutral Three tests in the shared acp-snapshot package hardcoded POSIX path separators in their assertions, so they failed on Windows where node:path.join produces backslash paths: - childFixturePaths (suite.spec.ts): expected literal '/snap/s/session.1.jsonl' but join returns '\snap\s\...' on Windows; use join() for the expected value. - harness.spec.ts (env-forwarding test): substring-matched a JSON-encoded path against raw stdout text, where backslash escaping makes the compare byte-fragile; parse the env-probe chunk and compare the structured value. - harness.spec.ts (harvested-cwd test): substring-matched the raw cwd against JSONL text where the cwd is JSON-escaped; parse the session line and compare the cwd field. These were master's latent bugs (the package's tests never ran on Windows until the Windows CI lane observed them). Verified green on Windows via scripts/caohuanqi-private/run-ci.py --windows. --- .../support/acp-snapshot/tests/harness.spec.ts | 18 ++++++++++++++++-- .../support/acp-snapshot/tests/suite.spec.ts | 2 +- 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index 1d953f5e95..d141fb1f09 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -72,7 +72,11 @@ describe('runScenario', () => { expect(result.sessionLogs[0]?.createdAt).toBe(42) expect(result.sessionLogs[0]?.content).toContain('turn/start') // The harvested log embeds the run's REAL temp cwd (template-substituted). - expect(result.sessionLogs[0]?.content).toContain(result.cwd) + // The cwd is JSON-encoded in the log line, so compare the parsed field + // rather than substring-matching a raw path (which breaks when the path + // separator is escaped inside JSON text on Windows). + const sessionLine = result.sessionLogs[0]?.content.split('\n').find(l => l.includes('"type":"session"')) ?? '{}' + expect((JSON.parse(sessionLine) as { cwd?: string }).cwd).toBe(result.cwd) }) it('forwards override/child fixture paths into the child env and captures stderr', { timeout: 20_000 }, async () => { @@ -93,7 +97,17 @@ describe('runScenario', () => { expect(result.stderr).toContain('fake bin booted') expect(result.rawStdout).toContain('replay.override.json') // Child paths ride one env var, joined with the platform delimiter. - expect(result.rawStdout).toContain(JSON.stringify(childFiles.join(delimiter)).slice(1, -1)) + // Parse the fake bin's env-probe chunk rather than substring-matching a + // JSON-encoded path (the escaping breaks raw-substring compares on Windows). + const envChunk = result.rawStdout.split('\n') + .map(l => l.trim()) + .filter(l => l.length > 0) + .map(l => JSON.parse(l) as { params?: { update?: { content?: { text?: string } } } }) + .find(f => f.params?.update?.content?.text?.startsWith('env:')) + const env = JSON.parse((envChunk?.params?.update?.content?.text ?? 'env:{}').slice('env:'.length)) as { + childFiles: string | null + } + expect(env.childFiles).toBe(childFiles.join(delimiter)) }) it('seeds the workspace dir into the temp cwd before the run', { timeout: 20_000 }, async () => { diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts index 4cedc1cdfb..c2007321de 100644 --- a/packages/support/acp-snapshot/tests/suite.spec.ts +++ b/packages/support/acp-snapshot/tests/suite.spec.ts @@ -181,7 +181,7 @@ describe('defineAcpSnapshotSuite: registration contract', () => { describe('childFixturePaths', () => { it('yields one sibling path per child, 1-based', () => { - expect(childFixturePaths('/snap/s', 2)).toEqual(['/snap/s/session.1.jsonl', '/snap/s/session.2.jsonl']) + expect(childFixturePaths('/snap/s', 2)).toEqual([join('/snap/s', 'session.1.jsonl'), join('/snap/s', 'session.2.jsonl')]) }) it('yields nothing for a single-session scenario', () => { From 1a4af034c0edd60e4bd54de1f2a1371afbdef056 Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Sun, 5 Jul 2026 04:45:41 +0800 Subject: [PATCH 03/53] Accept native ACP path separators in tests --- packages/ui/acp/README.md | 4 +- packages/ui/acp/tests/stream-update.spec.ts | 53 ++++++++++++++------- 2 files changed, 37 insertions(+), 20 deletions(-) diff --git a/packages/ui/acp/README.md b/packages/ui/acp/README.md index 300cd69023..4f810ba0b4 100644 --- a/packages/ui/acp/README.md +++ b/packages/ui/acp/README.md @@ -53,11 +53,11 @@ The shared [`ctx.tasks` runtime](../../tasks/tasks/) fences access to predictabl ## Tool-call presentation -Tools return provider-neutral `generic`, `terminal`, or `diff` render intents from `presentCall()` and `presentResult()`. The bridge maps the discriminator to ACP without special-casing tool names and falls back to a generic card. Per-session call-id state supplies result events with their omitted name and arguments during live streaming and replay. See [`dsh-tools`](../../core/tools/README.md#tool-owned-ui-presentation). +Tools return provider-neutral `generic`, `terminal`, or `diff` render intents from `presentCall()` and `presentResult()`. The bridge maps the discriminator to ACP without special-casing tool names and falls back to a generic card. Per-session call-id state supplies result events with their omitted name and arguments during live streaming and replay. File-card titles are relative to the session cwd and use the host separator, while location and diff paths remain raw so the editor opens the real file. See [`dsh-tools`](../../core/tools/README.md#tool-owned-ui-presentation). ## Terminal card (capability-gated) -When the client advertises `_meta.terminal_output`, terminal intents map to Zed's terminal info, output, and exit metadata. The bridge resolves relative cwd against the session, places the description before the terminal block, and omits result content because ACP updates replace call content. Other clients receive a generic card and bridge-derived fenced console fallback. Session creation snapshots the capability so call and result agree. The command still executes through the harness, not ACP terminal creation. See the [terminal-rendering RFC](../../../docs/rfc/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) and [render-intent RFC](../../../docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md). +When the client advertises `_meta.terminal_output`, terminal intents map to Zed's terminal info, output, and exit metadata. The bridge resolves relative cwd against the session and preserves the host filesystem separator, places the description before the terminal block, and omits result content because ACP updates replace call content. Other clients receive a generic card and bridge-derived fenced console fallback. Session creation snapshots the capability so call and result agree. The command still executes through the harness, not ACP terminal creation. See the [terminal-rendering RFC](../../../docs/rfc/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) and [render-intent RFC](../../../docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md). ## Settle-exactly-once diff --git a/packages/ui/acp/tests/stream-update.spec.ts b/packages/ui/acp/tests/stream-update.spec.ts index 415e9afb33..15a6d3c3fc 100644 --- a/packages/ui/acp/tests/stream-update.spec.ts +++ b/packages/ui/acp/tests/stream-update.spec.ts @@ -1,4 +1,5 @@ import { describe, expect, it } from 'vitest' +import { join as pathJoin, resolve as pathResolve } from 'node:path' import { Context } from 'cordis' import { CallId } from '@deepseek-ai/dsh-llm' import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session' @@ -49,6 +50,16 @@ function evt(type: T, data: Extract { it('maps assistant/chunk text-delta to agent_message_chunk', () => { expect(updatesFor(evt('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'hi' } }))) @@ -480,10 +491,10 @@ describe('terminal-card mapping (capability-gated)', () => { it('capability ON: an ABSOLUTE tool cwd wins; a RELATIVE one resolves against the session cwd', () => { const [absCall] = termUpdates(termTool({ card: 'terminal', cwd: '/explicit/abs' }, { output: 'x' }), true, '/work/proj', callEvent) expect((absCall as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe('/explicit/abs') - const [relCall] = termUpdates(termTool({ card: 'terminal', cwd: 'sub/dir' }, { output: 'x' }), true, '/work/proj', callEvent) + const [relCall] = termUpdates(termTool({ card: 'terminal', cwd: nativePath('sub', 'dir') }, { output: 'x' }), true, nativeAbsolute('/work/proj'), callEvent) // Relative workdir resolved against the session cwd — the card header matches // where execution actually ran (tool-bash resolves the same way). - expect((relCall as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe('/work/proj/sub/dir') + expect((relCall as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe(nativeAbsolute('/work/proj', 'sub', 'dir')) // No session cwd to resolve against → the relative tool cwd is passed through as-is. const [noSessionCwd] = termUpdates(termTool({ card: 'terminal', cwd: 'rel/only' }, { output: 'x' }), true, undefined, callEvent) expect((noSessionCwd as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe('rel/only') @@ -675,10 +686,12 @@ describe('result-time diff card (REAL fs edit tool → tool_call_update diff blo // paths remain absolute so the editor can open the real file. const ctx = await fsCtx() const presenter = new ToolPresenter(ctx.tools) - const args = JSON.stringify({ file_path: '/work/proj/src/b.ts', old_string: 'OLD', new_string: 'NEW' }) - const meta = { diffs: [{ path: '/work/proj/src/b.ts', oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }] } + const workspace = nativeAbsolute('/work/proj') + const file = nativeAbsolute('/work/proj', 'src', 'b.ts') + const args = JSON.stringify({ file_path: file, old_string: 'OLD', new_string: 'NEW' }) + const meta = { diffs: [{ path: file, oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }] } const out: SessionNotification['update'][] = [] - const rendering = { enabled: false, cwd: '/work/proj' } + const rendering = { enabled: false, cwd: workspace } for (const event of [ evt('tool/call', { turn: 1, step: 1, callId: CallId('e1'), name: 'edit', arguments: args }), evt('tool/result', { turn: 1, step: 1, callId: CallId('e1'), content: [{ type: 'text', text: 'ok' }], isError: false, meta }), @@ -687,8 +700,8 @@ describe('result-time diff card (REAL fs edit tool → tool_call_update diff blo sessionUpdate: 'tool_call_update', toolCallId: 'e1', status: 'completed', - title: 'Edit src/b.ts', - content: [{ type: 'diff', path: '/work/proj/src/b.ts', oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }], + title: `Edit ${nativePath('src', 'b.ts')}`, + content: [{ type: 'diff', path: file, oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }], }) await ctx.fiber.dispose() }) @@ -739,21 +752,25 @@ describe('relative-path display titles (bridge relativizes the title against the it('read: an absolute path inside the workspace relativizes the TITLE; the location path stays absolute', async () => { const ctx = await fsCtx() - const update = callUpdate(ctx, '/work/proj', 'read', { file_path: '/work/proj/src/a.ts', offset: 5 }) + const workspace = nativeAbsolute('/work/proj') + const file = nativeAbsolute('/work/proj', 'src', 'a.ts') + const update = callUpdate(ctx, workspace, 'read', { file_path: file, offset: 5 }) expect(update).toMatchObject({ - title: 'Read src/a.ts (from line 5)', - locations: [{ path: '/work/proj/src/a.ts', line: 5 }], + title: `Read ${nativePath('src', 'a.ts')} (from line 5)`, + locations: [{ path: file, line: 5 }], }) await ctx.fiber.dispose() }) it('edit: the diff TITLE relativizes; the diff/location paths stay absolute (the editor opens the real path)', async () => { const ctx = await fsCtx() - const update = callUpdate(ctx, '/work/proj', 'edit', { file_path: '/work/proj/src/b.ts', old_string: 'x', new_string: 'y' }) + const workspace = nativeAbsolute('/work/proj') + const file = nativeAbsolute('/work/proj', 'src', 'b.ts') + const update = callUpdate(ctx, workspace, 'edit', { file_path: file, old_string: 'x', new_string: 'y' }) expect(update).toMatchObject({ - title: 'Edit src/b.ts', - locations: [{ path: '/work/proj/src/b.ts' }], - content: [{ type: 'diff', path: '/work/proj/src/b.ts', oldText: 'x', newText: 'y' }], + title: `Edit ${nativePath('src', 'b.ts')}`, + locations: [{ path: file }], + content: [{ type: 'diff', path: file, oldText: 'x', newText: 'y' }], }) await ctx.fiber.dispose() }) @@ -770,8 +787,8 @@ describe('relative-path display titles (bridge relativizes the title against the // with the chars `..` but is not a parent segment. Segment-aware guarding must relativize it, // matching targets under `cwd + sep` in the reference adapter. const ctx = await fsCtx() - const update = callUpdate(ctx, '/work/proj', 'read', { file_path: '/work/proj/..cache/x.ts' }) - expect((update as { title: string }).title).toBe('Read ..cache/x.ts') + const update = callUpdate(ctx, nativeAbsolute('/work/proj'), 'read', { file_path: nativeAbsolute('/work/proj', '..cache', 'x.ts') }) + expect((update as { title: string }).title).toBe(`Read ${nativePath('..cache', 'x.ts')}`) await ctx.fiber.dispose() }) @@ -784,8 +801,8 @@ describe('relative-path display titles (bridge relativizes the title against the it('a relative path is passed through unchanged (already display-friendly)', async () => { const ctx = await fsCtx() - const update = callUpdate(ctx, '/work/proj', 'read', { file_path: 'src/a.ts' }) - expect((update as { title: string }).title).toBe('Read src/a.ts') + const update = callUpdate(ctx, nativeAbsolute('/work/proj'), 'read', { file_path: nativePath('src', 'a.ts') }) + expect((update as { title: string }).title).toBe(`Read ${nativePath('src', 'a.ts')}`) await ctx.fiber.dispose() }) }) From 130944caeb8118033f5de86f4a1df1c85e962595 Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Sun, 5 Jul 2026 17:47:24 +0800 Subject: [PATCH 04/53] Close SQLite probe handle after journalMode assertion --- .../session-persistence-sqlite/tests/sqlite.spec.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts index a728cc0b71..cebfae09a4 100644 --- a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts +++ b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts @@ -423,7 +423,9 @@ describe('SessionPersistenceSqlite: edge cases', () => { const walPath = await freshDbPath() const bWal = await backend(walPath) await bWal.ctx.sessionPersistence.create(meta('jm-wal')) - expect((openDatabase(walPath, 'wal').prepare('PRAGMA journal_mode').get() as { journal_mode: string }).journal_mode).toBe('wal') + const probe = openDatabase(walPath, 'wal') + expect((probe.prepare('PRAGMA journal_mode').get() as { journal_mode: string }).journal_mode).toBe('wal') + probe.close() await bWal.dispose() const deletePath = await freshDbPath() From 715aa7372a0ab51c5780a4d014009138da5f1444 Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Sun, 5 Jul 2026 18:57:23 +0800 Subject: [PATCH 05/53] Restore ENOTDIR semantic distinction in resolveLocalTarget on Windows --- packages/fs/fs-local/src/fsio.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts index 360145e8c8..e0745f1735 100644 --- a/packages/fs/fs-local/src/fsio.ts +++ b/packages/fs/fs-local/src/fsio.ts @@ -145,8 +145,22 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise Date: Sun, 5 Jul 2026 21:15:46 +0800 Subject: [PATCH 06/53] fs-local: POSIX-only mode-bit assertions, document Windows DACL-inheritance semantics Windows drives only the read-only attribute through chmod and reports synthetic stat mode bits, so writeFileAtomic's mode arguments are inert there; write-in-progress privacy comes from the staging dir (created in the target's parent) inheriting the destination directory's DACL. Production is deliberately unchanged -- the chmod calls are benign no-ops and platform-guarding them out buys nothing. Tests guard the mode-bit expects to POSIX; there is no Windows ACL assertion because an ACL check would pin OS inheritance plus the machine's %TEMP% ACL, not this package. Decision and rejected alternatives (explicit DACLs, Get-Acl/icacls test verification) recorded in the new RFC. --- docs/rfc/INDEX.md | 1 + .../2026-07-05-windows-fs-permissions.md | 29 +++++++++++++++++++ packages/fs/fs-local/README.md | 2 +- packages/fs/fs-local/src/fsio.ts | 4 ++- packages/fs/fs-local/tests/fsio.spec.ts | 19 +++++++++--- 5 files changed, 49 insertions(+), 6 deletions(-) create mode 100644 docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index 32f11b744a..5ebf52f07a 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -150,6 +150,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Prompt variables and tool-guidance ownership](implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) | 2026-07-05 | | [Every LLM request is reconstructable from the session log](implemented/architecture/2026-07-05-reconstructable-requests.md) | 2026-07-05 | | [Subagent provider-lifecycle events — `subagent/provider-added` / `subagent/provider-removed`](implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md) | 2026-07-05 | +| [Windows write-permission semantics — inherited DACLs, not mode bits](implemented/architecture/2026-07-05-windows-fs-permissions.md) | 2026-07-05 | | [Windows-native durable JSONL publication](implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md) | 2026-07-05 | | [A shared timeout/deadline primitive, with hard-kill left to each capability](implemented/architecture/2026-07-06-timeout-deadline-library.md) | 2026-07-06 | | [Tool result retention library](implemented/architecture/2026-07-06-tool-result-retention-library.md) | 2026-07-06 | diff --git a/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md b/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md new file mode 100644 index 0000000000..0001e8223c --- /dev/null +++ b/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md @@ -0,0 +1,29 @@ +# RFC: Windows write-permission semantics — inherited DACLs, not mode bits + +Status: implemented + +## Problem + +`writeFileAtomic` in `@deepseek-ai/dsh-fs-local` protects write-in-progress content with POSIX mode bits: the staging directory is created `0o700`, the temp file is opened `0o600`, and new files default to `0o600`. On POSIX this keeps temporary content owner-only regardless of the parent directory's permissions. + +Windows has no working equivalent behind the same API. Node's `chmod` there drives only the read-only attribute (every mode this package passes carries owner-write, so the calls are benign no-ops), and `stat().mode` reports synthetic `0o666`/`0o444` bits. The real security state is the file's DACL, which this code never sets; a newly created file or directory inherits its DACL from its parent directory. + +## Decision + +Production code is unchanged: no platform fork, no DACL management. The Windows privacy invariant is structural rather than mode-driven — the staging directory is created inside the target's parent directory (`dirname(absolutePath)`), so it and the temp file inherit exactly the destination directory's DACL, and write-in-progress content is never exposed more widely than the destination itself. In the typical deployment (a coding agent writing the user's own project tree under `C:\Users\\`) the inherited DACL is owner + SYSTEM + Administrators, matching the POSIX intent. + +Tests assert mode bits on POSIX only. There is no Windows-side ACL assertion because there is no Windows-side code behavior to pin: an ACL check on a `mkdtemp(tmpdir())` fixture would verify Windows DACL inheritance plus the machine's `%TEMP%` ACL — the operating system, not this package — and no change to this package could turn it red. + +## Alternatives considered + +**Explicit protected DACLs.** Granting owner-only access would require per-write FFI or a subprocess, break inheritance, and surprise users whose project directories are deliberately shared. This becomes appropriate only if the threat model includes hostile local readers of broadly accessible target directories. + +**Test-side ACL verification.** A `Get-Acl` SID allowlist or `icacls` would verify Windows inheritance and the machine's `%TEMP%` ACL rather than package behavior; `icacls` also localizes well-known account names, making parsing locale-fragile. + +**Skip `chmod` on Windows.** Platform-guarding benign no-op calls adds branches without changing behavior. + +## Consequences + +POSIX keeps the stronger guarantee: owner-only temp content regardless of the parent directory. Windows guarantees only "no wider than the destination": a target inside a broadly accessible directory (a share, a permissive `D:\` root) gets equally accessible write-in-progress content. The gap is deliberate and documented, not an oversight. + +Mode preservation across a replace degenerates to a no-op on Windows: a writable file probes as `0o666`, and replaying that through `chmod` leaves the read-only attribute clear. A read-only target cannot be replaced at all there — `rename` over it fails before the preserved mode would matter. diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md index 65ed76efce..7c3899e5cb 100644 --- a/packages/fs/fs-local/README.md +++ b/packages/fs/fs-local/README.md @@ -16,7 +16,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() }) - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence. - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing. - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`. -- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`. The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`). +- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows the mode bits drive only the read-only attribute, and write-in-progress privacy comes instead from the staging dir inheriting the destination directory's DACL ([Windows write-permission RFC](../../../docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`). - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`). The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring. diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts index e0745f1735..4603611ce4 100644 --- a/packages/fs/fs-local/src/fsio.ts +++ b/packages/fs/fs-local/src/fsio.ts @@ -408,9 +408,11 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow /** * Atomically replace a file through a private, synced staging file in the same directory. + * POSIX protects the staging directory and file with `0o700` and `0o600`; Windows + * inherits the destination directory's DACL because Node mode bits are synthetic there. * @param absolutePath - destination; missing parent directories are created. * @param content - the full UTF-8 text to write. - * @param mode - final mode, or `0o600` when omitted. + * @param mode - final POSIX mode, or `0o600` when omitted; inert on Windows. * @param signal - cancellation checked before the final rename. * @param internals - test seam for pinning temp names and observing the staged file. */ diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts index 199c01f411..559ef86563 100644 --- a/packages/fs/fs-local/tests/fsio.spec.ts +++ b/packages/fs/fs-local/tests/fsio.spec.ts @@ -367,6 +367,12 @@ describe('streamWholeText', () => { }) }) +// Windows drives only the read-only attribute through `chmod` and reports +// synthetic `stat` mode bits, so mode assertions are POSIX-only; on Windows +// write-in-progress privacy comes from the destination directory's inherited +// DACL (docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md). +const posixModes = process.platform !== 'win32' + describe('writeFileAtomic — temp-file safety', () => { it('writes through a private staging dir and owner-only temp file', async () => { const file = join(dir, 'a.txt') @@ -374,17 +380,22 @@ describe('writeFileAtomic — temp-file safety', () => { await writeFileAtomic(file, 'hello', 0o640, undefined, { inspectTemp: async ({ stagingDir, tempPath }) => { inspected = true - expect((await stat(stagingDir)).mode & 0o777).toBe(0o700) - expect((await stat(tempPath)).mode & 0o777).toBe(0o600) + const [staging, temp] = await Promise.all([stat(stagingDir), stat(tempPath)]) + expect(staging.isDirectory()).toBe(true) + expect(temp.isFile()).toBe(true) + if (posixModes) { + expect(staging.mode & 0o777).toBe(0o700) + expect(temp.mode & 0o777).toBe(0o600) + } }, }) expect(inspected).toBe(true) expect(await readFile(file, 'utf8')).toBe('hello') - expect((await stat(file)).mode & 0o777).toBe(0o640) + if (posixModes) expect((await stat(file)).mode & 0o777).toBe(0o640) expect((await readdir(dir)).filter(n => n.includes('.tmp'))).toEqual([]) }) - it('creates new files owner-only by default', async () => { + it.skipIf(!posixModes)('creates new files owner-only by default', async () => { const file = join(dir, 'a.txt') await writeFileAtomic(file, 'hello', undefined, undefined) expect((await stat(file)).mode & 0o777).toBe(0o600) From 5a2ca3ff3aaa6b3410572c9a443ca98625b557ad Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Fri, 17 Jul 2026 15:43:44 +0800 Subject: [PATCH 07/53] Restore JSONL ENOTDIR distinction on Windows --- .../session-persistence-jsonl/src/index.ts | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts index ac1c07860e..2f33664139 100644 --- a/packages/session-persistence/session-persistence-jsonl/src/index.ts +++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts @@ -8,7 +8,7 @@ import { Context } from 'cordis' import z from 'schemastery' -import { open, mkdir, readFile, readdir, link, rm, truncate } from 'node:fs/promises' +import { open, mkdir, readFile, readdir, link, rm, stat as fsStat, truncate } from 'node:fs/promises' import { dirname, resolve } from 'node:path' import { randomBytes } from 'node:crypto' import { @@ -389,7 +389,27 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } catch (error) { // Only ENOENT means absent. A permission/I/O error must surface rather // than letting load or collision checks proceed under false absence. - if (isENOENT(error)) return false + // Windows reports ENOENT, not ENOTDIR, for `regular-file/child`; verify + // the immediate parent so a blocked cwd bucket remains a storage fault. + if (isENOENT(error)) { + await this.assertLogParentAllowsAbsence(path) + return false + } + throw error + } + } + + private async assertLogParentAllowsAbsence(path: string): Promise { + try { + const parent = dirname(path) + const info = await fsStat(parent) + if (info.isDirectory()) return + const error = new Error(`ENOTDIR: parent path exists but is not a directory: ${parent}`) as NodeJS.ErrnoException + error.code = 'ENOTDIR' + error.path = parent + throw error + } catch (error) { + if (isENOENT(error)) return throw error } } From 86c09f6ca9d4bcec8226bd7a62febb1580bb96f4 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 17 Jul 2026 15:50:37 +0800 Subject: [PATCH 08/53] test(jsonl): mark native Windows ENOTDIR coverage --- docs/config-catalog.md | 2 +- .../session-persistence/session-persistence-jsonl/src/index.ts | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 3e3d8141fa..ba273888d1 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -634,7 +634,7 @@ export interface Config { } ``` -Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:24`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) +Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:25`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) ## `@deepseek-ai/dsh-session-persistence-sqlite` diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts index 2f33664139..39aa493a0b 100644 --- a/packages/session-persistence/session-persistence-jsonl/src/index.ts +++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts @@ -399,6 +399,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } } + /* v8 ignore start -- native Windows coverage exercises this repair; POSIX open reports ENOTDIR before this point. */ private async assertLogParentAllowsAbsence(path: string): Promise { try { const parent = dirname(path) @@ -413,6 +414,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi throw error } } + /* v8 ignore stop */ } export default SessionPersistenceJsonl From beb13c3808c643a93e3a4b0d6fc698d050638321 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 17 Jul 2026 13:53:13 +0800 Subject: [PATCH 09/53] test(acp): pin Windows-native snapshot paths --- examples/acp-agent/tests/acp.snapshot.ts | 10 +- .../stdout.golden.windows.jsonl | 132 ++++++++++++++++++ packages/support/acp-snapshot/README.md | 10 +- packages/support/acp-snapshot/src/harness.ts | 11 +- packages/support/acp-snapshot/src/index.ts | 2 + .../support/acp-snapshot/src/normalize.ts | 66 +++++++-- packages/support/acp-snapshot/src/suite.ts | 49 ++++++- .../acp-snapshot/tests/harness.spec.ts | 7 +- .../acp-snapshot/tests/normalize.spec.ts | 77 ++++++++++ .../support/acp-snapshot/tests/suite.spec.ts | 26 ++++ 10 files changed, 367 insertions(+), 23 deletions(-) create mode 100644 examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index 23eca9dbc0..e68724cbfe 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -57,7 +57,15 @@ const SCENARIOS: Scenario[] = [ { name: 'fs-terminal-card', hasModelTurn: true, recorded: true }, { name: 'todo-plan', hasModelTurn: true, recorded: true }, { name: 'skill-load', hasModelTurn: true, recorded: false, pinsHeader: true, headerClass: 'skill' }, - { name: 'workspace-edit', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'fs', configPath: FS_CONFIG }, + { + name: 'workspace-edit', + hasModelTurn: true, + recorded: true, + pinsHeader: true, + pinsNativeWindowsStdout: true, + headerClass: 'fs', + configPath: FS_CONFIG, + }, { name: 'fs-read', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG }, { name: 'fs-write', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG }, { name: 'fs-edit', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG }, diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl new file mode 100644 index 0000000000..5f8762adcd --- /dev/null +++ b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl @@ -0,0 +1,132 @@ +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} +{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"Sets this session's sandbox and approval behavior.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Read"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" greeting"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".txt"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Append"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" word"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" WORLD"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" as"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" second"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" line"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"3"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Read"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" back"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" cat"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" confirm"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"4"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" start"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" by"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reading"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" see"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" its"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" contents"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_OjRFB4zvxu6UALDjytZD0978","title":"Read greeting.txt","kind":"read","status":"in_progress","locations":[{"path":"greeting.txt","line":1}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_OjRFB4zvxu6UALDjytZD0978","status":"completed","content":[{"type":"content","content":{"type":"text","text":"{{cwd}}\\greeting.txt\nfile\n\n1: hello\n\n(End of file - total 1 lines)\n"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" contains"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"hello"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" on"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" one"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" line"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Now"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" append"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" second"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" line"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WOR"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"LD"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Then"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" cat"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" confirm"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_IUUvbNiPcnwhVL8ErEFS4806","title":"printf '\\nWORLD' >> greeting.txt","kind":"execute","status":"in_progress","rawInput":"printf '\\nWORLD' >> greeting.txt","content":[{"type":"content","content":{"type":"text","text":"Append newline and WORLD to greeting.txt"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_IUUvbNiPcnwhVL8ErEFS4806","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```console\n(no output)\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Good"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":","}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" now"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" read"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" back"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" cat"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_Wo4H7tFNheZJWKVDrAHK5851","title":"cat greeting.txt","kind":"execute","status":"in_progress","rawInput":"cat greeting.txt","content":[{"type":"content","content":{"type":"text","text":"Read greeting.txt to confirm"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_Wo4H7tFNheZJWKVDrAHK5851","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```console\nhello\n\nWORLD\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" now"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" has"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" two"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" lines"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" hello"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" WORLD"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"I"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" can"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md index 222d572043..9969eadb46 100644 --- a/packages/support/acp-snapshot/README.md +++ b/packages/support/acp-snapshot/README.md @@ -4,9 +4,9 @@ The ACP snapshot suite kit: the shared machinery behind the keyless snapshot tie Three layers, importable separately: -- **`runScenario` (harness)** — boots the real agent bin as a subprocess via tsx (unbuilt, Loader path), drives it over ACP JSON-RPC stdio from a deterministic `input.json` script, tees raw stdout for the golden + purity check, and harvests every persisted session JSONL (parent + subagent children, primary-first) after a graceful stdin-EOF shutdown. Parameterized by `AgentUnderTest` (`binScript`, `configPath`, `tsconfigPath` — absolute paths; the subprocess cwd is a temp dir outside the repo). Startup failures preserve captured agent stderr in the rejected diagnostic. -- **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)). -- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario golden + re-persisted-log compares, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, the per-header-class pin (`system-prompt.golden.md` plus `tool-schemas.golden.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Must be called at vitest collection time. +- **`runScenario` (harness)** — boots the real agent bin in the selected example mode: source under tsx or built `lib` under plain Node. It drives ACP JSON-RPC stdio from a deterministic `input.json` script, tees raw stdout for the golden and purity check, and harvests every persisted session JSONL (parent and subagent children, primary-first) after graceful stdin EOF. `AgentUnderTest` supplies absolute `binScript`, `configPath`, and `tsconfigPath` paths because the subprocess cwd is a temp directory outside the repo. Startup failures preserve captured agent stderr in the rejected diagnostic. +- **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; cwd-rooted separators → `/` for shared goldens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)). +- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario shared golden + re-persisted-log compares, optional Windows-native stdout sidecars, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, the per-header-class pin (`system-prompt.golden.md` plus `tool-schemas.golden.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Must be called at vitest collection time. A consuming `*.snapshot.ts` is the scenario table plus one factory call: @@ -37,6 +37,8 @@ defineAcpSnapshotSuite({ A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.golden.md` and the corresponding full tool-schema sequence in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences. +Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. A scenario may set `pinsNativeWindowsStdout` to add a Windows-only comparison against the complete `stdout.golden.windows.jsonl`; the shared golden still runs first on Windows, and the fixture guard requires the sidecar exactly when declared. + Examples use a `cordis.snapshot.yml` overlay with [`dsh-llm-replay`](../llm-replay/README.md). Recording calls the live model and updates model fixtures; keyless refresh replays those fixtures and updates derived stdout, session-log, prompt, and tool-schema snapshots. See the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md). `suite.ts` imports Vitest, so use this package only inside a Vitest run. The ACP-specific script queues permission answers by stable option kind and maps them to current option ids; a missing answer cancels, while an unavailable kind fails the scenario after cancelling the agent request. It can also set session config options or assert that unknown ids and values are rejected in the transcript. @@ -48,4 +50,4 @@ None, as this test-only harness records, normalizes, and compares ACP transcript ## Known Limitations and Deferred Work - **Session harvest is JSONL-only** — `runScenario` collects persisted `.jsonl` logs, so an example composed over the SQLite persistence backend has no snapshot path. -- **The subprocess boots the unbuilt tsx/Loader path only** — the built-bin artifact is guarded by the separate `built-bin` e2e smokes, never by this tier. +- **Built mode requires current artifacts** — run `pnpm run build` before selecting `DSH_EXAMPLE_MODE=lib`; source mode remains the zero-build path. diff --git a/packages/support/acp-snapshot/src/harness.ts b/packages/support/acp-snapshot/src/harness.ts index e2072b6b17..cf8d7afc27 100644 --- a/packages/support/acp-snapshot/src/harness.ts +++ b/packages/support/acp-snapshot/src/harness.ts @@ -150,6 +150,15 @@ export interface RunOptions { configPath?: string } +/** + * Return a fixed-length spill root across POSIX and Windows after Windows adds its drive prefix. + * @param platform - the host platform, injectable for unit coverage. + * @returns the root-relative snapshot spill directory. + */ +export function snapshotSpillRoot(platform: NodeJS.Platform = process.platform): string { + return platform === 'win32' ? '/t/dsh-acp-snapshot-spill' : '/tmp/dsh-acp-snapshot-spill' +} + /** * Run a scenario end-to-end against a freshly-spawned subprocess. Owns the * child and its temp dirs; always tears them down. Returns the captured stdout @@ -164,7 +173,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise const sessionsRoot = await mkdtemp(join(tmpdir(), 'acp-snap-sessions-')) // Fixed path length: spill-policy budgets the preview against the REAL path // before stdout normalization, so tmpdir() length differences churn goldens. - const spillRoot = '/tmp/dsh-acp-snapshot-spill' + const spillRoot = snapshotSpillRoot() // Everything past the temp-dir creation runs under a try/finally that always // removes both dirs — so a failure in workspace seeding, spawn, or any step // never leaks them (the "e2e tests own their resources" rule). diff --git a/packages/support/acp-snapshot/src/index.ts b/packages/support/acp-snapshot/src/index.ts index bdf8cccaf7..46eac5568b 100644 --- a/packages/support/acp-snapshot/src/index.ts +++ b/packages/support/acp-snapshot/src/index.ts @@ -21,7 +21,9 @@ export { scrubRequestHeaders, scrubSystemPrompts, scrubToolSchemas, + type CwdPathMode, type NormalizeContext, + type NormalizeOptions, } from './normalize.ts' export { defineAcpSnapshotSuite, diff --git a/packages/support/acp-snapshot/src/normalize.ts b/packages/support/acp-snapshot/src/normalize.ts index 48761864f0..76bd40d610 100644 --- a/packages/support/acp-snapshot/src/normalize.ts +++ b/packages/support/acp-snapshot/src/normalize.ts @@ -12,19 +12,33 @@ const SYSTEM = '{{system}}' const TOOLS = '{{tools}}' const MESSAGE_PREFIX = '{{messagePrefix}}' +/** A cwd-rooted path after volatile cwd replacement, through its last separator-delimited segment. */ +const CWD_ROOTED_PATH_RE = /\{\{cwd\}\}(?:[\\/][^\s<>"'`]+)+/g +const PATH_TAG_RE = /()([^<]*)(<\/path>)/g +const ADDITIONAL_INSTRUCTIONS_PATH_RE = /(Additional instructions from: )([^\r\n]+)/g + /** A UUID v4 string, the shape `randomUUID()` produces for session ids. */ const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi const LOCAL_SPILL_PATH_RE = new RegExp( - String.raw`\{\{cwd\}\}/\.spill/session-[0-9a-f]{12}/[0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`\{\{cwd\}\}[\\/]\.spill[\\/]session-[0-9a-f]{12}[\\/][0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`(?=\. Use read with offset/limit|[\s)]|$)`, 'g', ) const SNAPSHOT_SPILL_PATH_RE = new RegExp( - String.raw`/tmp/dsh-acp-snapshot-spill/session-[0-9a-f]{12}/[0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`(?:[A-Za-z]:)?[\\/](?:tmp|t)[\\/]dsh-acp-snapshot-spill[\\/]session-[0-9a-f]{12}[\\/][0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`(?=\. Use read with offset/limit|[\s)]|$)`, 'g', ) +/** Convert separators only inside generated path-bearing text markers. */ +function canonicalizeEmbeddedPaths(value: string): string { + return value + .replace(PATH_TAG_RE, (_match, open: string, path: string, close: string) => + `${open}${path.replaceAll('\\', '/')}${close}`) + .replace(ADDITIONAL_INSTRUCTIONS_PATH_RE, (_match, prefix: string, path: string) => + `${prefix}${path.replaceAll('\\', '/')}`) +} + /** Inputs the normalizers need to recognize a run's volatile values. */ export interface NormalizeContext { /** The session id(s) the run issued — replaced with `{{sessionId}}`. */ @@ -33,13 +47,28 @@ export interface NormalizeContext { cwd: string } +/** How cwd-rooted path separators are represented after the cwd is tokenized. */ +export type CwdPathMode = 'canonical' | 'native' + +/** Optional controls shared by stdout and session-log normalization. */ +export interface NormalizeOptions { + /** Use `/` for shared goldens, or preserve captured separators for a platform-specific golden. */ + cwdPathMode?: CwdPathMode +} + /** Replace cwd, session ids, and any stray UUID with stable tokens in a string. */ -function scrubString(value: string, ctx: NormalizeContext): string { +function scrubString(value: string, ctx: NormalizeContext, cwdPathMode: CwdPathMode): string { let out = value // cwd first (longest, most specific), then explicit session ids, then any // residual UUID (covers ids that appear in places we didn't enumerate). out = out.split(ctx.cwd).join(CWD) out = out.split(`/private${CWD}`).join(CWD) + if (cwdPathMode === 'canonical') { + // Restrict separator conversion to paths rooted at the cwd token. A global + // backslash rewrite would corrupt regexes, commands, and model-authored text. + out = out.replace(CWD_ROOTED_PATH_RE, path => path.replaceAll('\\', '/')) + out = canonicalizeEmbeddedPaths(out) + } out = out.replace(LOCAL_SPILL_PATH_RE, (_match, name: string) => `{{spillLocator:${name}}}`) out = out.replace(SNAPSHOT_SPILL_PATH_RE, (_match, name: string) => `{{spillLocator:${name}}}`) for (const id of ctx.sessionIds) out = out.split(id).join(SESSION_ID) @@ -48,12 +77,15 @@ function scrubString(value: string, ctx: NormalizeContext): string { } /** Recursively scrub a parsed JSON value (strings replaced; structure kept). */ -function scrubValue(value: unknown, ctx: NormalizeContext): unknown { - if (typeof value === 'string') return scrubString(value, ctx) - if (Array.isArray(value)) return value.map(v => scrubValue(v, ctx)) +function scrubValue(value: unknown, ctx: NormalizeContext, cwdPathMode: CwdPathMode, key?: string): unknown { + if (typeof value === 'string') { + const scrubbed = scrubString(value, ctx, cwdPathMode) + return cwdPathMode === 'canonical' && key === 'path' ? scrubbed.replaceAll('\\', '/') : scrubbed + } + if (Array.isArray(value)) return value.map(v => scrubValue(v, ctx, cwdPathMode)) if (value !== null && typeof value === 'object') { const out: Record = {} - for (const [k, v] of Object.entries(value)) out[k] = scrubValue(v, ctx) + for (const [k, v] of Object.entries(value)) out[k] = scrubValue(v, ctx, cwdPathMode, k) return out } return value @@ -67,9 +99,15 @@ function scrubValue(value: unknown, ctx: NormalizeContext): unknown { * * @param rawStdout The captured stdout bytes, decoded utf8. * @param ctx The run's volatile values to scrub. + * @param options Separator output controls; shared canonical paths are the default. * @returns The normalized NDJSON transcript, one frame per line. */ -export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): string { +export function normalizeStdout( + rawStdout: string, + ctx: NormalizeContext, + options: NormalizeOptions = {}, +): string { + const cwdPathMode = options.cwdPathMode ?? 'canonical' const lines = rawStdout.split('\n').filter(line => line.trim().length > 0) // Map each distinct JSON-RPC id (request/response correlate by id) to a stable // sequence number, in first-seen order, so id churn doesn't perturb the golden. @@ -85,7 +123,7 @@ export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): strin if ('id' in frame && frame.id !== undefined && frame.id !== null) { frame.id = stableId(frame.id) } - return scrubValue(frame, ctx) as Record + return scrubValue(frame, ctx, cwdPathMode) as Record }) return frames.map(f => JSON.stringify(f)).join('\n') + '\n' } @@ -99,9 +137,15 @@ export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): strin * * @param rawLog The raw session `.jsonl` content. * @param ctx The run's volatile values to scrub. + * @param options Separator output controls; shared canonical paths are the default. * @returns The normalized JSONL log, one record per line. */ -export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): string { +export function normalizeSessionLog( + rawLog: string, + ctx: NormalizeContext, + options: NormalizeOptions = {}, +): string { + const cwdPathMode = options.cwdPathMode ?? 'canonical' const lines = rawLog.split('\n').filter(line => line.trim().length > 0) const records = lines.map((line) => { const record = JSON.parse(line) as Record @@ -119,7 +163,7 @@ export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): stri if ('durationMs' in data) data.durationMs = 0 } } - return scrubValue(record, ctx) as Record + return scrubValue(record, ctx, cwdPathMode) as Record }) return records.map(r => JSON.stringify(r)).join('\n') + '\n' } diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts index 322439bb01..7fdc70dc67 100644 --- a/packages/support/acp-snapshot/src/suite.ts +++ b/packages/support/acp-snapshot/src/suite.ts @@ -21,6 +21,7 @@ import { join } from 'node:path' import { describe, expect, it } from 'vitest' import { type AgentUnderTest, type HarvestedLog, type InputScript, runScenario } from './harness.ts' import { + type CwdPathMode, type NormalizeContext, normalizeSessionLog, normalizeStdout, @@ -35,6 +36,9 @@ const SYSTEM_PROMPT_SNAPSHOT = 'system-prompt.golden.md' /** The structured tool-schema snapshot beside each header-pinning fixture. */ const TOOL_SCHEMAS_SNAPSHOT = 'tool-schemas.golden.json' +/** The optional full Windows-native stdout transcript. */ +const WINDOWS_STDOUT_SNAPSHOT = 'stdout.golden.windows.jsonl' + /** Stable session-log token standing in for the sidecar's initial schemas. */ const TOOLS_TOKEN = '{{tools}}' @@ -108,6 +112,35 @@ export interface Scenario { * {@link headerClass}. */ configPath?: string + /** + * Whether Windows additionally compares stdout with native separators against + * `stdout.golden.windows.jsonl`. The shared canonical stdout golden is still + * compared on every platform, and the fixture guard requires this sidecar + * exactly when the option is set. + */ + pinsNativeWindowsStdout?: boolean +} + +/** One stdout golden selected for a platform run. */ +interface StdoutGoldenVariant { + file: string + cwdPathMode: CwdPathMode +} + +/** + * Select the shared stdout golden plus any platform-native assertion declared by a scenario. + * + * @param scenario The scenario whose stdout contract is being selected. + * @param platform The running Node platform, injectable for unit coverage. + * @returns The ordered golden variants: shared canonical first, then optional Windows native. + */ +export function stdoutGoldenVariants( + scenario: Scenario, + platform: NodeJS.Platform = process.platform, +): StdoutGoldenVariant[] { + const canonical: StdoutGoldenVariant = { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' } + if (platform !== 'win32' || scenario.pinsNativeWindowsStdout !== true) return [canonical] + return [canonical, { file: WINDOWS_STDOUT_SNAPSHOT, cwdPathMode: 'native' }] } /** One suite's inputs: the agent to boot, where its fixtures live, and its scenario table. */ @@ -530,11 +563,13 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void { } } - const stdout = normalizeStdout(result.rawStdout, ctx) - if (REFRESHING) { - await writeFile(join(dir, 'stdout.golden.jsonl'), stdout) + for (const golden of stdoutGoldenVariants(scenario)) { + const stdout = normalizeStdout(result.rawStdout, ctx, { cwdPathMode: golden.cwdPathMode }) + if (REFRESHING) { + await writeFile(join(dir, golden.file), stdout) + } + await expect(stdout, `${golden.file} mismatch`).toMatchFileSnapshot(join(dir, golden.file)) } - await expect(stdout).toMatchFileSnapshot(join(dir, 'stdout.golden.jsonl')) // A model turn always produces a log worth comparing; a hook scenario can // produce one without a model turn (a `rejected` turn carrying `hook/*`). @@ -621,10 +656,14 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void { it('every registered scenario has its required fixture files', () => { // Every scenario has an input script and an stdout golden. - for (const { name, overridden, childSessions, pinsHeader } of scenarios) { + for (const { name, overridden, childSessions, pinsHeader, pinsNativeWindowsStdout } of scenarios) { const dir = join(snapshotsDir, name) expect(existsSync(join(dir, 'input.json')), `${name}/input.json`).toBe(true) expect(existsSync(join(dir, 'stdout.golden.jsonl')), `${name}/stdout.golden.jsonl`).toBe(true) + expect( + existsSync(join(dir, WINDOWS_STDOUT_SNAPSHOT)), + `${name}/${WINDOWS_STDOUT_SNAPSHOT} presence must match \`pinsNativeWindowsStdout\``, + ).toBe(pinsNativeWindowsStdout === true) expect(existsSync(join(dir, 'session.jsonl')), `${name}/session.jsonl`).toBe(true) expect(existsSync(join(dir, 'replay.override.json')), `${name}/replay.override.json presence must match \`overridden\``) .toBe(overridden === true) diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index d141fb1f09..35fcb21d09 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -3,7 +3,7 @@ import { tmpdir } from 'node:os' import { delimiter, join } from 'node:path' import { fileURLToPath } from 'node:url' import { afterAll, describe, expect, it } from 'vitest' -import { runScenario, type AgentUnderTest, type InputStep } from '../src/harness.ts' +import { runScenario, snapshotSpillRoot, type AgentUnderTest, type InputStep } from '../src/harness.ts' /** * Unit tests for the subprocess harness, driven through the REAL spawn path @@ -39,6 +39,11 @@ async function scenario(behavior: object): Promise<{ dir: string; fixtureFile: s const boot: InputStep[] = [{ op: 'initialize' }, { op: 'newSession' }] +it('keeps the resolved snapshot spill root length stable across platforms', () => { + expect(snapshotSpillRoot('linux')).toBe('/tmp/dsh-acp-snapshot-spill') + expect(snapshotSpillRoot('win32')).toBe('/t/dsh-acp-snapshot-spill') +}) + describe('runScenario', () => { it('includes agent stderr when the ACP connection closes during startup', { timeout: 20_000 }, async () => { const { fixtureFile } = await scenario({ failOnBoot: true, stderrNote: 'fake agent requested startup failure' }) diff --git a/packages/support/acp-snapshot/tests/normalize.spec.ts b/packages/support/acp-snapshot/tests/normalize.spec.ts index 2beaba5114..fed086fec7 100644 --- a/packages/support/acp-snapshot/tests/normalize.spec.ts +++ b/packages/support/acp-snapshot/tests/normalize.spec.ts @@ -44,6 +44,56 @@ describe('normalizeStdout', () => { expect(out).not.toContain(ctx.sessionIds[0] as string) }) + it('canonicalizes only cwd-rooted path separators', () => { + const windowsCtx: NormalizeContext = { + sessionIds: [], + cwd: String.raw`C:\Users\runner\AppData\Local\Temp\acp-snapshot`, + } + const raw = JSON.stringify({ + jsonrpc: '2.0', + method: 'session/update', + params: { + path: `${windowsCtx.cwd}\\nested\\proof.txt`, + regex: String.raw`\d+\w+`, + command: String.raw`printf "\\n"`, + }, + }) + const frame = JSON.parse(normalizeStdout(raw, windowsCtx)) as { + params: { path: string; regex: string; command: string } + } + expect(frame.params).toEqual({ + path: '{{cwd}}/nested/proof.txt', + regex: String.raw`\d+\w+`, + command: String.raw`printf "\\n"`, + }) + }) + + it('canonicalizes generated relative path fields and text markers without rewriting other text', () => { + const raw = JSON.stringify({ + path: String.raw`nested\AGENTS.md`, + content: String.raw`.\nested\task.txt +Additional instructions from: nested\AGENTS.md`, + regex: String.raw`\d+\w+`, + }) + const frame = JSON.parse(normalizeStdout(raw, { sessionIds: [], cwd: '/unused' })) as { + path: string + content: string + regex: string + } + expect(frame).toEqual({ + path: 'nested/AGENTS.md', + content: './nested/task.txt\nAdditional instructions from: nested/AGENTS.md', + regex: String.raw`\d+\w+`, + }) + }) + + it('can preserve native cwd-rooted separators for a platform golden', () => { + const windowsCtx: NormalizeContext = { sessionIds: [], cwd: String.raw`C:\work\snapshot` } + const raw = JSON.stringify({ path: `${windowsCtx.cwd}\\nested\\proof.txt` }) + const frame = JSON.parse(normalizeStdout(raw, windowsCtx, { cwdPathMode: 'native' })) as { path: string } + expect(frame.path).toBe(String.raw`{{cwd}}\nested\proof.txt`) + }) + it('scrubs a stray UUID not in the known list', () => { const raw = JSON.stringify({ jsonrpc: '2.0', method: 'x', params: { id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' } }) expect(normalizeStdout(raw, ctx)).toContain('{{sessionId}}') @@ -139,6 +189,33 @@ describe('normalizeSessionLog', () => { expect(out).not.toContain('/tmp/dsh-acp-snapshot-spill') }) + it('scrubs fixed snapshot spill paths with Windows drive and separators', () => { + const ev = JSON.stringify({ + type: 'tool/result', seq: 2, time: 5, + data: { + content: [{ + type: 'text', + text: String.raw`Full formatted result stored at: C:\t\dsh-acp-snapshot-spill\session-c22bc3f1d2af\8a7b6c5d4e3f-bash.txt. Use read with offset/limit, or grep this path to search within it.`, + }], + }, + }) + const out = normalizeSessionLog(`${header({ cwd: ctx.cwd })}\n${ev}\n`, ctx) + expect(out).toContain('{{spillLocator:bash.txt}}') + expect(out).not.toContain('C:\\t\\dsh-acp-snapshot-spill') + }) + + it('shares cwd-rooted path handling with stdout normalization', () => { + const windowsCtx: NormalizeContext = { sessionIds: [], cwd: String.raw`C:\work\snapshot` } + const ev = JSON.stringify({ + type: 'tool/result', seq: 2, time: 5, + data: { path: `${windowsCtx.cwd}\\nested\\proof.txt` }, + }) + expect(normalizeSessionLog(`${header({ cwd: windowsCtx.cwd })}\n${ev}\n`, windowsCtx)) + .toContain('{{cwd}}/nested/proof.txt') + expect(normalizeSessionLog(`${header({ cwd: windowsCtx.cwd })}\n${ev}\n`, windowsCtx, { cwdPathMode: 'native' })) + .toContain(String.raw`{{cwd}}\\nested\\proof.txt`) + }) + it('scrubs the session id in the header', () => { const out = normalizeSessionLog(`${header({ id: ctx.sessionIds[0] })}\n`, ctx) expect(out).toContain('{{sessionId}}') diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts index c2007321de..24812029dc 100644 --- a/packages/support/acp-snapshot/tests/suite.spec.ts +++ b/packages/support/acp-snapshot/tests/suite.spec.ts @@ -18,6 +18,7 @@ import { refreshFixtureReplacements, restorePinnedToolSchemas, stabilizeRefreshLog, + stdoutGoldenVariants, unknownToolCallIds, } from '../src/suite.ts' @@ -189,6 +190,31 @@ describe('childFixturePaths', () => { }) }) +describe('stdoutGoldenVariants', () => { + const scenario: Scenario = { + name: 'windows-native', + hasModelTurn: true, + recorded: true, + pinsNativeWindowsStdout: true, + } + + it('adds the native sidecar after the shared golden on Windows', () => { + expect(stdoutGoldenVariants(scenario, 'win32')).toEqual([ + { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' }, + { file: 'stdout.golden.windows.jsonl', cwdPathMode: 'native' }, + ]) + }) + + it('keeps only the shared golden on other platforms or without the declaration', () => { + expect(stdoutGoldenVariants(scenario, 'linux')).toEqual([ + { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' }, + ]) + expect(stdoutGoldenVariants({ ...scenario, pinsNativeWindowsStdout: false }, 'win32')).toEqual([ + { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' }, + ]) + }) +}) + describe('fixtureContext', () => { it('reads the fixture header id and cwd', () => { const ctx = fixtureContext('{"type":"session","id":"abc","cwd":"/rec"}\n{"type":"turn/start"}\n') From b5fa2cb2b8c3a320f773e21695daa7a8b222cc87 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 17 Jul 2026 12:30:16 +0800 Subject: [PATCH 10/53] test(windows): skip unsupported SDK test surfaces --- .../sdk/create-sdk/tests/create.snapshot.ts | 2 +- vitest.config.ts | 18 +++++++++++++++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/packages/sdk/create-sdk/tests/create.snapshot.ts b/packages/sdk/create-sdk/tests/create.snapshot.ts index a5ea46db53..4733653a0d 100644 --- a/packages/sdk/create-sdk/tests/create.snapshot.ts +++ b/packages/sdk/create-sdk/tests/create.snapshot.ts @@ -71,7 +71,7 @@ class RecordingPort implements PromptPort { } } -describe('create-sdk terminal contract', () => { +describe.skipIf(process.platform === 'win32')('create-sdk terminal contract', () => { it('renders package-manager-specific setup commands', () => { const model = packageManagerTemplateModel(createPackageManager('yarn', '4.0.0')) expect(CREATE_TEMPLATES.installQuestion.render(model)).toBe('Run yarn install and then build the project?\n') diff --git a/vitest.config.ts b/vitest.config.ts index c0946e2e10..1001b7daa3 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -1,6 +1,16 @@ import tsconfigPaths from 'vite-tsconfig-paths' import { defineConfig } from 'vitest/config' +const windowsUnsupportedPackages = process.platform === 'win32' + ? [ + 'packages/bash/*', + 'packages/hooks/*', + 'packages/sandbox/sandbox-local', + 'packages/sdk/create-sdk', + 'packages/sdk/helper', + ] + : [] + export default defineConfig({ // Native path resolution reads each package's nearest tsconfig, but only the root defines // workspace paths. Keep this plugin pinned to the root map so unbuilt bare package imports resolve @@ -8,6 +18,7 @@ export default defineConfig({ plugins: [tsconfigPaths({ projects: ['./tsconfig.json'] })], test: { include: ['packages/*/*/tests/**/*.spec.ts', 'examples/*/tests/**/*.spec.ts', 'scripts/**/*.spec.ts'], + exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`), coverage: { provider: 'v8', // Coverage measures OUR runtime source. Types-only files carry no @@ -16,7 +27,12 @@ export default defineConfig({ include: ['packages/*/*/src/**/*.ts'], // Types-only files have no runtime coverage. Importing self-executing bins/workers would boot // them inside the unit process, so real subprocess/Worker tests cover their thin entry glue. - exclude: ['packages/*/*/src/types.ts', 'packages/*/*/src/bin.ts', 'packages/*/*/src/worker.ts'], + exclude: [ + 'packages/*/*/src/types.ts', + 'packages/*/*/src/bin.ts', + 'packages/*/*/src/worker.ts', + ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`), + ], // 100% or it doesn't merge (docs/testing.md: excessive tests are welcome). // Per-file so a well-covered big file can't subsidize a bare one. // Every v8 ignore comment must carry a reason — see the quality-gates RFC From 228f6e3867ce4cdbbd2d4edb85ef132c91e5634c Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 17 Jul 2026 15:44:19 +0800 Subject: [PATCH 11/53] test(windows): skip POSIX-only assertions --- .../workspace-context/tests/workspace-context.spec.ts | 2 +- packages/spill/spill-local/tests/spill-local.spec.ts | 2 +- packages/subagent/subagent-acp/tests/subagent-acp.spec.ts | 2 +- .../subagent-subprocess/tests/subagent-subprocess.spec.ts | 5 +++-- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index b3a9947221..5f04b3a485 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -2403,7 +2403,7 @@ describe('dynamic nested workspace context injection', () => { } }) - it('skips unreadable nested instruction files without attaching empty context', async () => { + it.skipIf(process.platform === 'win32')('skips unreadable nested instruction files without attaching empty context', async () => { const root = await tempRepo() const home = await tempRepo() try { diff --git a/packages/spill/spill-local/tests/spill-local.spec.ts b/packages/spill/spill-local/tests/spill-local.spec.ts index d73fca9fe3..b4abc6e3d6 100644 --- a/packages/spill/spill-local/tests/spill-local.spec.ts +++ b/packages/spill/spill-local/tests/spill-local.spec.ts @@ -84,7 +84,7 @@ describe('saveTextFile', () => { expect(saved.path.includes('/..')).toBe(false) }) - it('creates the session dir with owner-only permissions', async () => { + it.skipIf(process.platform === 'win32')('creates the session dir with owner-only permissions', async () => { const saved = await saveTextFile({ root, sessionId: 'sess-1', suggestedName: 'r.txt', content: 'x' }) // 0o700 dir, 0o600 file (masked by umask, but the owner bits must hold). expect(statSync(dirname(saved.path)).mode & 0o700).toBe(0o700) diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts index bfc8476bae..e3fd3eda48 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts @@ -263,7 +263,7 @@ describe('dsh-subagent-acp', () => { } }) - it('escalates to SIGTERM for a child that ignores EOF but is not SIGTERM-trapping', async () => { + it.skipIf(process.platform === 'win32')('escalates to SIGTERM for a child that ignores EOF but is not SIGTERM-trapping', async () => { // A child that keeps its loop alive past stdin EOF (so the graceful window // times out) but exits cooperatively on SIGTERM must die on the SIGTERM tier // — dispose returns there, never reaching the SIGKILL tier. The child touches diff --git a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts index bdc0260c73..8ed3891578 100644 --- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts +++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts @@ -258,8 +258,9 @@ describe('createIsolatedConfigDir', () => { expect(dir.path.startsWith(join(tmpdir(), 'dsh-subagent-subprocess-test-'))).toBe(true) const st = await stat(dir.path) expect(st.isDirectory()).toBe(true) - // Private (0700) per the defensive-patterns temp-dir rule. - expect(st.mode & 0o777).toBe(0o700) + // Windows reports synthetic POSIX mode bits; privacy comes from the + // inherited directory ACL rather than chmod-compatible mode bits. + if (process.platform !== 'win32') expect(st.mode & 0o777).toBe(0o700) } finally { await dir.remove() } From 7e620db8ba470cc48b44c8a1887208b03206bd3a Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 17 Jul 2026 21:08:59 +0800 Subject: [PATCH 12/53] test(windows): use host path semantics --- .../tests/workspace-context.spec.ts | 46 +++++++++---------- .../fs/tool-fs-search/tests/tools.spec.ts | 7 +-- .../spill-local/tests/spill-local.spec.ts | 7 +-- packages/util/paths/tests/paths.spec.ts | 4 +- 4 files changed, 33 insertions(+), 31 deletions(-) diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index 5f04b3a485..9de003ae8d 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -1,5 +1,5 @@ import { chmod, mkdtemp, mkdir, rm, stat, symlink, utimes, writeFile } from 'node:fs/promises' -import { dirname, join } from 'node:path' +import { dirname, join, resolve } from 'node:path' import { tmpdir } from 'node:os' import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' @@ -61,7 +61,7 @@ class RecordingFileSystem extends FileSystem { override async resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise { if (opts?.signal !== undefined) this.signals.push(opts.signal) opts?.signal?.throwIfAborted() - const absolute = join(opts?.cwd ?? '/', path) + const absolute = resolve(opts?.cwd ?? '/', path) return { targetKey: FsTargetKey(absolute), displayPath: absolute } } @@ -277,8 +277,8 @@ describe('workspace context instruction discovery', () => { expect(files.map(file => file.displayPath)).toEqual([ '$DSH_HOME/AGENTS.md', 'AGENTS.md', - 'packages/CLAUDE.md', - 'packages/app/AGENTS.md', + join('packages', 'CLAUDE.md'), + join('packages', 'app', 'AGENTS.md'), ]) expect(files.map(file => file.absolutePath)).not.toContain(join(root, 'CLAUDE.md')) } finally { @@ -336,7 +336,7 @@ describe('workspace context instruction discovery', () => { } }) - it('skips a file that becomes unreadable after discovery without failing the request', async () => { + it.skipIf(process.platform === 'win32')('skips a file that becomes unreadable after discovery without failing the request', async () => { const root = await tempRepo() const home = await tempRepo() try { @@ -932,7 +932,7 @@ describe('workspace context request injection', () => { await composeBaselinePrefix(ctx, agent) expect(derivedText(agent)).toContain('omitted AGENTS.md') - expect(derivedText(agent)).toContain('Instructions from: pkg/AGENTS.md\n\npackage rule') + expect(derivedText(agent)).toContain(`Instructions from: ${join('pkg', 'AGENTS.md')}\n\npackage rule`) } finally { await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) @@ -1398,7 +1398,7 @@ describe('workspace context request injection', () => { await composeBaselinePrefix(ctx, agent) expect(derivedText(agent)).toContain('Instructions from: AGENTS.md\n\nroot schema default rule') - expect(derivedText(agent)).toContain('Instructions from: child/AGENTS.md\n\nchild schema default rule') + expect(derivedText(agent)).toContain(`Instructions from: ${join('child', 'AGENTS.md')}\n\nchild schema default rule`) await ctx.fiber.dispose() } finally { await rm(root, { recursive: true, force: true }) @@ -1700,7 +1700,7 @@ describe('dynamic nested workspace context injection', () => { changes: [{ action: 'set', scope: 'pkg', - path: 'pkg/AGENTS.md', + path: join('pkg', 'AGENTS.md'), }], }) const meta = workspaceContextOf(result)?.meta @@ -1714,7 +1714,7 @@ describe('dynamic nested workspace context injection', () => { const text = blocksText(workspaceContextOf(result)?.content) expect(text).toBe([ '', - 'Additional instructions from: pkg/AGENTS.md', + `Additional instructions from: ${join('pkg', 'AGENTS.md')}`, '', 'These instructions apply to work under `pkg`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.', '', @@ -1752,7 +1752,7 @@ describe('dynamic nested workspace context injection', () => { }) const text = blocksText(workspaceContextOf(result)?.content) - expect(text).toContain('Additional instructions from: pkg/CLAUDE.local.md') + expect(text).toContain(`Additional instructions from: ${join('pkg', 'CLAUDE.local.md')}`) expect(text).toContain('local package rule') expect(text).not.toContain('native package rule') } finally { @@ -1922,11 +1922,11 @@ describe('dynamic nested workspace context injection', () => { expect(workspaceContextOf(changed)?.meta).toMatchObject({ kind: 'workspace-instructions', - changes: [{ action: 'replace', scope: 'pkg', path: 'pkg/AGENTS.md' }], + changes: [{ action: 'replace', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], }) expect(blocksText(workspaceContextOf(changed)?.content)).toBe([ '', - 'Updated instructions from: pkg/AGENTS.md', + `Updated instructions from: ${join('pkg', 'AGENTS.md')}`, '', 'This file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.', '', @@ -1966,11 +1966,11 @@ describe('dynamic nested workspace context injection', () => { expect(workspaceContextOf(changed)?.meta).toMatchObject({ changes: [{ - action: 'replace', scope: 'pkg', path: 'pkg/CLAUDE.md', previousPath: 'pkg/AGENTS.md', + action: 'replace', scope: 'pkg', path: join('pkg', 'CLAUDE.md'), previousPath: join('pkg', 'AGENTS.md'), }], }) - expect(blocksText(workspaceContextOf(changed)?.content)).toContain('Updated instructions from: pkg/CLAUDE.md') - expect(blocksText(workspaceContextOf(changed)?.content)).toContain('The instructions previously loaded from `pkg/AGENTS.md` no longer apply. Use the following content for `pkg` instead.') + expect(blocksText(workspaceContextOf(changed)?.content)).toContain(`Updated instructions from: ${join('pkg', 'CLAUDE.md')}`) + expect(blocksText(workspaceContextOf(changed)?.content)).toContain(`The instructions previously loaded from \`${join('pkg', 'AGENTS.md')}\` no longer apply. Use the following content for \`pkg\` instead.`) expect(blocksText(workspaceContextOf(changed)?.content)).toContain('fallback package rule') expect(unchanged.additionalContexts).toBeUndefined() } finally { @@ -2002,11 +2002,11 @@ describe('dynamic nested workspace context injection', () => { expect(workspaceContextOf(removed)?.meta).toEqual({ kind: 'workspace-instructions', version: 1, - changes: [{ action: 'remove', scope: 'pkg', path: 'pkg/AGENTS.md' }], + changes: [{ action: 'remove', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], }) expect(blocksText(workspaceContextOf(removed)?.content)).toBe([ '', - 'Instructions removed: pkg/AGENTS.md', + `Instructions removed: ${join('pkg', 'AGENTS.md')}`, '', 'The previously loaded instructions from this file no longer apply.', '', @@ -2044,9 +2044,9 @@ describe('dynamic nested workspace context injection', () => { }) expect(workspaceContextOf(restored)?.meta).toMatchObject({ - changes: [{ action: 'set', scope: 'pkg', path: 'pkg/AGENTS.md' }], + changes: [{ action: 'set', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], }) - expect(blocksText(workspaceContextOf(restored)?.content)).toContain('Additional instructions from: pkg/AGENTS.md') + expect(blocksText(workspaceContextOf(restored)?.content)).toContain(`Additional instructions from: ${join('pkg', 'AGENTS.md')}`) expect(blocksText(workspaceContextOf(restored)?.content)).toContain('restored package rule') } finally { await rm(root, { recursive: true, force: true }) @@ -2146,7 +2146,7 @@ describe('dynamic nested workspace context injection', () => { const update = resumed.session.events.findLast(event => event.type === 'context/message') expect(update?.type === 'context/message' && update.data.meta).toMatchObject({ - changes: [{ action: 'replace', scope: 'pkg', path: 'pkg/AGENTS.md' }], + changes: [{ action: 'replace', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], }) expect(update?.type === 'context/message' && blocksText(update.data.content)).toContain('new nested rule after resume') } finally { @@ -2267,8 +2267,8 @@ describe('dynamic nested workspace context injection', () => { }) const firstText = blocksText(workspaceContextOf(first)?.content) - expect(firstText).toContain('omitted pkg/AGENTS.md') - expect(firstText).not.toContain('## pkg/AGENTS.md') + expect(firstText).toContain(`omitted ${join('pkg', 'AGENTS.md')}`) + expect(firstText).not.toContain(`## ${join('pkg', 'AGENTS.md')}`) expect(firstText).toContain('subtree rule') expect(blocksText(workspaceContextOf(second)?.content)).toContain('parent rule') } finally { @@ -2462,7 +2462,7 @@ describe('dynamic nested workspace context injection', () => { expect(workspaceContextOf(result)?.envelope).toBe('raw') expect(workspaceContextOf(result)?.meta).toMatchObject({ kind: 'workspace-instructions', - changes: [{ action: 'set', scope: 'pkg', path: 'pkg/AGENTS.md' }], + changes: [{ action: 'set', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], }) expect(blocksText(workspaceContextOf(result)?.content)).toContain('nested package rule') expect(blocksText(workspaceContextOf(result)?.content)).not.toContain('downstream context') diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts index 5363344f07..add5b932f9 100644 --- a/packages/fs/tool-fs-search/tests/tools.spec.ts +++ b/packages/fs/tool-fs-search/tests/tools.spec.ts @@ -12,6 +12,7 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' +import { join } from 'node:path' import { CallId } from '@deepseek-ai/dsh-llm' import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt' import ToolRegistry from '@deepseek-ai/dsh-tools' @@ -416,7 +417,7 @@ describe('glob results', () => { const { ctx, bash } = await setup() bash.handler = () => runResult('/sessions/s1/src/a.ts\n/elsewhere/b.ts\nrel/c.ts\n') const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/sessions/s1') }) - expect(text(result)).toBe('src/a.ts\n/elsewhere/b.ts\nrel/c.ts') + expect(text(result)).toBe(`${join('src', 'a.ts')}\n/elsewhere/b.ts\nrel/c.ts`) }) it('validates arguments (blank pattern, blank path)', async () => { @@ -498,7 +499,7 @@ describe('grep results', () => { const { ctx, bash } = await setup() bash.handler = () => runResult(`${matchLine('/sessions/s1/deep/a.ts', 2, 'hit')}\n`) const result = await call(ctx, 'grep', { pattern: 'hit', path: '/sessions/s1' }, { agent: agent('/sessions/s1') }) - expect(text(result)).toContain('deep/a.ts\nLine 2: hit') + expect(text(result)).toContain(`${join('deep', 'a.ts')}\nLine 2: hit`) }) it('previews a long matched line at grepMaxLineBytes preserving UTF-8', async () => { @@ -608,7 +609,7 @@ describe('presentation', () => { describe('helpers', () => { it('toWorkdirRelative maps inside-workdir absolutes and passes everything else through', () => { - expect(toWorkdirRelative('/w/a/b.ts', '/w')).toBe('a/b.ts') + expect(toWorkdirRelative('/w/a/b.ts', '/w')).toBe(join('a', 'b.ts')) expect(toWorkdirRelative('/w', '/w')).toBe('.') expect(toWorkdirRelative('/other/b.ts', '/w')).toBe('/other/b.ts') expect(toWorkdirRelative('/w-sibling/b.ts', '/w')).toBe('/w-sibling/b.ts') diff --git a/packages/spill/spill-local/tests/spill-local.spec.ts b/packages/spill/spill-local/tests/spill-local.spec.ts index b4abc6e3d6..46fa0b66b2 100644 --- a/packages/spill/spill-local/tests/spill-local.spec.ts +++ b/packages/spill/spill-local/tests/spill-local.spec.ts @@ -10,7 +10,7 @@ import { describe, expect, it, beforeEach, afterEach } from 'vitest' import { Context } from 'cordis' import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs' import { tmpdir } from 'node:os' -import { dirname, isAbsolute, join } from 'node:path' +import { basename, dirname, isAbsolute, join, normalize } from 'node:path' import { CallId } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' import type { SaveTextSpill } from '@deepseek-ai/dsh-spill' @@ -63,7 +63,8 @@ describe('sessionDir', () => { it('is a stable per-session hash under the root', () => { const dir = sessionDir('/spill', 'sess-1') expect(dir).toBe(sessionDir('/spill', 'sess-1')) - expect(dir).toMatch(/\/spill\/session-[0-9a-f]{12}$/) + expect(dirname(dir)).toBe(normalize('/spill')) + expect(basename(dir)).toMatch(/^session-[0-9a-f]{12}$/) expect(sessionDir('/spill', 'sess-2')).not.toBe(dir) }) }) @@ -74,7 +75,7 @@ describe('saveTextFile', () => { expect(readFileSync(saved.path, 'utf8')).toBe('héllo') expect(saved.bytes).toBe(Buffer.byteLength('héllo', 'utf8')) expect(dirname(saved.path)).toBe(sessionDir(root, 'sess-1')) - expect(saved.path).toMatch(/\/[0-9a-f]{12}-r\.txt$/) + expect(basename(saved.path)).toMatch(/^[0-9a-f]{12}-r\.txt$/) }) it('sanitizes a traversal-shaped suggested name into one segment', async () => { diff --git a/packages/util/paths/tests/paths.spec.ts b/packages/util/paths/tests/paths.spec.ts index 97e91a556e..4ba4fab155 100644 --- a/packages/util/paths/tests/paths.spec.ts +++ b/packages/util/paths/tests/paths.spec.ts @@ -1,5 +1,5 @@ import { homedir } from 'node:os' -import { join } from 'node:path' +import { join, resolve } from 'node:path' import { describe, expect, it } from 'vitest' import { DEFAULT_DSH_HOME_DISPLAY, @@ -28,7 +28,7 @@ describe('dsh path helpers', () => { const envHome = join(homedir(), 'env-dsh') expect(resolveDshHome(undefined, { DSH_HOME: '~/env-dsh' })).toBe(envHome) - expect(resolveDshHome('/tmp/explicit-dsh', { DSH_HOME: '~/env-dsh' })).toBe('/tmp/explicit-dsh') + expect(resolveDshHome('/tmp/explicit-dsh', { DSH_HOME: '~/env-dsh' })).toBe(resolve('/tmp/explicit-dsh')) expect(resolveDshHome(undefined, {})).toBe(defaultDshHome()) }) }) From 3a82b3edd7d52107578c1add212ade384bebfe55 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 15 Jul 2026 20:28:46 +0800 Subject: [PATCH 13/53] ci(windows): observe runtime coverage and snapshots docs: record cross-platform gate boundaries --- .github/AGENTS.md | 3 +++ .github/workflows/ci.yml | 24 +++++++++++++++++++----- scripts/AGENTS.md | 3 +++ 3 files changed, 25 insertions(+), 5 deletions(-) create mode 100644 .github/AGENTS.md create mode 100644 scripts/AGENTS.md diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 0000000000..00e3ed8f87 --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,3 @@ +# AGENTS.md — CI gates + +Run Windows gates from native `pwsh`, invoke pnpm shell-free, and normalize repo-relative glob paths to `/` at ingestion. Keep platform fixes at each gate boundary; do not add a shared platform layer. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bac25b07cb..de9a03288b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -182,11 +182,9 @@ jobs: - name: Build (tsc -b + tsdown) run: pnpm run build - # Observational, non-blocking Windows static, lint, and artifact lanes. Coverage - # and snapshot stay Linux-only until their platform-specific runtime failures - # have dedicated support. Run the gates from native PowerShell: an MSYS parent - # would change the environment being measured. This job intentionally stays - # out of all-checks-passed.needs. + # Observational, non-blocking Windows mirror of the Linux gate lanes. Run the + # gates from native PowerShell: an MSYS parent would change the environment + # being measured. This job intentionally stays out of all-checks-passed.needs. windows-gates: continue-on-error: true runs-on: windows-2025 @@ -194,6 +192,7 @@ jobs: env: DSH_GATE_CONCURRENCY: ${{ matrix.gate_concurrency }} DSH_PUBLINT_CONCURRENCY: ${{ matrix.publint_concurrency }} + DSH_COVERAGE_MAX_WORKERS: ${{ matrix.coverage_max_workers }} DSH_ESLINT_CACHE: ${{ matrix.eslint_cache }} strategy: fail-fast: false @@ -203,16 +202,31 @@ jobs: command: pnpm run check:ci:static gate_concurrency: '4' publint_concurrency: '8' + coverage_max_workers: '' eslint_cache: '' - lane: lint command: pnpm run check:ci:lint gate_concurrency: '1' publint_concurrency: '8' + coverage_max_workers: '' eslint_cache: '1' + - lane: coverage + command: pnpm run check:ci:coverage + gate_concurrency: '1' + publint_concurrency: '8' + coverage_max_workers: '4' + eslint_cache: '' + - lane: snapshot + command: pnpm run check:ci:snapshot + gate_concurrency: '1' + publint_concurrency: '8' + coverage_max_workers: '' + eslint_cache: '' - lane: artifacts command: pnpm run check:ci:artifacts gate_concurrency: '3' publint_concurrency: '8' + coverage_max_workers: '' eslint_cache: '' steps: - uses: actions/checkout@v6 diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md new file mode 100644 index 0000000000..2d1ebafc27 --- /dev/null +++ b/scripts/AGENTS.md @@ -0,0 +1,3 @@ +# AGENTS.md — Repository scripts + +Gate-related scripts follow the [CI gate rules](../.github/AGENTS.md). From 1d6acc331538aa7d5144257fcfd6690acd69eb1f Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 18 Jul 2026 03:23:52 +0800 Subject: [PATCH 14/53] test(loader-smoke): use native home paths --- packages/support/loader-smoke/tests/loader-smoke.spec.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/support/loader-smoke/tests/loader-smoke.spec.ts b/packages/support/loader-smoke/tests/loader-smoke.spec.ts index b99d810188..755197b134 100644 --- a/packages/support/loader-smoke/tests/loader-smoke.spec.ts +++ b/packages/support/loader-smoke/tests/loader-smoke.spec.ts @@ -1,4 +1,5 @@ import { existsSync } from 'node:fs' +import { join } from 'node:path' import { fileURLToPath } from 'node:url' import { describe, expect, it } from 'vitest' import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke' @@ -33,8 +34,8 @@ describe('runLoaderSmoke', () => { marker: 'present', input: 'one\ntwo\n', }) - expect(canonicalTempPath(output.dshHome)).toBe(`${canonicalTempPath(output.cwd)}/.dsh`) - expect(canonicalTempPath(output.agentsHome)).toBe(`${canonicalTempPath(output.cwd)}/.agents`) + expect(canonicalTempPath(output.dshHome)).toBe(canonicalTempPath(join(output.cwd, '.dsh'))) + expect(canonicalTempPath(output.agentsHome)).toBe(canonicalTempPath(join(output.cwd, '.agents'))) expect(result.stderr).toContain('fixture stderr') expect(existsSync(output.cwd)).toBe(false) }, LOADER_SMOKE_TEST_TIMEOUT_MS) From 588f4d948d8ac1c023366dbdc337546cb3ca65d3 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 18 Jul 2026 12:10:18 +0800 Subject: [PATCH 15/53] test(windows): mark platform-only coverage branches --- packages/context/workspace-context/src/files.ts | 1 + packages/context/workspace-context/src/state.ts | 1 + packages/fs/fs-local/src/fsio.ts | 1 + packages/sandbox/sandbox/src/index.ts | 1 + .../session-persistence-jsonl/src/index.ts | 5 +++++ packages/skill/skill-local/src/index.ts | 1 + 6 files changed, 10 insertions(+) diff --git a/packages/context/workspace-context/src/files.ts b/packages/context/workspace-context/src/files.ts index feb6304b4c..770024c569 100644 --- a/packages/context/workspace-context/src/files.ts +++ b/packages/context/workspace-context/src/files.ts @@ -459,6 +459,7 @@ export async function readScopeInstruction( signal?: AbortSignal, ): Promise { const content = await readBounded(file, maxSourceBytes, fileSystem, signal) + /* v8 ignore next -- Windows cannot reproduce a post-probe unreadable file with POSIX mode bits. */ if (content === undefined) return undefined return { absolutePath: file.absolutePath, diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts index 98b8fcc066..ab18f442f4 100644 --- a/packages/context/workspace-context/src/state.ts +++ b/packages/context/workspace-context/src/state.ts @@ -437,6 +437,7 @@ export async function reconcileInstructionContext( ) continue const file = await readScopeInstruction(probedFile, resolved.maxSourceBytes, fileSystem, options.signal) + /* v8 ignore next -- Windows cannot make the probed file unreadable through POSIX mode bits. */ if (file === undefined) continue const currentDigest = instructionContentSha1(file.content) const nextVersion: InstructionVersionState = { diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts index 4603611ce4..9592ba0349 100644 --- a/packages/fs/fs-local/src/fsio.ts +++ b/packages/fs/fs-local/src/fsio.ts @@ -175,6 +175,7 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise { await mkdir(this.root, { recursive: true, mode: 0o700 }) await this.syncDirPosix(dirname(this.root)) @@ -213,6 +214,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi /* v8 ignore next -- redundant temp link; publish already durable, rm failure is an unreachable IO edge */ } } + /* v8 ignore stop */ /* v8 ignore start -- native Windows coverage exercises this integration path */ private async materializeWin32(dir: string, finalPath: string, id: SessionId, content: string): Promise { @@ -254,6 +256,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } /** fsync a POSIX directory so a just-created/renamed entry is crash-durable. */ + /* v8 ignore start -- Windows uses write-through namespace operations; POSIX coverage exercises directory fsync. */ private async syncDirPosix(dir: string): Promise { const handle = await open(dir, 'r') try { @@ -262,6 +265,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi await handle.close() } } + /* v8 ignore stop */ /** * Append and fsync event lines. On a partial write or sync failure, restore the @@ -395,6 +399,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi await this.assertLogParentAllowsAbsence(path) return false } + /* v8 ignore next -- Windows repairs ENOTDIR from ENOENT above; POSIX covers direct ENOTDIR. */ throw error } } diff --git a/packages/skill/skill-local/src/index.ts b/packages/skill/skill-local/src/index.ts index ee109fbb16..29f5c622b9 100644 --- a/packages/skill/skill-local/src/index.ts +++ b/packages/skill/skill-local/src/index.ts @@ -317,6 +317,7 @@ async function nodeEntryKind(fullPath: string, entry: { isDirectory(): boolean; const info = await stat(fullPath) if (info.isDirectory()) return 'directory' if (info.isFile()) return 'file' + /* v8 ignore next -- The special-file symlink fixture relies on POSIX /dev/null. */ return undefined } catch (error) { ctx.logger.warn(`skill entry ${fullPath} ignored: failed to follow symbolic link: ${errorMessage(error)}`) From b426c2f19c06a6132e2d21992af8f2e2f5679506 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 18 Jul 2026 12:13:53 +0800 Subject: [PATCH 16/53] docs(api): refresh sandbox source link --- website/zh-CN/api/harness/sandbox.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/zh-CN/api/harness/sandbox.md b/website/zh-CN/api/harness/sandbox.md index bc5b1d38a5..51980d36d7 100644 --- a/website/zh-CN/api/harness/sandbox.md +++ b/website/zh-CN/api/harness/sandbox.md @@ -21,4 +21,4 @@ Wrap `argv` so it executes confined under `policy` on this host; the caller spaw **Returns** the argv to spawn instead, plus the enforcement completeness the selected backend achieves for it. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L127) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L128) From f62cc439e9bbc7e26e674e3a82b53e4dbb05469c Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 18 Jul 2026 13:03:44 +0800 Subject: [PATCH 17/53] docs(windows): clarify portability rules --- .github/AGENTS.md | 4 ++-- packages/support/acp-snapshot/README.md | 2 +- scripts/AGENTS.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/AGENTS.md b/.github/AGENTS.md index 00e3ed8f87..5f03c8617d 100644 --- a/.github/AGENTS.md +++ b/.github/AGENTS.md @@ -1,3 +1,3 @@ -# AGENTS.md — CI gates +# AGENTS.md — GitHub Actions -Run Windows gates from native `pwsh`, invoke pnpm shell-free, and normalize repo-relative glob paths to `/` at ingestion. Keep platform fixes at each gate boundary; do not add a shared platform layer. +Run Windows jobs under native `pwsh`. diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md index 9969eadb46..57f7245d7c 100644 --- a/packages/support/acp-snapshot/README.md +++ b/packages/support/acp-snapshot/README.md @@ -37,7 +37,7 @@ defineAcpSnapshotSuite({ A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.golden.md` and the corresponding full tool-schema sequence in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences. -Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. A scenario may set `pinsNativeWindowsStdout` to add a Windows-only comparison against the complete `stdout.golden.windows.jsonl`; the shared golden still runs first on Windows, and the fixture guard requires the sidecar exactly when declared. +Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. On Windows, `pinsNativeWindowsStdout` additionally compares the complete `stdout.golden.windows.jsonl` after the shared golden and requires that sidecar exactly when enabled. Examples use a `cordis.snapshot.yml` overlay with [`dsh-llm-replay`](../llm-replay/README.md). Recording calls the live model and updates model fixtures; keyless refresh replays those fixtures and updates derived stdout, session-log, prompt, and tool-schema snapshots. See the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md). diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md index 2d1ebafc27..68ea79ea7b 100644 --- a/scripts/AGENTS.md +++ b/scripts/AGENTS.md @@ -1,3 +1,3 @@ # AGENTS.md — Repository scripts -Gate-related scripts follow the [CI gate rules](../.github/AGENTS.md). +Gate scripts invoke pnpm shell-free, normalize repository-relative glob paths to `/` at ingestion, and keep platform adaptation at the owning gate boundary instead of a shared platform layer. From 7d28b611b2b72bec88c7e722add48d443c42f7e3 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 18 Jul 2026 15:55:37 +0800 Subject: [PATCH 18/53] test(windows): align platform coverage ignores --- packages/fs/fs-local/src/fsio.ts | 5 ++++- packages/sandbox/sandbox/src/index.ts | 2 +- .../session-persistence-jsonl/src/index.ts | 1 + packages/skill/skill-local/src/index.ts | 1 + 4 files changed, 7 insertions(+), 2 deletions(-) diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts index 9592ba0349..05d957105a 100644 --- a/packages/fs/fs-local/src/fsio.ts +++ b/packages/fs/fs-local/src/fsio.ts @@ -133,6 +133,7 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise Date: Sat, 18 Jul 2026 16:25:16 +0800 Subject: [PATCH 19/53] test(windows): replace POSIX-only filesystem fixtures --- .../context/workspace-context/src/files.ts | 1 - .../context/workspace-context/src/state.ts | 1 - .../tests/workspace-context.spec.ts | 43 ++++++++++++------- .../spill-local/tests/spill-local.spec.ts | 13 ++++-- 4 files changed, 36 insertions(+), 22 deletions(-) diff --git a/packages/context/workspace-context/src/files.ts b/packages/context/workspace-context/src/files.ts index 770024c569..feb6304b4c 100644 --- a/packages/context/workspace-context/src/files.ts +++ b/packages/context/workspace-context/src/files.ts @@ -459,7 +459,6 @@ export async function readScopeInstruction( signal?: AbortSignal, ): Promise { const content = await readBounded(file, maxSourceBytes, fileSystem, signal) - /* v8 ignore next -- Windows cannot reproduce a post-probe unreadable file with POSIX mode bits. */ if (content === undefined) return undefined return { absolutePath: file.absolutePath, diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts index ab18f442f4..98b8fcc066 100644 --- a/packages/context/workspace-context/src/state.ts +++ b/packages/context/workspace-context/src/state.ts @@ -437,7 +437,6 @@ export async function reconcileInstructionContext( ) continue const file = await readScopeInstruction(probedFile, resolved.maxSourceBytes, fileSystem, options.signal) - /* v8 ignore next -- Windows cannot make the probed file unreadable through POSIX mode bits. */ if (file === undefined) continue const currentDigest = instructionContentSha1(file.content) const nextVersion: InstructionVersionState = { diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index 9de003ae8d..75238d6fb6 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -1,4 +1,4 @@ -import { chmod, mkdtemp, mkdir, rm, stat, symlink, utimes, writeFile } from 'node:fs/promises' +import { mkdtemp, mkdir, rm, stat, symlink, utimes, writeFile } from 'node:fs/promises' import { dirname, join, resolve } from 'node:path' import { tmpdir } from 'node:os' import { describe, expect, it, vi } from 'vitest' @@ -53,6 +53,7 @@ class RecordingFileSystem extends FileSystem { entries = new Map() lstatTypes = new Map() throwOnStat = new Set() + throwOnRead = new Set() omitSizes = new Set() readTargets: string[] = [] readTextTargets: string[] = [] @@ -105,6 +106,7 @@ class RecordingFileSystem extends FileSystem { if (signal !== undefined) this.signals.push(signal) signal?.throwIfAborted() this.readTargets.push(target.targetKey) + if (this.throwOnRead.has(target.targetKey)) throw new Error(`read failed: ${target.displayPath}`) const content = this.entries.get(target.targetKey)?.content ?? '' return (async function* () { const midpoint = Math.ceil(content.length / 2) @@ -336,22 +338,25 @@ describe('workspace context instruction discovery', () => { } }) - it.skipIf(process.platform === 'win32')('skips a file that becomes unreadable after discovery without failing the request', async () => { + it('skips a provider file whose read fails after a successful metadata probe', async () => { const root = await tempRepo() const home = await tempRepo() + const ctx = new Context() try { const cwd = join(root, 'pkg') - await mkdir(join(root, '.git'), { recursive: true }) - await mkdir(cwd, { recursive: true }) const leaf = join(cwd, 'AGENTS.md') - await write(leaf, 'secret-ish rule') - await chmod(leaf, 0) + await ctx.plugin(RecordingFileSystem) + const fs = ctx.fs as RecordingFileSystem + fs.entries.set(join(root, '.git'), { type: 'directory' }) + fs.entries.set(leaf, { type: 'file', content: 'secret-ish rule' }) + fs.throwOnRead.add(leaf) - const loaded = await loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536 }) + const loaded = await loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536 }, fs) expect(loaded).toBeUndefined() - await chmod(leaf, 0o600) + expect(fs.readTargets).toEqual([leaf]) } finally { + await ctx.fiber.dispose() await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) } @@ -2403,17 +2408,22 @@ describe('dynamic nested workspace context injection', () => { } }) - it.skipIf(process.platform === 'win32')('skips unreadable nested instruction files without attaching empty context', async () => { + it('skips unreadable nested instruction files without attaching empty context', async () => { const root = await tempRepo() const home = await tempRepo() + const ctx = new Context() try { - await mkdir(join(root, '.git'), { recursive: true }) const nested = join(root, 'pkg/AGENTS.md') - await write(nested, 'nested package rule') - await write(join(root, 'pkg/deep/file.txt'), 'hello') - await chmod(nested, 0) - const ctx = new Context() - await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 }) + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(RecordingFileSystem) + const fs = ctx.fs as RecordingFileSystem + fs.entries.set(join(root, '.git'), { type: 'directory' }) + fs.entries.set(nested, { type: 'file', content: 'nested package rule' }) + fs.entries.set(join(root, 'pkg/deep/file.txt'), { type: 'file', content: 'hello' }) + fs.throwOnRead.add(nested) + await ctx.plugin(ToolFs) + await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 }) const result = await ctx.tools.execute({ callId: CallId('read-with-unreadable-nested-instruction'), @@ -2424,8 +2434,9 @@ describe('dynamic nested workspace context injection', () => { expect(result.isError).toBe(false) expect(result.additionalContexts).toBeUndefined() - await chmod(nested, 0o600) + expect(fs.readTargets).toContain(nested) } finally { + await ctx.fiber.dispose() await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) } diff --git a/packages/spill/spill-local/tests/spill-local.spec.ts b/packages/spill/spill-local/tests/spill-local.spec.ts index 46fa0b66b2..3c6f9ac82d 100644 --- a/packages/spill/spill-local/tests/spill-local.spec.ts +++ b/packages/spill/spill-local/tests/spill-local.spec.ts @@ -85,11 +85,16 @@ describe('saveTextFile', () => { expect(saved.path.includes('/..')).toBe(false) }) - it.skipIf(process.platform === 'win32')('creates the session dir with owner-only permissions', async () => { + it('creates the session directory and file with owner-only POSIX permissions', async () => { const saved = await saveTextFile({ root, sessionId: 'sess-1', suggestedName: 'r.txt', content: 'x' }) - // 0o700 dir, 0o600 file (masked by umask, but the owner bits must hold). - expect(statSync(dirname(saved.path)).mode & 0o700).toBe(0o700) - expect(statSync(saved.path).mode & 0o600).toBe(0o600) + const directory = statSync(dirname(saved.path)) + const file = statSync(saved.path) + expect(directory.isDirectory()).toBe(true) + expect(file.isFile()).toBe(true) + if (process.platform !== 'win32') { + expect(directory.mode & 0o777).toBe(0o700) + expect(file.mode & 0o777).toBe(0o600) + } }) it('gives distinct paths to two saves of the same name', async () => { From 64f64724e5caaca1c59db5bd953c4a8e1214c538 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 18 Jul 2026 16:25:51 +0800 Subject: [PATCH 20/53] fix(subprocess): honor Windows termination semantics --- docs/config-catalog.md | 2 +- packages/subagent/subagent-acp/README.md | 6 ++--- packages/subagent/subagent-acp/src/index.ts | 2 +- packages/subagent/subagent-acp/src/run.ts | 14 +++++------ .../subagent-acp/tests/subagent-acp.spec.ts | 16 ++++--------- .../subagent/subagent-subprocess/README.md | 10 ++++---- .../subagent/subagent-subprocess/src/index.ts | 23 +++++++++++++------ .../tests/subagent-subprocess.spec.ts | 13 ++++++++--- 8 files changed, 48 insertions(+), 38 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index ba273888d1..b31721ef99 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -853,7 +853,7 @@ export interface Config { * before the parent escalates to a signal. */ disposeEofGraceMs?: number - /** Grace period (ms) between `SIGTERM` and the `SIGKILL` escalation on dispose. */ + /** POSIX grace period (ms) between `SIGTERM` and `SIGKILL`; unused on Windows. */ disposeGraceMs?: number } diff --git a/packages/subagent/subagent-acp/README.md b/packages/subagent/subagent-acp/README.md index 69a5f14181..7b23d371a0 100644 --- a/packages/subagent/subagent-acp/README.md +++ b/packages/subagent/subagent-acp/README.md @@ -8,7 +8,7 @@ The ACP provider runs each subagent in a fresh subprocess and drives it as an Ag After publication, the provider sends the prompt and collects streamed `agent_message_chunk` text into `SubagentResult.output`. A prompt/transport failure resolves with `stopReason: 'error'`, or `aborted` when the required request signal or disposal requested cancellation. -`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, closes stdin, waits `disposeEofGraceMs`, escalates to SIGTERM, waits `disposeGraceMs`, and finally uses SIGKILL if necessary. Every run uses a fresh process; process pooling is not implemented. +`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, closes stdin, and waits `disposeEofGraceMs`. POSIX then escalates through SIGTERM and `disposeGraceMs` before SIGKILL; Windows force-terminates directly because Node maps both signals to `TerminateProcess`. Disposal resolves only after child exit. Every run uses a fresh process; process pooling is not implemented. ## Capabilities and context @@ -24,8 +24,8 @@ ACP advertises no start-time capabilities because this process cannot enforce th | `cwd` | process cwd | Child process and ACP session working directory. | | `permission` | `reject` | Auto-answer permission requests by rejecting or choosing the first allow-shaped option. | | `env` | `{}` | Explicit child environment layered over a credential-scrubbed parent environment. | -| `disposeEofGraceMs` | `6000` | Grace after stdin EOF before SIGTERM. | -| `disposeGraceMs` | `3000` | Grace after SIGTERM before SIGKILL. | +| `disposeEofGraceMs` | `6000` | Grace after stdin EOF before platform termination. | +| `disposeGraceMs` | `3000` | POSIX grace after SIGTERM before SIGKILL; unused on Windows. | ```yaml - id: subagent-acp diff --git a/packages/subagent/subagent-acp/src/index.ts b/packages/subagent/subagent-acp/src/index.ts index 80766ed831..697be5b98a 100644 --- a/packages/subagent/subagent-acp/src/index.ts +++ b/packages/subagent/subagent-acp/src/index.ts @@ -46,7 +46,7 @@ export interface Config { * before the parent escalates to a signal. */ disposeEofGraceMs?: number - /** Grace period (ms) between `SIGTERM` and the `SIGKILL` escalation on dispose. */ + /** POSIX grace period (ms) between `SIGTERM` and `SIGKILL`; unused on Windows. */ disposeGraceMs?: number } diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts index 9416d58865..c9f1c59e10 100644 --- a/packages/subagent/subagent-acp/src/run.ts +++ b/packages/subagent/subagent-acp/src/run.ts @@ -56,9 +56,9 @@ export interface AcpRunSpec { */ disposeEofGraceMs: number /** - * Grace period (ms) between `SIGTERM` and the `SIGKILL` escalation in - * {@link SubagentRun.dispose}. The plugin fills this from its - * `disposeGraceMs` config. + * POSIX grace period (ms) between `SIGTERM` and `SIGKILL` in + * {@link SubagentRun.dispose}; unused on Windows. The plugin fills this from + * its `disposeGraceMs` config. */ disposeGraceMs: number /** @@ -75,7 +75,7 @@ export interface AcpRunSpec { /** EOF grace for child flush and nested-process teardown; wider than the signal grace below. */ export const DEFAULT_DISPOSE_EOF_GRACE_MS = 6_000 -/** Default grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config; mirrors the bash executor). */ +/** Default POSIX grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config). */ export const DEFAULT_DISPOSE_GRACE_MS = 3_000 /** @@ -290,9 +290,9 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe if (disposal !== undefined) return disposal request.signal.removeEventListener('abort', onAbort) requestCancel() - // The shared EOF → TERM → KILL ladder awaits exit. ACP normally quiesces - // from stdin EOF, including the final flush, so this backend uses a wider - // EOF grace before signals escalate. + // The shared platform-aware ladder awaits exit. ACP normally quiesces from + // stdin EOF, including the final flush, so this backend uses a wider EOF + // grace before process termination escalates. disposal = disposeProcess() return disposal }, diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts index e3fd3eda48..a57263eb6c 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts @@ -263,13 +263,9 @@ describe('dsh-subagent-acp', () => { } }) - it.skipIf(process.platform === 'win32')('escalates to SIGTERM for a child that ignores EOF but is not SIGTERM-trapping', async () => { - // A child that keeps its loop alive past stdin EOF (so the graceful window - // times out) but exits cooperatively on SIGTERM must die on the SIGTERM tier - // — dispose returns there, never reaching the SIGKILL tier. The child touches - // a SIGTERM marker from its signal handler: SIGKILL is uncatchable, so if - // dispose had skipped the middle rung (EOF→SIGKILL) the handler would never - // run and the marker would be absent — making this a GENUINE middle-tier guard. + it('terminates a child that ignores EOF using the host platform semantics', async () => { + // POSIX uses the catchable SIGTERM tier and records the marker. Windows has + // no distinct graceful signal, so disposal skips directly to forced exit. const tmp = mkdtempSync(join(tmpdir(), 'acp-ignore-eof-')) const ready = join(tmp, 'ready') const sigterm = join(tmp, 'sigterm') @@ -283,7 +279,7 @@ describe('dsh-subagent-acp', () => { MOCK_HANG: '1', MOCK_IGNORE_EOF: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready, MOCK_SIGTERM_FILE: sigterm, }, - // Tiny EOF grace so the ignored-EOF window elapses fast, then SIGTERM. + // Tiny EOF grace so the ignored-EOF window elapses quickly. disposeEofGraceMs: 150, disposeGraceMs: 2000, } @@ -294,9 +290,7 @@ describe('dsh-subagent-acp', () => { run.dispose(), new Promise((_r, reject) => { setTimeout(() => { reject(new Error('dispose did not return')) }, 5000) }), ])).resolves.toBeUndefined() - // The child caught SIGTERM and exited — proof the middle rung fired (not a - // jump straight to the uncatchable SIGKILL). - expect(existsSync(sigterm)).toBe(true) + expect(existsSync(sigterm)).toBe(process.platform !== 'win32') } finally { rmSync(tmp, { recursive: true, force: true }) } diff --git a/packages/subagent/subagent-subprocess/README.md b/packages/subagent/subagent-subprocess/README.md index a3c0905422..48ce9ff0e4 100644 --- a/packages/subagent/subagent-subprocess/README.md +++ b/packages/subagent/subagent-subprocess/README.md @@ -20,13 +20,13 @@ Exit waits over a `ChildProcess`: resolve once the child exits by any code or si ### `disposeChildProcess(child, graces)` -The three-tier dispose ladder. Resolves only once the child has ACTUALLY exited — quiescence reached, not merely requested (see [defensive patterns](../../../docs/defensive-patterns.md)): +The platform-aware dispose ladder resolves only once the child has ACTUALLY exited — quiescence reached, not merely requested (see [defensive patterns](../../../docs/defensive-patterns.md)): 1. stdin EOF (when stdin is piped), then wait `graces.disposeEofGraceMs` — a cooperative child quiesces on its own, its flushes and nested-subprocess teardown intact; -2. `SIGTERM`, then wait `graces.disposeGraceMs`; -3. `SIGKILL`, then await the now-certain exit — a child that ignores EOF and traps `SIGTERM` cannot wedge dispose forever. +2. on POSIX, `SIGTERM`, then wait `graces.disposeGraceMs`; +3. force termination and await exit — `SIGKILL` on POSIX and Node's `TerminateProcess` mapping on Windows. -The two graces (`DisposeLadderGraces`) come from the consuming plugin's `disposeEofGraceMs`/`disposeGraceMs` Config fields; the EOF window is deliberately a separate — usually wider — grace than the signal tier, since a cooperative child's EOF teardown may itself await a signal-trapping grandchild plus a final flush. +The two graces (`DisposeLadderGraces`) come from the consuming plugin's `disposeEofGraceMs`/`disposeGraceMs` Config fields; `disposeGraceMs` is unused on Windows because Node maps `SIGTERM` and `SIGKILL` to the same forced termination. The EOF window is deliberately separate and usually wider, since cooperative teardown may await a signal-trapping grandchild plus a final flush. ### `createIsolatedConfigDir(prefix, pinnedPath?)` @@ -37,7 +37,7 @@ A per-run isolated config directory for an external CLI child (the target of `CL ## Testing -`tests/subagent-subprocess.spec.ts`: the env scrub and config-dir helpers run against the real process env and real filesystem (the rm-failure path injects its rejection at the fs boundary — a real recursive-rm failure is not portably provokable, and root ignores permission bits); the exit waits and the dispose ladder run against a scriptable fake child, driving each escalation tier deterministically. The [ACP backend suite](../subagent-acp/README.md) exercises the same ladder against real subprocesses (EOF-cooperative, EOF-ignoring, and SIGTERM-trapping children) end to end. +`tests/subagent-subprocess.spec.ts`: the env scrub and config-dir helpers run against the real process env and real filesystem (the rm-failure path injects its rejection at the fs boundary — a real recursive-rm failure is not portably provokable, and root ignores permission bits); the exit waits and platform termination paths run against a scriptable fake child. The [ACP backend suite](../subagent-acp/README.md) exercises them against real subprocesses end to end. ## Model Experience diff --git a/packages/subagent/subagent-subprocess/src/index.ts b/packages/subagent/subagent-subprocess/src/index.ts index 21bcca788e..360b12a70b 100644 --- a/packages/subagent/subagent-subprocess/src/index.ts +++ b/packages/subagent/subagent-subprocess/src/index.ts @@ -98,33 +98,42 @@ export interface DisposeLadderGraces { /** * Tier-1 window (ms): after stdin EOF, how long the child gets to quiesce * ON ITS OWN — flush durable state, tear down its own nested subprocesses — - * before the parent escalates to `SIGTERM`. A separate (usually WIDER) + * before the parent escalates to platform termination. A separate (usually WIDER) * grace than {@link DisposeLadderGraces.disposeGraceMs}: a cooperative * child's EOF-driven teardown may itself be waiting on a signal-trapping * grandchild plus a final flush, needing more than one signal-grace of * headroom. */ disposeEofGraceMs: number - /** Tier-2 window (ms): between `SIGTERM` and the `SIGKILL` escalation. */ + /** POSIX tier-2 window (ms): between `SIGTERM` and the `SIGKILL` escalation. */ disposeGraceMs: number } /** * Tear a child process down to quiescence, resolving only after exit: close stdin and allow - * cooperative flush, then send `SIGTERM`, then `SIGKILL` and await the forced exit. + * cooperative flush, then use the host's graceful and forced termination semantics. POSIX + * sends `SIGTERM` before `SIGKILL`; Windows skips directly to forced termination because Node + * maps both signals to `TerminateProcess`. * * @param child - the child process to tear down. * @param graces - the two grace periods, from the consuming plugin's Config. + * @param platform - the host platform, injectable for unit coverage. */ -export async function disposeChildProcess(child: ChildProcess, graces: DisposeLadderGraces): Promise { +export async function disposeChildProcess( + child: ChildProcess, + graces: DisposeLadderGraces, + platform: NodeJS.Platform = process.platform, +): Promise { // Already gone: nothing to reap. if (child.exitCode !== null || child.signalCode !== null) return // 1. Close stdin and allow cooperative teardown and durable-state flush. child.stdin?.end() if (await exitsWithin(child, graces.disposeEofGraceMs)) return - // 2. SIGTERM, escalating if the child still does not exit within the grace. - child.kill('SIGTERM') - if (await exitsWithin(child, graces.disposeGraceMs)) return + // 2. POSIX gets a catchable graceful signal; Windows signals all force-terminate. + if (platform !== 'win32') { + child.kill('SIGTERM') + if (await exitsWithin(child, graces.disposeGraceMs)) return + } // 3. Force-kill and await the (now-certain) exit. child.kill('SIGKILL') await waitForExit(child) diff --git a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts index 8ed3891578..9fedf37722 100644 --- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts +++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts @@ -229,7 +229,7 @@ describe('disposeChildProcess', () => { it('tier 2: a child that ignores EOF but honors SIGTERM dies on the middle rung', async () => { const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 }) - await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }) + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux') expect(fake.stdinEnded).toBe(true) expect(fake.kills).toEqual(['SIGTERM']) expect(fake.signalCode).toBe('SIGTERM') @@ -237,7 +237,7 @@ describe('disposeChildProcess', () => { it('tier 3: a SIGTERM-trapping child is SIGKILLed, and dispose resolves only after the exit', async () => { const fake = new FakeChild({ delayMs: 5 }) // only SIGKILL fells it - await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 }) + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 }, 'linux') expect(fake.kills).toEqual(['SIGTERM', 'SIGKILL']) // Quiescence, not a request: at resolution the child has ACTUALLY exited // (the exit event landed, despite the scripted post-SIGKILL delay). @@ -246,9 +246,16 @@ describe('disposeChildProcess', () => { it('walks the ladder for a child spawned without a stdin pipe', async () => { const fake = new FakeChild({ stdin: false, diesOn: 'SIGTERM', delayMs: 5 }) - await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }) + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux') expect(fake.kills).toEqual(['SIGTERM']) }) + + it('skips the redundant SIGTERM tier on Windows and awaits forced exit', async () => { + const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 }) + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'win32') + expect(fake.kills).toEqual(['SIGKILL']) + expect(fake.signalCode).toBe('SIGKILL') + }) }) describe('createIsolatedConfigDir', () => { From 462519596860baad18e6f2c2a61d60de82eaee37 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 12:19:33 +0800 Subject: [PATCH 21/53] fix(subagent): bound forced child termination Observe signal errors and bound the final forced-exit edge with disposeGraceMs so a refused or ineffective SIGKILL cannot leave disposal pending forever. Apply the confirmation bound on POSIX and Windows, remove listeners and timers on every outcome, and update the ACP consumer contract plus the generated config catalog. Cover emitted signal errors, synchronous kill exceptions, refused termination, and accepted termination that never reports exit. --- docs/config-catalog.md | 2 +- packages/subagent/subagent-acp/README.md | 4 +- packages/subagent/subagent-acp/src/index.ts | 2 +- packages/subagent/subagent-acp/src/run.ts | 6 +- .../subagent/subagent-subprocess/README.md | 4 +- .../subagent/subagent-subprocess/src/index.ts | 58 +++++++++++++---- .../tests/subagent-subprocess.spec.ts | 65 +++++++++++++++++++ 7 files changed, 118 insertions(+), 23 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 7921b98f55..dd652c7d45 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -866,7 +866,7 @@ export interface Config { * before the parent escalates to a signal. */ disposeEofGraceMs?: number - /** POSIX grace period (ms) between `SIGTERM` and `SIGKILL`; unused on Windows. */ + /** Termination confirmation window (ms), including forced exit on every platform. */ disposeGraceMs?: number } diff --git a/packages/subagent/subagent-acp/README.md b/packages/subagent/subagent-acp/README.md index 830335bbb5..240b79c2d7 100644 --- a/packages/subagent/subagent-acp/README.md +++ b/packages/subagent/subagent-acp/README.md @@ -10,7 +10,7 @@ The returned run id is minted in the parent namespace. The child server's sessio After publication, the provider sends the prompt and collects streamed `agent_message_chunk` text into `SubagentResult.output`. A prompt/transport failure resolves with `stopReason: 'error'`, or `aborted` when the required request signal or disposal requested cancellation. -`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, closes stdin, and waits `disposeEofGraceMs`. POSIX then escalates through SIGTERM and `disposeGraceMs` before SIGKILL; Windows force-terminates directly because Node maps both signals to `TerminateProcess`. Disposal resolves only after child exit. Every run uses a fresh process; process pooling is not implemented. +`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, closes stdin, and waits `disposeEofGraceMs`. POSIX then escalates through SIGTERM and `disposeGraceMs` before SIGKILL; Windows force-terminates directly because Node maps both signals to `TerminateProcess`. After forced termination, every platform waits at most `disposeGraceMs` for exit and rejects on a signal error or missing exit. Every run uses a fresh process; process pooling is not implemented. ## Capabilities and context @@ -27,7 +27,7 @@ ACP advertises no start-time capabilities because this process cannot enforce th | `permission` | `reject` | Auto-answer permission requests by rejecting or choosing the first allow-shaped option. | | `env` | `{}` | Explicit child environment layered over a credential-scrubbed parent environment. | | `disposeEofGraceMs` | `6000` | Grace after stdin EOF before platform termination. | -| `disposeGraceMs` | `3000` | POSIX grace after SIGTERM before SIGKILL; unused on Windows. | +| `disposeGraceMs` | `3000` | Exit-confirmation grace after termination; POSIX also waits this long after SIGTERM before SIGKILL. | ```yaml - id: subagent-acp diff --git a/packages/subagent/subagent-acp/src/index.ts b/packages/subagent/subagent-acp/src/index.ts index 697be5b98a..0a761831ea 100644 --- a/packages/subagent/subagent-acp/src/index.ts +++ b/packages/subagent/subagent-acp/src/index.ts @@ -46,7 +46,7 @@ export interface Config { * before the parent escalates to a signal. */ disposeEofGraceMs?: number - /** POSIX grace period (ms) between `SIGTERM` and `SIGKILL`; unused on Windows. */ + /** Termination confirmation window (ms), including forced exit on every platform. */ disposeGraceMs?: number } diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts index 9f037a170c..09a6ed81e9 100644 --- a/packages/subagent/subagent-acp/src/run.ts +++ b/packages/subagent/subagent-acp/src/run.ts @@ -56,9 +56,9 @@ export interface AcpRunSpec { */ disposeEofGraceMs: number /** - * POSIX grace period (ms) between `SIGTERM` and `SIGKILL` in - * {@link SubagentRun.dispose}; unused on Windows. The plugin fills this from - * its `disposeGraceMs` config. + * Termination confirmation window (ms) in {@link SubagentRun.dispose}; POSIX applies it after + * `SIGTERM` and `SIGKILL`, while Windows applies it after direct forced termination. The plugin + * fills this from its `disposeGraceMs` config. */ disposeGraceMs: number /** diff --git a/packages/subagent/subagent-subprocess/README.md b/packages/subagent/subagent-subprocess/README.md index 4a72f6279b..80be43125e 100644 --- a/packages/subagent/subagent-subprocess/README.md +++ b/packages/subagent/subagent-subprocess/README.md @@ -20,9 +20,9 @@ The platform-aware dispose ladder resolves only once the child has ACTUALLY exit 1. stdin EOF (when stdin is piped), then wait `graces.disposeEofGraceMs` — a cooperative child quiesces on its own, its flushes and nested-subprocess teardown intact; 2. on POSIX, `SIGTERM`, then wait `graces.disposeGraceMs`; -3. force termination and await exit — `SIGKILL` on POSIX and Node's `TerminateProcess` mapping on Windows. +3. force termination — `SIGKILL` on POSIX and Node's `TerminateProcess` mapping on Windows — then wait at most `graces.disposeGraceMs` for exit; a signal error or missing exit rejects disposal. -The two graces (`DisposeLadderGraces`) come from the consuming plugin's `disposeEofGraceMs`/`disposeGraceMs` Config fields; `disposeGraceMs` is unused on Windows because Node maps `SIGTERM` and `SIGKILL` to the same forced termination. The EOF window is deliberately separate and usually wider, since cooperative teardown may await a signal-trapping grandchild plus a final flush. +The two graces (`DisposeLadderGraces`) come from the consuming plugin's `disposeEofGraceMs`/`disposeGraceMs` Config fields. POSIX uses `disposeGraceMs` after both the graceful and forced signals; Windows skips the redundant graceful signal but uses it to bound forced-exit confirmation. The EOF window is deliberately separate and usually wider, since cooperative teardown may await a signal-trapping grandchild plus a final flush. The exit waits are internal to this ladder. They clean up their timer and listener on either outcome, so escalation never accumulates listeners on the child. diff --git a/packages/subagent/subagent-subprocess/src/index.ts b/packages/subagent/subagent-subprocess/src/index.ts index de4702bac9..47a97bafb6 100644 --- a/packages/subagent/subagent-subprocess/src/index.ts +++ b/packages/subagent/subagent-subprocess/src/index.ts @@ -51,16 +51,6 @@ export function spawnFailure(child: ChildProcess): Promise { }) } -/** - * Resolve once the child process exits (any code/signal); immediate if it is - * already gone. - * @param child - the child process to await. - */ -function waitForExit(child: ChildProcess): Promise { - if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve() - return new Promise(resolve => child.once('exit', () => { resolve() })) -} - /** * Race the child's exit against a timer. Neither outcome leaves anything * behind on the child: the exit listener is removed on timeout and the timer @@ -104,10 +94,49 @@ export interface DisposeLadderGraces { * headroom. */ disposeEofGraceMs: number - /** POSIX tier-2 window (ms): between `SIGTERM` and the `SIGKILL` escalation. */ + /** + * Termination confirmation window (ms): POSIX applies it after `SIGTERM` and again after + * `SIGKILL`; Windows applies it after the direct forced termination. + */ disposeGraceMs: number } +/** Force-terminate a child and reject if no exit edge arrives within the configured grace. */ +function forceTerminateWithin(child: ChildProcess, ms: number): Promise { + if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve() + return new Promise((resolve, reject) => { + let accepted = false + let settled = false + const cleanup = (): void => { + clearTimeout(timer) + child.off('exit', onExit) + child.off('error', onError) + } + const settle = (complete: () => void): void => { + if (settled) return + settled = true + cleanup() + complete() + } + const onExit = (): void => { settle(resolve) } + const onError = (error: Error): void => { settle(() => { reject(error) }) } + child.once('exit', onExit) + child.once('error', onError) + const timer = setTimeout(() => { + const disposition = accepted ? 'accepted' : 'refused' + settle(() => { + reject(new Error(`child process did not exit within ${ms}ms after SIGKILL was ${disposition}`)) + }) + }, ms).unref() + try { + accepted = child.kill('SIGKILL') + if (child.exitCode !== null || child.signalCode !== null) settle(resolve) + } catch (error: unknown) { + settle(() => { reject(new Error('SIGKILL failed', { cause: error })) }) + } + }) +} + /** * Tear a child process down to quiescence, resolving only after exit: close stdin and allow * cooperative flush, then use the host's graceful and forced termination semantics. POSIX @@ -117,6 +146,8 @@ export interface DisposeLadderGraces { * @param child - the child process to tear down. * @param graces - the two grace periods, from the consuming plugin's Config. * @param platform - the host platform, injectable for unit coverage. + * @throws When forced termination errors or the child does not report exit within + * `disposeGraceMs`. */ export async function disposeChildProcess( child: ChildProcess, @@ -133,9 +164,8 @@ export async function disposeChildProcess( child.kill('SIGTERM') if (await exitsWithin(child, graces.disposeGraceMs)) return } - // 3. Force-kill and await the (now-certain) exit. - child.kill('SIGKILL') - await waitForExit(child) + // 3. Force-kill and await a bounded exit edge. + await forceTerminateWithin(child, graces.disposeGraceMs) } /** diff --git a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts index 901989e074..7c17333c03 100644 --- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts +++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts @@ -234,6 +234,71 @@ describe('disposeChildProcess', () => { expect(fake.kills).toEqual(['SIGKILL']) expect(fake.signalCode).toBe('SIGKILL') }) + + it('propagates a forced-termination error without waiting for the grace', async () => { + const fake = new FakeChild() + const failure = Object.assign(new Error('kill EPERM'), { code: 'EPERM' }) + vi.spyOn(fake, 'kill').mockImplementation((signal) => { + fake.kills.push(signal) + fake.emit('error', failure) + return false + }) + + await expect(disposeChildProcess( + asChild(fake), + { disposeEofGraceMs: 1, disposeGraceMs: 1000 }, + 'win32', + )).rejects.toBe(failure) + expect(fake.kills).toEqual(['SIGKILL']) + expect(fake.listenerCount('error')).toBe(0) + expect(fake.listenerCount('exit')).toBe(0) + }) + + it('wraps a synchronous forced-termination exception and removes its listeners', async () => { + const fake = new FakeChild() + const failure = new Error('invalid signal state') + vi.spyOn(fake, 'kill').mockImplementation(() => { throw failure }) + + await expect(disposeChildProcess( + asChild(fake), + { disposeEofGraceMs: 1, disposeGraceMs: 1000 }, + 'win32', + )).rejects.toMatchObject({ message: 'SIGKILL failed', cause: failure }) + expect(fake.listenerCount('error')).toBe(0) + expect(fake.listenerCount('exit')).toBe(0) + }) + + it('bounds a refused forced termination that produces no error or exit', async () => { + const fake = new FakeChild() + vi.spyOn(fake, 'kill').mockImplementation((signal) => { + fake.kills.push(signal) + return false + }) + + await expect(disposeChildProcess( + asChild(fake), + { disposeEofGraceMs: 1, disposeGraceMs: 10 }, + 'win32', + )).rejects.toThrow('child process did not exit within 10ms after SIGKILL was refused') + expect(fake.listenerCount('error')).toBe(0) + expect(fake.listenerCount('exit')).toBe(0) + }) + + it('bounds an accepted forced termination that never reports exit', async () => { + const fake = new FakeChild() + vi.spyOn(fake, 'kill').mockImplementation((signal) => { + fake.kills.push(signal) + return true + }) + + await expect(disposeChildProcess( + asChild(fake), + { disposeEofGraceMs: 1, disposeGraceMs: 10 }, + 'win32', + )).rejects.toThrow('child process did not exit within 10ms after SIGKILL was accepted') + expect(fake.listenerCount('error')).toBe(0) + expect(fake.listenerCount('exit')).toBe(0) + }) }) describe('createIsolatedConfigDir', () => { From 46580e408329e027414273527bac39dbd39b1650 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 12:20:11 +0800 Subject: [PATCH 22/53] test(subagent): pin POSIX disposal scenarios Pass an explicit Linux platform to the two remaining SIGTERM-specific ladder tests instead of inheriting the host platform. This keeps their synchronous-exit assertions focused on the POSIX middle and final rungs while the dedicated Windows case continues to verify the direct SIGKILL path. Without the pin, native Windows coverage deterministically expected SIGTERM but observed the intended SIGKILL-only behavior. --- .../subagent-subprocess/tests/subagent-subprocess.spec.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts index 7c17333c03..e81957baa0 100644 --- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts +++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts @@ -200,7 +200,7 @@ describe('disposeChildProcess', () => { it('recognizes a child that exits synchronously on SIGTERM', async () => { const fake = new FakeChild({ diesOn: 'SIGTERM', synchronousExit: true }) - await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }) + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux') expect(fake.kills).toEqual(['SIGTERM']) expect(fake.signalCode).toBe('SIGTERM') expect(fake.listenerCount('exit')).toBe(0) @@ -217,7 +217,7 @@ describe('disposeChildProcess', () => { it('recognizes a child already gone when the final exit wait begins', async () => { const fake = new FakeChild({ synchronousExit: true }) - await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 }) + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 }, 'linux') expect(fake.kills).toEqual(['SIGTERM', 'SIGKILL']) expect(fake.signalCode).toBe('SIGKILL') }) From 2b673bd68dbc41798d138454e4def2b2f265046f Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 12:38:18 +0800 Subject: [PATCH 23/53] fix(fs): preserve Windows DACLs across atomic replacement Copy an existing target's DACL onto the empty staging file before any content is written, then publish with ReplaceFileW so Windows replacement keeps the target security descriptor instead of inheriting the broader parent policy. Keep new-file inheritance and POSIX mode behavior unchanged, retain the already-protected temp when a concurrently removed target requires rename fallback, and translate native errors into Node-style codes for the filesystem error boundary. Add host-independent Win32 binding coverage, native Windows descriptor assertions, package documentation, and a bilingual implemented RFC that supersedes the earlier inheritance-only replacement claim. --- docs/rfc/INDEX.md | 6 + .../2026-07-05-windows-fs-permissions.md | 14 +- ...s-atomic-write-dacl-preservation.i18n.yaml | 6 + ...-windows-atomic-write-dacl-preservation.md | 27 ++++ ...ndows-atomic-write-dacl-preservation.zh.md | 27 ++++ packages/fs/fs-local/README.md | 2 +- packages/fs/fs-local/package.json | 1 + packages/fs/fs-local/src/fsio.ts | 34 +++- packages/fs/fs-local/src/win32.ts | 134 ++++++++++++++++ packages/fs/fs-local/tests/fsio.spec.ts | 89 ++++++++++- packages/fs/fs-local/tests/win32.spec.ts | 145 ++++++++++++++++++ pnpm-lock.yaml | 3 + 12 files changed, 472 insertions(+), 16 deletions(-) create mode 100644 docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml create mode 100644 docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md create mode 100644 docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md create mode 100644 packages/fs/fs-local/src/win32.ts create mode 100644 packages/fs/fs-local/tests/win32.spec.ts diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index ceaf70cd87..6ca005be8d 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -89,6 +89,12 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Optional time-context plugin](implemented/feature/2026-07-14-time-context-plugin.md) | 2026-07-14 | | [Durable per-step time context](implemented/feature/2026-07-16-durable-per-step-time-context.md) | 2026-07-16 | +### Bug-fix + +| Title | First proposed | +|---|---| +| [Preserve Windows DACLs during atomic file replacement](implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md) | 2026-07-19 | + ### Simplification | Title | First proposed | diff --git a/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md b/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md index 0001e8223c..4d477990cd 100644 --- a/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md +++ b/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md @@ -2,21 +2,23 @@ Status: implemented +The replacement-file decision in this record is superseded by [Windows DACL preservation](../bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md). + ## Problem `writeFileAtomic` in `@deepseek-ai/dsh-fs-local` protects write-in-progress content with POSIX mode bits: the staging directory is created `0o700`, the temp file is opened `0o600`, and new files default to `0o600`. On POSIX this keeps temporary content owner-only regardless of the parent directory's permissions. -Windows has no working equivalent behind the same API. Node's `chmod` there drives only the read-only attribute (every mode this package passes carries owner-write, so the calls are benign no-ops), and `stat().mode` reports synthetic `0o666`/`0o444` bits. The real security state is the file's DACL, which this code never sets; a newly created file or directory inherits its DACL from its parent directory. +Windows has no working equivalent behind the same API. Node's `chmod` there drives only the read-only attribute (every mode this package passes carries owner-write, so the calls are benign no-ops), and `stat().mode` reports synthetic `0o666`/`0o444` bits. The real security state is the file's DACL: a newly created file or directory inherits from its parent, while replacement needs the explicit handling owned by the superseding RFC. ## Decision -Production code is unchanged: no platform fork, no DACL management. The Windows privacy invariant is structural rather than mode-driven — the staging directory is created inside the target's parent directory (`dirname(absolutePath)`), so it and the temp file inherit exactly the destination directory's DACL, and write-in-progress content is never exposed more widely than the destination itself. In the typical deployment (a coding agent writing the user's own project tree under `C:\Users\\`) the inherited DACL is owner + SYSTEM + Administrators, matching the POSIX intent. +New Windows files use directory inheritance rather than synthetic mode bits: the staging directory is created inside the target's parent directory (`dirname(absolutePath)`), so it and the temp file inherit the destination directory's DACL. Replacement files follow the stricter [DACL preservation contract](../bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md). -Tests assert mode bits on POSIX only. There is no Windows-side ACL assertion because there is no Windows-side code behavior to pin: an ACL check on a `mkdtemp(tmpdir())` fixture would verify Windows DACL inheritance plus the machine's `%TEMP%` ACL — the operating system, not this package — and no change to this package could turn it red. +Tests assert mode bits on POSIX only. Native Windows coverage pins the package-owned replacement behavior; new-file inheritance remains an operating-system contract rather than a machine-specific ACL allowlist. ## Alternatives considered -**Explicit protected DACLs.** Granting owner-only access would require per-write FFI or a subprocess, break inheritance, and surprise users whose project directories are deliberately shared. This becomes appropriate only if the threat model includes hostile local readers of broadly accessible target directories. +**Explicit owner-only DACLs for new files.** Rejected because they would break inheritance and surprise users whose project directories are deliberately shared. Replacement writes copy the target's existing DACL rather than inventing an owner-only policy. **Test-side ACL verification.** A `Get-Acl` SID allowlist or `icacls` would verify Windows inheritance and the machine's `%TEMP%` ACL rather than package behavior; `icacls` also localizes well-known account names, making parsing locale-fragile. @@ -24,6 +26,6 @@ Tests assert mode bits on POSIX only. There is no Windows-side ACL assertion bec ## Consequences -POSIX keeps the stronger guarantee: owner-only temp content regardless of the parent directory. Windows guarantees only "no wider than the destination": a target inside a broadly accessible directory (a share, a permissive `D:\` root) gets equally accessible write-in-progress content. The gap is deliberate and documented, not an oversight. +POSIX keeps owner-only temp content regardless of the parent directory. A new Windows target inside a broadly accessible directory inherits that accessibility by design; a replacement retains the target's narrower DACL when one exists. -Mode preservation across a replace degenerates to a no-op on Windows: a writable file probes as `0o666`, and replaying that through `chmod` leaves the read-only attribute clear. A read-only target cannot be replaced at all there — `rename` over it fails before the preserved mode would matter. +Mode preservation across a replace degenerates to a no-op on Windows: a writable file probes as `0o666`, and replaying that through `chmod` leaves the read-only attribute clear. A read-only target cannot be replaced there because publication fails before the synthetic mode would matter. diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml new file mode 100644 index 0000000000..5f37bf3ca3 --- /dev/null +++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write +2026-07-19-windows-atomic-write-dacl-preservation.md: 393ce8a992b8c0b7b580f2c794e098d66e14258e +2026-07-19-windows-atomic-write-dacl-preservation.zh.md: c7a0b6278cf739cc5ef4432d679e48b88b61d198 diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md new file mode 100644 index 0000000000..393ce8a992 --- /dev/null +++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md @@ -0,0 +1,27 @@ +# RFC: Preserve Windows DACLs during atomic file replacement + +Status: implemented + +English | [中文](2026-07-19-windows-atomic-write-dacl-preservation.zh.md) + +## Problem + +On Windows, creating the staging directory and temp file under the target's parent and relying only on inherited DACLs is sufficient for a new file, but not for replacing an existing file whose explicit or protected DACL is narrower than its parent: content is written under the broader parent DACL, and rename carries that staging descriptor onto the replacement. + +## Decision + +`dsh-fs-local` reads an existing target's DACL with `GetFileSecurityW`, applies it to the empty temp file with inheritance protected before writing content, and publishes the closed temp with `ReplaceFileW`. The protected staging descriptor prevents the temp directory's inherited entries from broadening access; `ReplaceFileW` preserves the original target security descriptor and other replacement metadata. New files have no prior descriptor to preserve and continue to inherit the destination directory's DACL. + +Native Windows coverage protects a target DACL, inspects the written staging file, and compares the final replacement descriptor. Host-independent binding tests cover Win32 error translation and every native call boundary. + +## Alternatives considered + +**Rely on directory inheritance for replacements.** Rejected because a target may carry a narrower explicit or protected DACL than its parent, so inheritance neither protects staged content nor preserves the target access policy. + +**Use `ReplaceFileW` without protecting the temp.** Rejected because it repairs the final descriptor only after the content has already been written under the staging file's inherited DACL. + +**Install an owner-only DACL for every write.** Rejected because it would discard deliberate project sharing. Copying the target DACL preserves the deployment's existing access policy instead of inventing one. + +## Consequences + +Replacing a Windows file now requires permission to read the target DACL and set the temp DACL; failure is loud before content is written. The package carries Koffi for the narrow Win32 calls, loaded only on Windows replacement paths. New-file behavior remains directory-inherited, and POSIX mode behavior is unchanged. diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md new file mode 100644 index 0000000000..c7a0b6278c --- /dev/null +++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md @@ -0,0 +1,27 @@ +# RFC: Windows 原子文件替换期间保留 DACL + +Status: implemented + +[English](2026-07-19-windows-atomic-write-dacl-preservation.md) | 中文 + +## 问题 + +在 Windows 上，在目标文件的父目录下创建暂存目录和临时文件，并且只依赖继承的 DACL，足以满足新建文件的需要，但无法安全替换显式或受保护 DACL 比父目录更严格的现有文件：内容会在权限更宽松的父目录 DACL 下写入，而重命名又会把这个暂存安全描述符带到替换后的文件上。 + +## 决策 + +`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的安全描述符及其他替换元数据。新建文件没有既有描述符需要保留，因此仍继承目标目录的 DACL。 + +Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件的描述符。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。 + +## 备选方案 + +**替换文件时依赖目录继承。** 不予采用，因为目标文件可能带有比父目录更严格的显式或受保护 DACL；目录继承既无法保护暂存内容，也无法保留目标文件的访问策略。 + +**使用 `ReplaceFileW`，但不保护临时文件。** 不予采用，因为这只能在内容已经按暂存文件继承的 DACL 写入之后修复最终描述符。 + +**每次写入都设置仅所有者可访问的 DACL。** 不予采用，因为这会破坏项目有意设置的共享权限。复制目标文件的 DACL 可以保留部署中已有的访问策略，无需另行创设策略。 + +## 影响 + +替换 Windows 文件现在要求调用方有权读取目标 DACL 并设置临时文件 DACL；如果权限不足，系统会在写入内容前明确失败。该包（package）引入 Koffi 以执行少量 Win32 调用，并且只在 Windows 替换路径上加载。新建文件仍按目录继承，POSIX mode 行为保持不变。 diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md index 7c3899e5cb..551492db67 100644 --- a/packages/fs/fs-local/README.md +++ b/packages/fs/fs-local/README.md @@ -16,7 +16,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() }) - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence. - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing. - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`. -- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows the mode bits drive only the read-only attribute, and write-in-progress privacy comes instead from the staging dir inheriting the destination directory's DACL ([Windows write-permission RFC](../../../docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`). +- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original descriptor survives ([Windows DACL preservation RFC](../../../docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`). - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`). The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring. diff --git a/packages/fs/fs-local/package.json b/packages/fs/fs-local/package.json index dd80cb4d9c..ded2a9d55f 100644 --- a/packages/fs/fs-local/package.json +++ b/packages/fs/fs-local/package.json @@ -26,6 +26,7 @@ "cordis": "^4.0.0-rc.7" }, "dependencies": { + "koffi": "^3.1.0", "schemastery": "^3.18.0" }, "devDependencies": { diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts index 05d957105a..549554043f 100644 --- a/packages/fs/fs-local/src/fsio.ts +++ b/packages/fs/fs-local/src/fsio.ts @@ -12,6 +12,7 @@ import type { BigIntStats, Dirent, Stats } from 'node:fs' import { basename, dirname, join, resolve } from 'node:path' import { TextDecoder } from 'node:util' import { FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs' +import { copyFileDaclWin32, replaceFileWin32 } from './win32.ts' const BINARY_SAMPLE_BYTES = 8192 @@ -74,10 +75,16 @@ function versionOf(info: BigIntStats): FsVersion { * file before it is renamed over the target. */ export interface FsIoInternals { + /** Override the host platform for native-publication unit coverage. */ + platform?: NodeJS.Platform /** Override the generated private staging-dir name (relative to the target dir). */ tempDirName?: (writePath: string) => string /** Override the generated temp-file name (relative to the private staging dir). */ tempName?: (writePath: string) => string + /** Override the Win32 DACL copy boundary. */ + copyFileDacl?: (source: string, destination: string) => Promise + /** Override the Win32 security-preserving replacement boundary. */ + replaceFile?: (replaced: string, replacement: string) => Promise /** Test hook after the temp file is written/synced but before final chmod+rename. */ inspectTemp?: (paths: { stagingDir: string; tempPath: string }) => void | Promise } @@ -412,11 +419,13 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow /** * Atomically replace a file through a private, synced staging file in the same directory. - * POSIX protects the staging directory and file with `0o700` and `0o600`; Windows - * inherits the destination directory's DACL because Node mode bits are synthetic there. + * POSIX protects the staging directory and file with `0o700` and `0o600`. A new Windows file + * inherits the destination directory's DACL; a replacement copies the existing target's DACL + * onto the empty temp before writing and preserves the target descriptor at publication. * @param absolutePath - destination; missing parent directories are created. * @param content - the full UTF-8 text to write. - * @param mode - final POSIX mode, or `0o600` when omitted; inert on Windows. + * @param mode - existing destination's POSIX mode to preserve, or `undefined` for a new file; + * inert as a mode on Windows but identifies replacement security semantics. * @param signal - cancellation checked before the final rename. * @param internals - test seam for pinning temp names and observing the staged file. */ @@ -436,6 +445,9 @@ export async function writeFileAtomic( const stagingDir = join(directory, stagingDirName) const tempName = internals.tempName?.(absolutePath) ?? `${basename(absolutePath)}.tmp` const tempPath = join(stagingDir, tempName) + const platform = internals.platform ?? process.platform + const copyFileDacl = internals.copyFileDacl ?? copyFileDaclWin32 + const replaceFile = internals.replaceFile ?? replaceFileWin32 let handle: Awaited> | undefined let stagingCreated = false try { @@ -445,6 +457,9 @@ export async function writeFileAtomic( handle = await open(tempPath, 'wx', 0o600) await handle.chmod(0o600) + if (platform === 'win32' && mode !== undefined) { + await copyFileDacl(absolutePath, tempPath) + } await handle.writeFile(content, { encoding: 'utf8', ...signal ? { signal } : {} }) await handle.sync() await internals.inspectTemp?.({ stagingDir, tempPath }) @@ -453,7 +468,18 @@ export async function writeFileAtomic( handle = undefined throwIfAborted(signal, 'write') - await rename(tempPath, absolutePath) + if (platform === 'win32' && mode !== undefined) { + try { + await replaceFile(absolutePath, tempPath) + } catch (error: unknown) { + // Preserve the old behavior when an external actor removes the observed target during + // staging: the temp already carries that target's protected DACL, so rename recreates it. + if (!isENOENT(error)) throw error + await rename(tempPath, absolutePath) + } + } else { + await rename(tempPath, absolutePath) + } await rm(stagingDir, { recursive: true, force: true }) } catch (error: unknown) { /* v8 ignore next -- abort-mid-write needs a writeFile/signal race; the non-abort (rename/open) side is tested. */ diff --git a/packages/fs/fs-local/src/win32.ts b/packages/fs/fs-local/src/win32.ts new file mode 100644 index 0000000000..6f459898a9 --- /dev/null +++ b/packages/fs/fs-local/src/win32.ts @@ -0,0 +1,134 @@ +/** + * Windows security-descriptor helpers for atomic local-file replacement. Koffi loads lazily so + * non-Windows processes never open Win32 libraries. + * @module @deepseek-ai/dsh-fs-local/win32 + */ + +import { toNamespacedPath } from 'node:path' + +type GetFileSecurityW = ( + path: string, + requestedInformation: number, + descriptor: Buffer | null, + length: number, + needed: [number], +) => number +type SetFileSecurityW = (path: string, securityInformation: number, descriptor: Buffer) => number +type ReplaceFileW = ( + replaced: string, + replacement: string, + backup: null, + flags: number, + exclude: null, + reserved: null, +) => number +type GetLastError = () => number + +interface Win32Bindings { + getFileSecurityW: GetFileSecurityW + setFileSecurityW: SetFileSecurityW + replaceFileW: ReplaceFileW + getLastError: GetLastError +} + +interface Win32ErrnoException extends NodeJS.ErrnoException { + win32Code: number +} + +const DACL_SECURITY_INFORMATION = 0x00000004 +const PROTECTED_DACL_SECURITY_INFORMATION = 0x80000000 +const ERROR_FILE_NOT_FOUND = 2 +const ERROR_PATH_NOT_FOUND = 3 +const ERROR_ACCESS_DENIED = 5 + +let bindings: Win32Bindings | undefined + +async function win32(): Promise { + if (bindings !== undefined) return bindings + const koffi = (await import('koffi')).default + const advapi32 = koffi.load('advapi32.dll') + const kernel32 = koffi.load('kernel32.dll') + bindings = { + getFileSecurityW: advapi32.func('int __stdcall GetFileSecurityW(const char16_t *path, uint32_t requested, void *descriptor, uint32_t length, _Out_ uint32_t *needed)') as GetFileSecurityW, + setFileSecurityW: advapi32.func('int __stdcall SetFileSecurityW(const char16_t *path, uint32_t information, const void *descriptor)') as SetFileSecurityW, + replaceFileW: kernel32.func('int __stdcall ReplaceFileW(const char16_t *replaced, const char16_t *replacement, const char16_t *backup, uint32_t flags, void *exclude, void *reserved)') as ReplaceFileW, + getLastError: kernel32.func('uint32_t __stdcall GetLastError()') as GetLastError, + } + return bindings +} + +function errnoCode(win32Code: number): string { + switch (win32Code) { + case ERROR_FILE_NOT_FOUND: + case ERROR_PATH_NOT_FOUND: + return 'ENOENT' + case ERROR_ACCESS_DENIED: + return 'EACCES' + default: + return 'EIO' + } +} + +function win32Error(syscall: string, win32Code: number, path: string): Win32ErrnoException { + const code = errnoCode(win32Code) + const error = new Error(`${syscall} ${code} (Win32 ${win32Code}): ${path}`) as Win32ErrnoException + error.code = code + error.errno = win32Code + error.syscall = syscall + error.path = path + error.win32Code = win32Code + return error +} + +/** + * Read a file's self-relative DACL security descriptor. + * @param path - existing file whose DACL is read. + * @returns a descriptor buffer accepted by `SetFileSecurityW`. + */ +export async function readFileDaclWin32(path: string): Promise { + const api = await win32() + const nativePath = toNamespacedPath(path) + const needed: [number] = [0] + api.getFileSecurityW(nativePath, DACL_SECURITY_INFORMATION, null, 0, needed) + if (needed[0] === 0) throw win32Error('GetFileSecurityW', api.getLastError(), path) + + const descriptor = Buffer.alloc(needed[0]) + if (api.getFileSecurityW(nativePath, DACL_SECURITY_INFORMATION, descriptor, descriptor.length, needed) === 0) { + throw win32Error('GetFileSecurityW', api.getLastError(), path) + } + return descriptor.subarray(0, needed[0]) +} + +/** + * Copy an existing file's DACL onto another file and protect it from staging-parent inheritance. + * The destination must still be empty when confidentiality depends on this call. + * @param source - existing file whose DACL is copied. + * @param destination - existing file that receives the protected DACL. + */ +export async function copyFileDaclWin32(source: string, destination: string): Promise { + const descriptor = await readFileDaclWin32(source) + const api = await win32() + const information = (DACL_SECURITY_INFORMATION | PROTECTED_DACL_SECURITY_INFORMATION) >>> 0 + if (api.setFileSecurityW(toNamespacedPath(destination), information, descriptor) === 0) { + throw win32Error('SetFileSecurityW', api.getLastError(), destination) + } +} + +/** + * Replace a Windows file while preserving the replaced file's ACL and other replace metadata. + * @param replaced - existing destination file. + * @param replacement - closed staging file on the same volume. + */ +export async function replaceFileWin32(replaced: string, replacement: string): Promise { + const api = await win32() + if (api.replaceFileW( + toNamespacedPath(replaced), + toNamespacedPath(replacement), + null, + 0, + null, + null, + ) === 0) { + throw win32Error('ReplaceFileW', api.getLastError(), replaced) + } +} diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts index 559ef86563..d292f0bfb7 100644 --- a/packages/fs/fs-local/tests/fsio.spec.ts +++ b/packages/fs/fs-local/tests/fsio.spec.ts @@ -6,7 +6,7 @@ */ import { afterEach, beforeEach, describe, expect, it } from 'vitest' -import { chmod, mkdtemp, readFile, rm, stat, symlink, unlink, writeFile, mkdir, readdir, realpath } from 'node:fs/promises' +import { chmod, mkdtemp, readFile, rename, rm, stat, symlink, unlink, writeFile, mkdir, readdir, realpath } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { createServer } from 'node:net' @@ -23,6 +23,7 @@ import { writeFileAtomic, } from '../src/fsio.ts' import type { LocalTarget } from '../src/fsio.ts' +import { copyFileDaclWin32, readFileDaclWin32 } from '../src/win32.ts' import { FsError, FsTargetKey } from '@deepseek-ai/dsh-fs' let dir: string @@ -367,15 +368,15 @@ describe('streamWholeText', () => { }) }) -// Windows drives only the read-only attribute through `chmod` and reports -// synthetic `stat` mode bits, so mode assertions are POSIX-only; on Windows -// write-in-progress privacy comes from the destination directory's inherited -// DACL (docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md). +// Windows drives only the read-only attribute through `chmod` and reports synthetic `stat` mode +// bits, so mode assertions are POSIX-only; native DACL preservation is asserted separately. const posixModes = process.platform !== 'win32' describe('writeFileAtomic — temp-file safety', () => { it('writes through a private staging dir and owner-only temp file', async () => { const file = join(dir, 'a.txt') + await writeFile(file, 'old') + if (posixModes) await chmod(file, 0o640) let inspected = false await writeFileAtomic(file, 'hello', 0o640, undefined, { inspectTemp: async ({ stagingDir, tempPath }) => { @@ -395,6 +396,84 @@ describe('writeFileAtomic — temp-file safety', () => { expect((await readdir(dir)).filter(n => n.includes('.tmp'))).toEqual([]) }) + it.skipIf(process.platform !== 'win32')('protects staged content with the existing target DACL and preserves it after replacement', async () => { + const file = join(dir, 'protected.txt') + await writeFile(file, 'old') + await copyFileDaclWin32(file, file) + const expectedDacl = await readFileDaclWin32(file) + + await writeFileAtomic(file, 'new', (await stat(file)).mode, undefined, { + inspectTemp: async ({ tempPath }) => { + expect(await readFileDaclWin32(tempPath)).toEqual(expectedDacl) + }, + }) + + expect(await readFile(file, 'utf8')).toBe('new') + expect(await readFileDaclWin32(file)).toEqual(expectedDacl) + }) + + it('copies a Windows target DACL before content and publishes through secure replacement', async () => { + const file = join(dir, 'a.txt') + await writeFile(file, 'old') + const calls: string[] = [] + + await writeFileAtomic(file, 'new', 0o666, undefined, { + platform: 'win32', + copyFileDacl: async (source, temp) => { + calls.push(`copy:${source}`) + expect(await readFile(temp, 'utf8')).toBe('') + }, + replaceFile: async (target, temp) => { + calls.push(`replace:${target}`) + await rename(temp, target) + }, + }) + + expect(calls).toEqual([`copy:${file}`, `replace:${file}`]) + expect(await readFile(file, 'utf8')).toBe('new') + }) + + it('creates a new Windows file through directory inheritance without replacement calls', async () => { + const file = join(dir, 'new.txt') + const unexpected = async (): Promise => { throw new Error('unexpected native replacement call') } + + await writeFileAtomic(file, 'new', undefined, undefined, { + platform: 'win32', + copyFileDacl: unexpected, + replaceFile: unexpected, + }) + + expect(await readFile(file, 'utf8')).toBe('new') + }) + + it('recreates a vanished Windows target with the already-protected temp', async () => { + const file = join(dir, 'a.txt') + await writeFile(file, 'old') + const missing = Object.assign(new Error('target vanished'), { code: 'ENOENT' }) + + await writeFileAtomic(file, 'new', 0o666, undefined, { + platform: 'win32', + copyFileDacl: () => Promise.resolve(), + replaceFile: async () => { throw missing }, + }) + + expect(await readFile(file, 'utf8')).toBe('new') + }) + + it('surfaces a Windows secure-replacement failure and cleans the staging directory', async () => { + const file = join(dir, 'a.txt') + await writeFile(file, 'old') + const denied = Object.assign(new Error('replace denied'), { code: 'EACCES' }) + + await expect(writeFileAtomic(file, 'new', 0o666, undefined, { + platform: 'win32', + copyFileDacl: () => Promise.resolve(), + replaceFile: async () => { throw denied }, + })).rejects.toBe(denied) + expect(await readFile(file, 'utf8')).toBe('old') + expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([]) + }) + it.skipIf(!posixModes)('creates new files owner-only by default', async () => { const file = join(dir, 'a.txt') await writeFileAtomic(file, 'hello', undefined, undefined) diff --git a/packages/fs/fs-local/tests/win32.spec.ts b/packages/fs/fs-local/tests/win32.spec.ts new file mode 100644 index 0000000000..dc2b69ea82 --- /dev/null +++ b/packages/fs/fs-local/tests/win32.spec.ts @@ -0,0 +1,145 @@ +/** Host-independent binding tests for the Win32 DACL and replacement helpers. */ + +import { afterEach, describe, expect, it, vi } from 'vitest' + +type GetFileSecurityW = ( + path: string, + requestedInformation: number, + descriptor: Buffer | null, + length: number, + needed: [number], +) => number +type SetFileSecurityW = (path: string, securityInformation: number, descriptor: Buffer) => number +type ReplaceFileW = ( + replaced: string, + replacement: string, + backup: null, + flags: number, + exclude: null, + reserved: null, +) => number + +interface NativeMock { + getFileSecurityW: GetFileSecurityW + setFileSecurityW: SetFileSecurityW + replaceFileW: ReplaceFileW + getLastError: () => number +} + +async function importWithNative(native: NativeMock): Promise { + vi.resetModules() + vi.doMock('koffi', () => ({ + default: { + load: () => ({ + func: (definition: string) => { + if (definition.includes('GetFileSecurityW')) return native.getFileSecurityW + if (definition.includes('SetFileSecurityW')) return native.setFileSecurityW + if (definition.includes('ReplaceFileW')) return native.replaceFileW + if (definition.includes('GetLastError')) return native.getLastError + throw new Error(`unexpected native function: ${definition}`) + }, + }), + }, + })) + return import('../src/win32.ts') +} + +function successfulNative(descriptor: Buffer): NativeMock & { installed: Buffer[]; replacements: string[][] } { + let lastError = 0 + const installed: Buffer[] = [] + const replacements: string[][] = [] + return { + installed, + replacements, + getLastError: () => lastError, + getFileSecurityW: (_path, _requested, output, _length, needed) => { + needed[0] = descriptor.length + if (output === null) { + lastError = 122 + return 0 + } + descriptor.copy(output) + lastError = 0 + return 1 + }, + setFileSecurityW: (_path, information, value) => { + expect(information).toBe(0x80000004) + installed.push(Buffer.from(value)) + lastError = 0 + return 1 + }, + replaceFileW: (replaced, replacement, backup, flags, exclude, reserved) => { + expect([backup, flags, exclude, reserved]).toEqual([null, 0, null, null]) + replacements.push([replaced, replacement]) + lastError = 0 + return 1 + }, + } +} + +afterEach(() => { + vi.doUnmock('koffi') + vi.resetModules() +}) + +describe('Windows file-security helpers', () => { + it('reads and installs a protected DACL before replacing the destination', async () => { + const descriptor = Buffer.from([1, 2, 3, 4]) + const native = successfulNative(descriptor) + const { copyFileDaclWin32, readFileDaclWin32, replaceFileWin32 } = await importWithNative(native) + + expect(await readFileDaclWin32('source')).toEqual(descriptor) + await copyFileDaclWin32('source', 'temp') + expect(native.installed).toEqual([descriptor]) + await replaceFileWin32('target', 'temp') + expect(native.replacements).toEqual([['target', 'temp']]) + }) + + it('maps descriptor-size probe failures to Node-style codes', async () => { + const cases = [[2, 'ENOENT'], [3, 'ENOENT'], [5, 'EACCES'], [9999, 'EIO']] as const + for (const [win32Code, code] of cases) { + const native = successfulNative(Buffer.from([1])) + native.getFileSecurityW = (_path, _requested, _output, _length, needed) => { + needed[0] = 0 + return 0 + } + native.getLastError = () => win32Code + const { readFileDaclWin32 } = await importWithNative(native) + await expect(readFileDaclWin32('source')).rejects.toMatchObject({ code, win32Code, path: 'source' }) + } + }) + + it('surfaces a descriptor read failure after the size probe', async () => { + const native = successfulNative(Buffer.from([1, 2])) + native.getFileSecurityW = (_path, _requested, _output, _length, needed) => { + needed[0] = 2 + return 0 + } + native.getLastError = () => 5 + const { readFileDaclWin32 } = await importWithNative(native) + + await expect(readFileDaclWin32('source')).rejects.toMatchObject({ code: 'EACCES', syscall: 'GetFileSecurityW' }) + }) + + it('surfaces DACL installation and replacement failures', async () => { + const setFailure = successfulNative(Buffer.from([1])) + setFailure.setFileSecurityW = () => 0 + setFailure.getLastError = () => 5 + const setModule = await importWithNative(setFailure) + await expect(setModule.copyFileDaclWin32('source', 'temp')).rejects.toMatchObject({ + code: 'EACCES', + syscall: 'SetFileSecurityW', + path: 'temp', + }) + + const replaceFailure = successfulNative(Buffer.from([1])) + replaceFailure.replaceFileW = () => 0 + replaceFailure.getLastError = () => 2 + const replaceModule = await importWithNative(replaceFailure) + await expect(replaceModule.replaceFileWin32('target', 'temp')).rejects.toMatchObject({ + code: 'ENOENT', + syscall: 'ReplaceFileW', + path: 'target', + }) + }) +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5c591034cc..0ed8c8449c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -819,6 +819,9 @@ importers: packages/fs/fs-local: dependencies: + koffi: + specifier: ^3.1.0 + version: 3.1.1 schemastery: specifier: ^3.18.0 version: 3.18.0 From f110c5e08377f4074a0ec5927226f72c821a742b Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 12:41:46 +0800 Subject: [PATCH 24/53] fix(acp-snapshot): accept Windows termination exit races Treat a fallback kill refusal as successful termination when the child already carries an OS exit marker. Windows maps Node's supported signal names to forced termination, so the requested signal can end the process between the launcher error race and its fallback SIGKILL. Drain inherited stdio, the ACP parser, and in-flight callbacks before propagating the original child error in either exit-race path. Preserve AggregateError reporting only for a refused fallback while the process is still live, and add a deterministic cross-platform regression for that ordering. --- packages/support/acp-snapshot/src/launcher.ts | 17 ++++++++++--- .../acp-snapshot/tests/harness.spec.ts | 24 +++++++++++++++++++ 2 files changed, 38 insertions(+), 3 deletions(-) diff --git a/packages/support/acp-snapshot/src/launcher.ts b/packages/support/acp-snapshot/src/launcher.ts index de5082eca4..e39c6552f0 100644 --- a/packages/support/acp-snapshot/src/launcher.ts +++ b/packages/support/acp-snapshot/src/launcher.ts @@ -231,6 +231,15 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe return } + const propagateFailureAfterDrain = async (): Promise => { + await drained + closeUpdateStream() + throw failure + } + // Windows implements the supported signal names as forced termination. The exit markers + // may therefore arrive after the error wins the race above but before fallback begins. + if (!isRunning(child)) return propagateFailureAfterDrain() + // An `error` after spawn is not an exit edge: in particular, a failed // signal can leave the subprocess live. Force termination, await the // already-observed exit edge, and only then propagate the child error so @@ -240,6 +249,10 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe child.once('error', observeFallbackError) if (!child.kill('SIGKILL')) { child.off('error', observeFallbackError) + // A successful earlier signal may win between the live check and this fallback call. + // In that case `kill()` correctly reports no process to signal; the original child error + // remains the shutdown result once inherited stdio and callbacks have drained. + if (!isRunning(child)) return propagateFailureAfterDrain() closeUpdateStream() throw new AggregateError( [failure, new Error('Fallback SIGKILL was not accepted by the child process')], @@ -258,9 +271,7 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe 'ACP test agent failed and fallback termination was refused', ) } - await drained - closeUpdateStream() - throw failure + return propagateFailureAfterDrain() }, } } diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index 5589858fe9..2c4478e158 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -176,6 +176,30 @@ describe('runScenario', () => { } }) + it('preserves the child error when fallback refusal races with an exit marker', async () => { + const { dir } = await scenario({}) + const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir }) + await launched.spawned + + const childFailure = Object.assign(new Error('signal failed while the child exited'), { code: 'EPERM' }) + const originalKill = launched.child.kill.bind(launched.child) + const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => { + if (signal === 'SIGTERM') return true + originalKill('SIGKILL') + Object.defineProperty(launched.child, 'signalCode', { configurable: true, enumerable: true, writable: true, value: 'SIGKILL' }) + return false + }) + try { + launched.child.emit('error', childFailure) + await expect(launched.close('SIGTERM')).rejects.toBe(childFailure) + expect(kill).toHaveBeenNthCalledWith(1, 'SIGTERM') + expect(kill).toHaveBeenNthCalledWith(2, 'SIGKILL') + } finally { + kill.mockRestore() + if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL') + } + }) + it('rejects promptly when fallback termination emits an error', async () => { const { dir } = await scenario({}) const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir }) From 0f4bc645dab2f4f03c45e59e0feaf36f64767a7c Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 12:42:59 +0800 Subject: [PATCH 25/53] test(acp-snapshot): inherit descendant stdio portably Pass the fake descendant the parent process's stdout and stderr stream handles instead of Unix-style numeric file descriptors. This lets Windows duplicate the live ACP and diagnostic pipes so launcher shutdown can prove that inherited handles, buffered frames, and stderr all drain after the parent exits. Observe the pending update promise before initiating shutdown as well, preventing a missing late frame from becoming a transient unhandled rejection before the assertion reports the fixture failure. --- .../support/acp-snapshot/tests/fixtures/fake-acp-agent.ts | 4 +++- packages/support/acp-snapshot/tests/harness.spec.ts | 3 +++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts index 5dd5524ed0..647ffbb5d9 100644 --- a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts +++ b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts @@ -266,7 +266,9 @@ function flushLogsAndExit(): void { `setTimeout(() => process.stdout.write(${JSON.stringify(`${frame}\n`)}), 50)`, `setTimeout(() => process.stderr.write(${JSON.stringify('late inherited stderr\n')}), 75)`, ].join(';') - spawn(process.execPath, ['-e', code], { stdio: ['ignore', 1, 2] }).unref() + spawn(process.execPath, ['-e', code], { + stdio: ['ignore', process.stdout, process.stderr], + }).unref() } process.exit(0) } diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index 2c4478e158..08b069338c 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -139,6 +139,9 @@ describe('runScenario', () => { update.sessionUpdate === 'agent_message_chunk' && update.content.type === 'text' && update.content.text === 'late inherited stdout') + // Arm rejection handling before close may exhaust the stream; the later assertion still + // observes the original promise and turns a missing inherited frame into the test failure. + void lateUpdate.catch(() => undefined) await launched.close() From 3dc82b1e870e2f1bd732093909d23ead9e605d14 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 12:43:58 +0800 Subject: [PATCH 26/53] test(snapshot): refresh Windows workspace permission prose Update the workspace-edit Windows sidecar to the current permission preset description emitted by the ACP session configuration. The shared golden already carried this contract; only the native-Windows transcript retained the superseded wording. Leave the platform-specific backslash path rendering unchanged so the sidecar continues to pin the one intentional Windows transcript difference. --- .../tests/snapshots/workspace-edit/stdout.golden.windows.jsonl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl index 5f8762adcd..7438c3f43f 100644 --- a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl +++ b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl @@ -1,5 +1,5 @@ {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} -{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"Sets this session's sandbox and approval behavior.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}} +{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} From 4bf2ef89c4d6c5164140e5e522612b19444a8008 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 12:44:47 +0800 Subject: [PATCH 27/53] fix(jsonl): bind MoveFileExW with the Win32 BOOL ABI Declare MoveFileExW's return value as Koffi int and model it as a numeric 32-bit Win32 BOOL. The previous Koffi bool declaration represented a one-byte C boolean and could read the native return register with the wrong ABI. Test zero and nonzero results explicitly and assert the binding result type while preserving the existing write-through flags, error translation, and durable directory race behavior. --- .../session-persistence-jsonl/src/win32.ts | 6 ++--- .../tests/win32.spec.ts | 23 ++++++++++--------- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/packages/session-persistence/session-persistence-jsonl/src/win32.ts b/packages/session-persistence/session-persistence-jsonl/src/win32.ts index 143f230ea3..a8c1b6fb8d 100644 --- a/packages/session-persistence/session-persistence-jsonl/src/win32.ts +++ b/packages/session-persistence/session-persistence-jsonl/src/win32.ts @@ -14,7 +14,7 @@ import { mkdtemp, rm, stat } from 'node:fs/promises' import { basename, join, parse, resolve, toNamespacedPath } from 'node:path' -type MoveFileExW = (existing: string, replacement: string, flags: number) => boolean +type MoveFileExW = (existing: string, replacement: string, flags: number) => number type GetLastError = () => number interface Win32Bindings { @@ -44,7 +44,7 @@ async function win32(): Promise { const koffi = (await import('koffi')).default const kernel32 = koffi.load('kernel32.dll') bindings = { - moveFileExW: kernel32.func('__stdcall', 'MoveFileExW', 'bool', ['str16', 'str16', 'uint']) as MoveFileExW, + moveFileExW: kernel32.func('__stdcall', 'MoveFileExW', 'int', ['str16', 'str16', 'uint']) as MoveFileExW, getLastError: kernel32.func('__stdcall', 'GetLastError', 'uint', []) as GetLastError, } return bindings @@ -113,7 +113,7 @@ async function assertDirectory(path: string): Promise { export async function publishNewFileWin32(existing: string, replacement: string): Promise { const api = await win32() const ok = api.moveFileExW(toNamespacedPath(existing), toNamespacedPath(replacement), MOVEFILE_WRITE_THROUGH) - if (!ok) throw win32Error('MoveFileExW', api.getLastError(), existing, replacement) + if (ok === 0) throw win32Error('MoveFileExW', api.getLastError(), existing, replacement) } /** diff --git a/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts index 760eb3d455..b4a2d11f28 100644 --- a/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts +++ b/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts @@ -19,7 +19,7 @@ const ERROR_FILE_EXISTS = 80 const ERROR_INVALID_NAME = 123 const ERROR_ALREADY_EXISTS = 183 -type MoveFileExW = (existing: string, replacement: string, flags: number, setLastError: (code: number) => void) => boolean +type MoveFileExW = (existing: string, replacement: string, flags: number, setLastError: (code: number) => void) => number const roots: string[] = [] @@ -42,14 +42,15 @@ async function importWithMove(moveFileExW: MoveFileExW): Promise { lastError = code } const move: MoveFileExW = (existing, replacement, flags, setError) => { const ok = moveFileExW(existing, replacement, flags, setError) - lastError = ok ? 0 : lastError + lastError = ok === 0 ? lastError : 0 return ok } return { default: { load: () => ({ - func: (_convention: string, name: string) => { + func: (_convention: string, name: string, result: string) => { if (name === 'MoveFileExW') return (existing: string, replacement: string, flags: number) => { + expect(result).toBe('int') const ok = move(existing, replacement, flags, setLastError) return ok } @@ -68,7 +69,7 @@ async function importWithError(code: number): Promise ({ func: (_convention: string, name: string) => { - if (name === 'MoveFileExW') return () => false + if (name === 'MoveFileExW') return () => 0 return () => code }, }), @@ -82,10 +83,10 @@ async function importWithFilesystemMove(): Promise { if (to === raced) { mkdirSync(to) setLastError(ERROR_ALREADY_EXISTS) - return false + return 0 } - if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return false } - if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return false } + if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return 0 } + if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return 0 } renameSync(from, to) - return true + return 1 }) await ensureDurableDirectoryWin32(join(root, 'a', 'b')) From c660048759fa0e20bc4f7cd953652176cd8f5950 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 12:52:42 +0800 Subject: [PATCH 28/53] test(subagent): cover late forced-wait exit markers Exercise both exitCode and signalCode arriving after the SIGTERM grace begins but before the bounded SIGKILL confirmation helper starts. This pins the fast path that avoids signaling an already-terminated child and restores the package's per-file 100% branch and statement coverage. Keep the marker transition deterministic by withholding the synthetic exit event, matching the OS state race the defensive pre-check exists to absorb. --- .../tests/subagent-subprocess.spec.ts | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts index e81957baa0..d674937e92 100644 --- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts +++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts @@ -222,6 +222,21 @@ describe('disposeChildProcess', () => { expect(fake.signalCode).toBe('SIGKILL') }) + it.each(['exitCode', 'signalCode'] as const)('accepts a late OS %s marker before the final forced wait', async (marker) => { + const fake = new FakeChild() + vi.spyOn(fake, 'kill').mockImplementation((signal) => { + fake.kills.push(signal) + queueMicrotask(() => { + if (marker === 'exitCode') fake.exitCode = 0 + else fake.signalCode = 'SIGTERM' + }) + return true + }) + + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 1, disposeGraceMs: 10 }, 'linux') + expect(fake.kills).toEqual(['SIGTERM']) + }) + it('walks the ladder for a child spawned without a stdin pipe', async () => { const fake = new FakeChild({ stdin: false, diesOn: 'SIGTERM', delayMs: 5 }) await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux') From e9aac53fdec49c951db97f8a1c2e677c35818d98 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 12:53:41 +0800 Subject: [PATCH 29/53] test(acp-snapshot): cover pre-fallback Windows exit state Model the requested signal setting a child termination marker before the launcher begins fallback handling. The regression proves close drains inherited stdio and propagates the original process error without sending a redundant SIGKILL. This complements the post-check fallback-refusal race and restores the launcher's required 100% per-file statement and branch coverage. --- .../acp-snapshot/tests/harness.spec.ts | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index 08b069338c..61b40010df 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -179,6 +179,29 @@ describe('runScenario', () => { } }) + it('preserves the child error when the requested signal sets an exit marker', async () => { + const { dir } = await scenario({}) + const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir }) + await launched.spawned + + const childFailure = Object.assign(new Error('signal failed as the child exited'), { code: 'EPERM' }) + const originalKill = launched.child.kill.bind(launched.child) + const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => { + expect(signal).toBe('SIGTERM') + originalKill('SIGKILL') + Object.defineProperty(launched.child, 'signalCode', { configurable: true, enumerable: true, writable: true, value: 'SIGTERM' }) + return true + }) + try { + launched.child.emit('error', childFailure) + await expect(launched.close('SIGTERM')).rejects.toBe(childFailure) + expect(kill).toHaveBeenCalledOnce() + } finally { + kill.mockRestore() + if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL') + } + }) + it('preserves the child error when fallback refusal races with an exit marker', async () => { const { dir } = await scenario({}) const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir }) From 0f8d0082e4b916f2afed3fec850853a9d26dfb77 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 13:20:59 +0800 Subject: [PATCH 30/53] fix(tui): stabilize Windows terminal snapshots Treat an absolute path.relative() result as a cross-volume path instead of incorrectly abbreviating it beneath the user's home directory. Allow embeddings to project a logical footer cwd without changing the operational session cwd. The recorded-session harness now uses a POSIX-shaped display alias for both the footer and filesystem result paths, preserving the existing pre-normalization layout width on every host. Keep runtime-provided labels behind terminal-control escaping, cover that boundary, and document the embedding contract. --- examples/tui-agent/tests/tui.snapshot.ts | 35 ++++++++++++++++++++---- packages/ui/tui/README.md | 2 ++ packages/ui/tui/src/index.ts | 27 ++++++++++++++---- packages/ui/tui/tests/harness.ts | 9 ++++-- packages/ui/tui/tests/tui.spec.ts | 7 +++++ 5 files changed, 68 insertions(+), 12 deletions(-) diff --git a/examples/tui-agent/tests/tui.snapshot.ts b/examples/tui-agent/tests/tui.snapshot.ts index c0537021e8..5c443ee474 100644 --- a/examples/tui-agent/tests/tui.snapshot.ts +++ b/examples/tui-agent/tests/tui.snapshot.ts @@ -1,6 +1,6 @@ import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' -import { basename, dirname, join } from 'node:path' +import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path' import { fileURLToPath } from 'node:url' import { afterAll, describe, expect, it } from 'vitest' import { Context } from 'cordis' @@ -106,6 +106,13 @@ function snapshotModeFromEnv(value: string | undefined): SnapshotMode { const MODE = snapshotModeFromEnv(process.env.DSH_SNAPSHOT) const observedScenarios = new Set() +function snapshotDisplayPath(displayPath: string, cwd: string, displayCwd: string): string { + const rel = relative(cwd, displayPath) + if (rel === '') return displayCwd + if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`)) return displayPath + return `${displayCwd}/${rel.split(sep).join('/')}` +} + function scenarioDir(scenario: Scenario): string { return join(SNAPSHOTS_DIR, scenario.name) } @@ -136,9 +143,10 @@ function rawSessionLog(session: Session): string { ].join('\n') } -function normalizeTerminalSnapshot(snapshot: string, cwd: string): string { +function normalizeTerminalSnapshot(snapshot: string, cwd: string, displayCwd: string): string { return snapshot .split(`/private${cwd}`).join('/workspace/project') + .split(displayCwd).join('/workspace/project') .split(cwd).join('/workspace/project') .replace(UUID_RE, '{{uuid}}') } @@ -157,9 +165,20 @@ async function settleTerminal(terminal: HeadlessTerminal): Promise { async function mountScenarioContext( scenario: Scenario, cwd: string, + displayCwd: string, fixtureFile: string, childFiles: string[], ): Promise { + class SnapshotLocalFileSystem extends LocalFileSystem { + override async resolve( + path: string, + opts?: { cwd?: string; signal?: AbortSignal }, + ): Promise>> { + const target = await super.resolve(path, opts) + return { ...target, displayPath: snapshotDisplayPath(target.displayPath, cwd, displayCwd) } + } + } + const ctx = new Context() await ctx.plugin(AgentCore, { agents: [], @@ -169,7 +188,7 @@ async function mountScenarioContext( skills: { local: { agentsHome: join(cwd, '.agents') } }, }) await ctx.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 }) - await ctx.plugin(LocalFileSystem, { cwd: '/' }) + await ctx.plugin(SnapshotLocalFileSystem, { cwd: '/' }) await ctx.plugin(FsPolicy) await ctx.plugin(ToolFs) await ctx.plugin(UserInteractionService) @@ -207,6 +226,7 @@ async function runScenario(scenario: Scenario): Promise { expect(prompts.length, `${scenario.name} must carry at least one recorded user prompt`).toBeGreaterThan(0) const cwd = await mkdtemp(join(SNAPSHOT_TMP_ROOT, `dsh-tui-snapshot-${scenario.name}-`)) + const displayCwd = `/tmp/${basename(cwd)}` let ctx: Context | undefined let controller: ReturnType | undefined const terminal = new HeadlessTerminal(100, 36) @@ -215,7 +235,7 @@ async function runScenario(scenario: Scenario): Promise { const source = join(scenarioDir(scenario), 'workspace') await cp(source, cwd, { recursive: true }) } - ctx = await mountScenarioContext(scenario, cwd, fixtureFile, childFiles) + ctx = await mountScenarioContext(scenario, cwd, displayCwd, fixtureFile, childFiles) const disposedSessions: Session[] = [] ctx.on('session/disposed', (session) => { disposedSessions.push(session) }) const workflowEvents: string[] = [] @@ -235,7 +255,11 @@ async function runScenario(scenario: Scenario): Promise { title: 'DSH TUI snapshot', welcome: `Recorded replay: ${scenario.name}`, maxToolOutputLines: 8, - }, { terminal, exit: () => {} }) + }, { + terminal, + exit: () => {}, + formatCwd: () => displayCwd, + }) await settleTerminal(terminal) for (const prompt of prompts) { @@ -266,6 +290,7 @@ async function runScenario(scenario: Scenario): Promise { const snapshot = normalizeTerminalSnapshot( await terminal.snapshot({ includeScrollback: true }), cwd, + displayCwd, ) await handle.dispose() const children = disposedSessions diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md index e426640ae5..34987c5d55 100644 --- a/packages/ui/tui/README.md +++ b/packages/ui/tui/README.md @@ -8,6 +8,8 @@ This package owns interactive terminal presentation and input only. It injects ` The TUI rebuilds resumed history from the active session surface, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the latest `todo/write` plan above the editor, and presents `ctx.userInteraction` questions as keyboard-driven overlays. Surface replacement events rebuild the transcript so compacted history does not reappear. +An embedding may provide `TuiRuntime.formatCwd` when its logical workspace label differs from the session's host directory. The override changes only the footer label; tools continue to use the session `cwd`. + Before model output, session events, tool presenters, questions, configuration, or diagnostics reach pi-tui's ANSI-aware renderers or the terminal title, the TUI renders C0 and C1 controls other than line feeds as visible `\xNN` text. Those sources cannot add terminal control sequences; the TUI and pi-tui retain ownership of terminal rendering and styling. While the agent is running, editor submissions call `agent.steer()`; otherwise they call `agent.send()`. Ctrl+C or Escape cancels a running turn. Ctrl+O expands tool cards, Ctrl+R toggles reasoning, Ctrl+L redraws, and Ctrl+D exits while idle. `/help`, `/clear`, `/cancel`, `/reasoning`, `/tools`, `/redraw`, and `/exit` provide the same actions without key chords. diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index 0906b7bc9f..210ff10071 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -6,7 +6,7 @@ */ import { homedir } from 'node:os' -import { relative, resolve, sep } from 'node:path' +import { isAbsolute, relative, resolve, sep } from 'node:path' import { CombinedAutocompleteProvider, Container, @@ -135,6 +135,12 @@ export interface TuiRuntime { terminal: Terminal /** Exit hook used by terminal shutdown or a target-agent startup failure. */ exit(code: number): void + /** + * Override the footer's logical working-directory label without changing the session directory used by tools. + * @param cwd - Operational working directory from the session header. + * @returns Unescaped label; the TUI makes terminal controls visible. + */ + formatCwd?: (cwd: string | undefined) => string } /** @@ -608,8 +614,10 @@ function formatCwd(cwd: string | undefined): string { const home = homedir() const rel = relative(resolve(home), resolve(cwd)) if (rel === '') return '~' - if (rel !== '..' && !rel.startsWith(`..${sep}`)) return displayText(`~${sep}${rel}`) - return displayText(cwd) + /* v8 ignore next -- Windows cross-drive coverage; POSIX relative() cannot return an absolute path. */ + if (isAbsolute(rel)) return cwd + if (rel !== '..' && !rel.startsWith(`..${sep}`)) return `~${sep}${rel}` + return cwd } function sessionTokens(session: Session): { input: number; output: number } { @@ -630,13 +638,15 @@ class FooterComponent implements Component { private readonly toolsExpanded: () => boolean, private readonly showReasoning: () => boolean, private readonly tokens: () => { input: number; output: number }, + private readonly cwdFormatter: TuiRuntime['formatCwd'], ) {} invalidate(): void {} render(width: number): string[] { const { input, output } = this.tokens() - const left = `${formatCwd(this.agent.session.header.cwd)} ↑${formatTokens(input)} ↓${formatTokens(output)}` + const cwd = this.cwdFormatter?.(this.agent.session.header.cwd) ?? formatCwd(this.agent.session.header.cwd) + const left = `${displayText(cwd)} ↑${formatTokens(input)} ↓${formatTokens(output)}` const right = `${this.agent.status} reasoning:${this.showReasoning() ? 'on' : 'off'} tools:${this.toolsExpanded() ? 'expanded' : 'compact'}` const leftStyled = this.palette.dim(left) const available = Math.max(0, width - visibleWidth(left) - 2) @@ -843,7 +853,14 @@ export function createTuiChat( const welcome = config.welcome ?? 'ready.' const header = new HeaderComponent(agent, welcome, palette) - const footer = new FooterComponent(agent, palette, () => toolsExpanded, () => showReasoning, () => tokens) + const footer = new FooterComponent( + agent, + palette, + () => toolsExpanded, + () => showReasoning, + () => tokens, + runtime.formatCwd, + ) ui.addChild(header) ui.addChild(chat) ui.addChild(statusContainer) diff --git a/packages/ui/tui/tests/harness.ts b/packages/ui/tui/tests/harness.ts index 9994833308..7cef8ed185 100644 --- a/packages/ui/tui/tests/harness.ts +++ b/packages/ui/tui/tests/harness.ts @@ -5,7 +5,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm' import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session' import type { ToolDefinition } from '@deepseek-ai/dsh-tools' import UserInteractionService from '@deepseek-ai/dsh-user-interaction' -import { createTuiChat, type Config } from '../src/index.ts' +import { createTuiChat, type Config, type TuiRuntime } from '../src/index.ts' interface FakeAgent extends Agent { status: AgentStatus @@ -21,6 +21,7 @@ export interface TuiHarnessOptions { configureContext?: (ctx: Context) => Promise beforeMount?: (session: Session) => void cwd?: string | null + formatCwd?: TuiRuntime['formatCwd'] } export interface TuiHarness void> { @@ -95,7 +96,11 @@ export async function createTuiTestHarness { const outsideResult = await setup({ cwd: '/opt' }) expect(outsideResult.terminal.output).toContain('/opt') await dispose(outsideResult) + + const logicalResult = await setup({ + cwd: '/host/worktree', + formatCwd: cwd => `logical:${cwd}\x1b`, + }) + expect(logicalResult.terminal.output).toContain('logical:/host/worktree\\x1b') + await dispose(logicalResult) }) it('sends, steers, handles commands, global keys, and disposed-agent input', async () => { From a6b8ce456a94de5d19d29228fe4ed19903481280 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 13:25:15 +0800 Subject: [PATCH 31/53] test(fs): compare Windows DACL access policy ReplaceFileW preserves ACLs by merging security information, which may reserialize auto-inheritance state and duplicate equivalent ACEs. Compare the final ordered, de-duplicated ACE policy instead of requiring byte-identical self-relative descriptor buffers. Update the host-independent binding assertion to expect the namespaced absolute paths that the Win32 boundary actually receives, and align the package and bilingual RFC contracts with the semantic DACL guarantee. --- ...-windows-atomic-write-dacl-preservation.md | 4 ++-- ...ndows-atomic-write-dacl-preservation.zh.md | 4 ++-- packages/fs/fs-local/README.md | 2 +- packages/fs/fs-local/tests/fsio.spec.ts | 24 ++++++++++++++++++- packages/fs/fs-local/tests/win32.spec.ts | 3 ++- 5 files changed, 30 insertions(+), 7 deletions(-) diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md index 393ce8a992..13ec1546ce 100644 --- a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md +++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md @@ -10,9 +10,9 @@ On Windows, creating the staging directory and temp file under the target's pare ## Decision -`dsh-fs-local` reads an existing target's DACL with `GetFileSecurityW`, applies it to the empty temp file with inheritance protected before writing content, and publishes the closed temp with `ReplaceFileW`. The protected staging descriptor prevents the temp directory's inherited entries from broadening access; `ReplaceFileW` preserves the original target security descriptor and other replacement metadata. New files have no prior descriptor to preserve and continue to inherit the destination directory's DACL. +`dsh-fs-local` reads an existing target's DACL with `GetFileSecurityW`, applies it to the empty temp file with inheritance protected before writing content, and publishes the closed temp with `ReplaceFileW`. The protected staging descriptor prevents the temp directory's inherited entries from broadening access; `ReplaceFileW` preserves the original target access policy and other replacement metadata. Its ACL merge may reserialize auto-inheritance state or duplicate equivalent ACEs, so self-relative descriptor buffers are not a stable equality contract. New files have no prior descriptor to preserve and continue to inherit the destination directory's DACL. -Native Windows coverage protects a target DACL, inspects the written staging file, and compares the final replacement descriptor. Host-independent binding tests cover Win32 error translation and every native call boundary. +Native Windows coverage protects a target DACL, inspects the written staging file, and compares the final replacement's ordered, de-duplicated ACE policy. Host-independent binding tests cover Win32 error translation and every native call boundary. ## Alternatives considered diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md index c7a0b6278c..ca72ec2213 100644 --- a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md +++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md @@ -10,9 +10,9 @@ Status: implemented ## 决策 -`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的安全描述符及其他替换元数据。新建文件没有既有描述符需要保留，因此仍继承目标目录的 DACL。 +`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的访问策略及其他替换元数据。其 ACL 合并过程可能重新序列化自动继承状态或复制等价 ACE，因此不能把自相对安全描述符缓冲区的逐字节相等作为稳定契约。新建文件没有既有描述符需要保留，因此仍继承目标目录的 DACL。 -Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件的描述符。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。 +Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件中保持顺序且去重后的 ACE 策略。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。 ## 备选方案 diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md index 551492db67..e8f57e5084 100644 --- a/packages/fs/fs-local/README.md +++ b/packages/fs/fs-local/README.md @@ -16,7 +16,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() }) - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence. - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing. - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`. -- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original descriptor survives ([Windows DACL preservation RFC](../../../docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`). +- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation RFC](../../../docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`). - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`). The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring. diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts index d292f0bfb7..15588e40b9 100644 --- a/packages/fs/fs-local/tests/fsio.spec.ts +++ b/packages/fs/fs-local/tests/fsio.spec.ts @@ -372,6 +372,28 @@ describe('streamWholeText', () => { // bits, so mode assertions are POSIX-only; native DACL preservation is asserted separately. const posixModes = process.platform !== 'win32' +function daclAcePolicy(descriptor: Buffer): string[] { + const daclOffset = descriptor.readUInt32LE(16) + if (daclOffset === 0) return [] + const aceCount = descriptor.readUInt16LE(daclOffset + 4) + const policy: string[] = [] + const seen = new Set() + let offset = daclOffset + 8 + for (let index = 0; index < aceCount; index++) { + const size = descriptor.readUInt16LE(offset + 2) + const ace = Buffer.from(descriptor.subarray(offset, offset + size)) + // INHERITED_ACE records provenance, not the entry's access policy. + ace.writeUInt8(ace.readUInt8(1) & ~0x10, 1) + const key = ace.toString('hex') + if (!seen.has(key)) { + seen.add(key) + policy.push(key) + } + offset += size + } + return policy +} + describe('writeFileAtomic — temp-file safety', () => { it('writes through a private staging dir and owner-only temp file', async () => { const file = join(dir, 'a.txt') @@ -409,7 +431,7 @@ describe('writeFileAtomic — temp-file safety', () => { }) expect(await readFile(file, 'utf8')).toBe('new') - expect(await readFileDaclWin32(file)).toEqual(expectedDacl) + expect(daclAcePolicy(await readFileDaclWin32(file))).toEqual(daclAcePolicy(expectedDacl)) }) it('copies a Windows target DACL before content and publishes through secure replacement', async () => { diff --git a/packages/fs/fs-local/tests/win32.spec.ts b/packages/fs/fs-local/tests/win32.spec.ts index dc2b69ea82..4a8687d9e8 100644 --- a/packages/fs/fs-local/tests/win32.spec.ts +++ b/packages/fs/fs-local/tests/win32.spec.ts @@ -1,5 +1,6 @@ /** Host-independent binding tests for the Win32 DACL and replacement helpers. */ +import { toNamespacedPath } from 'node:path' import { afterEach, describe, expect, it, vi } from 'vitest' type GetFileSecurityW = ( @@ -92,7 +93,7 @@ describe('Windows file-security helpers', () => { await copyFileDaclWin32('source', 'temp') expect(native.installed).toEqual([descriptor]) await replaceFileWin32('target', 'temp') - expect(native.replacements).toEqual([['target', 'temp']]) + expect(native.replacements).toEqual([[toNamespacedPath('target'), toNamespacedPath('temp')]]) }) it('maps descriptor-size probe failures to Node-style codes', async () => { From 5d6b589922b0fde638d8ae855f2db4356f601d3a Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 13:28:19 +0800 Subject: [PATCH 32/53] fix(acp-snapshot): await delayed Windows exit markers A successful Windows termination request can end the process before Node publishes exitCode or signalCode. If a child error wins the shutdown race, give that accepted exit a bounded observation window before escalating or reporting fallback refusal. Cover a delayed real exit edge, preserve prompt refusal behavior for a genuinely live child, and document the launcher grace without weakening the complete stdio and parser drain boundary. --- packages/support/acp-snapshot/README.md | 2 +- packages/support/acp-snapshot/src/launcher.ts | 17 ++++++++++++-- .../acp-snapshot/tests/harness.spec.ts | 22 +++++++++++++++++++ 3 files changed, 38 insertions(+), 3 deletions(-) diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md index 43a315e230..53289fda35 100644 --- a/packages/support/acp-snapshot/README.md +++ b/packages/support/acp-snapshot/README.md @@ -4,7 +4,7 @@ The ACP snapshot suite kit: the shared machinery behind the keyless snapshot tie Four layers, importable separately: -- **`launchAcpTestAgent` (launcher)** — boots a source agent under tsx or a built `lib` agent under plain Node from a temp cwd, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, surfaces asynchronous spawn failures through startup, fails closed on unhandled permission requests, and owns graceful or signalled shutdown. Shutdown waits for process exit, inherited stdio closure, and ACP parser exhaustion before resolving or propagating a child error, so captures are complete and callers can remove owned paths after either outcome. Snapshot and ordinary e2e suites share this process boundary; a test supplies only agent paths, cwd, environment overrides, and any permission policy. +- **`launchAcpTestAgent` (launcher)** — boots a source agent under tsx or a built `lib` agent under plain Node from a temp cwd, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, surfaces asynchronous spawn failures through startup, fails closed on unhandled permission requests, and owns graceful or signalled shutdown. Shutdown waits for process exit, inherited stdio closure, and ACP parser exhaustion before resolving or propagating a child error, so captures are complete and callers can remove owned paths after either outcome. When Windows accepts forced termination but publishes its exit marker asynchronously, shutdown gives that marker a bounded grace before treating fallback refusal as a second failure. Snapshot and ordinary e2e suites share this process boundary; a test supplies only agent paths, cwd, environment overrides, and any permission policy. - **`runScenario` (harness)** — drives ACP JSON-RPC stdio from a deterministic `input.json` script through the launcher, tees raw stdout for the golden and purity check, and harvests every persisted session JSONL (parent and subagent children, primary-first) after graceful stdin EOF. `AgentUnderTest` supplies absolute `binScript`, optional `libBinScript`, `configPath`, and `tsconfigPath` paths because the subprocess cwd is outside the repo. Startup failures preserve captured agent stderr in the rejected diagnostic. - **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; cwd-rooted separators selected as canonical `/` or host-native; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)). - **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario shared golden and re-persisted-log compares, optional Windows-native stdout sidecars, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, the per-header-class pin (`system-prompt.golden.md` plus `tool-schemas.golden.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Each scenario directory's `session.jsonl` plus contiguous `session..jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time. diff --git a/packages/support/acp-snapshot/src/launcher.ts b/packages/support/acp-snapshot/src/launcher.ts index e39c6552f0..441ab463d7 100644 --- a/packages/support/acp-snapshot/src/launcher.ts +++ b/packages/support/acp-snapshot/src/launcher.ts @@ -21,6 +21,8 @@ import { } from '@agentclientprotocol/sdk' import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' +const EXIT_MARKER_GRACE_MS = 250 + /** The source/built agent entry, leaf config, and workspace tsconfig an ACP test boots. */ export interface AgentUnderTest { /** The agent source bin entry (for example `packages/examples/acp-demo/src/bin.ts`). */ @@ -238,7 +240,7 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe } // Windows implements the supported signal names as forced termination. The exit markers // may therefore arrive after the error wins the race above but before fallback begins. - if (!isRunning(child)) return propagateFailureAfterDrain() + if (!isRunning(child) || await exitMarkerWithinGrace(exited)) return propagateFailureAfterDrain() // An `error` after spawn is not an exit edge: in particular, a failed // signal can leave the subprocess live. Force termination, await the @@ -252,7 +254,7 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe // A successful earlier signal may win between the live check and this fallback call. // In that case `kill()` correctly reports no process to signal; the original child error // remains the shutdown result once inherited stdio and callbacks have drained. - if (!isRunning(child)) return propagateFailureAfterDrain() + if (!isRunning(child) || await exitMarkerWithinGrace(exited)) return propagateFailureAfterDrain() closeUpdateStream() throw new AggregateError( [failure, new Error('Fallback SIGKILL was not accepted by the child process')], @@ -281,6 +283,17 @@ function waitForExit(child: ChildProcessWithoutNullStreams): Promise { return new Promise(resolve => child.once('exit', () => { resolve() })) } +/** Give an accepted Windows termination request a bounded window to publish its exit marker. */ +function exitMarkerWithinGrace(exited: Promise): Promise { + return Promise.race([ + exited.then(() => true), + new Promise((resolve) => { + const timer = setTimeout(() => { resolve(false) }, EXIT_MARKER_GRACE_MS) + timer.unref() + }), + ]) +} + /** Whether the child still lacks either OS termination marker. */ function isRunning(child: ChildProcessWithoutNullStreams): boolean { return child.exitCode === null && child.signalCode === null diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index 61b40010df..5d12b2da97 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -202,6 +202,28 @@ describe('runScenario', () => { } }) + it('preserves the child error when the requested signal publishes its exit marker later', async () => { + const { dir } = await scenario({}) + const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir }) + await launched.spawned + + const childFailure = Object.assign(new Error('signal failed before the delayed exit marker'), { code: 'EPERM' }) + const originalKill = launched.child.kill.bind(launched.child) + const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => { + expect(signal).toBe('SIGTERM') + setTimeout(() => { originalKill('SIGKILL') }, 10) + return true + }) + try { + launched.child.emit('error', childFailure) + await expect(launched.close('SIGTERM')).rejects.toBe(childFailure) + expect(kill).toHaveBeenCalledOnce() + } finally { + kill.mockRestore() + if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL') + } + }) + it('preserves the child error when fallback refusal races with an exit marker', async () => { const { dir } = await scenario({}) const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir }) From 97f9ec7c19f7651b06c4cd79f875510c64b99992 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 13:29:31 +0800 Subject: [PATCH 33/53] test(acp-snapshot): inherit descendant pipes portably Use Node's explicit inherit stdio mode for the fake descendant instead of passing the parent process stream objects as child descriptors. This keeps the grandchild's stdout and stderr handles open across the fake ACP parent's exit on Windows, so launcher shutdown must drain the late buffered update and stderr bytes just as it does on POSIX. --- packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts index 647ffbb5d9..fbac6dfa10 100644 --- a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts +++ b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts @@ -267,7 +267,7 @@ function flushLogsAndExit(): void { `setTimeout(() => process.stderr.write(${JSON.stringify('late inherited stderr\n')}), 75)`, ].join(';') spawn(process.execPath, ['-e', code], { - stdio: ['ignore', process.stdout, process.stderr], + stdio: ['ignore', 'inherit', 'inherit'], }).unref() } process.exit(0) From 37d2556a7bebfd6aeceba1932e0f039f66ae7ae9 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 13:33:08 +0800 Subject: [PATCH 34/53] docs(fs): record the revised DACL translation pair Update the bilingual pairing checksum after the English and Chinese Windows DACL RFCs were revised together to describe semantic ACE-policy comparison. This restores the repository's recorded translation-consistency contract without changing either document's content. --- ...026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml index 5f37bf3ca3..e388c22c18 100644 --- a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml +++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -2026-07-19-windows-atomic-write-dacl-preservation.md: 393ce8a992b8c0b7b580f2c794e098d66e14258e -2026-07-19-windows-atomic-write-dacl-preservation.zh.md: c7a0b6278cf739cc5ef4432d679e48b88b61d198 +2026-07-19-windows-atomic-write-dacl-preservation.md: 13ec1546ce3a739039045ab5db9b935a83e84098 +2026-07-19-windows-atomic-write-dacl-preservation.zh.md: ca72ec22132777a12f1fcdc1b7f8816a710c0845 From b1b076f99333046ad4c6751dc031552d63056b78 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 13:49:48 +0800 Subject: [PATCH 35/53] test(acp-snapshot): cover accepted fallback termination Drive the shutdown path where the requested signal reports a child error without exiting, the bounded marker grace expires, and fallback SIGKILL is accepted. Assert that both signals are attempted and that close drains the successful fallback exit before preserving the original child error, restoring per-file 100% branch and line coverage for the launcher. --- .../acp-snapshot/tests/harness.spec.ts | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index 5d12b2da97..64076c1217 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -248,6 +248,28 @@ describe('runScenario', () => { } }) + it('preserves the child error after accepted fallback termination drains', async () => { + const { dir } = await scenario({}) + const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir }) + await launched.spawned + + const childFailure = Object.assign(new Error('requested signal failed before fallback'), { code: 'EPERM' }) + const originalKill = launched.child.kill.bind(launched.child) + const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => { + if (signal === 'SIGTERM') return true + return originalKill('SIGKILL') + }) + try { + launched.child.emit('error', childFailure) + await expect(launched.close('SIGTERM')).rejects.toBe(childFailure) + expect(kill).toHaveBeenNthCalledWith(1, 'SIGTERM') + expect(kill).toHaveBeenNthCalledWith(2, 'SIGKILL') + } finally { + kill.mockRestore() + if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL') + } + }) + it('rejects promptly when fallback termination emits an error', async () => { const { dir } = await scenario({}) const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir }) From a246afa33a424d831b6f5c59fac7f07aebdf4a03 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 14:14:00 +0800 Subject: [PATCH 36/53] test(acp-snapshot): detach the inherited-stdio fixture Windows does not guarantee that an ordinary child process will continue after its parent exits. The fake ACP agent exited immediately after spawning its late-output descendant, so Windows could tear down that descendant and close the protocol stream before the delayed ACP update was written. Launch the descendant in detached mode while continuing to inherit stdout and stderr, then unref it as before. This preserves the intended regression boundary: launcher shutdown must wait for descendant-held stdio and parse the final buffered frame after the direct ACP parent exits. --- packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts index fbac6dfa10..c5a5810068 100644 --- a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts +++ b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts @@ -267,6 +267,7 @@ function flushLogsAndExit(): void { `setTimeout(() => process.stderr.write(${JSON.stringify('late inherited stderr\n')}), 75)`, ].join(';') spawn(process.execPath, ['-e', code], { + detached: true, stdio: ['ignore', 'inherit', 'inherit'], }).unref() } From f6f984de06dd9542603120681201bbf72bb7a5a2 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 14:21:58 +0800 Subject: [PATCH 37/53] test(tui): cover same-volume cwd outside home The existing /opt footer case reaches the ordinary outside-home return on POSIX, but Windows resolves it on the checkout drive while the user profile is on another drive. That exercises the cross-drive guard instead and leaves the same-volume fallback uncovered in Windows coverage. Add the resolved parent of the home directory as a platform-neutral outside-home path. The case now covers the fallback on every host while retaining /opt to exercise the Windows cross-drive path, restoring per-file branch, statement, and line coverage without platform-specific expectations. --- packages/ui/tui/tests/tui.spec.ts | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 4437369728..c13c7a164e 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -1,5 +1,5 @@ import { homedir } from 'node:os' -import { join } from 'node:path' +import { join, resolve } from 'node:path' import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' import type { Terminal } from '@earendil-works/pi-tui' @@ -361,6 +361,11 @@ describe('pi-tui chat lifecycle and transcript', () => { expect(unsetResult.terminal.output).toContain('cwd unset') await dispose(unsetResult) + const homeParent = resolve(home, '..') + const parentResult = await setup({ cwd: homeParent }) + expect(parentResult.terminal.output).toContain(homeParent) + await dispose(parentResult) + const outsideResult = await setup({ cwd: '/opt' }) expect(outsideResult.terminal.output).toContain('/opt') await dispose(outsideResult) From 0c1bc50b9830266382f1e4d960cdd531d00c6423 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 19 Jul 2026 14:30:46 +0800 Subject: [PATCH 38/53] test(code-runtime): widen the idle-budget timing margin The slow-binding test used a 250 ms compute budget, which is below the instrumented worker startup cost seen intermittently in the four-worker Windows coverage job. That startup activity could exhaust the budget before the program settled into the awaited binding, making the timing assertion depend on runner load. Use a one-second compute budget and a two-second binding delay. The awaited wall time still exceeds the busy-time allowance by a clear factor, so the test continues to prove that binding wait time is not charged while leaving enough headroom for worker initialization under coverage. --- .../code-runtime/code-runtime-worker/tests/runtime.spec.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts index 23c9a8ee60..e95f7cc95b 100644 --- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts +++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts @@ -129,10 +129,10 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => { }, 15_000) it('does not charge time spent awaiting a slow binding against the compute budget', async () => { - const { runtime } = await setup({ computeMs: 250, maxWallMs: 30_000 }) + const { runtime } = await setup({ computeMs: 1_000, maxWallMs: 30_000 }) const result = await runtime.run({ program: 'return await tools.slow({})', - bindings: tools({ slow: () => new Promise(resolve => setTimeout(() => { resolve('slow-done') }, 700)) }), + bindings: tools({ slow: () => new Promise(resolve => setTimeout(() => { resolve('slow-done') }, 2_000)) }), }) expect(result.error).toBeUndefined() expect(result.value).toBe('slow-done') From 95d803e53d700f18ee761978adac2cb4587e573d Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sun, 19 Jul 2026 18:20:42 +0800 Subject: [PATCH 39/53] test(tui): pin footer-assertion cwd to a fixed path The two transcript tests that assert footer token counters inherited process.cwd() as the session cwd. In a checkout deep enough that the footer label exceeds the 88-column fake terminal, the counters never render and the assertions fail. Pin those tests to a short fixed cwd; cwd rendering keeps its dedicated variants test. --- packages/ui/tui/tests/tui.spec.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index c13c7a164e..d27051572e 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -147,6 +147,10 @@ describe('TUI config', () => { describe('pi-tui chat lifecycle and transcript', () => { it('renders its header, footer, replay, streaming answer, todos, and status', async () => { const result = await setup({ + // A fixed short cwd keeps the footer's token counters inside the 88-column + // fake terminal regardless of where the checkout lives; cwd rendering has + // its own dedicated variants test below. + cwd: '/workspace', beforeMount(session) { appendUser(session, 'restored prompt') appendAssistant(session, [ @@ -278,6 +282,7 @@ describe('pi-tui chat lifecycle and transcript', () => { it('renders the ANSI palette and every markdown/content style', async () => { const result = await setup({ + cwd: '/workspace', config: { color: true }, beforeMount(session) { session.append('user/message', { From 5faf8d120096d2193c1c2a2b3663871381b2cddd Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sun, 19 Jul 2026 19:02:06 +0800 Subject: [PATCH 40/53] test(acp-snapshot): skip POSIX-cancel scenarios on Windows The cancel-tool-calls scenario cancels a live bash call, which relies on POSIX detached-process-group termination; bash has no Windows process-tree kill yet (deferred with the Bash execution domain), so the hung call times the scenario out on the native Windows snapshot lane. Add a posixOnly scenario declaration that skips the run test on win32 while the fixture guards keep covering committed files on every platform, and mark cancel-tool-calls with it. --- examples/acp-agent/tests/acp.snapshot.ts | 4 ++- packages/support/acp-snapshot/README.md | 2 +- packages/support/acp-snapshot/src/suite.ts | 31 +++++++++++++++++-- .../support/acp-snapshot/tests/suite.spec.ts | 18 +++++++++++ 4 files changed, 51 insertions(+), 4 deletions(-) diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index 6c34847295..7ec82d692d 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -111,7 +111,9 @@ const SCENARIOS: Scenario[] = [ configPath: WORKSPACE_CONTEXT_CONFIG, }, { name: 'cancel', hasModelTurn: true, recorded: false, overridden: true }, - { name: 'cancel-tool-calls', hasModelTurn: true, recorded: false, overridden: true }, + // Cancelling a live bash call relies on POSIX process-group termination; + // Windows bash process-tree kill is deferred with the Bash execution domain. + { name: 'cancel-tool-calls', hasModelTurn: true, recorded: false, overridden: true, posixOnly: true }, { name: 'subagent-spawn', hasModelTurn: true, recorded: true }, { name: 'subagent-multi', hasModelTurn: true, recorded: true }, { name: 'subagent-fork', hasModelTurn: true, recorded: true }, diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md index 53289fda35..062a43a2fc 100644 --- a/packages/support/acp-snapshot/README.md +++ b/packages/support/acp-snapshot/README.md @@ -38,7 +38,7 @@ defineAcpSnapshotSuite({ A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.golden.md` and the corresponding full tool-schema sequence in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences. -Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. On Windows, `pinsNativeWindowsStdout` additionally compares the complete `stdout.golden.windows.jsonl` after the shared golden and requires that sidecar exactly when enabled. +Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. On Windows, `pinsNativeWindowsStdout` additionally compares the complete `stdout.golden.windows.jsonl` after the shared golden and requires that sidecar exactly when enabled. A scenario whose driven behavior needs POSIX process semantics (e.g. cancelling a live bash call kills a detached process group) declares `posixOnly`, which skips its run test on Windows while the fixture guards keep covering its committed files everywhere. The example also ships a `cordis.snapshot.yml` replay overlay next to its `cordis.yml` (the bin swaps them under `DSH_SNAPSHOT=replay` — [single-source replay config RFC](../../../docs/rfc/implemented/testing/2026-07-04-single-source-acp-replay-config.md)); replay fixtures are served by [`dsh-llm-replay`](../llm-replay/README.md), which this package points at via the `DSH_SNAPSHOT_*` env vars it sets on the child. `pnpm run test:snapshot:record` calls the live LLM and rewrites the recorded scenarios' model fixtures; `pnpm run test:snapshot:refresh` stays keyless, runs the replay overlay, and rewrites stdout, comparable session-log goldens, and each pin's prompt and tool-schema sidecars from the committed model scripts. Fixture roles, record/replay/refresh semantics, and scenario-table fields are documented on `Scenario` and in the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md). diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts index cd99f3d0c2..850afb1723 100644 --- a/packages/support/acp-snapshot/src/suite.ts +++ b/packages/support/acp-snapshot/src/suite.ts @@ -111,6 +111,32 @@ export interface Scenario { * exactly when the option is set. */ pinsNativeWindowsStdout?: boolean + /** + * Whether the driven behavior needs POSIX process semantics the harness + * cannot exercise on Windows (e.g. cancelling a live bash tool call kills a + * detached process group). The scenario's run test is skipped on Windows; + * its fixtures stay guarded on every platform. + */ + posixOnly?: boolean +} + +/** + * Whether a scenario's run test is skipped for this mode and host: record mode + * skips authored (non-`recorded`) scenarios, and {@link Scenario.posixOnly} + * scenarios skip on Windows. + * + * @param scenario The scenario whose run test is being registered. + * @param recording Whether the suite runs in record mode. + * @param platform The running Node platform, injectable for unit coverage. + * @returns True when the scenario's run test must not execute. + */ +export function scenarioSkipped( + scenario: Scenario, + recording: boolean, + platform: NodeJS.Platform = process.platform, +): boolean { + if (recording && !scenario.recorded) return true + return scenario.posixOnly === true && platform === 'win32' } /** One stdout golden selected for a platform run. */ @@ -499,8 +525,9 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void { scenarioSuite('snapshot scenarios', () => { for (const scenario of scenarios) { // In RECORD mode, only re-run the `recorded` (live-API) scenarios; the `authored` ones - // (sidecar-driven errors/cancel) are never re-recorded. - it.skipIf(RECORDING && !scenario.recorded)(`snapshot: ${scenario.name} matches the goldens`, async ({ expect }) => { + // (sidecar-driven errors/cancel) are never re-recorded. `posixOnly` scenarios skip on + // Windows, where their process semantics cannot be driven. + it.skipIf(scenarioSkipped(scenario, RECORDING))(`snapshot: ${scenario.name} matches the goldens`, async ({ expect }) => { const dir = join(snapshotsDir, scenario.name) const input = JSON.parse(await readFile(join(dir, 'input.json'), 'utf8')) as InputScript const overrideFile = join(dir, 'replay.override.json') diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts index da439378dd..e2ee55f5aa 100644 --- a/packages/support/acp-snapshot/tests/suite.spec.ts +++ b/packages/support/acp-snapshot/tests/suite.spec.ts @@ -15,6 +15,7 @@ import { normalizedToolSchemas, parseToolSchemasSnapshot, refreshFixtureReplacements, + scenarioSkipped, sessionFixtureNames, restorePinnedToolSchemas, stabilizeRefreshLog, @@ -256,6 +257,23 @@ describe('stdoutGoldenVariants', () => { }) }) +describe('scenarioSkipped', () => { + const authored: Scenario = { name: 'authored', hasModelTurn: true, recorded: false } + const posix: Scenario = { name: 'posix-cancel', hasModelTurn: true, recorded: false, posixOnly: true } + + it('skips authored scenarios only while recording', () => { + expect(scenarioSkipped(authored, true, 'linux')).toBe(true) + expect(scenarioSkipped(authored, false, 'linux')).toBe(false) + }) + + it('skips posixOnly scenarios on Windows and nowhere else', () => { + expect(scenarioSkipped(posix, false, 'win32')).toBe(true) + expect(scenarioSkipped(posix, false, 'linux')).toBe(false) + expect(scenarioSkipped(posix, false, 'darwin')).toBe(false) + expect(scenarioSkipped(authored, false, 'win32')).toBe(false) + }) +}) + describe('fixtureContext', () => { it('reads the fixture header id and cwd', () => { const ctx = fixtureContext('{"type":"session","id":"abc","cwd":"/rec"}\n{"type":"turn/start"}\n') From ed784cfdcef09749f814970088fb4f3672b95d07 Mon Sep 17 00:00:00 2001 From: Turtle Date: Mon, 20 Jul 2026 11:17:09 +0800 Subject: [PATCH 41/53] Render error cause chains at every diagnostic seam A TUI run against an unreachable endpoint failed with only 'fetch failed': undici wraps transport failures in a bare TypeError whose diagnosis lives on .cause, and every diagnostic seam rendered only error.message. The readline front door additionally rendered failed turns as pure silence. - dsh-llm: new errorChain(value) renders the full cause chain and AggregateError members with circular/hostile-coercion containment. - llm-deepseek: pre-response transport failures throw LlmError('NETWORK') naming the endpoint and chaining the fetch TypeError; aborts keep their DOMException so the loop still classifies them as cancellation. - agent-loop: durable turn/end error messages and logger warnings render through errorChain; local renderThrown copies removed. - ui-stdio: failure turn/end reasons now render ([turn failed ], [turn aborted], [turn rejected], output-token-limit); startup-failure logs use errorChain. - ui-tui: agent/error notices and the startup-failure line use errorChain. --- ...20-error-cause-chain-diagnostics.i18n.yaml | 6 +++ ...026-07-20-error-cause-chain-diagnostics.md | 37 ++++++++++++++ ...-07-20-error-cause-chain-diagnostics.zh.md | 37 ++++++++++++++ docs/config-catalog.md | 6 +-- docs/cordis-catalog/events.md | 2 +- docs/cordis-catalog/services.md | 2 +- packages/core/agent-loop/src/agent.ts | 8 +--- packages/core/agent-loop/src/index.ts | 17 ++----- packages/core/agent-loop/src/loop.ts | 13 +++-- .../tests/config-session-id.spec.ts | 12 ++--- packages/llm/llm-deepseek/README.md | 2 +- packages/llm/llm-deepseek/src/adapter.ts | 48 +++++++++++++------ .../llm/llm-deepseek/tests/adapter.spec.ts | 35 +++++++++++++- packages/llm/llm/README.md | 1 + packages/llm/llm/src/error.ts | 45 +++++++++++++++++ packages/llm/llm/tests/service.spec.ts | 45 +++++++++++++++++ packages/ui/stdio/README.md | 2 +- packages/ui/stdio/src/index.ts | 29 ++++++----- packages/ui/stdio/tests/stdio.spec.ts | 39 ++++++++++++++- packages/ui/tui/src/index.ts | 16 ++----- packages/ui/tui/tests/tui.spec.ts | 4 +- website/zh-CN/api/harness/agent-loop.md | 8 ++-- website/zh-CN/api/harness/events.md | 2 +- 23 files changed, 333 insertions(+), 83 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md create mode 100644 .agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml new file mode 100644 index 0000000000..630a1b05e6 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write +2026-07-20-error-cause-chain-diagnostics.md: 2d860d0e966158dd9ec12b45f88e3b031e1cb35a +2026-07-20-error-cause-chain-diagnostics.zh.md: 6eac19dd08d50e4662d53889577b5e3ddabaafdd diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md new file mode 100644 index 0000000000..2d860d0e96 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md @@ -0,0 +1,37 @@ +# Agent Note: Render error cause chains at every diagnostic seam + +Status: implemented + +English | [中文](2026-07-20-error-cause-chain-diagnostics.zh.md) + +## Problem + +A TUI run against an unreachable DeepSeek endpoint failed with the single notice `fetch failed` and no further detail. Two independent gaps produced that dead end: + +1. undici's `fetch` wraps every transport failure (DNS, refused connection, TLS, proxy) in a bare `TypeError: fetch failed` whose actionable detail — `ECONNREFUSED`, `bad port`, the Happy Eyeballs AggregateError — lives on `error.cause`. Every diagnostic seam in the harness rendered only `error.message` (or `String(error)`, which is equivalent for Errors), so the wrapper masked the diagnosis in the TUI notice, the durable `turn/end` reason, and every logger line. +2. The readline front door (`dsh-stdio`) rendered no failure reason at all: a `turn/end` with `reason.kind === 'error'` printed nothing but the next `> ` prompt, so the same failure in `demo:repl` was pure silence. + +## Decision + +- `dsh-llm` exports `errorChain(value)`: renders a thrown value with its full `cause` chain (`outer: inner: …`) and AggregateError members (`msg [m1; m2]`), with circular-cause and hostile-coercion containment. It is a diagnostic-surface renderer only; routing stays on `HarnessError.code`. +- The DeepSeek adapter wraps a pre-response transport failure in `LlmError('NETWORK')` naming the configured `baseURL` and chaining the original `TypeError` as `cause`. An aborted request keeps its `DOMException` so the loop still classifies it as cancellation, not a provider failure. +- Every diagnostic seam renders through `errorChain` instead of `error.message`/`String(error)`: the agent-loop's durable `turn/end` error message (`errorData`), its logger warnings, the TUI's `agent/error` notice and startup-failure line, and `dsh-stdio`'s startup-failure log lines. The per-package `renderThrown` copies in `dsh-agent-loop`, `dsh-stdio`, and `dsh-tui` are deleted in favor of the one shared renderer. +- `dsh-stdio` renders failure `turn/end` reasons: `[turn failed ] `, `[turn aborted] `, `[turn rejected] `, `[turn interrupted by a previous process exit]`, and the output-token-limit notice. Unknown merge-extended kinds fall through as ordinary turn ends. + +`errorChain` lives in `dsh-llm` beside `HarnessError` for the same reason the base class does: it is the leaf package every consumer already imports, so sharing costs no new dependency edge. + +## Alternatives considered + +**Chain rendering inside each error's constructor (bake the cause into `message`).** Rejected: it double-renders once consumers also walk `cause` (the first draft of the adapter fix produced `… fetch failed: bad port: fetch failed: bad port`), and it destroys the structured chain for consumers that want to route on the inner error. + +**A `cause`-aware logger exporter only.** Rejected: the durable `turn/end` reason and the TUI notice are not logger lines; the masked message would persist in the session log — the single durable record of an in-turn failure — and in the primary UI surface. + +**Per-package `renderThrown` upgrades.** Rejected: three packages already carried near-identical private copies; upgrading each separately entrenches the duplication the shared renderer removes. + +## Consequences + +- A transport failure now reads `DeepSeek API request to failed: fetch failed: connect ECONNREFUSED …` in the TUI notice, the readline transcript, and the persisted session log, at the cost of longer diagnostic strings. +- Durable `turn/end` error messages include cause detail. Existing snapshot fixtures replay byte-identically because their scripted errors carry no `cause` (for such errors `errorChain(err)` equals `err.message`); only unit-test expectation strings changed. A fixture recorded from a real transport failure would carry the chain. +- `errorChain` renders `message` without the class name (`String(error)` rendered `Error: `), so a bare `TypeError` in a log line loses its type label unless its message is empty (then the name is the fallback). The chain detail was judged worth more than the class name at these seams. +- `dsh-stdio` output for failed turns is no longer silent; piped consumers that parsed the transcript see new `[turn …]` lines. +- Remaining `renderThrown` copies in `dsh-subagent`, `dsh-workflow`, `dsh-skill`, `dsh-workflow-workerthread`, and `cli-demo` still render without the chain; they wrap package-local errors that carry their own messages, and can adopt `errorChain` when their diagnostics prove insufficient. diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md new file mode 100644 index 0000000000..6eac19dd08 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md @@ -0,0 +1,37 @@ +# Agent Note: 在每个诊断接缝处渲染错误 cause 链 + +Status: implemented + +[English](2026-07-20-error-cause-chain-diagnostics.md) | 中文 + +## Problem + +TUI 连接不可达的 DeepSeek 端点时，失败只显示一条 `fetch failed` 通知，没有任何进一步细节。两个独立缺口共同造成了这个死胡同： + +1. undici 的 `fetch` 把所有传输层失败（DNS、连接被拒、TLS、代理）包装成裸的 `TypeError: fetch failed`，可操作的细节——`ECONNREFUSED`、`bad port`、Happy Eyeballs 的 AggregateError——都在 `error.cause` 上。harness 里的每个诊断接缝都只渲染 `error.message`（或对 Error 等价的 `String(error)`），于是包装层在 TUI 通知、持久化的 `turn/end` reason 和所有日志行里都掩盖了诊断信息。 +2. readline 前门（`dsh-stdio`）完全不渲染失败原因：`reason.kind === 'error'` 的 `turn/end` 只打印下一个 `> ` 提示符，同样的失败在 `demo:repl` 里就是纯粹的沉默。 + +## Decision + +- `dsh-llm` 导出 `errorChain(value)`：渲染抛出值及其完整 `cause` 链（`outer: inner: …`）与 AggregateError 成员（`msg [m1; m2]`），并容错循环 cause 和恶意强制转换。它只是诊断表面的渲染器；路由仍然基于 `HarnessError.code`。 +- DeepSeek 适配器把拿到响应之前的传输失败包装成 `LlmError('NETWORK')`，写明配置的 `baseURL` 并把原始 `TypeError` 链为 `cause`。被中止的请求保留其 `DOMException`，使循环仍将其归类为取消而非 provider 失败。 +- 每个诊断接缝改用 `errorChain` 而非 `error.message`/`String(error)`：agent-loop 的持久化 `turn/end` 错误消息（`errorData`）、其日志警告、TUI 的 `agent/error` 通知与启动失败行、以及 `dsh-stdio` 的启动失败日志行。`dsh-agent-loop`、`dsh-stdio`、`dsh-tui` 里各自的 `renderThrown` 副本被删除，统一使用这一个共享渲染器。 +- `dsh-stdio` 渲染失败的 `turn/end` reason：`[turn failed ] `、`[turn aborted] `、`[turn rejected] `、`[turn interrupted by a previous process exit]` 以及输出 token 上限通知。未知的 merge 扩展 kind 按普通 turn 结束处理。 + +`errorChain` 与 `HarnessError` 一样放在 `dsh-llm` 里，理由相同：它是每个消费者都已导入的叶子包，共享不增加新的依赖边。 + +## Alternatives considered + +**在每个错误的构造函数里渲染链（把 cause 烤进 `message`）。** 否决：当消费者同时遍历 `cause` 时会双重渲染（适配器修复的第一版产出了 `… fetch failed: bad port: fetch failed: bad port`），并且破坏了想按内层错误路由的消费者所需的结构化链。 + +**只做一个感知 `cause` 的日志导出器。** 否决：持久化的 `turn/end` reason 和 TUI 通知不是日志行；被掩盖的消息会留在会话日志——回合内失败的唯一持久记录——以及主要 UI 表面里。 + +**逐包升级 `renderThrown`。** 否决：三个包已经各自持有几乎相同的私有副本；分别升级只会固化共享渲染器所要消除的重复。 + +## Consequences + +- 传输失败现在在 TUI 通知、readline transcript 和持久化会话日志里显示为 `DeepSeek API request to failed: fetch failed: connect ECONNREFUSED …`，代价是更长的诊断字符串。 +- 持久化的 `turn/end` 错误消息包含 cause 细节。现有 snapshot fixture 字节级一致地回放，因为其脚本化错误不带 `cause`（对这类错误 `errorChain(err)` 等于 `err.message`）；只有单元测试的期望字符串有变化。从真实传输失败录制的 fixture 会携带完整链。 +- `errorChain` 渲染 `message` 而不带类名（`String(error)` 会渲染 `Error: `），因此日志行里的裸 `TypeError` 会丢失类型标签，除非消息为空（此时回退到类名）。在这些接缝上，链细节被判断为比类名更有价值。 +- `dsh-stdio` 对失败回合的输出不再沉默；解析 transcript 的管道消费者会看到新的 `[turn …]` 行。 +- `dsh-subagent`、`dsh-workflow`、`dsh-skill`、`dsh-workflow-workerthread`、`cli-demo` 里剩余的 `renderThrown` 副本仍不渲染链；它们包装的是自带消息的包内错误，等诊断信息证明不足时再采用 `errorChain`。 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index e6934564ae..a4eedf25cc 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -101,7 +101,7 @@ export interface Config { Depends on: [`AgentOptions`](core-data-structures/core.md) · [`SessionId`](core-data-structures/core.md) -Source: [`packages/core/agent-loop/src/index.ts:369`](../packages/core/agent-loop/src/index.ts) +Source: [`packages/core/agent-loop/src/index.ts:360`](../packages/core/agent-loop/src/index.ts) ## `@deepseek-ai/dsh-agent-spine-demo` @@ -858,7 +858,7 @@ export interface Config { } ``` -Source: [`packages/ui/stdio/src/index.ts:33`](../packages/ui/stdio/src/index.ts) +Source: [`packages/ui/stdio/src/index.ts:34`](../packages/ui/stdio/src/index.ts) ## `@deepseek-ai/dsh-stdio-demo` @@ -1302,7 +1302,7 @@ export interface TuiConfig { } ``` -Source: [`packages/ui/tui/src/index.ts:100`](../packages/ui/tui/src/index.ts) +Source: [`packages/ui/tui/src/index.ts:101`](../packages/ui/tui/src/index.ts) ## `@deepseek-ai/dsh-user-approval` diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 612de06e82..4728f2d65a 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -366,7 +366,7 @@ A declarative agent entry failed before it could publish a live agent. Consumers Types: [SessionId](../core-data-structures/core.md) -Source: [`packages/core/agent-loop/src/index.ts:362`](../../packages/core/agent-loop/src/index.ts) +Source: [`packages/core/agent-loop/src/index.ts:353`](../../packages/core/agent-loop/src/index.ts) ## `approval/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 42d645e6d9..af94bc90d3 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -44,7 +44,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise { - const rendered = renderThrown(error) + const rendered = errorChain(error) const err = error instanceof Error ? error : new Error(rendered) this.loopCtx.logger.warn(`agent "${this.id}": flush after idle injection failed: ${rendered}`) agentEvents(this.loopCtx, this).emit('agent/error', turn, 0, err) @@ -445,7 +445,3 @@ export class ReactLoopAgent implements Agent { } } -/** Render an ordinary thrown value for the error event and log. */ -function renderThrown(value: unknown): string { - return value instanceof Error ? value.message : String(value) -} diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts index 2a77afc983..24e18d5c32 100644 --- a/packages/core/agent-loop/src/index.ts +++ b/packages/core/agent-loop/src/index.ts @@ -20,7 +20,7 @@ import type { ResumeAgentOptions, SessionStartSource, } from '@deepseek-ai/dsh-agent' -import type {} from '@deepseek-ai/dsh-llm' +import { errorChain } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' import type { Session, SessionHeader } from '@deepseek-ai/dsh-session' import type {} from '@deepseek-ai/dsh-system-prompt' @@ -41,15 +41,6 @@ const INACTIVE_STATES: ReadonlySet = new Set([ FiberState.FAILED, ]) -/** Render an arbitrary thrown value without letting coercion escape containment. */ -function renderThrown(value: unknown): string { - try { - return String(value) - } catch { - return '' - } -} - /** Factory-level ownership of every preparing or live transaction. */ class FactoryOwnership { private accepting = true @@ -475,16 +466,16 @@ export class AgentLoop extends Service implements AgentFactory { error: unknown, ): void { if (!this.ownership.isActive()) return - this.ctx.logger.warn(`agent "${configId}": config-driven ${action} of "${sessionId}" failed: ${renderThrown(error)}`) + this.ctx.logger.warn(`agent "${configId}": config-driven ${action} of "${sessionId}" failed: ${errorChain(error)}`) const args: unknown[] = ['agent-loop/config-start-failed', sessionId, error] for (const callback of this.ctx.events.dispatch('emit', args)) { try { const returned: unknown = callback(...args) void Promise.resolve(returned).catch((listenerError: unknown) => { - this.ctx.logger.warn(`agent "${configId}": config-start-failed listener rejected: ${renderThrown(listenerError)}`) + this.ctx.logger.warn(`agent "${configId}": config-start-failed listener rejected: ${errorChain(listenerError)}`) }) } catch (listenerError: unknown) { - this.ctx.logger.warn(`agent "${configId}": config-start-failed listener threw: ${renderThrown(listenerError)}`) + this.ctx.logger.warn(`agent "${configId}": config-start-failed listener threw: ${errorChain(listenerError)}`) } } } diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts index bc18ee52d3..80da07ea10 100644 --- a/packages/core/agent-loop/src/loop.ts +++ b/packages/core/agent-loop/src/loop.ts @@ -8,7 +8,7 @@ import type { Context } from 'cordis' import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, Message } from '@deepseek-ai/dsh-llm' import { isDeepStrictEqual } from 'node:util' -import { BlockAssembler, HarnessError, assertNever, deepFreeze, isLlmAdapterFailure } from '@deepseek-ai/dsh-llm' +import { BlockAssembler, HarnessError, assertNever, deepFreeze, errorChain, isLlmAdapterFailure } from '@deepseek-ai/dsh-llm' import { agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent' import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision, RequestError, RequestErrorDecision } from '@deepseek-ai/dsh-agent' import { canonicalHeader } from '@deepseek-ai/dsh-session' @@ -56,9 +56,12 @@ function finishError(finish: FinishReason): RequestError | undefined { /** * Build the `{ message, code? }` part of an error payload, omitting the * `code` key entirely when absent (exactOptionalPropertyTypes-correct). + * The durable message renders the full cause chain: `turn/end` is the single + * durable record of an in-turn failure, so a wrapper message alone (e.g. + * `fetch failed`) would lose the diagnosis the session log exists to keep. */ function errorData(err: RequestError): { message: string; code?: string } { - return { message: err.message, ...typeof err.code === 'string' ? { code: err.code } : {} } + return { message: errorChain(err), ...typeof err.code === 'string' ? { code: err.code } : {} } } /** Map a successful max-token finish onto the turn reason; other successful finishes add nothing. */ @@ -151,7 +154,7 @@ export async function runLoop(ctx: Context, handle: LoopHandle): Promise { } catch (error: unknown) { // Pre-turn failure has no durable boundary to close; report it without appending outside a turn. const err = toError(error) - ctx.logger.warn(`agent "${agent.id}": turn ${turn} failed before it started: ${err.message}`) + ctx.logger.warn(`agent "${agent.id}": turn ${turn} failed before it started: ${errorChain(err)}`) try { events.emit('agent/error', turn, 0, err) } catch { /* contained: a throwing agent/error listener must not kill the driver */ } @@ -387,7 +390,7 @@ async function runTurn( ) } catch (recoveryError: unknown) { ctx.logger.warn( - `agent "${agent.id}": request recovery failed at turn ${turn}, step ${step}: ${toError(recoveryError).message}`, + `agent "${agent.id}": request recovery failed at turn ${turn}, step ${step}: ${errorChain(recoveryError)}`, ) } handle.setAbort(undefined) @@ -551,7 +554,7 @@ async function runTurn( } catch (error: unknown) { // The turn is closed, so report the failed flush live rather than append outside a turn. const err = toError(error) - ctx.logger.warn(`agent "${agent.id}": session/flush failed at turn ${turn}: ${err.message}`) + ctx.logger.warn(`agent "${agent.id}": session/flush failed at turn ${turn}: ${errorChain(err)}`) try { events.emit('agent/error', turn, step, err) } catch { diff --git a/packages/core/agent-loop/tests/config-session-id.spec.ts b/packages/core/agent-loop/tests/config-session-id.spec.ts index cadc176aea..5f9bf3dd07 100644 --- a/packages/core/agent-loop/tests/config-session-id.spec.ts +++ b/packages/core/agent-loop/tests/config-session-id.spec.ts @@ -217,14 +217,14 @@ describe('config-driven session id', () => { }) await expect.poll(() => warn).toHaveBeenCalledWith(expect.stringContaining( - 'config-driven restore of "stdio-exact-failure" failed: Error: persistence index failed', + 'config-driven restore of "stdio-exact-failure" failed: persistence index failed', )) expect(failures).toEqual([{ sessionId: SessionId('stdio-exact-failure'), error: failure }]) expect(warn).toHaveBeenCalledWith( - 'agent "main": config-start-failed listener threw: Error: failure observer failed', + 'agent "main": config-start-failed listener threw: failure observer failed', ) await expect.poll(() => warn).toHaveBeenCalledWith( - 'agent "main": config-start-failed listener rejected: Error: async failure observer failed', + 'agent "main": config-start-failed listener rejected: async failure observer failed', ) expect(ctx.agents.get(SessionId('stdio-exact-failure'))).toBeUndefined() warn.mockRestore() @@ -256,13 +256,13 @@ describe('config-driven session id', () => { await expect.poll(() => failures).toEqual([unrenderable]) expect(warn).toHaveBeenCalledWith( - 'agent "main": config-driven restore of "stdio-exact-unrenderable" failed: ', + 'agent "main": config-driven restore of "stdio-exact-unrenderable" failed: ', ) expect(warn).toHaveBeenCalledWith( - 'agent "main": config-start-failed listener threw: ', + 'agent "main": config-start-failed listener threw: ', ) await expect.poll(() => warn).toHaveBeenCalledWith( - 'agent "main": config-start-failed listener rejected: ', + 'agent "main": config-start-failed listener rejected: ', ) await ctx.fiber.dispose() }) diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md index 27bf4b626a..ee4c705560 100644 --- a/packages/llm/llm-deepseek/README.md +++ b/packages/llm/llm-deepseek/README.md @@ -42,7 +42,7 @@ Every request carries the shared attribution header from dsh-llm's `attributionH ## Errors -Non-2xx responses throw `LlmError` with stable codes: `AUTH` (401/403), `RATE_LIMIT` (429), `CONTEXT_WINDOW_EXCEEDED` (a 400 whose provider code, type, or message identifies context overflow), `INVALID_REQUEST` (other 400s), `SERVER` (5xx), `HTTP_` otherwise. Protocol violations throw `STREAM_CLOSED` (no `[DONE]`) or `MALFORMED_RESPONSE` (bad JSON payload). Unknown wire `finish_reason`s (e.g. `content_filter`, `insufficient_system_resource`) become `finish {kind: 'error', code: }` chunks. +Non-2xx responses throw `LlmError` with stable codes: `AUTH` (401/403), `RATE_LIMIT` (429), `CONTEXT_WINDOW_EXCEEDED` (a 400 whose provider code, type, or message identifies context overflow), `INVALID_REQUEST` (other 400s), `SERVER` (5xx), `HTTP_` otherwise. A transport failure before any response (DNS, refused connection, TLS, proxy) throws `NETWORK` naming the configured endpoint and chaining fetch's `TypeError: fetch failed` as `cause`, so `errorChain` renders the underlying diagnosis; an abort keeps its `DOMException` so the loop classifies it as cancellation. Protocol violations throw `STREAM_CLOSED` (no `[DONE]`) or `MALFORMED_RESPONSE` (bad JSON payload). Unknown wire `finish_reason`s (e.g. `content_filter`, `insufficient_system_resource`) become `finish {kind: 'error', code: }` chunks. ## Testing diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts index 918c8eee82..66520a83d4 100644 --- a/packages/llm/llm-deepseek/src/adapter.ts +++ b/packages/llm/llm-deepseek/src/adapter.ts @@ -81,23 +81,43 @@ export class DeepSeekAdapter extends LlmAdapter { async * stream(options: GenerateOptions): AsyncIterable { const body = serializeRequest(options, this.options.defaults ?? {}) + // Prepared outside the try so the NETWORK label below covers exactly the + // transport boundary, never a serialization failure. + const payload = JSON.stringify(body) + const headers = { + 'authorization': `Bearer ${this.options.apiKey}`, + 'content-type': 'application/json', + 'accept': 'text/event-stream', + ...attributionHeaders(), + ...options.sessionId !== undefined + ? { 'x-deepseek-harness-session-id': String(options.sessionId) } + : {}, + } // TODO(http): adopt the Cordis HTTP service when shared transport configuration // outweighs its additional runtime dependencies. - const response = await fetch(`${this.options.baseURL}/chat/completions`, { - method: 'POST', - headers: { - 'authorization': `Bearer ${this.options.apiKey}`, - 'content-type': 'application/json', - 'accept': 'text/event-stream', - ...attributionHeaders(), - ...options.sessionId !== undefined - ? { 'x-deepseek-harness-session-id': String(options.sessionId) } - : {}, - }, - body: JSON.stringify(body), - ...options.signal ? { signal: options.signal } : {}, - }) + let response: Response + try { + response = await fetch(`${this.options.baseURL}/chat/completions`, { + method: 'POST', + headers, + body: payload, + ...options.signal ? { signal: options.signal } : {}, + }) + } catch (error: unknown) { + // An aborted request rethrows its original rejection (the signal's abort + // reason) so the loop classifies it as cancellation, not a provider failure. + if (options.signal?.aborted) throw error + // fetch wraps every transport failure (DNS, refused connection, TLS, + // proxy) in a bare `TypeError: fetch failed` whose actionable detail + // lives on `cause`. Wrapping with the endpoint and chaining the cause + // lets `errorChain` render the full diagnosis at every reporting seam. + throw new LlmError( + `DeepSeek API request to ${this.options.baseURL} failed`, + 'NETWORK', + { cause: error }, + ) + } if (!response.ok) { let message = `DeepSeek API error (HTTP ${response.status})` diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts index 954a0ecebd..b92f96dbda 100644 --- a/packages/llm/llm-deepseek/tests/adapter.spec.ts +++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts @@ -2,7 +2,7 @@ import { createServer } from 'node:http' import type { IncomingMessage, Server, ServerResponse } from 'node:http' import { afterEach, describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' -import LlmService, { CONTEXT_WINDOW_EXCEEDED_CODE, LlmError, userAgent } from '@deepseek-ai/dsh-llm' +import LlmService, { CONTEXT_WINDOW_EXCEEDED_CODE, errorChain, LlmError, userAgent } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' import { DeepSeekAdapter } from '@deepseek-ai/dsh-llm-deepseek' @@ -228,6 +228,39 @@ describe('DeepSeekAdapter against a mock server', () => { expect(httpErrorCode(418)).toBe('HTTP_418') }) + it('wraps a transport failure in NETWORK with the fetch cause chain in the message', async () => { + // Port 1 is reserved/unbound: fetch rejects with `TypeError: fetch failed` + // whose actionable detail (ECONNREFUSED) lives on `cause`. + const ctx = await harness('http://127.0.0.1:1') + let caught: unknown + try { + await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] }) + } catch (error: unknown) { + caught = error + } + expect(caught).toBeInstanceOf(LlmError) + const llmError = caught as LlmError + expect(llmError.code).toBe('NETWORK') + expect(llmError.message).toContain('http://127.0.0.1:1') + expect(llmError.cause).toBeInstanceOf(TypeError) + // The chain renderer reaches the transport diagnosis through the cause. + expect(errorChain(llmError)).toMatch(/ECONNREFUSED|EADDRNOTAVAIL|bad port/) + }) + + it('keeps an abort rejection unwrapped so the loop classifies it as cancellation', async () => { + const controller = new AbortController() + controller.abort() + const ctx = await harness('http://127.0.0.1:1') + let caught: unknown + try { + await assemble(ctx, { model: 'deepseek-v4-flash', messages: [], signal: controller.signal }) + } catch (error: unknown) { + caught = error + } + expect(caught).not.toBeInstanceOf(LlmError) + expect((caught as Error).name).toBe('AbortError') + }) + it('throws EMPTY_RESPONSE when the response has no body', async () => { const adapter = new DeepSeekAdapter({ apiKey: 'k', baseURL: 'http://127.0.0.1:1' }) const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue( diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md index f9142dbc52..82ca7f901c 100644 --- a/packages/llm/llm/README.md +++ b/packages/llm/llm/README.md @@ -48,6 +48,7 @@ Every product adapter sends application identity on provider HTTP requests. `att - `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and an assistant message. The agent loop feeds it raw chunks (logging them for replay) while reading the assembled blocks/message for history. - `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at seams. - `LlmError` — extends `HarnessError`; its stable `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) is the programmatic failure contract. +- `errorChain(value)` — renders a thrown value with its full `cause` chain and AggregateError members for diagnostic surfaces (UI notices, logger lines, durable `turn/end` messages), so transport wrappers like undici's `TypeError: fetch failed` surface the underlying `ECONNREFUSED`/DNS/TLS detail instead of masking it. Rendering only — route on `code`, never by parsing the result. - `CONTEXT_WINDOW_EXCEEDED_CODE` — the provider-neutral code both DeepSeek adapters use when a request exceeds the model context window, regardless of thrown-HTTP versus in-band finish delivery. `isContextWindowExceededError(detail)` is their shared conservative classifier for OpenAI-compatible provider detail. ### Real adapters diff --git a/packages/llm/llm/src/error.ts b/packages/llm/llm/src/error.ts index 8c1c736492..c351060ee5 100644 --- a/packages/llm/llm/src/error.ts +++ b/packages/llm/llm/src/error.ts @@ -62,6 +62,51 @@ export function isContextWindowExceededError(detail: string): boolean { || EXCEEDS_MODEL_CONTEXT.test(detail) } +/** + * Render a thrown value with its full `cause` chain and AggregateError + * members, so transport wrappers like undici's `TypeError: fetch failed` + * surface the underlying failure instead of masking it. Diagnostic-surface + * rendering only (messages, notices, logs) — never parse the result; route on + * {@link HarnessError.code}. + * @param value - the caught value (`unknown` in catch clauses). + * @returns the outermost message first, each cause appended with `: ` (skipped + * when it repeats the wrapper message verbatim), and AggregateError members + * bracketed and `; `-joined. + */ +export function errorChain(value: unknown): string { + // Tracks the active recursion path (entries removed on exit), so only true + // cycles are flagged and a diamond-shared cause still renders in full. + const path = new Set() + const render = (current: unknown): string => { + if (path.has(current)) return '' + path.add(current) + try { + if (!(current instanceof Error)) return String(current) + const message = current.message === '' ? current.name : current.message + const members = current instanceof AggregateError && current.errors.length > 0 + ? ` [${current.errors.map(render).join('; ')}]` + : '' + const causeText = current.cause === undefined || current.cause === null + ? '' + : render(current.cause) + // Wrappers like `new HarnessError(String(value), code, { cause: value })` + // repeat their cause verbatim; rendering it again would only add noise. + const cause = causeText === '' || causeText === message ? '' : `: ${causeText}` + return `${message}${members}${cause}` + } catch { + // Only hostile coercion or hostile accessors (a throwing toString / + // Symbol.toPrimitive on a non-Error, or a throwing message/name/cause/ + // errors getter on an Error subclass): this renderer feeds UI notices + // and logs, so nothing may escape. Inner frames catch their own throws, + // so only the hostile node collapses, not the whole chain. + return '' + } finally { + path.delete(current) + } + } + return render(value) +} + /** * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at seams). * @param value - the caught value (`unknown` in catch clauses). diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts index 6e14d749ba..67b90d1c2f 100644 --- a/packages/llm/llm/tests/service.spec.ts +++ b/packages/llm/llm/tests/service.spec.ts @@ -1,6 +1,7 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' import LlmService, { + errorChain, GenerateOptions, HarnessError, isContextWindowExceededError, @@ -80,6 +81,50 @@ describe('LlmService', () => { expect(isContextWindowExceededError('context window size must be positive')).toBe(false) }) + it('errorChain renders the full cause chain of a wrapped transport failure', () => { + const chain = new TypeError('fetch failed', { cause: new Error('connect ECONNREFUSED 127.0.0.1:443') }) + expect(errorChain(chain)).toBe('fetch failed: connect ECONNREFUSED 127.0.0.1:443') + }) + + it('errorChain renders AggregateError members (Happy Eyeballs multi-address failures)', () => { + const aggregate = new AggregateError( + [new Error('connect ECONNREFUSED ::1:443'), new Error('connect ECONNREFUSED 127.0.0.1:443')], + '', + ) + const wrapped = new TypeError('fetch failed', { cause: aggregate }) + expect(errorChain(wrapped)).toBe( + 'fetch failed: AggregateError [connect ECONNREFUSED ::1:443; connect ECONNREFUSED 127.0.0.1:443]', + ) + }) + + it('errorChain survives non-Error values, hostile coercion, and circular causes', () => { + expect(errorChain('plain string')).toBe('plain string') + expect(errorChain({ toString: () => { throw new Error('hostile') } })).toBe('') + const circular = new Error('outer') + circular.cause = circular + expect(errorChain(circular)).toBe('outer: ') + // A hostile accessor collapses only its own node, not the whole chain. + const hostileNode = new Error('node') + Object.defineProperty(hostileNode, 'message', { get() { throw new Error('hostile getter') } }) + expect(errorChain(new Error('outer', { cause: hostileNode }))).toBe('outer: ') + // A diamond-shared (non-cyclic) cause renders in full on both paths. + const shared = new Error('shared') + const diamond = new AggregateError([new Error('a', { cause: shared }), new Error('b', { cause: shared })], 'agg') + expect(errorChain(diamond)).toBe('agg [a: shared; b: shared]') + }) + + it('errorChain falls back to the error name, skips empty aggregates, and stops at null causes', () => { + expect(errorChain(new TypeError('', { cause: null }))).toBe('TypeError') + expect(errorChain(new AggregateError([], 'all failed'))).toBe('all failed') + }) + + it('errorChain collapses a cause that repeats the wrapper message verbatim', () => { + // The `new HarnessError(String(value), code, { cause: value })` normalization + // pattern repeats its cause; rendering it twice would only add noise. + const wrapped = new HarnessError('boom', 'UNKNOWN', { cause: 'boom' }) + expect(errorChain(wrapped)).toBe('boom') + }) + it('routes stream() to the registered adapter', async () => { const ctx = new Context() await ctx.plugin(LlmService) diff --git a/packages/ui/stdio/README.md b/packages/ui/stdio/README.md index eda7d00b8b..869dd7b4df 100644 --- a/packages/ui/stdio/README.md +++ b/packages/ui/stdio/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-stdio -The terminal readline front door for DeepSeek Harness agents. It reads prompts from stdin, sends or steers them through `ctx.agents`, renders the durable `session/event` transcript to stdout, and answers `ctx.userInteraction` requests in the same terminal. +The terminal readline front door for DeepSeek Harness agents. It reads prompts from stdin, sends or steers them through `ctx.agents`, renders the durable `session/event` transcript to stdout, and answers `ctx.userInteraction` requests in the same terminal. Failed turns render their durable `turn/end` reason — `[turn failed ]`, `[turn aborted]`, `[turn rejected]`, `[turn interrupted …]`, or the output-token-limit notice — so a provider or network failure is never silent; unknown merge-extended reason kinds fall through as ordinary turn ends. This package owns the terminal channel only. It injects `agents` and `userInteraction`, then drives an agent created or resumed by app or developer code. The agent spine, agent lifecycle, console logger, and model-facing [`ask_user_question`](../tool-ask-user/README.md) tool remain separate composition entries. diff --git a/packages/ui/stdio/src/index.ts b/packages/ui/stdio/src/index.ts index 6f73d948bf..4f7695d906 100644 --- a/packages/ui/stdio/src/index.ts +++ b/packages/ui/stdio/src/index.ts @@ -15,6 +15,7 @@ import type { Readable, Writable } from 'node:stream' import type { Context } from 'cordis' import z from 'schemastery' import type { Agent } from '@deepseek-ai/dsh-agent' +import { errorChain } from '@deepseek-ai/dsh-llm' import type {} from '@deepseek-ai/dsh-agent-loop' import { SessionId } from '@deepseek-ai/dsh-session' import { @@ -62,15 +63,6 @@ function isTTYPair(input: Readable, output: Writable): boolean { return Boolean((input as { isTTY?: boolean }).isTTY && (output as { isTTY?: boolean }).isTTY) } -/** Render an arbitrary failure without allowing hostile coercion to escape the UI boundary. */ -function renderThrown(value: unknown): string { - try { - return String(value) - } catch { - return '' - } -} - interface PendingQuestion { request: AskUserQuestionRequest questionIndex: number @@ -138,6 +130,21 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt } else if (event.type === 'turn/end') { if (inReasoning) output.write('\x1B[0m') inReasoning = false + // Failure reasons must reach the terminal: turn/end is the durable record + // of an in-turn failure, and without this line a failed turn renders as + // silence. Merge-extensible unknown kinds fall through as ordinary ends. + const { reason } = event.data + if (reason.kind === 'error') { + output.write(`\n[turn failed${reason.code === undefined ? '' : ` ${reason.code}`}] ${reason.message}`) + } else if (reason.kind === 'aborted') { + output.write(`\n[turn aborted]${reason.reason === undefined ? '' : ` ${reason.reason}`}`) + } else if (reason.kind === 'rejected') { + output.write(`\n[turn rejected] ${reason.reason}`) + } else if (reason.kind === 'max-tokens') { + output.write('\n[turn hit the output-token limit]') + } else if (reason.kind === 'interrupted') { + output.write('\n[turn interrupted by a previous process exit]') + } output.write('\n> ') } else if (event.type === 'tool/call') { const { name: toolName, arguments: args } = event.data @@ -235,7 +242,7 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt queuedInput.length = 0 submittedWork = sawRunning if (dropped > 0) { - ctx.logger.error(`ui-stdio: main agent failed to start; dropped queued stdin (${dropped} line(s)): ${renderThrown(error)}`) + ctx.logger.error(`ui-stdio: main agent failed to start; dropped queued stdin (${dropped} line(s)): ${errorChain(error)}`) } maybeExit() }) @@ -395,7 +402,7 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt const text = line.trim() if (!text) return if (failedStartup !== undefined) { - ctx.logger.error(`ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): ${renderThrown(failedStartup.error)}`) + ctx.logger.error(`ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): ${errorChain(failedStartup.error)}`) return } const agent = target diff --git a/packages/ui/stdio/tests/stdio.spec.ts b/packages/ui/stdio/tests/stdio.spec.ts index a3069462ff..10fa956f25 100644 --- a/packages/ui/stdio/tests/stdio.spec.ts +++ b/packages/ui/stdio/tests/stdio.spec.ts @@ -227,6 +227,41 @@ describe('createStdioChat rendering', () => { expect(out.text()).toContain('\n> ') }) + it('renders failure turn/end reasons so a failed turn is not silent', async () => { + const { ctx, out } = await setup() + const session = makeSession('main') + ctx.emit('session/event', session, { + type: 'turn/end', seq: 1, time: 0, + data: { turn: 1, reason: { kind: 'error', step: 1, message: 'fetch failed: connect ECONNREFUSED', code: 'NETWORK' } }, + } as SessionEvent) + expect(out.text()).toContain('[turn failed NETWORK] fetch failed: connect ECONNREFUSED') + ctx.emit('session/event', session, { + type: 'turn/end', seq: 2, time: 0, + data: { turn: 2, reason: { kind: 'error', step: 1, message: 'uncoded failure' } }, + } as SessionEvent) + expect(out.text()).toContain('[turn failed] uncoded failure') + ctx.emit('session/event', session, { + type: 'turn/end', seq: 3, time: 0, data: { turn: 3, reason: { kind: 'aborted', reason: 'user cancelled' } }, + } as SessionEvent) + expect(out.text()).toContain('[turn aborted] user cancelled') + ctx.emit('session/event', session, { + type: 'turn/end', seq: 4, time: 0, data: { turn: 4, reason: { kind: 'aborted' } }, + } as SessionEvent) + expect(out.text()).toContain('[turn aborted]\n> ') + ctx.emit('session/event', session, { + type: 'turn/end', seq: 5, time: 0, data: { turn: 5, reason: { kind: 'rejected', reason: 'policy veto' } }, + } as SessionEvent) + expect(out.text()).toContain('[turn rejected] policy veto') + ctx.emit('session/event', session, { + type: 'turn/end', seq: 6, time: 0, data: { turn: 6, reason: { kind: 'max-tokens' } }, + } as SessionEvent) + expect(out.text()).toContain('[turn hit the output-token limit]') + ctx.emit('session/event', session, { + type: 'turn/end', seq: 7, time: 0, data: { turn: 7, reason: { kind: 'interrupted' } }, + } as SessionEvent) + expect(out.text()).toContain('[turn interrupted by a previous process exit]') + }) + it('uses the session id as the label for a non-target session', async () => { const { ctx, out } = await setup() // No target exists, so the event's durable identity is the label. @@ -814,7 +849,7 @@ describe('createStdioChat input', () => { await new Promise(r => setImmediate(r)) expect(error).toHaveBeenCalledWith( - 'ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): ', + 'ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): ', ) }) @@ -902,7 +937,7 @@ describe('createStdioChat EOF exit', () => { await flushExit() expect(error).toHaveBeenCalledWith( - 'ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): ', + 'ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): ', ) expect(exit).toHaveBeenCalledWith(0) }) diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index 1c3fc1315c..ae0c480dde 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -35,6 +35,7 @@ import type { Context } from 'cordis' import z from 'schemastery' import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent' import type {} from '@deepseek-ai/dsh-agent-loop' +import { errorChain } from '@deepseek-ai/dsh-llm' import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm' import { SessionId, type Session, type SessionEvent, type TodoItem } from '@deepseek-ai/dsh-session' import type { @@ -191,15 +192,6 @@ function displayText(text: string): string { `\\x${control.charCodeAt(0).toString(16).padStart(2, '0')}`) } -/** Render an arbitrary failure without allowing hostile coercion to escape the UI boundary. */ -function renderThrown(value: unknown): string { - try { - return String(value) - } catch { - return '' - } -} - /** * Theme-agnostic palette built from the standard 16-color ANSI set plus SGR * attributes, which every terminal remaps to its active color scheme. Body @@ -1263,7 +1255,9 @@ export function createTuiChat( const disposeError = ctx.on('agent/error', (subject, turn, step, error) => { if (subject !== agent) return liveErrors.add(`${turn}:${step}`) - appendNotice(error.message, 'error') + // Full cause chain: wrapper messages like `fetch failed` carry the + // actionable transport detail on `cause`. + appendNotice(errorChain(error), 'error') }) const disposeAgent = ctx.on('agent/disposed', (subject) => { if (subject !== agent) return @@ -1330,7 +1324,7 @@ export function mountTui(ctx: Context, config: Config, runtime: TuiRuntime): voi if (settled || failedSessionId !== sessionId) return settled = true stopWaiting() - runtime.terminal.write(displayText(`ui-tui: session "${sessionId}" failed to start: ${renderThrown(error)}\n`)) + runtime.terminal.write(displayText(`ui-tui: session "${sessionId}" failed to start: ${errorChain(error)}\n`)) runtime.exit(1) } diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 27200e0fa9..8e0df2cc75 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -864,7 +864,7 @@ describe('terminal mounting', () => { expect(terminal.output).toBe('') expect(exit).not.toHaveBeenCalled() ctx.emit('agent-loop/config-start-failed', SessionId('main-session'), new Error('resume \u001b]2;failure-controlled\u0007')) - expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: Error: resume \\x1b]2;failure-controlled\\x07\n') + expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: resume \\x1b]2;failure-controlled\\x07\n') expect(exit).toHaveBeenCalledWith(1) const session = ctx.sessions.create(SessionId('main-session')) @@ -892,7 +892,7 @@ describe('terminal mounting', () => { }) expect(terminal.started).toBe(0) - expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: \n') + expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: \n') expect(exit).toHaveBeenCalledWith(1) await ctx.fiber.dispose() }) diff --git a/website/zh-CN/api/harness/agent-loop.md b/website/zh-CN/api/harness/agent-loop.md index 9a43a1ba14..750f6a49dc 100644 --- a/website/zh-CN/api/harness/agent-loop.md +++ b/website/zh-CN/api/harness/agent-loop.md @@ -6,7 +6,7 @@ Concrete agent factory and driver service. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L407) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L398) ### ctx.agentLoop.create(id, options?, meta?) @@ -31,7 +31,7 @@ Create an agent and session under one caller-supplied identity, owned by the acc **Returns** the published running agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L542) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L533) ### ctx.agentLoop.createAgent(ownerCtx, options) @@ -52,7 +52,7 @@ Create an owned agent on a caller-supplied session id. **Returns** the published handle. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L564) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L555) ### ctx.agentLoop.resume(ownerCtx, options) @@ -73,4 +73,4 @@ Resume an owned agent from the configured persistence service. **Returns** the published handle. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L596) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L587) diff --git a/website/zh-CN/api/harness/events.md b/website/zh-CN/api/harness/events.md index a9ce1990c0..30298bdc97 100644 --- a/website/zh-CN/api/harness/events.md +++ b/website/zh-CN/api/harness/events.md @@ -423,7 +423,7 @@ A declarative agent entry failed before it could publish a live agent. Consumers - `sessionId` — exact shared agent/session identity that failed startup. - `error` — persistence, setup, or publication failure. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L362) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L353) ## approval/* From 3a1b500cefdcdcac688110b2ab218b0ed3c7dc21 Mon Sep 17 00:00:00 2001 From: Turtle Date: Mon, 20 Jul 2026 14:48:05 +0800 Subject: [PATCH 42/53] fix(tui): detect terminal color scheme and apply light-optimised palette --- packages/ui/tui/src/index.ts | 37 +++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index ae0c480dde..41abe9c7d8 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -30,6 +30,7 @@ import { type OverlayHandle, type SelectListTheme, type Terminal, + type TerminalColorScheme, } from '@earendil-works/pi-tui' import type { Context } from 'cordis' import z from 'schemastery' @@ -199,17 +200,21 @@ function displayText(text: string): string { * backgrounds alike; grouping uses foreground-only gutter bars and reverse * video rather than fixed background fills. */ -function createPalette(enabled: boolean): Palette { +function createPalette(enabled: boolean, scheme: TerminalColorScheme = 'dark'): Palette { return { accent: ansi('94', '39', enabled), accent2: ansi('95', '39', enabled), text: text => text, muted: ansi('90', '39', enabled), - dim: ansi('2', '22', enabled), + // SGR 2 (dim) lightens text on a light background — substitute ANSI 90 + // (bright black / gray) which renders as a readable muted tone on any scheme. + dim: scheme === 'light' ? ansi('90', '39', enabled) : ansi('2', '22', enabled), success: ansi('32', '39', enabled), warning: ansi('33', '39', enabled), error: ansi('31', '39', enabled), - code: ansi('36', '39', enabled), + // ANSI 36 (cyan) is difficult to read on a light background — use + // ANSI 34 (blue) which is legible on both light and dark schemes. + code: scheme === 'light' ? ansi('34', '39', enabled) : ansi('36', '39', enabled), added: ansi('32', '39', enabled), removed: ansi('31', '39', enabled), bold: ansi('1', '22', enabled), @@ -1123,6 +1128,31 @@ export function createTuiChat( { name: 'exit', description: 'Exit after the active turn reaches idle' }, ], agent.session.header.cwd ?? process.cwd())) + /** Swap the palette and all derived themes for the given terminal color scheme. */ + const applyColorScheme = (scheme: TerminalColorScheme): void => { + if (scheme === currentScheme) return + currentScheme = scheme + Object.assign(palette, createPalette(resolved.color, scheme)) + Object.assign(mdTheme, markdownTheme(palette)) + editor.borderColor = text => palette.dim(text) + rebuildTranscript(false) + setStatus(agent.status) + requestRender() + } + let currentScheme: TerminalColorScheme = 'dark' + + // Detect the terminal's color scheme via device-status report. Most terminals + // do not respond, so the promise settles with `undefined` and we keep the + // dark-optimised palette. + ui.queryTerminalColorScheme({ timeoutMs: 2000 }).then((scheme) => { + if (scheme !== undefined) applyColorScheme(scheme) + }).catch(() => { + // Timeout or query failure — keep dark default. + }) + + // Live-update when the user switches their terminal theme behind us. + const disposeSchemeListener = ui.onTerminalColorSchemeChange(applyColorScheme) + const toggleTools = (): void => { toolsExpanded = !toolsExpanded for (const card of allToolCards) card.setExpanded(toolsExpanded) @@ -1271,6 +1301,7 @@ export function createTuiChat( disposeStatus() disposeError() disposeAgent() + disposeSchemeListener() } rebuildTranscript(true) From a661f5c8f329c022e5510dc5f8ba6467d5a935ca Mon Sep 17 00:00:00 2001 From: Turtle Date: Mon, 20 Jul 2026 14:54:09 +0800 Subject: [PATCH 43/53] test(tui): prove color scheme detection switches palette ANSI codes --- packages/ui/tui/tests/tui.spec.ts | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 8e0df2cc75..51a3ee4ec0 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -936,4 +936,31 @@ describe('terminal mounting', () => { expect(() => createTuiChat(ctx, { sessionId: 'missing' }, runtime)).toThrow('is not running') await ctx.fiber.dispose() }) + + it('detects a light terminal color scheme and switches from dark- to light-optimised ANSI codes', async () => { + const result = await setup({ config: { color: true } }) + // Initial render uses dark-optimised palette: SGR 2 (dim) for dim text. + expect(result.terminal.output).toContain('\x1b[2mdeepseek-v4-flash') + + // Simulate the terminal responding with a light color scheme report + // (ESC [?997;2n = light, ESC [?997;1n = dark). + result.terminal.send('\x1b[?997;2n') + await tick() + await tick() + + // After switching to light-optimised palette: palette.dim uses ANSI 90 + // (gray) instead of SGR 2. The header now uses \x1b[90m for the detail + // line. The cumulative output still contains the initial SGR 2 render, + // so we assert that a LATER write (appended after the scheme switch) + // uses ANSI 90 for the same header text. + expect(result.terminal.output).toContain('\x1b[90mdeepseek-v4-flash') + + // Switch back to dark scheme. + result.terminal.send('\x1b[?997;1n') + await tick() + await tick() + // After switching back, a new write uses SGR 2 for the header detail. + expect(result.terminal.output).toContain('\x1b[2mdeepseek-v4-flash') + await dispose(result) + }) }) From 734bd40bb67de5663715dbe7b02f63079d1b7345 Mon Sep 17 00:00:00 2001 From: Turtle Date: Mon, 20 Jul 2026 19:03:15 +0800 Subject: [PATCH 44/53] docs: regenerate config catalog after stacking on #425 --- docs/config-catalog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index a4eedf25cc..e5ac98b5c8 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -1302,7 +1302,7 @@ export interface TuiConfig { } ``` -Source: [`packages/ui/tui/src/index.ts:101`](../packages/ui/tui/src/index.ts) +Source: [`packages/ui/tui/src/index.ts:102`](../packages/ui/tui/src/index.ts) ## `@deepseek-ai/dsh-user-approval` From 37f2c15e6854135d2b17316aaa291b8e3c862b9c Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 20 Jul 2026 21:03:01 +0800 Subject: [PATCH 45/53] fix(fs-sandbox): recognize Windows path aliases --- ...26-07-14-cross-family-fs-sandbox.i18n.yaml | 4 +- .../2026-07-14-cross-family-fs-sandbox.md | 6 +- .../2026-07-14-cross-family-fs-sandbox.zh.md | 6 +- packages/fs/fs-sandbox/README.md | 4 +- packages/fs/fs-sandbox/src/containment.ts | 74 +++++++++++++++++++ packages/fs/fs-sandbox/src/index.ts | 18 ++--- .../fs/fs-sandbox/tests/containment.spec.ts | 56 ++++++++++++++ .../fs/fs-sandbox/tests/fs-sandbox.spec.ts | 13 ++-- 8 files changed, 155 insertions(+), 26 deletions(-) create mode 100644 packages/fs/fs-sandbox/src/containment.ts create mode 100644 packages/fs/fs-sandbox/tests/containment.spec.ts diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml index 8e44e3a6bc..41246ca3b3 100644 --- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -2026-07-14-cross-family-fs-sandbox.md: 9b6312e5994469606bd1645902fc798f70258580 -2026-07-14-cross-family-fs-sandbox.zh.md: d4816e03d94bdf12b2db875d71dccb7db3a2c0d7 +2026-07-14-cross-family-fs-sandbox.md: 0897695cc14b7573ebb53f3ffa6a460652882b37 +2026-07-14-cross-family-fs-sandbox.zh.md: 15de061a0d2b18392f839c927e9b0f5d0cacf28b diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md index 9b6312e599..0897695cc1 100644 --- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md +++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md @@ -31,7 +31,7 @@ Three coordinated pieces, all composed from the leaf `cordis.yml`, none touching `packages/fs/fs-sandbox/` (`@deepseek-ai/dsh-fs-sandbox`) mirrors the `bash-local`/`bash-sandbox` split: `SandboxedFileSystem extends LocalFileSystem`, registered as `ctx.fs`, injecting `sandboxPolicy`. Reads (`resolve`/`stat`/`readText`/`streamText`/`listDir`) pass through untouched — every mode permits reading. The two mutations enforce by mode before delegating to the inherited atomic write: - `read-only` denies `writeText`/`editText` outright. -- `workspace-write` fences the canonicalized target against the writable-root set — `writableRoots(policy)` in `dsh-sandbox`: the workspace root plus the platform temp areas (`/tmp`, `os.tmpdir()`), each realpathed — the SAME set the Seatbelt profile grants, so the fs fence is the fourth dialect of one mode meaning alongside the bwrap/Landlock/Seatbelt profiles, and "the write tool cannot write `/tmp` but bash can" asymmetries cannot arise. Containment is prefix-inclusion on real paths; the target is re-canonicalized (`resolve` realpaths the deepest existing ancestor) immediately before delegating, so an ancestor symlink swapped since the tool resolved it is caught. +- `workspace-write` fences the canonicalized target against the writable-root set — `writableRoots(policy)` in `dsh-sandbox`: the workspace root plus the platform temp areas (`/tmp`, `os.tmpdir()`), each realpathed — the SAME set the Seatbelt profile grants, so the fs fence is the fourth dialect of one mode meaning alongside the bwrap/Landlock/Seatbelt profiles, and "the write tool cannot write `/tmp` but bash can" asymmetries cannot arise. Canonical spellings take a lexical containment fast path; when Windows exposes one directory through different casing or long-name/8.3 spellings, an ancestor walk compares filesystem identity rather than weakening the boundary to textual prefix guesses. The target is re-canonicalized (`resolve` realpaths the deepest existing ancestor) immediately before delegating, so an ancestor symlink swapped since the tool resolved it is caught. - `danger-full-access` delegates unfenced. A denial is the structured `FS_SANDBOX_DENIED` carrying the effective mode — distinct from `FS_PERMISSION_DENIED` (a host EACCES is the world refusing; this is policy refusing). No text inference: an in-process fence knows exactly what it denied. The per-call carrier is a trailing optional `sandboxMode` on `writeText`/`editText` (the filesystem twin of `BashExecRequest.sandboxMode`); the seam stays session-free (the caller stamps, exactly as `resolve` takes a cwd), and the bare local backend carries-and-ignores it. `FileSystem.sandboxMode` is the capability fact (`undefined` on the base and `fs-local`, the default on `SandboxedFileSystem`), so the tool layer advertises escalation from composition truth. @@ -74,7 +74,7 @@ The sandbox Agent Note's original cross-family sketch put fs enforcement on the What shipped — the tiers in § Testing hold each: - Under `read-only`, `write`/`edit` return the `[sandbox: file access denied under read-only mode]` marker and the disk is untouched; `read`/`listDir` behave identically to `dsh-fs-local`. -- Under `workspace-write`, mutations land under the workspace root and the temp areas and are denied outside; the containment matrix — `..` traversal, absolute paths outside, a pre-existing symlinked directory inside pointing out, and a new file created under such a symlink — denies every escape on real disks. +- Under `workspace-write`, mutations land under the workspace root and the temp areas and are denied outside; the containment matrix — `..` traversal, absolute paths outside, a pre-existing symlinked directory inside pointing out, a new file created under such a symlink, and alias-equivalent root spellings — denies every escape while admitting the same directory identity on real disks. - A denied fs mutation retried once with `sandbox_permissions` + `justification` prompts through the composed approval chain; a grant runs exactly that call under the wider mode and the write lands; rejected/cancelled/unavailable each produce their verbatim fail-closed text and mutate nothing. - One `permission` preset switch governs both families: after a session switches modes, the next bash call and the next fs mutation both honor the new mode from the same `sandbox/mode` fold. - A direct `ctx.fs.writeText` with no per-call stamp is confined at the deployment default. @@ -90,5 +90,5 @@ Costs and accepted limits: ## Testing -- Unit: `dsh-sandbox` pins the escalation ladder, the marker builders, the argument-pairing validation, and `approveEscalation`'s ordered fail-closed sequence (non-widening, no-approval, no-agent, each outcome), plus `writableRoots`/`canonicalPath`. `dsh-sandbox-policy` pins the default accessors, the fold/setter, the load-time mode rejection, and HMR safety. `dsh-fs-sandbox` pins the per-mode fence and the containment matrix (inside, temp area, absolute-outside, `..`, symlinked-out directory, new file under one, path-equals-root, root-ending-in-separator) on a real filesystem, plus the per-call override and HMR safety. `dsh-tool-fs` pins advertisement gating, the mode stamp, the fold, denial-marker mapping, and the full escalation matrix (grant, reject, no-service, no-agent, pairing, non-confining guard). `dsh-tool-bash`, `dsh-bash-sandbox`, and `dsh-permission` migrate to the relocated policy/kit. +- Unit: `dsh-sandbox` pins the escalation ladder, the marker builders, the argument-pairing validation, and `approveEscalation`'s ordered fail-closed sequence (non-widening, no-approval, no-agent, each outcome), plus `writableRoots`/`canonicalPath`. `dsh-sandbox-policy` pins the default accessors, the fold/setter, the load-time mode rejection, and HMR safety. `dsh-fs-sandbox` pins the per-mode fence and the containment matrix (inside, temp area, absolute-outside, `..`, symlinked-out directory, new file under one, path-equals-root, filesystem-root, and alias-equivalent spelling) on a real filesystem, plus the per-call override and HMR safety. `dsh-tool-fs` pins advertisement gating, the mode stamp, the fold, denial-marker mapping, and the full escalation matrix (grant, reject, no-service, no-agent, pairing, non-confining guard). `dsh-tool-bash`, `dsh-bash-sandbox`, and `dsh-permission` migrate to the relocated policy/kit. - Snapshot: the acp-agent example composes `dsh-sandbox-policy` + `dsh-fs-sandbox`; the pinned header carries the fs escalation fields and the `sandbox/mode` event name, re-recorded once. diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md index d4816e03d9..15de061a0d 100644 --- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md +++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md @@ -31,7 +31,7 @@ Status: implemented `packages/fs/fs-sandbox/`(`@deepseek-ai/dsh-fs-sandbox`)镜像 `bash-local`/`bash-sandbox` 的拆分:`SandboxedFileSystem extends LocalFileSystem`,注册为 `ctx.fs`,注入 `sandboxPolicy`。读取(`resolve`/`stat`/`readText`/`streamText`/`listDir`)原样透传——每种模式都允许读。两个变更操作在委托给继承来的原子写之前按模式执行: - `read-only` 直接拒绝 `writeText`/`editText`。 -- `workspace-write` 把规范化后的目标围栏于可写根集合——`dsh-sandbox` 中的 `writableRoots(policy)`:工作区根加上平台临时目录(`/tmp`、`os.tmpdir()`),各自 realpath——与 Seatbelt profile 授予的是同一个集合,所以 fs 围栏是这一个模式含义在 bwrap/Landlock/Seatbelt profile 之外的第四种方言,因此不会出现「write 工具不能写 `/tmp` 而 bash 能」的不对称。包含判定是对真实路径的前缀包含;目标在委托前被立即重新规范化(`resolve` 对最深的既有祖先做 realpath),因此自工具解析该目标以来被换出的祖先符号链接会被捕获。 +- `workspace-write` 把规范化后的目标围栏于可写根集合——`dsh-sandbox` 中的 `writableRoots(policy)`:工作区根加上平台临时目录(`/tmp`、`os.tmpdir()`),各自 realpath——与 Seatbelt profile 授予的是同一个集合,所以 fs 围栏是这一个模式含义在 bwrap/Landlock/Seatbelt profile 之外的第四种方言,因此不会出现「write 工具不能写 `/tmp` 而 bash 能」的不对称。规范化路径写法采用词法包含的快速路径；当 Windows 以大小写不同的路径、长文件名或 8.3 短文件名表示同一目录时，系统会逐级遍历祖先目录并比较文件系统身份，而不会把边界弱化为依据文本前缀猜测包含关系。目标在委托前被立即重新规范化(`resolve` 对最深的既有祖先做 realpath),因此自工具解析该目标以来被换出的祖先符号链接会被捕获。 - `danger-full-access` 不加围栏地委托。 拒绝是结构化的 `FS_SANDBOX_DENIED`,携带生效模式——区别于 `FS_PERMISSION_DENIED`(宿主 EACCES 是世界在拒绝;这里是策略在拒绝)。无文本推断:进程内围栏确切知道它拒绝了什么。per-call 载体是 `writeText`/`editText` 上一个末尾可选的 `sandboxMode`(文件系统侧对应 `BashExecRequest.sandboxMode`);该 seam 保持无会话依赖(由调用方盖章,正如 `resolve` 接收一个 cwd),而裸的本地后端携带并忽略它。`FileSystem.sandboxMode` 是能力事实(在基类与 `fs-local` 上为 `undefined`,在 `SandboxedFileSystem` 上为默认值),所以工具层按组合真相来宣告升级。 @@ -74,7 +74,7 @@ Status: implemented 已交付的部分——§ Testing 的各层各自钉住: - 在 `read-only` 下,`write`/`edit` 返回 `[sandbox: file access denied under read-only mode]` 标记,磁盘不受触动;`read`/`listDir` 与 `dsh-fs-local` 行为一致。 -- 在 `workspace-write` 下,变更落在工作区根与临时目录下,其外被拒;包含矩阵——`..` 穿越、指向外部的绝对路径、一个既有的、指向外部的工作区内符号链接目录,以及在这样一个符号链接下新建的文件——在真实磁盘上拒绝每一种逃逸。 +- 在 `workspace-write` 下,变更落在工作区根与临时目录下,其外被拒;包含矩阵——`..` 穿越、指向外部的绝对路径、一个既有的、指向外部的工作区内符号链接目录、在这样一个符号链接下新建的文件,以及根路径的等价别名形式——在真实磁盘上拒绝每一种逃逸,同时允许文件系统认定为同一目录的路径。 - 一个被拒的 fs 变更,携带 `sandbox_permissions` + `justification` 重试一次,会经组合的审批链提示;一次授权让恰好那一次调用在更宽的模式下运行且写入落盘;rejected/cancelled/unavailable 各自产生其逐字的 fail-closed 文案且不做任何变更。 - 一次 `permission` 预设切换同时管辖两个家族:会话切换模式后,下一次 bash 调用与下一次 fs 变更都从同一个 `sandbox/mode` 折叠遵循新模式。 - 一次无 per-call 盖章的直连 `ctx.fs.writeText` 会被围栏于部署默认值。 @@ -90,5 +90,5 @@ Status: implemented ## Testing -- 单元:`dsh-sandbox` 钉住升级阶梯、标记构造器、参数配对校验,以及 `approveEscalation` 的有序 fail-closed 序列(非加宽、无 approval、无 agent、各结果),外加 `writableRoots`/`canonicalPath`。`dsh-sandbox-policy` 钉住默认访问器、折叠/setter、加载期模式拒绝,以及 HMR 安全。`dsh-fs-sandbox` 在真实文件系统上钉住 per-mode 围栏与包含矩阵(内部、临时目录、绝对路径-外部、`..`、指向外部的符号链接目录、其下的新建文件、路径等于根、以分隔符结尾的根),外加 per-call 覆盖与 HMR 安全。`dsh-tool-fs` 钉住宣告门控、模式盖章、折叠、拒绝标记映射,以及完整的升级矩阵(授权、拒绝、无服务、无 agent、配对、非受限守卫)。`dsh-tool-bash`、`dsh-bash-sandbox` 与 `dsh-permission` 迁移到迁移后的策略/工具集。 +- 单元:`dsh-sandbox` 钉住升级阶梯、标记构造器、参数配对校验,以及 `approveEscalation` 的有序 fail-closed 序列(非加宽、无 approval、无 agent、各结果),外加 `writableRoots`/`canonicalPath`。`dsh-sandbox-policy` 钉住默认访问器、折叠/setter、加载期模式拒绝,以及 HMR 安全。`dsh-fs-sandbox` 在真实文件系统上钉住 per-mode 围栏与包含矩阵(内部、临时目录、绝对路径-外部、`..`、指向外部的符号链接目录、其下的新建文件、路径等于根、文件系统根、等价别名形式),外加 per-call 覆盖与 HMR 安全。`dsh-tool-fs` 钉住宣告门控、模式盖章、折叠、拒绝标记映射,以及完整的升级矩阵(授权、拒绝、无服务、无 agent、配对、非受限守卫)。`dsh-tool-bash`、`dsh-bash-sandbox` 与 `dsh-permission` 迁移到迁移后的策略/工具集。 - 快照:acp-agent 示例组合 `dsh-sandbox-policy` + `dsh-fs-sandbox`;被钉住的 header 携带 fs 升级字段与 `sandbox/mode` 事件名,一次性重录。 diff --git a/packages/fs/fs-sandbox/README.md b/packages/fs/fs-sandbox/README.md index 685ab838c8..c7043e2e70 100644 --- a/packages/fs/fs-sandbox/README.md +++ b/packages/fs/fs-sandbox/README.md @@ -9,14 +9,14 @@ Loading it INSTEAD OF `dsh-fs-local`, together with a [`ctx.sandboxPolicy`](../. The per-call mode is the tool-stamped effective mode (session override or escalation grant), falling back to the deployment default: - `read-only` — denies every mutation with the structured `FS_SANDBOX_DENIED`. -- `workspace-write` — allows a mutation only when the target canonicalizes under a writable root: the workspace root plus the platform temp areas (`/tmp`, `os.tmpdir()`), the SAME set the Seatbelt profile grants, derived from the one [`writableRoots`](../../sandbox/README.md) function so the fs fence and the bash runner cannot drift. The target is re-canonicalized immediately before delegating, so an ancestor symlink swapped since the tool resolved it is caught. +- `workspace-write` — allows a mutation only when the target canonicalizes under a writable root: the workspace root plus the platform temp areas (`/tmp`, `os.tmpdir()`), the SAME set the Seatbelt profile grants, derived from the one [`writableRoots`](../../sandbox/README.md) function so the fs fence and the bash runner cannot drift. Canonical spellings use a lexical fast path; an identity-based ancestor fallback recognizes alias-equivalent roots such as Windows long names and 8.3 names without treating unrelated prefixes as contained. The target is re-canonicalized immediately before delegating, so an ancestor symlink swapped since the tool resolved it is caught. - `danger-full-access` — delegates unfenced. ## Threat model: a policy fence, not a kernel boundary The fence is a check in TRUSTED code over a MODEL-CONTROLLED path — the operations are the seam's own (open, rename), only the target path is untrusted, so canonicalize-then-contain is the complete answer to this surface. This mirrors the `code-runtime` stance: containment, not a security boundary. Kernel-grade isolation of untrusted CODE stays `ctx.bash`'s job ([`dsh-bash-sandbox`](../../bash/bash-sandbox/README.md)). The residual TOCTOU (an ancestor symlink swapped between the containment re-check and the syscall) is narrowed by re-canonicalizing immediately before the write and is accepted for this threat model; a kernel-tight boundary needs `openat2`-class primitives not worth their portability cost here. -A denial is a structured `FsError` (`FS_SANDBOX_DENIED`, carrying the effective mode) — no stderr text inference (unlike bash's kernel denials), because an in-process fence knows exactly what it refused. The model-facing `[sandbox: file access denied under mode]` marker and the one-approved-wider retry live in the tool layer (`dsh-tool-fs`), exactly as bash's do. See [the cross-family fs sandbox RFC](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md). +A denial is a structured `FsError` (`FS_SANDBOX_DENIED`, carrying the effective mode) — no stderr text inference (unlike bash's kernel denials), because an in-process fence knows exactly what it refused. The model-facing `[sandbox: file access denied under mode]` marker and the one-approved-wider retry live in the tool layer (`dsh-tool-fs`), exactly as bash's do. See [the cross-family fs sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md). ## Model Experience diff --git a/packages/fs/fs-sandbox/src/containment.ts b/packages/fs/fs-sandbox/src/containment.ts new file mode 100644 index 0000000000..782ceb151d --- /dev/null +++ b/packages/fs/fs-sandbox/src/containment.ts @@ -0,0 +1,74 @@ +/** + * Path-containment mechanics for the filesystem sandbox. Canonical spellings + * take the fast lexical path; filesystem identity supplies the conservative + * fallback for alias-equivalent roots such as Windows 8.3 names and casing. + * @module @deepseek-ai/dsh-fs-sandbox/containment + */ + +import type { BigIntStats } from 'node:fs' +import { stat } from 'node:fs/promises' +import { dirname, sep } from 'node:path' + +function isMissing(error: unknown): boolean { + const code = (error as NodeJS.ErrnoException).code + return code === 'ENOENT' || code === 'ENOTDIR' +} + +function comparablePath(path: string, caseSensitive: boolean): string { + return caseSensitive ? path : path.toLowerCase() +} + +function isLexicallyUnder(path: string, root: string, caseSensitive: boolean): boolean { + const comparableTarget = comparablePath(path, caseSensitive) + const comparableRoot = comparablePath(root, caseSensitive) + if (comparableTarget === comparableRoot) return true + const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep + return comparableTarget.startsWith(prefix) +} + +async function statIfPresent(path: string): Promise { + try { + return await stat(path, { bigint: true }) + } catch (error: unknown) { + /* v8 ignore else -- a non-missing stat failure requires a host permission or I/O fault after resolve reached this ancestor. */ + if (isMissing(error)) return undefined + /* v8 ignore next -- requires a host permission or I/O fault after resolve already reached this ancestor. */ + throw error + } +} + +function sameIdentity(left: BigIntStats, right: BigIntStats): boolean { + return left.dev === right.dev && left.ino === right.ino +} + +/** + * Determine whether a canonical target is a writable root or lies beneath it. + * The lexical fast path handles normal canonical spellings. When spellings + * differ, walk the target's existing ancestors and compare filesystem identity + * with the root; this recognizes Windows long-name/8.3 aliases and casing + * without weakening containment to a textual approximation. + * @param path - canonical target key, which may end in a missing suffix. + * @param root - canonical writable root. + * @param caseSensitive - whether lexical comparison preserves case; defaults + * to the host filesystem convention used by supported platforms. + * @returns whether the target is the root or a descendant of it. + */ +export async function isPathUnder( + path: string, + root: string, + caseSensitive = process.platform !== 'win32', +): Promise { + if (isLexicallyUnder(path, root, caseSensitive)) return true + + const rootInfo = await statIfPresent(root) + if (!rootInfo) return false + + let ancestor = path + while (true) { + const ancestorInfo = await statIfPresent(ancestor) + if (ancestorInfo && sameIdentity(ancestorInfo, rootInfo)) return true + const parent = dirname(ancestor) + if (parent === ancestor) return false + ancestor = parent + } +} diff --git a/packages/fs/fs-sandbox/src/index.ts b/packages/fs/fs-sandbox/src/index.ts index 314778968e..5268412955 100644 --- a/packages/fs/fs-sandbox/src/index.ts +++ b/packages/fs/fs-sandbox/src/index.ts @@ -30,7 +30,6 @@ * @module @deepseek-ai/dsh-fs-sandbox */ -import { sep } from 'node:path' import { Context } from 'cordis' import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local' import type { Config as LocalConfig } from '@deepseek-ai/dsh-fs-local' @@ -39,6 +38,7 @@ import type { FsEditOutcome, FsEditRequest, FsTarget, FsVersion, FsWriteIntent, import { writableRoots } from '@deepseek-ai/dsh-sandbox' import type { SandboxMode } from '@deepseek-ai/dsh-sandbox' import type {} from '@deepseek-ai/dsh-sandbox-policy' +import { isPathUnder } from './containment.ts' /** * Plugin config: the local backend's knobs, verbatim (only `cwd`, the resolve @@ -48,13 +48,6 @@ import type {} from '@deepseek-ai/dsh-sandbox-policy' */ export type Config = LocalConfig -/** Whether `path` is `root` itself or lies beneath it (both already canonical). */ -function isUnder(path: string, root: string): boolean { - if (path === root) return true - const prefix = root.endsWith(sep) ? root : root + sep - return path.startsWith(prefix) -} - /** * Sandbox-enforcing filesystem backend. Registers as `ctx.fs` (loading it * INSTEAD OF `dsh-fs-local`, together with a `ctx.sandboxPolicy`, is the whole @@ -147,7 +140,14 @@ export class SandboxedFileSystem extends LocalFileSystem { // symlink ancestor swapped since the tool resolved this target), and the // mutation delegates with THIS fresh target — never the stale one. const fresh = await this.resolve(target.displayPath) - if (!this.writableRoots.some(root => isUnder(fresh.targetKey, root))) { + let contained = false + for (const root of this.writableRoots) { + if (await isPathUnder(fresh.targetKey, root)) { + contained = true + break + } + } + if (!contained) { throw new FsError(`cannot write "${target.displayPath}": file access denied under workspace-write mode`, 'FS_SANDBOX_DENIED') } return fresh diff --git a/packages/fs/fs-sandbox/tests/containment.spec.ts b/packages/fs/fs-sandbox/tests/containment.spec.ts new file mode 100644 index 0000000000..30821cc826 --- /dev/null +++ b/packages/fs/fs-sandbox/tests/containment.spec.ts @@ -0,0 +1,56 @@ +/** + * Containment tests for lexical canonical paths and filesystem-identity aliases. + */ + +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { mkdir, mkdtemp, realpath, rm, symlink, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join, parse } from 'node:path' +import { isPathUnder } from '../src/containment.ts' + +let base: string + +beforeEach(async () => { + base = await mkdtemp(join(tmpdir(), 'dsh-fssbx-containment-')) +}) + +afterEach(async () => { + await rm(base, { recursive: true, force: true }) +}) + +describe('filesystem sandbox containment', () => { + it('accepts equal paths, descendants, and a filesystem-root boundary', async () => { + expect(await isPathUnder(base, base)).toBe(true) + expect(await isPathUnder(join(base, 'child'), base)).toBe(true) + expect(await isPathUnder(base, parse(base).root)).toBe(true) + }) + + it('uses case-insensitive lexical comparison for Windows-style containment', async () => { + expect(await isPathUnder(join(base.toUpperCase(), 'child'), base.toLowerCase(), false)).toBe(true) + }) + + it('recognizes an alias-equivalent root by filesystem identity for a missing target', async () => { + const realRoot = join(base, 'real') + const aliasRoot = join(base, 'alias') + await mkdir(realRoot) + await symlink(realRoot, aliasRoot) + expect(await isPathUnder(join(await realpath(realRoot), 'missing', 'file.txt'), aliasRoot)).toBe(true) + }) + + it('denies unrelated and missing roots', async () => { + const allowed = join(base, 'allowed') + const outside = join(base, 'outside') + await mkdir(allowed) + await mkdir(outside) + expect(await isPathUnder(join(outside, 'file.txt'), allowed)).toBe(false) + expect(await isPathUnder(join(outside, 'file.txt'), join(base, 'missing-root'))).toBe(false) + }) + + it('treats a regular-file path segment as a missing target, not containment', async () => { + const allowed = join(base, 'allowed') + const blocker = join(base, 'blocker') + await mkdir(allowed) + await writeFile(blocker, 'not a directory') + expect(await isPathUnder(join(blocker, 'child.txt'), allowed)).toBe(false) + }) +}) diff --git a/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts b/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts index 12f0abb0df..65472f2ece 100644 --- a/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts +++ b/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts @@ -12,7 +12,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest' import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises' import { existsSync } from 'node:fs' import { homedir, tmpdir } from 'node:os' -import { join } from 'node:path' +import { join, parse } from 'node:path' import { Context } from 'cordis' import { FsError, FsTargetKey } from '@deepseek-ai/dsh-fs' import type { FsTarget } from '@deepseek-ai/dsh-fs' @@ -167,16 +167,15 @@ describe('workspace-write containment', () => { }) describe('workspace-write with the filesystem root as the workspace (a root ending in the path separator)', () => { - it('grants writes anywhere: containment against `/` allows any absolute path', async () => { - // A degenerate but valid config — workspaceRoot '/'. It exercises isUnder's - // separator-suffixed-root branch: `/` already ends in the separator, so the - // prefix stays `/` and every absolute path is contained. + it('grants writes anywhere on that volume', async () => { + // A degenerate but valid config: the filesystem root containing the target. + // It exercises the separator-suffixed-root branch on POSIX and Windows. const rootCtx = new Context() - await rootCtx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: '/' }) + await rootCtx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: parse(base).root }) const rootFiber = await rootCtx.plugin(SandboxedFileSystem, { cwd: workspace }) const rootFs = rootCtx.fs as SandboxedFileSystem try { - const path = join(base, 'anywhere.txt') // under HOME, outside /tmp — allowed only via the `/` root + const path = join(base, 'anywhere.txt') // under HOME, outside temp — allowed only via the filesystem root await rootFs.writeText(await rootFs.resolve(path), 'anywhere') expect(await readFile(path, 'utf8')).toBe('anywhere') } finally { From 23379de6298c66b771a2d69332f534803ad9e133 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 20 Jul 2026 21:10:53 +0800 Subject: [PATCH 46/53] docs: retire removed stdio paths --- .../simplification/2026-07-04-fold-stdio-ui-helper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md index c44201b4e6..5ed4150883 100644 --- a/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md +++ b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md @@ -12,7 +12,7 @@ The boundary bought package metadata, workspace and tsconfig references, module- ## Decision -The helper lives in `@deepseek-ai/dsh-stdio` as the terminal-channel plugin (`packages/ui/stdio/src/index.ts`): `createStdioChat`, its `StdioRuntime` test seam, and its unit tests (`packages/ui/stdio/tests/stdio.spec.ts`, `readline.spec.ts`) moved with it, so EOF handling, rendering, disposal, and piped-vs-TTY behavior stay unit-covered under the per-file coverage gate without hijacking process globals. The module keeps the named `name`/`inject`/`Config`/`apply` export shape — the contract the app's `ctx.plugin(uiStdio, …)` mount consumes — and the keyless Loader-path smokes in `examples/echo-agent` and `examples/repl-agent` keep proving the composed tree boots through the real Loader (the stdio package's plugin-shape unit suite pins the explicit `unwrapExports` assertion, since a bundle without `inject` would boot past a stray default rather than crash). +At the time, the helper moved into `@deepseek-ai/dsh-stdio` as its terminal-channel plugin: `createStdioChat`, its `StdioRuntime` test seam, and its unit tests moved with it, so EOF handling, rendering, disposal, and piped-vs-TTY behavior stayed unit-covered under the per-file coverage gate without hijacking process globals. The module kept the named `name`/`inject`/`Config`/`apply` export shape — the contract the app's `ctx.plugin(uiStdio, …)` mount consumed — and the keyless Loader-path smokes in `examples/echo-agent` and `examples/repl-agent` kept proving the composed tree booted through the real Loader (the stdio package's plugin-shape unit suite pinned the explicit `unwrapExports` assertion, since a bundle without `inject` would boot past a stray default rather than crash). The `packages/support/ui-stdio` package is gone: manifest, tsconfig references, module-graph rows, and README rows deleted; the doc comments that named the package (the example e2e module docs, `packages/README.md`, the support and todo READMEs, [the ui group README](../../../../packages/ui/README.md)) describe the in-package module. From 7239513b982201abc1641b3960ad41a85af51bf9 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 20 Jul 2026 21:20:55 +0800 Subject: [PATCH 47/53] test(fs-sandbox): keep Windows coverage portable --- packages/fs/fs-sandbox/src/containment.ts | 4 +++- packages/fs/fs-sandbox/tests/containment.spec.ts | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/fs/fs-sandbox/src/containment.ts b/packages/fs/fs-sandbox/src/containment.ts index 782ceb151d..41b9bdd08a 100644 --- a/packages/fs/fs-sandbox/src/containment.ts +++ b/packages/fs/fs-sandbox/src/containment.ts @@ -9,9 +9,11 @@ import type { BigIntStats } from 'node:fs' import { stat } from 'node:fs/promises' import { dirname, sep } from 'node:path' +const MISSING_CODES: ReadonlySet = new Set(['ENOENT', 'ENOTDIR']) + function isMissing(error: unknown): boolean { const code = (error as NodeJS.ErrnoException).code - return code === 'ENOENT' || code === 'ENOTDIR' + return MISSING_CODES.has(code) } function comparablePath(path: string, caseSensitive: boolean): string { diff --git a/packages/fs/fs-sandbox/tests/containment.spec.ts b/packages/fs/fs-sandbox/tests/containment.spec.ts index 30821cc826..35dc52029b 100644 --- a/packages/fs/fs-sandbox/tests/containment.spec.ts +++ b/packages/fs/fs-sandbox/tests/containment.spec.ts @@ -27,6 +27,7 @@ describe('filesystem sandbox containment', () => { it('uses case-insensitive lexical comparison for Windows-style containment', async () => { expect(await isPathUnder(join(base.toUpperCase(), 'child'), base.toLowerCase(), false)).toBe(true) + expect(await isPathUnder(join(base, 'case-sensitive-child'), base, true)).toBe(true) }) it('recognizes an alias-equivalent root by filesystem identity for a missing target', async () => { From f81d382230c77b9d5cd53a64d29f203972166d08 Mon Sep 17 00:00:00 2001 From: Turtle Date: Mon, 20 Jul 2026 22:06:13 +0800 Subject: [PATCH 48/53] fix(tui): make color-scheme detection fully covered and race-free MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The color-scheme detection block left packages/ui/tui/src/index.ts below the 100% per-file coverage gate on three counts: the .then callback's `scheme === undefined` branch was reachable only via the 2s query timeout, the .catch only via a query-write failure, and the `editor.borderColor` assignment inside applyColorScheme was dead code — the next line's setStatus() immediately reassigns editor.borderColor. Register the scheme listener before firing the startup query so the query's own reply is delivered through the listener (the same path as later theme switches), which removes the redundant .then re-application and its uncoverable undefined branch, and closes the theoretical window where a synchronous reply lands before the listener exists. Drop the dead editor.borderColor line. Cover the rest: a same-scheme report (early return) and a terminal that throws on the query write (the swallowed .catch). --- packages/ui/tui/src/index.ts | 21 ++++++++++----------- packages/ui/tui/tests/tui.spec.ts | 26 ++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 11 deletions(-) diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index 9544d13cb0..17fef4c1e6 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -1134,25 +1134,24 @@ export function createTuiChat( currentScheme = scheme Object.assign(palette, createPalette(resolved.color, scheme)) Object.assign(mdTheme, markdownTheme(palette)) - editor.borderColor = text => palette.dim(text) rebuildTranscript(false) setStatus(agent.status) requestRender() } let currentScheme: TerminalColorScheme = 'dark' - // Detect the terminal's color scheme via device-status report. Most terminals - // do not respond, so the promise settles with `undefined` and we keep the - // dark-optimised palette. - ui.queryTerminalColorScheme({ timeoutMs: 2000 }).then((scheme) => { - if (scheme !== undefined) applyColorScheme(scheme) - }).catch(() => { - // Timeout or query failure — keep dark default. - }) - - // Live-update when the user switches their terminal theme behind us. + // Apply any color scheme the terminal reports. Registering before the query + // below means even a synchronous reply reaches `applyColorScheme`; in practice + // the startup query's reply is the only report, since dsh-tui leaves + // unsolicited color-scheme notifications disabled. const disposeSchemeListener = ui.onTerminalColorSchemeChange(applyColorScheme) + // Ask the terminal for its color scheme via device-status report; the reply, + // if any, arrives through the listener above. Most terminals do not respond, + // so we keep the dark-optimised palette. Swallow a query-write failure for the + // same reason. + ui.queryTerminalColorScheme({ timeoutMs: 2000 }).catch(() => {}) + const toggleTools = (): void => { toolsExpanded = !toolsExpanded for (const card of allToolCards) card.setExpanded(toolsExpanded) diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 51a3ee4ec0..3eacfa4fcf 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -942,6 +942,13 @@ describe('terminal mounting', () => { // Initial render uses dark-optimised palette: SGR 2 (dim) for dim text. expect(result.terminal.output).toContain('\x1b[2mdeepseek-v4-flash') + // A report matching the current scheme is a no-op: no palette rebuild or + // re-render (ESC [?997;1n = dark, the startup default). + const beforeSameScheme = result.terminal.output.length + result.terminal.send('\x1b[?997;1n') + await tick() + expect(result.terminal.output.length).toBe(beforeSameScheme) + // Simulate the terminal responding with a light color scheme report // (ESC [?997;2n = light, ESC [?997;1n = dark). result.terminal.send('\x1b[?997;2n') @@ -963,4 +970,23 @@ describe('terminal mounting', () => { expect(result.terminal.output).toContain('\x1b[2mdeepseek-v4-flash') await dispose(result) }) + + it('keeps the dark palette when the terminal rejects the color-scheme query', async () => { + class QueryFailTerminal extends FakeTerminal { + override write(data: string): void { + // The device-status query is the only write that fails; the promise + // rejects and the swallowed `.catch` leaves the dark palette in place. + if (data === '\x1b[?996n') throw new Error('query write failed') + super.write(data) + } + } + const terminal = new QueryFailTerminal() + const result = await createTuiTestHarness(terminal, vi.fn(), { + config: { color: true }, + cwd: process.cwd(), + }) + await tick() + expect(terminal.output).toContain('\x1b[2mdeepseek-v4-flash') + await disposeTuiTestHarness(result) + }) }) From 16163434233c3849b2bbd970ae92065dcf7be8d0 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 20 Jul 2026 22:50:19 +0800 Subject: [PATCH 49/53] test(tui): await validation render --- packages/ui/tui/tests/tui.spec.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 5e38967f42..fa8fed6381 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -819,8 +819,9 @@ describe('TUI user-interaction dialogs', () => { result.terminal.send('x') result.terminal.send(' ') result.terminal.send('\r') - await tick() - expect(result.terminal.output).toContain('Select at least one option') + await vi.waitFor(() => { + expect(result.terminal.output).toContain('Select at least one option') + }) result.terminal.send('c') await tick() result.terminal.send('\x1b') From a205ba4c29a514838638ff988a6b07fd6e4556c0 Mon Sep 17 00:00:00 2001 From: Turtle Date: Tue, 21 Jul 2026 09:42:12 +0800 Subject: [PATCH 50/53] test(sandbox): give the probe-timeout test headroom over vitest's default MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `bounds the default probes` runs a real launcher that sleeps 1s under the 5000ms default probe budget, all wrapped in vitest's 5000ms default test timeout. The blocking spawnSync races that wrapper and tips over under the load spike of a full parallel run — a pre-existing, load-sensitive flake (noted as unrelated in this PR's original description). Give the test an explicit 20s timeout so its bounded subprocess work never races the default. --- packages/sandbox/sandbox-local/tests/local.spec.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/sandbox/sandbox-local/tests/local.spec.ts b/packages/sandbox/sandbox-local/tests/local.spec.ts index f9efbf992c..3ef5f7a586 100644 --- a/packages/sandbox/sandbox-local/tests/local.spec.ts +++ b/packages/sandbox/sandbox-local/tests/local.spec.ts @@ -339,7 +339,10 @@ describe('probeTimeoutMs config', () => { { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher }, ) expect(() => impatient.sandbox.confine(['true'], RO)).toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE })) - }) + // The patient probe blocks on a real 1s launcher under the 5000ms default + // budget; an explicit timeout keeps the test clear of vitest's 5000ms + // default, which the blocking spawnSync would otherwise race under load. + }, 20_000) }) describe('the default seatbelt probe (sandbox-exec contract)', () => { From dd57d3009d12ac2272a6ca42973823f6fa23aedc Mon Sep 17 00:00:00 2001 From: Turtle Date: Tue, 21 Jul 2026 10:07:03 +0800 Subject: [PATCH 51/53] test(sandbox): decouple the probe-timeout test from the racy default budget The earlier fix only widened the vitest timeout, but the real race is the patient probe reading the 1s launcher under the 5000ms *default* probe budget: under a full parallel run spawnSync blocks the worker and fork/exec latency can push the launcher's wall-clock past 5000ms, so the patient probe wrongly reads unusable and the assertion fails. Give the patient probe a generous explicit 15000ms budget (still far below its 1s launcher runtime margin) so only the 250ms impatient probe races the launcher; keep a 30s vitest timeout above the patient budget. --- .../sandbox/sandbox-local/tests/local.spec.ts | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/packages/sandbox/sandbox-local/tests/local.spec.ts b/packages/sandbox/sandbox-local/tests/local.spec.ts index 3ef5f7a586..f7cc952498 100644 --- a/packages/sandbox/sandbox-local/tests/local.spec.ts +++ b/packages/sandbox/sandbox-local/tests/local.spec.ts @@ -325,13 +325,19 @@ describe('probeTimeoutMs config', () => { }) it('bounds the default probes: a launcher slower than the configured timeout reads as unusable', async () => { - // The same sleeping launcher passes under the default 5000ms budget and - // fails under a 250ms one — the config demonstrably reaches spawnSync. + // The same 1s launcher reads usable under a generous budget and unusable + // under a 250ms one — the config demonstrably reaches spawnSync. Both bounds + // keep a wide margin from the launcher's 1s runtime so a loaded host (where + // spawnSync blocks the worker and fork/exec latency inflates wall-clock) + // cannot flip either verdict; the vitest timeout clears the patient budget. const dir = mkdtempSync(join(tmpdir(), 'dsh-slow-landlock-')) const launcher = join(dir, 'landlock-run') writeFileSync(launcher, '#!/bin/sh\nsleep 1\necho "landlock: fully enforced"\nexit 0\n', { mode: 0o755 }) - const patient = await setup({}, { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher }) + const patient = await setup( + { probeTimeoutMs: 15_000 }, + { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher }, + ) expect(patient.sandbox.confine(['true'], RO).enforcement).toBe('full') const impatient = await setup( @@ -339,10 +345,7 @@ describe('probeTimeoutMs config', () => { { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher }, ) expect(() => impatient.sandbox.confine(['true'], RO)).toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE })) - // The patient probe blocks on a real 1s launcher under the 5000ms default - // budget; an explicit timeout keeps the test clear of vitest's 5000ms - // default, which the blocking spawnSync would otherwise race under load. - }, 20_000) + }, 30_000) }) describe('the default seatbelt probe (sandbox-exec contract)', () => { From 92180069ea29acc726baf882d506cefc26dd9bc0 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Tue, 21 Jul 2026 17:26:36 +0800 Subject: [PATCH 52/53] test(acp-snapshot): sync Windows goal command transcript --- .../tests/snapshots/workspace-edit/stdout.expected.windows.jsonl | 1 + 1 file changed, 1 insertion(+) diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl index 7438c3f43f..754b9c5841 100644 --- a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl +++ b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl @@ -1,5 +1,6 @@ {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[|clear|edit |pause|resume]"}}]}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} From f8008b571dbaa10d6b24197faf3a32e09e9c94f5 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Tue, 21 Jul 2026 23:47:14 +0800 Subject: [PATCH 53/53] fix(tui): preserve footer truncation after merge --- .../snapshots/workspace-edit/stdout.expected.windows.jsonl | 1 + packages/ui/tui/src/index.ts | 5 +---- packages/ui/tui/tests/tui.spec.ts | 4 ++-- 3 files changed, 4 insertions(+), 6 deletions(-) diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl index 754b9c5841..f39ff91716 100644 --- a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl +++ b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl @@ -1,6 +1,7 @@ {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[|clear|edit |pause|resume]"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"A file named greeting.txt in","updatedAt":"{{updatedAt}}"}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index 5cb23b31c0..2b16036ada 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -777,10 +777,7 @@ class FooterComponent implements Component { return [`${' '.repeat(Math.max(0, width - visibleWidth(compact)))}${this.palette.dim(compact)}`] } const rightAvailable = width - visibleWidth(counters) - 1 - const fullWidth = visibleWidth(formattedCwd) + visibleWidth(counters) + visibleWidth(fullRight) + 3 - const right = this.cwdFormatter === undefined - ? (visibleWidth(fullRight) <= rightAvailable ? fullRight : compactRight) - : (fullWidth <= width ? fullRight : compactRight) + const right = visibleWidth(fullRight) <= rightAvailable ? fullRight : compactRight const rightClipped = truncateToWidth(right, rightAvailable, '') const cwdAvailable = Math.max(0, width - visibleWidth(counters) - visibleWidth(rightClipped) - 3) const cwd = truncateToWidth(formattedCwd, cwdAvailable, '') diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 796f84b895..7474add504 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -511,10 +511,10 @@ describe('pi-tui chat lifecycle and transcript', () => { await dispose(outsideResult) const logicalResult = await setup({ - cwd: '/host/worktree', + cwd: '/w', formatCwd: cwd => `logical:${cwd}\x1b`, }) - expect(logicalResult.terminal.output).toContain('logical:/host/worktree\\x1b') + expect(logicalResult.terminal.output).toContain('logical:/w\\x1b') await dispose(logicalResult) })