From 5000bcb7bca6715b3734e8fbcce38f4d609de8f5 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 4 Nov 2026 12:39:03 +0530 Subject: [PATCH 1/6] fix(cli): install the pinned iii engine on Windows A fresh agentmemory on win32 exited with "Auto-install unavailable on win32" because the installer only handled tar.gz assets through sh, curl and tar. Windows assets are zip files. The zip path now downloads the pinned asset with fetch, checks it against the same pinned SHA-256 table as every other platform, and extracts iii.exe into the private bin directory with System32 tar.exe, falling back to PowerShell Expand-Archive. Both run without a shell. A missing checksum still downloads nothing, and a mismatch deletes the archive before any extraction. --- src/cli.ts | 28 ++++++-- src/cli/engine-install.ts | 123 +++++++++++++++++++++++++++++++++++- test/engine-install.test.ts | 115 +++++++++++++++++++++++++++++++++ 3 files changed, 260 insertions(+), 6 deletions(-) diff --git a/src/cli.ts b/src/cli.ts index b9e512e3d8..8c36c19f66 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -57,7 +57,7 @@ import { } from "./cli/remove-plan.js"; import { portFlagSuffix } from "./cli/ready-hint.js"; import { embeddingStatusLabel } from "./cli/embedding-status.js"; -import { expectedIiiSha256, iiiManualInstallCommand, installIiiArchive } from "./cli/engine-install.js"; +import { expectedIiiSha256, iiiManualInstallCommand, installIiiArchive, installIiiZip } from "./cli/engine-install.js"; import { runtimeConfigPath, redactCredentialUrls, @@ -959,12 +959,30 @@ async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null } if (IS_WINDOWS || isZipAsset) { - p.log.info( - `Auto-install unavailable on ${platform()} — ${asset} isn't tar-compatible. Install manually:\n` + + const binDir = agentmemoryBinDir(); + const binPath = privateIiiPath(); + const label = `Installing iii-engine v${IIPINNED_VERSION} (pinned)`; + const spinner = p.spinner(); + spinner.start(label); + const outcome = await installIiiZip({ + releaseUrl, + version: IIPINNED_VERSION, + asset: asset ?? "", + binDir, + binPath, + }); + if (outcome.ok) { + spinner.stop(`${label} ${pc.green("✓")}`); + iiiProbeScan?.delete(binPath); + return { ok: true, binPath }; + } + spinner.stop(`${label} ${pc.red("✗")}`); + p.log.warn( + `iii-engine auto-install failed: ${outcome.detail.slice(0, 300)}\n` + + `Install it manually, then re-run agentmemory:\n` + ` 1. Download ${releaseUrl}\n` + ` Its SHA-256 must be ${expectedIiiSha256(IIPINNED_VERSION, asset ?? "") ?? `the value in ${releaseUrl.replace(/\.zip$/, ".sha256")}`}\n` + - ` 2. Extract iii.exe and place it on PATH (e.g. %USERPROFILE%\\.local\\bin)\n` + - `Install the pinned iii binary from ${releaseUrl}`, + ` 2. Extract iii.exe into ${binDir}`, ); return { ok: false, binPath: null }; } diff --git a/src/cli/engine-install.ts b/src/cli/engine-install.ts index a9979a5ee6..0b05030a2c 100644 --- a/src/cli/engine-install.ts +++ b/src/cli/engine-install.ts @@ -1,6 +1,6 @@ import { spawnSync } from "node:child_process"; import { createHash } from "node:crypto"; -import { readFileSync, rmSync } from "node:fs"; +import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; export const III_INSTALL_CONNECT_TIMEOUT_S = 15; @@ -140,3 +140,124 @@ export function installIiiArchive(opts: { } return { ok: true }; } + +export type ZipRunResult = { + status: number | null; + stdout?: string | null; + stderr?: string | null; + error?: Error & { code?: string }; + signal?: NodeJS.Signals | null; +}; + +export type ZipCommandRunner = (command: string, args: string[]) => ZipRunResult; + +export type ZipDownloader = (url: string, dest: string) => Promise; + +export function iiiZipArchivePath(binDir: string): string { + return join(binDir, ".iii-download.zip"); +} + +export function powershellLiteral(value: string): string { + return `'${value.replace(/'/g, "''")}'`; +} + +export function windowsZipExtractCommands( + archive: string, + binDir: string, + env: NodeJS.ProcessEnv = process.env, +): { command: string; args: string[] }[] { + const systemRoot = env["SystemRoot"] || env["SYSTEMROOT"] || "C:\\Windows"; + const system32 = join(systemRoot, "System32"); + return [ + { command: join(system32, "tar.exe"), args: ["-xf", archive, "-C", binDir] }, + { + command: join(system32, "WindowsPowerShell", "v1.0", "powershell.exe"), + args: [ + "-NoProfile", + "-NonInteractive", + "-Command", + `Expand-Archive -LiteralPath ${powershellLiteral(archive)} -DestinationPath ${powershellLiteral(binDir)} -Force`, + ], + }, + ]; +} + +export async function downloadToFile(url: string, dest: string): Promise { + const res = await fetch(url, { + redirect: "follow", + signal: AbortSignal.timeout(III_INSTALL_MAX_TIME_S * 1000), + }); + if (!res.ok) throw new Error(`download failed with HTTP ${res.status} ${res.statusText}`.trim()); + writeFileSync(dest, Buffer.from(await res.arrayBuffer())); +} + +function defaultZipRunner(command: string, args: string[]): ZipRunResult { + return spawnSync(command, args, { + stdio: "pipe", + encoding: "utf-8", + timeout: III_INSTALL_SPAWN_TIMEOUT_MS, + windowsHide: true, + shell: false, + }); +} + +export async function installIiiZip(opts: { + releaseUrl: string; + version: string; + asset: string; + binDir: string; + binPath: string; + env?: NodeJS.ProcessEnv; + checksums?: ChecksumTable; + download?: ZipDownloader; + run?: ZipCommandRunner; +}): Promise { + const expected = expectedIiiSha256(opts.version, opts.asset, opts.checksums); + if (!expected) { + return { + ok: false, + reason: "no-checksum", + detail: `no pinned SHA-256 for ${opts.asset} in iii v${opts.version}, so the download cannot be verified`, + }; + } + const download = opts.download ?? downloadToFile; + const run = opts.run ?? defaultZipRunner; + const archive = iiiZipArchivePath(opts.binDir); + + try { + mkdirSync(opts.binDir, { recursive: true }); + rmSync(archive, { force: true }); + await download(opts.releaseUrl, archive); + } catch (err) { + rmSync(archive, { force: true }); + return { ok: false, reason: "download", detail: err instanceof Error ? err.message : String(err) }; + } + + let actual: string; + try { + actual = sha256File(archive); + } catch (err) { + rmSync(archive, { force: true }); + return { ok: false, reason: "download", detail: err instanceof Error ? err.message : String(err) }; + } + if (actual !== expected) { + rmSync(archive, { force: true }); + return { + ok: false, + reason: "checksum", + detail: `SHA-256 mismatch for ${opts.asset}: expected ${expected}, got ${actual}. The download was deleted and nothing was installed`, + }; + } + + const failures: string[] = []; + for (const step of windowsZipExtractCommands(archive, opts.binDir, opts.env)) { + const result = run(step.command, step.args); + if (result.status === 0 && existsSync(opts.binPath)) { + rmSync(archive, { force: true }); + return { ok: true }; + } + failures.push(`${step.command}: ${result.status === 0 ? `finished but ${opts.binPath} is missing` : describeInstallFailure(result)}`); + } + rmSync(archive, { force: true }); + return { ok: false, reason: "extract", detail: failures.join("; ") }; +} diff --git a/test/engine-install.test.ts b/test/engine-install.test.ts index 0186a288cc..624d1c6494 100644 --- a/test/engine-install.test.ts +++ b/test/engine-install.test.ts @@ -13,6 +13,9 @@ import { iiiManualInstallCommand, installIiiArchive, sha256File, + installIiiZip, + powershellLiteral, + windowsZipExtractCommands, } from "../src/cli/engine-install.js"; import { III_PINNED_VERSION } from "../src/version.js"; @@ -214,3 +217,115 @@ describe("iii engine auto-installer", () => { expect(existsSync(binPath)).toBe(true); }); }); + +describe("iii engine Windows zip installer", () => { + const ZIP_ASSET = "iii-x86_64-pc-windows-msvc.zip"; + const ZIP_BYTES = Buffer.from("fake windows iii zip"); + + function zipChecksums(bytes: Buffer = ZIP_BYTES) { + const dir = sandbox(); + const file = join(dir, "probe.zip"); + writeFileSync(file, bytes); + return { "9.9.9": { [ZIP_ASSET]: sha256File(file) } }; + } + + function zipOpts(binDir: string, extra: Record = {}) { + return { + releaseUrl: "https://example.invalid/iii.zip", + version: "9.9.9", + asset: ZIP_ASSET, + binDir, + binPath: join(binDir, "iii.exe"), + env: { SystemRoot: "C:\\Windows" }, + checksums: zipChecksums(), + download: async (_url: string, dest: string) => writeFileSync(dest, ZIP_BYTES), + ...extra, + }; + } + + it("extracts with System32 tar.exe first and PowerShell Expand-Archive second, without a shell", () => { + const steps = windowsZipExtractCommands("C:\\a\\.iii-download.zip", "C:\\a", { SystemRoot: "C:\\Windows" }); + expect(steps).toHaveLength(2); + expect(steps[0].command).toMatch(/System32[\\/]tar\.exe$/); + expect(steps[0].args).toEqual(["-xf", "C:\\a\\.iii-download.zip", "-C", "C:\\a"]); + expect(steps[1].command).toMatch(/WindowsPowerShell[\\/]v1\.0[\\/]powershell\.exe$/); + expect(steps[1].args.slice(0, 3)).toEqual(["-NoProfile", "-NonInteractive", "-Command"]); + expect(steps[1].args[3]).toContain("Expand-Archive -LiteralPath 'C:\\a\\.iii-download.zip'"); + }); + + it("quotes PowerShell paths so a quote in the profile path cannot end the string", () => { + expect(powershellLiteral("C:\\Users\\o'brien")).toBe("'C:\\Users\\o''brien'"); + }); + + it("installs when the download matches the pinned SHA-256 and tar.exe extracts iii.exe", async () => { + const binDir = join(sandbox(), "bin"); + const calls: string[] = []; + const outcome = await installIiiZip(zipOpts(binDir, { + run: (command: string) => { + calls.push(command); + writeFileSync(join(binDir, "iii.exe"), "bin"); + return { status: 0 }; + }, + })); + expect(outcome).toEqual({ ok: true }); + expect(calls).toHaveLength(1); + expect(calls[0]).toMatch(/tar\.exe$/); + expect(existsSync(join(binDir, ".iii-download.zip"))).toBe(false); + }); + + it("falls back to Expand-Archive when tar.exe fails", async () => { + const binDir = join(sandbox(), "bin"); + const calls: string[] = []; + const outcome = await installIiiZip(zipOpts(binDir, { + run: (command: string) => { + calls.push(command); + if (command.endsWith("tar.exe")) return { status: 1, stderr: "tar: unsupported" }; + writeFileSync(join(binDir, "iii.exe"), "bin"); + return { status: 0 }; + }, + })); + expect(outcome).toEqual({ ok: true }); + expect(calls.map((c) => c.split(/[\\/]/).pop())).toEqual(["tar.exe", "powershell.exe"]); + }); + + it("never extracts a download whose SHA-256 does not match", async () => { + const binDir = join(sandbox(), "bin"); + let ran = false; + const outcome = await installIiiZip(zipOpts(binDir, { + download: async (_url: string, dest: string) => writeFileSync(dest, Buffer.from("tampered")), + run: () => { + ran = true; + return { status: 0 }; + }, + })); + expect(outcome.ok).toBe(false); + expect(outcome.ok === false && outcome.reason).toBe("checksum"); + expect(ran).toBe(false); + expect(existsSync(join(binDir, ".iii-download.zip"))).toBe(false); + }); + + it("downloads nothing for an asset without a pinned SHA-256", async () => { + const binDir = join(sandbox(), "bin"); + let downloaded = false; + const outcome = await installIiiZip(zipOpts(binDir, { + checksums: { "9.9.9": {} }, + download: async () => { + downloaded = true; + }, + })); + expect(outcome.ok === false && outcome.reason).toBe("no-checksum"); + expect(downloaded).toBe(false); + }); + + it("reports an extract failure when neither extractor produces iii.exe", async () => { + const binDir = join(sandbox(), "bin"); + const outcome = await installIiiZip(zipOpts(binDir, { run: () => ({ status: 0 }) })); + expect(outcome.ok === false && outcome.reason).toBe("extract"); + expect(outcome.ok === false && outcome.detail).toContain("iii.exe is missing"); + }); + + it("pins a SHA-256 for both Windows assets of the pinned release", () => { + expect(expectedIiiSha256(III_PINNED_VERSION, "iii-x86_64-pc-windows-msvc.zip")).toMatch(/^[0-9a-f]{64}$/); + expect(expectedIiiSha256(III_PINNED_VERSION, "iii-aarch64-pc-windows-msvc.zip")).toMatch(/^[0-9a-f]{64}$/); + }); +}); From fe008bd8f30f8fc43242a0de2d049a711687d500 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 4 Nov 2026 13:19:06 +0530 Subject: [PATCH 2/6] fix(cli): isolate concurrent Windows iii installs and honor proxies - Each install downloads to its own archive name (pid plus random suffix), so two starts into the same bin directory cannot delete or overwrite each other's download before verification. - Archive cleanup never throws, so a failed delete after a successful extraction no longer turns the install into a failure. - When HTTPS_PROXY, HTTP_PROXY or ALL_PROXY is set, the zip is fetched with System32 curl.exe, which honors those variables on every supported Node version. Without a proxy the built-in fetch is used. Signed-off-by: Rohit Ghumare --- src/cli/engine-install.ts | 63 +++++++++++++++++++++++++++++++------ test/engine-install.test.ts | 34 ++++++++++++++++++-- 2 files changed, 85 insertions(+), 12 deletions(-) diff --git a/src/cli/engine-install.ts b/src/cli/engine-install.ts index 0b05030a2c..20275b1450 100644 --- a/src/cli/engine-install.ts +++ b/src/cli/engine-install.ts @@ -1,5 +1,5 @@ import { spawnSync } from "node:child_process"; -import { createHash } from "node:crypto"; +import { createHash, randomBytes } from "node:crypto"; import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; @@ -154,7 +154,40 @@ export type ZipCommandRunner = (command: string, args: string[]) => ZipRunResult export type ZipDownloader = (url: string, dest: string) => Promise; export function iiiZipArchivePath(binDir: string): string { - return join(binDir, ".iii-download.zip"); + return join(binDir, `.iii-download-${process.pid}-${randomBytes(4).toString("hex")}.zip`); +} + +function removeQuietly(path: string): void { + try { + rmSync(path, { force: true }); + } catch {} +} + +const PROXY_ENV_KEYS = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"]; + +export function proxyConfigured(env: NodeJS.ProcessEnv): boolean { + return PROXY_ENV_KEYS.some((key) => Boolean(env[key]?.trim())); +} + +export function windowsCurlDownloadCommand( + url: string, + dest: string, + env: NodeJS.ProcessEnv = process.env, +): { command: string; args: string[] } { + const systemRoot = env["SystemRoot"] || env["SYSTEMROOT"] || "C:\\Windows"; + return { + command: join(systemRoot, "System32", "curl.exe"), + args: [ + "-fsSL", + "--connect-timeout", + String(III_INSTALL_CONNECT_TIMEOUT_S), + "--max-time", + String(III_INSTALL_MAX_TIME_S), + "-o", + dest, + url, + ], + }; } export function powershellLiteral(value: string): string { @@ -182,7 +215,18 @@ export function windowsZipExtractCommands( ]; } -export async function downloadToFile(url: string, dest: string): Promise { +export async function downloadToFile( + url: string, + dest: string, + env: NodeJS.ProcessEnv = process.env, + run: ZipCommandRunner = defaultZipRunner, +): Promise { + if (proxyConfigured(env)) { + const step = windowsCurlDownloadCommand(url, dest, env); + const result = run(step.command, step.args); + if (result.status !== 0) throw new Error(describeInstallFailure(result)); + return; + } const res = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(III_INSTALL_MAX_TIME_S * 1000), @@ -220,16 +264,15 @@ export async function installIiiZip(opts: { detail: `no pinned SHA-256 for ${opts.asset} in iii v${opts.version}, so the download cannot be verified`, }; } - const download = opts.download ?? downloadToFile; const run = opts.run ?? defaultZipRunner; + const download = opts.download ?? ((url: string, dest: string) => downloadToFile(url, dest, opts.env ?? process.env, run)); const archive = iiiZipArchivePath(opts.binDir); try { mkdirSync(opts.binDir, { recursive: true }); - rmSync(archive, { force: true }); await download(opts.releaseUrl, archive); } catch (err) { - rmSync(archive, { force: true }); + removeQuietly(archive); return { ok: false, reason: "download", detail: err instanceof Error ? err.message : String(err) }; } @@ -237,11 +280,11 @@ export async function installIiiZip(opts: { try { actual = sha256File(archive); } catch (err) { - rmSync(archive, { force: true }); + removeQuietly(archive); return { ok: false, reason: "download", detail: err instanceof Error ? err.message : String(err) }; } if (actual !== expected) { - rmSync(archive, { force: true }); + removeQuietly(archive); return { ok: false, reason: "checksum", @@ -253,11 +296,11 @@ export async function installIiiZip(opts: { for (const step of windowsZipExtractCommands(archive, opts.binDir, opts.env)) { const result = run(step.command, step.args); if (result.status === 0 && existsSync(opts.binPath)) { - rmSync(archive, { force: true }); + removeQuietly(archive); return { ok: true }; } failures.push(`${step.command}: ${result.status === 0 ? `finished but ${opts.binPath} is missing` : describeInstallFailure(result)}`); } - rmSync(archive, { force: true }); + removeQuietly(archive); return { ok: false, reason: "extract", detail: failures.join("; ") }; } diff --git a/test/engine-install.test.ts b/test/engine-install.test.ts index 624d1c6494..65132bbf3b 100644 --- a/test/engine-install.test.ts +++ b/test/engine-install.test.ts @@ -13,8 +13,11 @@ import { iiiManualInstallCommand, installIiiArchive, sha256File, + downloadToFile, + iiiZipArchivePath, installIiiZip, powershellLiteral, + proxyConfigured, windowsZipExtractCommands, } from "../src/cli/engine-install.js"; import { III_PINNED_VERSION } from "../src/version.js"; @@ -222,6 +225,10 @@ describe("iii engine Windows zip installer", () => { const ZIP_ASSET = "iii-x86_64-pc-windows-msvc.zip"; const ZIP_BYTES = Buffer.from("fake windows iii zip"); + function leftoverArchives(binDir: string): string[] { + return existsSync(binDir) ? readdirSync(binDir).filter((name) => name.startsWith(".iii-download")) : []; + } + function zipChecksums(bytes: Buffer = ZIP_BYTES) { const dir = sandbox(); const file = join(dir, "probe.zip"); @@ -270,7 +277,7 @@ describe("iii engine Windows zip installer", () => { expect(outcome).toEqual({ ok: true }); expect(calls).toHaveLength(1); expect(calls[0]).toMatch(/tar\.exe$/); - expect(existsSync(join(binDir, ".iii-download.zip"))).toBe(false); + expect(leftoverArchives(binDir)).toEqual([]); }); it("falls back to Expand-Archive when tar.exe fails", async () => { @@ -301,7 +308,7 @@ describe("iii engine Windows zip installer", () => { expect(outcome.ok).toBe(false); expect(outcome.ok === false && outcome.reason).toBe("checksum"); expect(ran).toBe(false); - expect(existsSync(join(binDir, ".iii-download.zip"))).toBe(false); + expect(leftoverArchives(binDir)).toEqual([]); }); it("downloads nothing for an asset without a pinned SHA-256", async () => { @@ -324,6 +331,29 @@ describe("iii engine Windows zip installer", () => { expect(outcome.ok === false && outcome.detail).toContain("iii.exe is missing"); }); + it("gives every install its own archive file so concurrent starts cannot clobber each other", () => { + const a = iiiZipArchivePath("C:\\bin"); + const b = iiiZipArchivePath("C:\\bin"); + expect(a).not.toBe(b); + expect(a).toContain(`.iii-download-${process.pid}-`); + expect(a.endsWith(".zip")).toBe(true); + }); + + it("downloads through System32 curl.exe when a proxy is configured", async () => { + expect(proxyConfigured({})).toBe(false); + expect(proxyConfigured({ HTTPS_PROXY: "http://proxy:3128" })).toBe(true); + expect(proxyConfigured({ http_proxy: " " })).toBe(false); + const calls: { command: string; args: string[] }[] = []; + await downloadToFile("https://example.invalid/iii.zip", "C:\\bin\\a.zip", { SystemRoot: "C:\\Windows", HTTPS_PROXY: "http://proxy:3128" }, (command, args) => { + calls.push({ command, args }); + return { status: 0 }; + }); + expect(calls).toHaveLength(1); + expect(calls[0].command).toMatch(/System32[\\/]curl\.exe$/); + expect(calls[0].args).toEqual(expect.arrayContaining(["-o", "C:\\bin\\a.zip", "https://example.invalid/iii.zip", "--max-time"])); + await expect(downloadToFile("https://example.invalid/iii.zip", "C:\\bin\\a.zip", { HTTPS_PROXY: "http://proxy:3128" }, () => ({ status: 22, stderr: "curl: (22) 407" }))).rejects.toThrow("407"); + }); + it("pins a SHA-256 for both Windows assets of the pinned release", () => { expect(expectedIiiSha256(III_PINNED_VERSION, "iii-x86_64-pc-windows-msvc.zip")).toMatch(/^[0-9a-f]{64}$/); expect(expectedIiiSha256(III_PINNED_VERSION, "iii-aarch64-pc-windows-msvc.zip")).toMatch(/^[0-9a-f]{64}$/); From 4575a17803d5cddf6dff569ed5add2c5b8d1f610 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 4 Nov 2026 13:37:24 +0530 Subject: [PATCH 3/6] fix(cli): stage Windows iii extraction and keep installs cancelable - Extraction now writes into a per-install staging directory and moves iii.exe over the existing binary only after the staged copy exists, so a failed or partial extraction never destroys a working iii.exe. - Install commands (proxied curl download, tar.exe, Expand-Archive) run through an async spawn with a kill timeout instead of spawnSync, so the startup Ctrl+C handlers keep running during a stalled download. - Archives and staging folders left by earlier failed installs are removed once they are older than 15 minutes. Signed-off-by: Rohit Ghumare --- src/cli/engine-install.ts | 101 ++++++++++++++++++++++++++++-------- test/engine-install.test.ts | 79 ++++++++++++++++++++++++++-- 2 files changed, 152 insertions(+), 28 deletions(-) diff --git a/src/cli/engine-install.ts b/src/cli/engine-install.ts index 20275b1450..5472b439ab 100644 --- a/src/cli/engine-install.ts +++ b/src/cli/engine-install.ts @@ -1,7 +1,7 @@ -import { spawnSync } from "node:child_process"; +import { spawn, spawnSync } from "node:child_process"; import { createHash, randomBytes } from "node:crypto"; -import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; -import { join } from "node:path"; +import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"; +import { basename, join } from "node:path"; export const III_INSTALL_CONNECT_TIMEOUT_S = 15; export const III_INSTALL_MAX_TIME_S = 300; @@ -149,7 +149,7 @@ export type ZipRunResult = { signal?: NodeJS.Signals | null; }; -export type ZipCommandRunner = (command: string, args: string[]) => ZipRunResult; +export type ZipCommandRunner = (command: string, args: string[]) => ZipRunResult | Promise; export type ZipDownloader = (url: string, dest: string) => Promise; @@ -159,10 +159,34 @@ export function iiiZipArchivePath(binDir: string): string { function removeQuietly(path: string): void { try { - rmSync(path, { force: true }); + rmSync(path, { force: true, recursive: true }); } catch {} } +export const STALE_INSTALL_FILE_MS = 15 * 60 * 1000; + +export function removeStaleInstallFiles(binDir: string, now: number = Date.now()): string[] { + const removed: string[] = []; + let entries: string[]; + try { + entries = readdirSync(binDir); + } catch { + return removed; + } + for (const name of entries) { + if (!name.startsWith(".iii-download-") && !name.startsWith(".iii-staging-")) continue; + const path = join(binDir, name); + try { + if (now - statSync(path).mtimeMs < STALE_INSTALL_FILE_MS) continue; + } catch { + continue; + } + removeQuietly(path); + if (!existsSync(path)) removed.push(name); + } + return removed; +} + const PROXY_ENV_KEYS = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"]; export function proxyConfigured(env: NodeJS.ProcessEnv): boolean { @@ -219,11 +243,11 @@ export async function downloadToFile( url: string, dest: string, env: NodeJS.ProcessEnv = process.env, - run: ZipCommandRunner = defaultZipRunner, + run: ZipCommandRunner = runInstallCommand, ): Promise { if (proxyConfigured(env)) { const step = windowsCurlDownloadCommand(url, dest, env); - const result = run(step.command, step.args); + const result = await run(step.command, step.args); if (result.status !== 0) throw new Error(describeInstallFailure(result)); return; } @@ -235,13 +259,30 @@ export async function downloadToFile( writeFileSync(dest, Buffer.from(await res.arrayBuffer())); } -function defaultZipRunner(command: string, args: string[]): ZipRunResult { - return spawnSync(command, args, { - stdio: "pipe", - encoding: "utf-8", - timeout: III_INSTALL_SPAWN_TIMEOUT_MS, - windowsHide: true, - shell: false, +export function runInstallCommand(command: string, args: string[]): Promise { + return new Promise((done) => { + let stdout = ""; + let stderr = ""; + let timedOut = false; + const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"], windowsHide: true, shell: false }); + const timer = setTimeout(() => { + timedOut = true; + child.kill(); + }, III_INSTALL_SPAWN_TIMEOUT_MS); + child.stdout?.on("data", (chunk) => { stdout += chunk; }); + child.stderr?.on("data", (chunk) => { stderr += chunk; }); + child.on("error", (error: Error & { code?: string }) => { + clearTimeout(timer); + done({ status: null, stdout, stderr, error }); + }); + child.on("close", (status, signal) => { + clearTimeout(timer); + if (timedOut) { + done({ status: null, stdout, stderr, signal, error: Object.assign(new Error("timed out"), { code: "ETIMEDOUT" }) }); + return; + } + done({ status, stdout, stderr, signal }); + }); }); } @@ -264,12 +305,13 @@ export async function installIiiZip(opts: { detail: `no pinned SHA-256 for ${opts.asset} in iii v${opts.version}, so the download cannot be verified`, }; } - const run = opts.run ?? defaultZipRunner; + const run = opts.run ?? runInstallCommand; const download = opts.download ?? ((url: string, dest: string) => downloadToFile(url, dest, opts.env ?? process.env, run)); const archive = iiiZipArchivePath(opts.binDir); try { mkdirSync(opts.binDir, { recursive: true }); + removeStaleInstallFiles(opts.binDir); await download(opts.releaseUrl, archive); } catch (err) { removeQuietly(archive); @@ -292,15 +334,28 @@ export async function installIiiZip(opts: { }; } + const staging = join(opts.binDir, `.iii-staging-${process.pid}-${randomBytes(4).toString("hex")}`); + const staged = join(staging, basename(opts.binPath)); const failures: string[] = []; - for (const step of windowsZipExtractCommands(archive, opts.binDir, opts.env)) { - const result = run(step.command, step.args); - if (result.status === 0 && existsSync(opts.binPath)) { - removeQuietly(archive); - return { ok: true }; + try { + for (const step of windowsZipExtractCommands(archive, staging, opts.env)) { + removeQuietly(staging); + mkdirSync(staging, { recursive: true }); + const result = await run(step.command, step.args); + if (result.status === 0 && existsSync(staged)) { + try { + renameSync(staged, opts.binPath); + return { ok: true }; + } catch (err) { + failures.push(`could not move ${staged} to ${opts.binPath}: ${err instanceof Error ? err.message : String(err)}`); + break; + } + } + failures.push(`${step.command}: ${result.status === 0 ? `finished but ${basename(opts.binPath)} is missing from the archive` : describeInstallFailure(result)}`); } - failures.push(`${step.command}: ${result.status === 0 ? `finished but ${opts.binPath} is missing` : describeInstallFailure(result)}`); + return { ok: false, reason: "extract", detail: failures.join("; ") }; + } finally { + removeQuietly(staging); + removeQuietly(archive); } - removeQuietly(archive); - return { ok: false, reason: "extract", detail: failures.join("; ") }; } diff --git a/test/engine-install.test.ts b/test/engine-install.test.ts index 65132bbf3b..ea9c0987db 100644 --- a/test/engine-install.test.ts +++ b/test/engine-install.test.ts @@ -18,6 +18,9 @@ import { installIiiZip, powershellLiteral, proxyConfigured, + removeStaleInstallFiles, + runInstallCommand, + STALE_INSTALL_FILE_MS, windowsZipExtractCommands, } from "../src/cli/engine-install.js"; import { III_PINNED_VERSION } from "../src/version.js"; @@ -226,7 +229,13 @@ describe("iii engine Windows zip installer", () => { const ZIP_BYTES = Buffer.from("fake windows iii zip"); function leftoverArchives(binDir: string): string[] { - return existsSync(binDir) ? readdirSync(binDir).filter((name) => name.startsWith(".iii-download")) : []; + return existsSync(binDir) ? readdirSync(binDir).filter((name) => name.startsWith(".iii-download") || name.startsWith(".iii-staging")) : []; + } + + function extractDest(args: string[]): string { + if (args[0] === "-xf") return args[3]; + const match = /-DestinationPath '((?:[^']|'')*)'/.exec(args[3] ?? ""); + return (match?.[1] ?? "").replace(/''/g, "'"); } function zipChecksums(bytes: Buffer = ZIP_BYTES) { @@ -268,9 +277,9 @@ describe("iii engine Windows zip installer", () => { const binDir = join(sandbox(), "bin"); const calls: string[] = []; const outcome = await installIiiZip(zipOpts(binDir, { - run: (command: string) => { + run: (command: string, args: string[]) => { calls.push(command); - writeFileSync(join(binDir, "iii.exe"), "bin"); + writeFileSync(join(extractDest(args), "iii.exe"), "bin"); return { status: 0 }; }, })); @@ -284,10 +293,10 @@ describe("iii engine Windows zip installer", () => { const binDir = join(sandbox(), "bin"); const calls: string[] = []; const outcome = await installIiiZip(zipOpts(binDir, { - run: (command: string) => { + run: (command: string, args: string[]) => { calls.push(command); if (command.endsWith("tar.exe")) return { status: 1, stderr: "tar: unsupported" }; - writeFileSync(join(binDir, "iii.exe"), "bin"); + writeFileSync(join(extractDest(args), "iii.exe"), "bin"); return { status: 0 }; }, })); @@ -331,6 +340,66 @@ describe("iii engine Windows zip installer", () => { expect(outcome.ok === false && outcome.detail).toContain("iii.exe is missing"); }); + it("extracts into a staging directory and keeps a working iii.exe when extraction fails", async () => { + const binDir = join(sandbox(), "bin"); + mkdirSync(binDir, { recursive: true }); + writeFileSync(join(binDir, "iii.exe"), "working"); + const dests: string[] = []; + const outcome = await installIiiZip(zipOpts(binDir, { + run: (_command: string, args: string[]) => { + dests.push(extractDest(args)); + writeFileSync(join(extractDest(args), "iii.exe"), "partial"); + return { status: 1, stderr: "disk full" }; + }, + })); + expect(outcome.ok === false && outcome.reason).toBe("extract"); + expect(dests.every((dest) => dest !== binDir && dest.includes(".iii-staging-"))).toBe(true); + expect(readFileSync(join(binDir, "iii.exe"), "utf-8")).toBe("working"); + expect(leftoverArchives(binDir)).toEqual([]); + }); + + it("replaces iii.exe only after the staged copy exists", async () => { + const binDir = join(sandbox(), "bin"); + mkdirSync(binDir, { recursive: true }); + writeFileSync(join(binDir, "iii.exe"), "old"); + const outcome = await installIiiZip(zipOpts(binDir, { + run: (_command: string, args: string[]) => { + writeFileSync(join(extractDest(args), "iii.exe"), "new"); + return { status: 0 }; + }, + })); + expect(outcome).toEqual({ ok: true }); + expect(readFileSync(join(binDir, "iii.exe"), "utf-8")).toBe("new"); + expect(leftoverArchives(binDir)).toEqual([]); + }); + + it("runs install commands without blocking the event loop, so Ctrl+C handlers can still run", async () => { + let timerFired = false; + setTimeout(() => { timerFired = true; }, 20); + const pending = runInstallCommand(process.execPath, ["-e", "setTimeout(() => process.stdout.write('done'), 300)"]); + await new Promise((resolve) => setTimeout(resolve, 100)); + expect(timerFired).toBe(true); + const result = await pending; + expect(result.status).toBe(0); + expect(result.stdout).toBe("done"); + }); + + it("removes stale archives and staging folders from earlier failed installs", () => { + const binDir = join(sandbox(), "bin"); + mkdirSync(join(binDir, ".iii-staging-1-old"), { recursive: true }); + writeFileSync(join(binDir, ".iii-download-1-old.zip"), "x"); + writeFileSync(join(binDir, ".iii-download-2-fresh.zip"), "x"); + writeFileSync(join(binDir, "iii.exe"), "keep"); + const later = Date.now() + STALE_INSTALL_FILE_MS + 1000; + const freshNow = Date.now(); + const removedLater = removeStaleInstallFiles(binDir, later); + expect(removedLater.sort()).toEqual([".iii-download-1-old.zip", ".iii-download-2-fresh.zip", ".iii-staging-1-old"]); + expect(existsSync(join(binDir, "iii.exe"))).toBe(true); + writeFileSync(join(binDir, ".iii-download-3-new.zip"), "x"); + expect(removeStaleInstallFiles(binDir, freshNow)).toEqual([]); + expect(existsSync(join(binDir, ".iii-download-3-new.zip"))).toBe(true); + }); + it("gives every install its own archive file so concurrent starts cannot clobber each other", () => { const a = iiiZipArchivePath("C:\\bin"); const b = iiiZipArchivePath("C:\\bin"); From f614eefe5fe4929807f4d3d77beb1898bb3bec69 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 4 Nov 2026 13:55:55 +0530 Subject: [PATCH 4/6] fix(cli): point the Windows setup steps at the private bin folder After a failed install the warning said to extract iii.exe into %USERPROFILE%\.agentmemory\bin, while the Setup required box below it still said %USERPROFILE%\.local\bin. Both folders are searched; the setup steps now name the one the installer itself uses. Signed-off-by: Rohit Ghumare --- src/cli.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cli.ts b/src/cli.ts index 8c36c19f66..b802d3e7e5 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -1501,7 +1501,7 @@ function installInstructions(): string[] { ` 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`, ` 2. Download iii-x86_64-pc-windows-msvc.zip (or iii-aarch64-pc-windows-msvc.zip on ARM)`, verify, - " 3. Extract iii.exe to %USERPROFILE%\\.local\\bin\\iii.exe (or add to PATH)", + " 3. Extract iii.exe to %USERPROFILE%\\.agentmemory\\bin\\iii.exe (or add to PATH)", " 4. Re-run: npx @agentmemory/agentmemory", "", "Or skip the engine entirely (standalone MCP): npx @agentmemory/agentmemory mcp", From c04718f5d8b6547acf150550ee6d748fa10471c0 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 4 Nov 2026 13:59:16 +0530 Subject: [PATCH 5/6] fix(cli): stop install children on exit and report staging errors - A running curl, tar or PowerShell child is killed when the CLI exits, so cancelling a start with Ctrl+C no longer leaves it downloading or extracting in the background. - A filesystem error while creating the staging folder or running an extractor now returns an extract failure, so the spinner stops and the manual install steps are printed. Signed-off-by: Rohit Ghumare --- src/cli/engine-install.ts | 11 +++++++++++ test/engine-install.test.ts | 22 ++++++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/src/cli/engine-install.ts b/src/cli/engine-install.ts index 5472b439ab..6f3ac273a8 100644 --- a/src/cli/engine-install.ts +++ b/src/cli/engine-install.ts @@ -265,6 +265,12 @@ export function runInstallCommand(command: string, args: string[]): Promise { + try { + child.kill(); + } catch {} + }; + process.once("exit", killOnExit); const timer = setTimeout(() => { timedOut = true; child.kill(); @@ -273,10 +279,12 @@ export function runInstallCommand(command: string, args: string[]): Promise { stderr += chunk; }); child.on("error", (error: Error & { code?: string }) => { clearTimeout(timer); + process.off("exit", killOnExit); done({ status: null, stdout, stderr, error }); }); child.on("close", (status, signal) => { clearTimeout(timer); + process.off("exit", killOnExit); if (timedOut) { done({ status: null, stdout, stderr, signal, error: Object.assign(new Error("timed out"), { code: "ETIMEDOUT" }) }); return; @@ -354,6 +362,9 @@ export async function installIiiZip(opts: { failures.push(`${step.command}: ${result.status === 0 ? `finished but ${basename(opts.binPath)} is missing from the archive` : describeInstallFailure(result)}`); } return { ok: false, reason: "extract", detail: failures.join("; ") }; + } catch (err) { + failures.push(err instanceof Error ? err.message : String(err)); + return { ok: false, reason: "extract", detail: failures.join("; ") }; } finally { removeQuietly(staging); removeQuietly(archive); diff --git a/test/engine-install.test.ts b/test/engine-install.test.ts index ea9c0987db..2efd55b00f 100644 --- a/test/engine-install.test.ts +++ b/test/engine-install.test.ts @@ -384,6 +384,28 @@ describe("iii engine Windows zip installer", () => { expect(result.stdout).toBe("done"); }); + it("returns an extract failure instead of throwing when an extractor throws", async () => { + const binDir = join(sandbox(), "bin"); + const outcome = await installIiiZip(zipOpts(binDir, { + run: () => { + throw new Error("EPERM: staging denied"); + }, + })); + expect(outcome.ok === false && outcome.reason).toBe("extract"); + expect(outcome.ok === false && outcome.detail).toContain("EPERM: staging denied"); + expect(leftoverArchives(binDir)).toEqual([]); + }); + + it("kills a running install command when the CLI exits", async () => { + const before = process.listenerCount("exit"); + const pending = runInstallCommand(process.execPath, ["-e", "setTimeout(() => {}, 5000)"]); + expect(process.listenerCount("exit")).toBe(before + 1); + process.listeners("exit").at(-1)?.call(process, 0); + const result = await pending; + expect(result.status === 0).toBe(false); + expect(process.listenerCount("exit")).toBe(before); + }); + it("removes stale archives and staging folders from earlier failed installs", () => { const binDir = join(sandbox(), "bin"); mkdirSync(join(binDir, ".iii-staging-1-old"), { recursive: true }); From 443a944ff970083eb4acfadb297e0a0b79f9a1d6 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Wed, 4 Nov 2026 14:20:50 +0530 Subject: [PATCH 6/6] fix(cli): wait for a spawned install child to close The error handler resolved as soon as any child error fired. When a kill failed on a child that was still running, the installer moved on and removed the staging folder while the extractor kept writing, and the exit-time kill was dropped. The runner now resolves from error only when the child never spawned; otherwise it waits for close. Signed-off-by: Rohit Ghumare --- src/cli/engine-install.ts | 7 +++++++ test/engine-install.test.ts | 6 ++++++ 2 files changed, 13 insertions(+) diff --git a/src/cli/engine-install.ts b/src/cli/engine-install.ts index 6f3ac273a8..83ee9ff434 100644 --- a/src/cli/engine-install.ts +++ b/src/cli/engine-install.ts @@ -277,7 +277,10 @@ export function runInstallCommand(command: string, args: string[]): Promise { stdout += chunk; }); child.stderr?.on("data", (chunk) => { stderr += chunk; }); + let spawnError: (Error & { code?: string }) | undefined; child.on("error", (error: Error & { code?: string }) => { + spawnError = error; + if (child.pid !== undefined) return; clearTimeout(timer); process.off("exit", killOnExit); done({ status: null, stdout, stderr, error }); @@ -285,6 +288,10 @@ export function runInstallCommand(command: string, args: string[]): Promise { clearTimeout(timer); process.off("exit", killOnExit); + if (spawnError && status === null && !timedOut) { + done({ status: null, stdout, stderr, signal, error: spawnError }); + return; + } if (timedOut) { done({ status: null, stdout, stderr, signal, error: Object.assign(new Error("timed out"), { code: "ETIMEDOUT" }) }); return; diff --git a/test/engine-install.test.ts b/test/engine-install.test.ts index 2efd55b00f..d7a065f5a2 100644 --- a/test/engine-install.test.ts +++ b/test/engine-install.test.ts @@ -396,6 +396,12 @@ describe("iii engine Windows zip installer", () => { expect(leftoverArchives(binDir)).toEqual([]); }); + it("reports a missing executable without waiting for a close event", async () => { + const result = await runInstallCommand(join(sandbox(), "no-such-tool.exe"), []); + expect(result.status).toBeNull(); + expect(result.error?.code).toBe("ENOENT"); + }); + it("kills a running install command when the CLI exits", async () => { const before = process.listenerCount("exit"); const pending = runInstallCommand(process.execPath, ["-e", "setTimeout(() => {}, 5000)"]);