Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix: provision the ephemeral project root in ok start (PRD-8210) (#3756)
mike-inkeep670c38cc0dfb
diff --git a/.changeset/single-file-ephemeral-projectdir.md b/.changeset/single-file-ephemeral-projectdir.mdnew file mode 100644index 000000000..213285498--- /dev/null+++ b/.changeset/single-file-ephemeral-projectdir.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++`ok start --single-file` no longer deletes the directory it runs in. Previously, running it from inside an initialized OK project silently adopted that project as the session's "throwaway" root and recursively deleted it — content, `.git`, everything — when idle shutdown fired; from a non-project directory it refused to start with `MissingOkConfigError`. The command now provisions its own temp project root when `--project-dir` is absent (removing it on shutdown), requires any provided `--project-dir` to be a throwaway `ok-ephemeral-*` temp dir (seeding the synthesized config into it when bare; anything else — an ordinary directory or a real initialized project — is refused with a clear message instead of written to), and the ephemeral cleanup refuses to remove any directory that does not resolve to an `ok-ephemeral-*` temp dir — symlinks included — so no flag combination can point the reap at real data. `--project-dir` without `--single-file` is now rejected instead of silently ignored, ephemeral sessions no longer inherit the enclosing project's `server.*` settings — the user-global `~/.ok/global.yml` layer still applies, matching `ok <file>`, and flags and env still override — and both flags are hidden from `ok start --help` — they are the desktop spawn contract, and `ok <file>` is the supported way to open one file.diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.tsindex 65a56d95c..e8080cdb9 100644--- a/packages/cli/src/commands/start.test.ts+++ b/packages/cli/src/commands/start.test.ts@@ -1,9 +1,17 @@import type { spawn as NativeSpawn } from 'node:child_process';-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readdirSync,+ rmSync,+ symlinkSync,+ writeFileSync,+} from 'node:fs';import { mkdtemp, rm } from 'node:fs/promises';import { request as httpRequest } from 'node:http';import { tmpdir } from 'node:os';-import { join, resolve } from 'node:path';+import { basename, dirname, join, resolve } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';import { idleShutdownToMs } from '@inkeep/open-knowledge-core';import { type Config, ConfigSchema } from '@inkeep/open-knowledge-server';@@ -12,9 +20,11 @@ import {type BootedStartServer,bootStartServer,deriveServerProcessTitle,+ EphemeralProjectDirNotThrowawayError,formatServerReuseNotice,formatShutdownNotice,isLoopbackHost,+ isReapableEphemeralProjectDir,isServerLockCollision,OkDirMissingError,parseExternalUrlFlag,@@ -23,6 +33,7 @@ import {resolveBundledReactShellDir,resolveHost,resolveServerReuse,+ resolveStartConfig,resolveStartConsoleLevel,resolveStartShellDir,shouldOpenBrowser,@@ -788,6 +799,163 @@ describe('bootStartServer (integration)', () => {await rm(shellDir, { recursive: true, force: true });}});++ // --- ephemeral single-file: bootStartServer establishes the root it consumes ---++ test('--single-file with no projectDir self-provisions a throwaway root — cwd is never consumed', async () => {+ // cwd (tmpDir) is an initialized project (beforeEach seeds .ok/config.yml)+ // — exactly the shape the old cwd fallback consumed as the "throwaway"+ // ephemeral root and then recursively deleted on idle shutdown.+ const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));+ const sentinel = join(tmpDir, 'IMPORTANT.md');+ writeFileSync(sentinel, 'keep me', 'utf-8');+ try {+ writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');+ booted = await bootStartServer({+ config: makeTestConfig(),+ cwd: tmpDir,+ host: TEST_HOST,+ skipAutoInit: true,+ singleFile: join(looseDir, 'note.md'),+ });+ await booted.ready;++ // The ephemeral root is a fresh ok-ephemeral-* temp dir, not cwd.+ const ephemeralRoot = dirname(dirname(booted.lockDir)); // lockDir = <projectDir>/.ok/local+ expect(ephemeralRoot).not.toBe(tmpDir);+ expect(booted.lockDir.startsWith(tmpDir)).toBe(false);+ expect(basename(ephemeralRoot).startsWith('ok-ephemeral-')).toBe(true);+ expect(existsSync(join(ephemeralRoot, '.ok', 'config.yml'))).toBe(true);++ // destroy() reaps the self-provisioned root; the cwd project survives.+ await booted.destroy();+ booted = null;+ expect(existsSync(ephemeralRoot)).toBe(false);+ expect(existsSync(sentinel)).toBe(true);+ expect(existsSync(join(tmpDir, '.ok', 'config.yml'))).toBe(true);+ } finally {+ await rm(looseDir, { recursive: true, force: true });+ }+ });++ test('--single-file with a provided empty --project-dir seeds the synthesized config and boots', async () => {+ // The parent-spawn ABI hands over a pre-created dir; a directly-typed+ // --project-dir may be bare. Boot seeds the missing config instead of+ // refusing with MissingOkConfigError.+ const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));+ const providedDir = await mkdtemp(resolve(tmpdir(), 'ok-ephemeral-'));+ try {+ writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');+ booted = await bootStartServer({+ config: makeTestConfig(),+ cwd: tmpDir,+ host: TEST_HOST,+ skipAutoInit: true,+ singleFile: join(looseDir, 'note.md'),+ projectDir: providedDir,+ });+ await booted.ready;+ expect(existsSync(join(providedDir, '.ok', 'config.yml'))).toBe(true);+ expect(existsSync(join(providedDir, '.ok', '.gitignore'))).toBe(true);++ // Parent-provided: destroy leaves the dir for the parent to remove.+ await booted.destroy();+ booted = null;+ expect(existsSync(providedDir)).toBe(true);+ } finally {+ await rm(looseDir, { recursive: true, force: true });+ await rm(providedDir, { recursive: true, force: true });+ }+ });++ test('--single-file with an ordinary bare --project-dir is refused, not seeded', async () => {+ // Only the sanctioned throwaway shape gets the synthesized config. An+ // arbitrary user directory must stay untouched: no .ok/ written, no boot.+ const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));+ const ordinaryDir = await mkdtemp(resolve(tmpdir(), 'ok-start-ordinary-'));+ try {+ writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');+ await expect(+ bootStartServer({+ config: makeTestConfig(),+ cwd: tmpDir,+ host: TEST_HOST,+ skipAutoInit: true,+ singleFile: join(looseDir, 'note.md'),+ projectDir: ordinaryDir,+ }),+ ).rejects.toThrow(EphemeralProjectDirNotThrowawayError);+ expect(existsSync(join(ordinaryDir, '.ok'))).toBe(false);+ } finally {+ await rm(looseDir, { recursive: true, force: true });+ await rm(ordinaryDir, { recursive: true, force: true });+ }+ });++ test('--single-file with an initialized real project as --project-dir is refused untouched', async () => {+ // The highest-risk input class: a real project has a config, so it passes+ // the boot config gate — the throwaway check must gate it BEFORE that,+ // or the ephemeral session scatters .ok/local state into a real project.+ const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));+ const realProject = await mkdtemp(resolve(tmpdir(), 'ok-start-realproj-'));+ try {+ writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');+ mkdirSync(join(realProject, '.ok'), { recursive: true });+ writeFileSync(join(realProject, '.ok', 'config.yml'), 'content:\n dir: .\n', 'utf-8');+ writeFileSync(join(realProject, 'KEEP.md'), 'keep me', 'utf-8');+ await expect(+ bootStartServer({+ config: makeTestConfig(),+ cwd: tmpDir,+ host: TEST_HOST,+ skipAutoInit: true,+ singleFile: join(looseDir, 'note.md'),+ projectDir: realProject,+ }),+ ).rejects.toThrow(EphemeralProjectDirNotThrowawayError);+ expect(existsSync(join(realProject, 'KEEP.md'))).toBe(true);+ expect(existsSync(join(realProject, '.ok', 'local'))).toBe(false);+ } finally {+ await rm(looseDir, { recursive: true, force: true });+ await rm(realProject, { recursive: true, force: true });+ }+ });++ test('boot failure after self-provisioning reaps the freshly created ephemeral dir', async () => {+ // Force the failure AFTER the dir is minted by pre-binding the requested+ // port. TMPDIR scopes the mint to a private root (os.tmpdir() reads env+ // per call), so the "nothing left behind" assertion cannot race other+ // suites minting ok-ephemeral-* dirs in the shared temp root.+ const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));+ const privateTmp = await mkdtemp(resolve(tmpdir(), 'ok-start-privtmp-'));+ const prevTmpdirEnv = process.env.TMPDIR;+ const { createServer } = await import('node:http');+ const blocker = createServer(() => {});+ await new Promise<void>((r) => blocker.listen(0, '127.0.0.1', () => r()));+ const addr = blocker.address();+ const blockedPort = typeof addr === 'object' && addr !== null ? addr.port : 0;+ try {+ writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');+ process.env.TMPDIR = privateTmp;+ await expect(+ bootStartServer({+ config: makeTestConfig(),+ cwd: tmpDir,+ host: TEST_HOST,+ skipAutoInit: true,+ singleFile: join(looseDir, 'note.md'),+ port: blockedPort,+ }),+ ).rejects.toThrow();+ expect(readdirSync(privateTmp).filter((n) => n.startsWith('ok-ephemeral-'))).toEqual([]);+ } finally {+ if (prevTmpdirEnv === undefined) delete process.env.TMPDIR;+ else process.env.TMPDIR = prevTmpdirEnv;+ await new Promise<void>((r) => blocker.close(() => r()));+ await rm(looseDir, { recursive: true, force: true });+ await rm(privateTmp, { recursive: true, force: true });+ }+ });});describe('bootStartServer — no auto git-init from ok start (US-004)', () => {@@ -1135,20 +1303,105 @@ describe('tryDescribeLockCollision', () => {});});+describe('resolveStartConfig (ephemeral config isolation)', () => {+ test('single-file sessions drop the project config but keep the user-global layer', () => {+ // The cwd anchor points at whatever project the shell sits in — unrelated+ // to the loose file. Its server.* settings must not leak into the session,+ // but the user-global layer must survive (parity with `ok <file>`, whose+ // loadConfig on the ephemeral root reads user-global first).+ const projectConfig = ConfigSchema.parse({ server: { port: 4242 } });+ const userConfig = ConfigSchema.parse({ server: { port: 5151 } });+ const resolved = resolveStartConfig(projectConfig, '/tmp/note.md', () => userConfig);+ expect(resolved.server?.port).toBe(5151);+ expect(resolved).not.toBe(projectConfig);+ });++ test('plain ok start keeps the loaded project config untouched', () => {+ const projectConfig = ConfigSchema.parse({ server: { port: 4242 } });+ let userReads = 0;+ const resolved = resolveStartConfig(projectConfig, undefined, () => {+ userReads += 1;+ return ConfigSchema.parse({});+ });+ expect(resolved).toBe(projectConfig);+ expect(userReads).toBe(0);+ });+});++describe('isReapableEphemeralProjectDir', () => {+ test('accepts a direct ok-ephemeral-* child of os.tmpdir()', () => {+ expect(isReapableEphemeralProjectDir(join(tmpdir(), 'ok-ephemeral-abc123'))).toBe(true);+ });++ test('rejects a dir outside the temp root, whatever its name', () => {+ // The exact shape the cwd-fallback bug produced: a real project handed to+ // the reap. Containment must refuse it regardless of contents.+ expect(isReapableEphemeralProjectDir('/Users/someone/my-project')).toBe(false);+ });++ test('rejects a temp-root child without the ok-ephemeral- prefix', () => {+ // A user project living directly in the temp dir (common on Linux where+ // tmpdir() is /tmp) is not reapable — provenance requires the prefix.+ expect(isReapableEphemeralProjectDir(join(tmpdir(), 'my-scratch-project'))).toBe(false);+ });++ test('rejects an ok-ephemeral-* dir nested deeper than the temp root', () => {+ expect(isReapableEphemeralProjectDir(join(tmpdir(), 'nested', 'ok-ephemeral-x'))).toBe(false);+ });++ test('pierces temp-root symlinks via the injected realpath (macOS /tmp → /private/tmp)', () => {+ // The whole target is realpath-resolved: a literal '/tmp/ok-ephemeral-x'+ // matches when realpath maps the /tmp prefix onto the temp root.+ const realpathFn = (p: string): string =>+ p === '/tmp' || p.startsWith('/tmp/') ? p.replace(/^\/tmp/, '/private/tmp') : p;+ expect(+ isReapableEphemeralProjectDir('/tmp/ok-ephemeral-x', {+ tmpdirFn: () => '/private/tmp',+ realpathFn,+ }),+ ).toBe(true);+ });++ test('resolves a symlink leaf: an ok-ephemeral-* link pointing elsewhere is refused', () => {+ // The predicate canonicalizes the LEAF too — a link named ok-ephemeral-*+ // must not launder its target into reapability.+ const targetDir = mkdtempSync(join(tmpdir(), 'ok-start-symtarget-'));+ const link = join(tmpdir(), `ok-ephemeral-link-${basename(targetDir)}`);+ symlinkSync(targetDir, link);+ try {+ expect(isReapableEphemeralProjectDir(link)).toBe(false);+ } finally {+ rmSync(link, { force: true });+ rmSync(targetDir, { recursive: true, force: true });+ }+ });++ test('accepts a real mkdtemp ok-ephemeral-* dir on this OS (symlinked temp prefix and all)', () => {+ const real = mkdtempSync(join(tmpdir(), 'ok-ephemeral-'));+ try {+ expect(isReapableEphemeralProjectDir(real)).toBe(true);+ } finally {+ rmSync(real, { recursive: true, force: true });+ }+ });+});+describe('withEphemeralTempDirReap', () => {+ const reapable = join(tmpdir(), 'ok-ephemeral-x');+test('runs the inner handler, then removes the temp projectDir', async () => {const order: string[] = [];const handler = async () => {order.push('handler');};const removed: string[] = [];- const wrapped = withEphemeralTempDirReap(handler, '/tmp/ok-ephemeral-x', async (dir) => {+ const wrapped = withEphemeralTempDirReap(handler, reapable, async (dir) => {order.push('rm');removed.push(dir);});await wrapped();expect(order).toEqual(['handler', 'rm']);- expect(removed).toEqual(['/tmp/ok-ephemeral-x']);+ expect(removed).toEqual([reapable]);});test('swallows a rm failure (best-effort) — the handler still completes', async () => {@@ -1157,7 +1410,7 @@ describe('withEphemeralTempDirReap', () => {async () => {handled = true;},- '/tmp/ok-ephemeral-y',+ reapable,async () => {throw new Error('EBUSY');},@@ -1165,19 +1418,39 @@ describe('withEphemeralTempDirReap', () => {await expect(wrapped()).resolves.toBeUndefined();expect(handled).toBe(true);});+test('reaps the temp dir even when the inner handler throws (finally)', async () => {const removed: string[] = [];const wrapped = withEphemeralTempDirReap(async () => {throw new Error('destroy failed');},- '/tmp/ok-ephemeral-throw',+ reapable,async (dir) => {removed.push(dir);},);await expect(wrapped()).rejects.toThrow('destroy failed');- expect(removed).toEqual(['/tmp/ok-ephemeral-throw']);+ expect(removed).toEqual([reapable]);+ });++ test('REFUSES to rm a non-throwaway target — the containment backstop', async () => {+ // A real project wired into the ephemeral teardown must be leaked, never+ // deleted. The handler still runs; only the rm is withheld.+ const removed: string[] = [];+ let handled = false;+ const wrapped = withEphemeralTempDirReap(+ async () => {+ handled = true;+ },+ '/Users/someone/my-project',+ async (dir) => {+ removed.push(dir);+ },+ );+ await wrapped();+ expect(handled).toBe(true);+ expect(removed).toEqual([]);});});diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.tsindex f5dad23a3..973a9b1e6 100644--- a/packages/cli/src/commands/start.ts+++ b/packages/cli/src/commands/start.ts@@ -20,10 +20,11 @@* path the CLI uses, without process-level signal coupling.*/import { spawn as nativeSpawn } from 'node:child_process';-import { existsSync as fsExistsSync } from 'node:fs';+import { existsSync as fsExistsSync, realpathSync } from 'node:fs';import { rm } from 'node:fs/promises';import type { Server as HttpServer } from 'node:http';-import { basename, resolve as pathResolve } from 'node:path';+import { tmpdir } from 'node:os';+import { basename, dirname, resolve as pathResolve } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';import {applyConfigOverlay,@@ -32,19 +33,22 @@ import {EnvVarError,IDLE_SHUTDOWN_DURATION_RE,idleShutdownToMs,+ OK_DIR,resolveEnvConfigLayer,resolveServerRuntimeConfig,type ServerRuntimeConfig,} from '@inkeep/open-knowledge-core';+import { readConfigSafely, resolveConfigPath } from '@inkeep/open-knowledge-core/server';import {type BootedServer,type Config,+ EPHEMERAL_PROJECT_DIR_PREFIX,isProjectRoot,lockAdvertisesUi,type PinoLogger,prepareSingleFileOpen,} from '@inkeep/open-knowledge-server';-import { Command, InvalidArgumentError } from 'commander';+import { Command, InvalidArgumentError, Option } from 'commander';import { makeLazyEmbeddingsKeyStore } from '../auth/embeddings-key-store.ts';import { detectGh } from '../auth/gh-detect.ts';import { makeLazyProbeTokenStore } from '../auth/token-store.ts';@@ -268,13 +272,89 @@ export class OkDirMissingError extends Error {}}+/**+ * Thrown by `bootStartServer` when `--single-file` is given a `--project-dir`+ * that is not the sanctioned throwaway shape (`ok-ephemeral-*` directly under+ * the OS temp dir) — whether bare or already initialized. Booting with an+ * ordinary directory as the ephemeral root would write `.ok/` state into a+ * directory the user may not consider disposable, and the shutdown reap would+ * then (rightly) decline to clean it up. Refuse up front with the working+ * alternatives instead.+ */+export class EphemeralProjectDirNotThrowawayError extends Error {+ readonly projectDir: string;+ constructor(projectDir: string) {+ super(+ `--project-dir must be a throwaway ${EPHEMERAL_PROJECT_DIR_PREFIX}* directory under the OS temp dir. ` ++ `Refusing to write ephemeral session state into ${projectDir}. ` ++ 'Omit --project-dir to let ok start create (and clean up) its own.',+ );+ this.name = 'EphemeralProjectDirNotThrowawayError';+ this.projectDir = projectDir;+ }+}++/**+ * Provenance check for the destructive ephemeral reap: the CANONICAL target+ * must be a direct `ok-ephemeral-*` child of `os.tmpdir()` — the exact shape+ * `createEphemeralProjectDir` mints. The reap recursively deletes its target,+ * so it must never trust a flag value alone: `--project-dir` is user-reachable,+ * and an earlier cwd fallback let the reap delete a real project (content,+ * `.git`, everything) on idle shutdown.+ *+ * The whole path is realpath-resolved before the check: a symlinked temp-root+ * prefix (macOS `/tmp` → `/private/tmp`, `/var` → `/private/var`) still+ * matches, and a symlink LEAF named `ok-ephemeral-*` resolves to its target,+ * so a link pointing at a real project fails the check and is refused. When+ * the leaf does not exist (already reaped), its parent is still resolved and+ * the literal basename is kept. Any other realpath failure (EACCES, ELOOP,+ * EIO) fails CLOSED: a path that cannot be trusted is not a reap target.+ * Never throws. Deps are injectable for tests.+ */+export function isReapableEphemeralProjectDir(+ dir: string,+ deps: { tmpdirFn?: () => string; realpathFn?: (path: string) => string } = {},+): boolean {+ const tmpdirFn = deps.tmpdirFn ?? tmpdir;+ const realpathFn = deps.realpathFn ?? realpathSync;+ const canonical = (path: string): string | null => {+ try {+ return realpathFn(path);+ } catch (err) {+ return (err as NodeJS.ErrnoException).code === 'ENOENT' ? pathResolve(path) : null;+ }+ };+ const literal = pathResolve(dir);+ let target: string | null;+ try {+ target = realpathFn(literal);+ } catch (err) {+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') {+ const parent = canonical(dirname(literal));+ target = parent === null ? null : pathResolve(parent, basename(literal));+ } else {+ target = null;+ }+ }+ if (target === null) return false;+ const tmpRoot = canonical(tmpdirFn());+ if (tmpRoot === null) return false;+ return dirname(target) === tmpRoot && basename(target).startsWith(EPHEMERAL_PROJECT_DIR_PREFIX);+}+/*** Wrap an idle-shutdown handler so that, after the server is destroyed, the* ephemeral session's throwaway temp projectDir is removed. Without this an* agent- or tab-closed single-file session leaks its temp dir — boot's destroy* alone releases the locks but leaves the dir on disk. Reaping is best-effort- * (the dir lives in os.tmpdir and is OS-reaped regardless). `rmFn` is injected- * for testing.+ * (the dir lives in os.tmpdir and is OS-reaped regardless). `rmFn` is+ * injected for testing.+ *+ * The reap REFUSES any target that fails `isReapableEphemeralProjectDir` —+ * this is the containment backstop for a recursive delete of a user-influenced+ * path, and it must stay in front of every rm this wrapper performs. The+ * predicate is deliberately NOT injectable: an injection seam here is a+ * bypass door for the one check standing between a flag value and `rm -rf`.*/export function withEphemeralTempDirReap(handler: () => Promise<void>,@@ -287,14 +367,22 @@ export function withEphemeralTempDirReap(} finally {// `finally` so a throwing handler (e.g. destroy() propagating) still reaps// the temp dir rather than leaking it.- try {- await rmFn(projectDir);- } catch (err) {- // best-effort; the dir is in os.tmpdir (OS-reaped) regardless. rm with- // force already swallows ENOENT, so anything here (EPERM, bad path) is- // unexpected — log it so leaked dirs are attributable.+ if (isReapableEphemeralProjectDir(projectDir)) {+ try {+ await rmFn(projectDir);+ } catch (err) {+ // best-effort; the dir is in os.tmpdir (OS-reaped) regardless. rm with+ // force already swallows ENOENT, so anything here (EPERM, bad path) is+ // unexpected — log it so leaked dirs are attributable.+ process.stderr.write(+ `[start] ephemeral temp dir reap failed for ${projectDir}: ${err instanceof Error ? err.message : String(err)}\n`,+ );+ }+ } else {+ // A non-throwaway target means a caller wired a real directory into the+ // ephemeral teardown — leave it in place rather than delete user data.process.stderr.write(- `[start] ephemeral temp dir reap failed for ${projectDir}: ${err instanceof Error ? err.message : String(err)}\n`,+ `[start] leaving ${projectDir} in place: only ${EPHEMERAL_PROJECT_DIR_PREFIX}* dirs under the OS temp dir are removed on ephemeral teardown\n`,);}}@@ -498,14 +586,18 @@ interface BootStartServerOptions {* - boots with `ephemeral: true` + `gitEnabled: false` + MCP unmounted, and* skips the init-required guard and the reclaim sweeps (no project to* reclaim).- * The caller (`runSingleFileBrowserOpen` / the desktop spawn) owns the temp- * projectDir's lifecycle and removes it on teardown.+ * With `projectDir` set, the caller (`runSingleFileBrowserOpen` / the desktop+ * spawn) owns the temp dir's lifecycle and removes it on teardown; without+ * it, `bootStartServer` creates its own throwaway dir and reaps it on+ * destroy and idle shutdown.*/singleFile?: string;/*** Explicit project root, distinct from `cwd`. Only meaningful in the* ephemeral single-file path, where it is the throwaway temp dir carrying the- * synthesized `.ok/config.yml`. Defaults to `cwd`.+ * synthesized `.ok/config.yml` (seeded on boot when missing). When absent in+ * that path, a fresh temp dir is created — never `cwd`: a real project as the+ * ephemeral root gets recursively deleted by the idle-shutdown reap.*/projectDir?: string;}@@ -546,9 +638,16 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Booopts.idleThresholdMs === undefined ? DEFAULT_IDLE_THRESHOLD_MS : opts.idleThresholdMs;const { existsSync, mkdirSync } = await import('node:fs');- const { basename, dirname } = await import('node:path');- const { bootServer, getLogger, resolveContentDir, resolveLockDir, waitForServerLockDrain } =- await import('@inkeep/open-knowledge-server');+ const { basename, dirname, resolve } = await import('node:path');+ const {+ bootServer,+ createEphemeralProjectDir,+ getLogger,+ resolveContentDir,+ resolveLockDir,+ seedEphemeralProjectDir,+ waitForServerLockDrain,+ } = await import('@inkeep/open-knowledge-server');const log = opts.log ?? getLogger('start');@@ -558,7 +657,6 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Boo// `.ok/` state lives only in the throwaway `projectDir`. The init-required// guard + reclaim sweeps target a real project — neither applies here.const ephemeral = opts.singleFile !== undefined;- const ephemeralProjectDir = opts.projectDir ?? cwd;// `--single-file` is the desktop→child spawn contract (the desktop passes a// path already validated by `prepareSingleFileOpen`), but the flag is directly// reachable. Re-validate to the same typed rejections `ok <file>` gives@@ -571,6 +669,65 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Booconst ephemeralContentDir = ephemeralFile ? dirname(ephemeralFile) : undefined;const ephemeralDocRelPath = ephemeralFile ? basename(ephemeralFile) : undefined;+ // Establish the ephemeral project root this boot consumes — the invariant is+ // that whoever boots the ephemeral shape provisions its throwaway projectDir.+ // A parent-provided `--project-dir` (the desktop / `ok <file>` spawn ABI) is+ // used as-is, seeded if its synthesized config is missing; with no+ // `--project-dir`, a fresh temp dir is created HERE and owned by this boot+ // (reaped on destroy and on idle shutdown). Never fall back to cwd: an+ // initialized cwd passes the boot config gate and the ephemeral teardown+ // would then recursively delete a real project on idle shutdown.+ let ephemeralProjectDir: string | undefined;+ let ownsEphemeralProjectDir = false;+ if (ephemeralContentDir !== undefined) {+ if (opts.projectDir !== undefined) {+ ephemeralProjectDir = opts.projectDir;+ // EVERY provided --project-dir must be the sanctioned throwaway shape,+ // config or no config. Gating only the seeding branch would wave through+ // an initialized real project (it has a config), boot with it as the+ // ephemeral root, and scatter `.ok/local/` runtime state into it — the+ // exact input class the cwd fallback destroyed. Both spawn-ABI producers+ // pass a `createEphemeralProjectDir` result, which satisfies this.+ if (!isReapableEphemeralProjectDir(ephemeralProjectDir)) {+ throw new EphemeralProjectDirNotThrowawayError(ephemeralProjectDir);+ }+ if (!existsSync(resolve(ephemeralProjectDir, OK_DIR, 'config.yml'))) {+ seedEphemeralProjectDir(ephemeralProjectDir, ephemeralContentDir);+ }+ } else {+ ephemeralProjectDir = createEphemeralProjectDir(ephemeralContentDir);+ ownsEphemeralProjectDir = true;+ }+ }+ // Best-effort cleanup for the self-provisioned dir when boot fails below —+ // the parent-provided dir stays the parent's to remove. Failures are logged,+ // not swallowed: this process is the dir's sole owner, so a silent rm+ // failure would orphan `ok-ephemeral-*` dirs with no diagnostic trail.+ const reapOwnedEphemeralDir = async (): Promise<void> => {+ if (!ownsEphemeralProjectDir || ephemeralProjectDir === undefined) return;+ if (!isReapableEphemeralProjectDir(ephemeralProjectDir)) {+ // Can only fire if the dir this process minted stopped resolving to the+ // throwaway shape between mint and teardown — something replaced it+ // under a running session. Worth a trail, not silence.+ log.warn(+ { ephemeralProjectDir },+ '[start] refusing to reap self-provisioned ephemeral dir: no longer resolves to an ok-ephemeral-* temp dir',+ );+ return;+ }+ try {+ await rm(ephemeralProjectDir, { recursive: true, force: true });+ } catch (err) {+ log.warn(+ { err, ephemeralProjectDir },+ '[start] failed to reap self-provisioned ephemeral temp dir',+ );+ }+ };+ // `const` capture: `let` narrowing does not survive into the idle-shutdown+ // closure passed to bootServer below.+ const reapDirOnIdle = ephemeralProjectDir;+if (!ephemeral) {// Guard: cwd must already be a valid OK project root (`.ok/config.yml`// exists as a regular file). ok start no longer scaffolds — run `ok init`@@ -673,95 +830,119 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Boo// within the predecessor's last seconds. On timeout we proceed anyway and// let the acquire collide: a wedged teardown should fail loud, not spawn a// duplicate.- {- const drainLockDir = resolveLockDir(ephemeral ? ephemeralProjectDir : cwd);- const drainWaitStartedAt = Date.now();- const drainOutcome = await waitForServerLockDrain(drainLockDir);- if (drainOutcome !== 'no-drain') {- // `waitedMs` is the tuning signal for the 10s drain timeout: released- // durations creeping toward it mean real teardowns are outgrowing the- // budget and would start colliding under normal load.- log.info(- {- event: 'start-waited-for-draining-predecessor',- outcome: drainOutcome,- waitedMs: Date.now() - drainWaitStartedAt,- drainLockDir,- },- drainOutcome === 'released'- ? '[start] predecessor server finished draining — proceeding'- : '[start] predecessor server still draining after wait — proceeding to collide',- );+ // From here to the end of bootServer a throw must clean up the+ // self-provisioned ephemeral dir — the caller never learns the path, so an+ // unreaped dir on a failed boot is unattributable.+ let booted: BootedServer;+ try {+ {+ const drainLockDir = resolveLockDir(ephemeralProjectDir ?? cwd);+ const drainWaitStartedAt = Date.now();+ const drainOutcome = await waitForServerLockDrain(drainLockDir);+ if (drainOutcome !== 'no-drain') {+ // `waitedMs` is the tuning signal for the 10s drain timeout: released+ // durations creeping toward it mean real teardowns are outgrowing the+ // budget and would start colliding under normal load.+ log.info(+ {+ event: 'start-waited-for-draining-predecessor',+ outcome: drainOutcome,+ waitedMs: Date.now() - drainWaitStartedAt,+ drainLockDir,+ },+ drainOutcome === 'released'+ ? '[start] predecessor server finished draining — proceeding'+ : '[start] predecessor server still draining after wait — proceeding to collide',+ );+ }}++ booted = await bootServer({+ config,+ contentDir,+ projectDir: ephemeralProjectDir ?? cwd,+ contentRoot: ephemeral ? undefined : config.content.dir,+ port: opts.port,+ host,+ quiet: false,+ detectGh,+ tokenStore,+ embeddingsKeyStore,+ mcpTomlEditor: getNativeTomlMcpEditor(),+ // Ephemeral single-file mode: scope content to the one doc, no MCP, no git+ // (shadow repo + commits off), and a no-op git preflight so a machine+ // without git can still open a loose file. The synthesized config lives at+ // `ephemeralProjectDir/.ok/config.yml`; the file edit lands on the real+ // file inside `contentDir`.+ ...(ephemeral+ ? {+ ephemeral: true as const,+ singleDocRelPath: ephemeralDocRelPath,+ gitEnabled: false as const,+ gitPreflight: () => ({+ ok: true as const,+ version: '0.0.0',+ resolvedPath: 'git',+ source: 'PATH' as const,+ }),+ }+ : {}),+ // Pass the exact runtime that started this server so /api/local-op/* can+ // spawn additional CLI processes without needing open-knowledge on PATH.+ localOpCliArgs: [process.execPath, process.argv[1]],+ // ACP threads skip injecting the `open-knowledge` MCP server when the+ // agent's own harness already loads OK's managed editor-config entry.+ probeHarnessManagedMcpEntry: (editorId, agentCwd) =>+ probeOwnManagedEditorMcpEntry(editorId, agentCwd),+ // Pi has no MCP client, so its ACP threads get OK tools from the managed+ // bridge extension in the project instead — probed at session setup and,+ // with the user's consent, provisioned there and then.+ probePiAcpBridge: (agentCwd) => probePiBridgeState(agentCwd),+ ensurePiAcpBridge: (agentCwd) => ensurePiBridge(agentCwd),+ // CLI-specific opt-ins+ idleShutdownMs: idleThresholdMs,+ ...(opts.serverRuntime !== undefined ? { serverRuntime: opts.serverRuntime } : {}),+ ...(opts.bind !== undefined ? { bind: opts.bind } : {}),+ skipAutoInit: true, // Guard already ran above; no scaffold fn to pass+ idleShutdownHandler: (destroyServer) => {+ const handler = destroyServer;+ const reaped =+ reapDirOnIdle !== undefined ? withEphemeralTempDirReap(handler, reapDirOnIdle) : handler;+ // Outermost: the exit fires only after destroy AND the ephemeral temp+ // dir reap have both run.+ return withIdleShutdownProcessExit(reaped, { log, exit: opts.idleExit });+ },+ log,+ // Content assets serve by default (bootServer default-on). The React+ // shell dir is passed through when present — the default for plain+ // `ok start` — so the one-listener composition is the norm.+ ...(opts.serveContentAssets !== undefined+ ? { serveContentAssets: opts.serveContentAssets }+ : {}),+ ...(opts.reactShellDistDir ? { reactShellDistDir: opts.reactShellDistDir } : {}),+ });+ } catch (err) {+ await reapOwnedEphemeralDir();+ throw err;}- const booted: BootedServer = await bootServer({- config,- contentDir,- projectDir: ephemeral ? ephemeralProjectDir : cwd,- contentRoot: ephemeral ? undefined : config.content.dir,- port: opts.port,- host,- quiet: false,- detectGh,- tokenStore,- embeddingsKeyStore,- mcpTomlEditor: getNativeTomlMcpEditor(),- // Ephemeral single-file mode: scope content to the one doc, no MCP, no git- // (shadow repo + commits off), and a no-op git preflight so a machine- // without git can still open a loose file. The synthesized config lives at- // `ephemeralProjectDir/.ok/config.yml`; the file edit lands on the real- // file inside `contentDir`.- ...(ephemeral- ? {- ephemeral: true as const,- singleDocRelPath: ephemeralDocRelPath,- gitEnabled: false as const,- gitPreflight: () => ({- ok: true as const,- version: '0.0.0',- resolvedPath: 'git',- source: 'PATH' as const,- }),+ // A parent-provided dir stays the parent's to remove (the desktop and the+ // `ok <file>` browser path both reap their own temp dir on teardown); the+ // self-provisioned dir has no other owner, so destroy() reaps it here.+ const innerDestroy = booted.destroy;+ const destroy = ownsEphemeralProjectDir+ ? async (): Promise<void> => {+ try {+ await innerDestroy();+ } finally {+ await reapOwnedEphemeralDir();}- : {}),- // Pass the exact runtime that started this server so /api/local-op/* can- // spawn additional CLI processes without needing open-knowledge on PATH.- localOpCliArgs: [process.execPath, process.argv[1]],- // ACP threads skip injecting the `open-knowledge` MCP server when the- // agent's own harness already loads OK's managed editor-config entry.- probeHarnessManagedMcpEntry: (editorId, agentCwd) =>- probeOwnManagedEditorMcpEntry(editorId, agentCwd),- // Pi has no MCP client, so its ACP threads get OK tools from the managed- // bridge extension in the project instead — probed at session setup and,- // with the user's consent, provisioned there and then.- probePiAcpBridge: (agentCwd) => probePiBridgeState(agentCwd),- ensurePiAcpBridge: (agentCwd) => ensurePiBridge(agentCwd),- // CLI-specific opt-ins- idleShutdownMs: idleThresholdMs,- ...(opts.serverRuntime !== undefined ? { serverRuntime: opts.serverRuntime } : {}),- ...(opts.bind !== undefined ? { bind: opts.bind } : {}),- skipAutoInit: true, // Guard already ran above; no scaffold fn to pass- idleShutdownHandler: (destroyServer) => {- const handler = destroyServer;- const reaped = ephemeral ? withEphemeralTempDirReap(handler, ephemeralProjectDir) : handler;- // Outermost: the exit fires only after destroy AND the ephemeral temp- // dir reap have both run.- return withIdleShutdownProcessExit(reaped, { log, exit: opts.idleExit });- },- log,- // Content assets serve by default (bootServer default-on). The React- // shell dir is passed through when present — the default for plain- // `ok start` — so the one-listener composition is the norm.- ...(opts.serveContentAssets !== undefined- ? { serveContentAssets: opts.serveContentAssets }- : {}),- ...(opts.reactShellDistDir ? { reactShellDistDir: opts.reactShellDistDir } : {}),- });+ }+ : innerDestroy;return {httpServer: booted.httpServer,- destroy: booted.destroy,+ destroy,lockDir: booted.lockDir,contentDir,port: booted.port,@@ -815,6 +996,34 @@ interface StartCommandOptions {externalUrl?: string;}+/**+ * Resolve the file-layer config for a `start` invocation. An ephemeral+ * single-file session drops the PROJECT layers: the CLI's cwd anchor points+ * at whatever project the shell happens to sit in, which is unrelated to the+ * loose file being opened — inheriting its `server.*` settings made the same+ * session behave differently by cwd. The user-global `~/.ok/global.yml`+ * layer SURVIVES, matching `ok <file>` (whose `loadConfig(ephemeralRoot)`+ * reads user-global plus the synthesized project config, which contributes+ * only `content.dir` — overridden explicitly by the ephemeral boot anyway).+ * Flags and env still override through the normal precedence.+ *+ * The user-layer read does not sideline a broken file (the primary+ * `loadConfig` this session already did that and reported it); it degrades+ * to schema defaults. `readUserConfig` is injected for tests.+ */+export function resolveStartConfig(+ config: Config,+ singleFile: string | undefined,+ readUserConfig: () => Config = () =>+ readConfigSafely({+ absPath: resolveConfigPath('user', process.cwd()),+ sideline: false,+ warn: () => {},+ }).value,+): Config {+ return singleFile !== undefined ? readUserConfig() : config;+}+/*** Validator for Commander's `option` parser — restricts `--mode` to the* documented enum. Throws `InvalidArgumentError` for anything else,@@ -873,7 +1082,8 @@ export function formatShutdownNotice(signal: NodeJS.Signals): string[] {* This is the "browser mode" path; bit-for-bit identical to today's* behavior when called with no `--mode` or with `--mode=browser`.*/-export async function runStartCommand(config: Config, opts: StartCommandOptions): Promise<void> {+export async function runStartCommand(configArg: Config, opts: StartCommandOptions): Promise<void> {+ const config = resolveStartConfig(configArg, opts.singleFile);// Quiet the terminal BEFORE any getLogger()/reclaim sweep fires (both happen// inside bootStartServer below). The `start` logger and the skill-reclaim// sweep are constructed before bootServer wires the file sink, so a level@@ -1043,6 +1253,13 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)process.exit(1);}+ // --project-dir refused (not a throwaway shape) — the message carries the+ // fix; render it cleanly like the other flag-validation rejections.+ if (err instanceof EphemeralProjectDirNotThrowawayError) {+ console.error(error(err.message));+ process.exit(1);+ }+// Git preflight failure: bootServer already emitted telemetry, logged the// event, wrote install guidance to stderr, and flushed the OTel exporter// before re-throwing the typed error. The CLI just maps it to EX_CONFIG@@ -1075,6 +1292,15 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)process.exit(1);}+ // bootServer's own config gate (`.ok/config.yml` absent at the resolved+ // projectDir). The CLI guard above normally fires first; this arm covers+ // the remaining direct-flag shapes so the user gets the message, not a+ // stack trace.+ if (err instanceof serverModule.MissingOkConfigError) {+ console.error(error(err.message));+ process.exit(1);+ }+// Spawn-or-reuse: a plain `ok start` that collided with a live server// reads the holder's advertisement, reports its URL, and exits 0 — a// second start attaches to the running composition instead of failing.@@ -1391,13 +1617,20 @@ export function startCommand(getConfig: () => Config): Command {'Serve content assets from this server (now the default; kept for compatibility)',).option('--react-shell-dist-dir <path>', 'Serve React shell from <path>')- .option(- '--single-file <path>',- 'No-project ephemeral single-file mode: scope the server to one markdown file (git + MCP off)',+ // Hidden from --help: both are the desktop→child spawn ABI, not a user+ // surface — the supported way to open one file is `ok <file>`. They stay+ // functional (and validated) for parent spawners and anyone who knows.+ .addOption(+ new Option(+ '--single-file <path>',+ 'No-project ephemeral single-file mode: scope the server to one markdown file (git + MCP off)',+ ).hideHelp(),)- .option(- '--project-dir <dir>',- 'Throwaway project root for --single-file (where ephemeral .ok/ state lives)',+ .addOption(+ new Option(+ '--project-dir <dir>',+ 'Throwaway project root for --single-file (where ephemeral .ok/ state lives)',+ ).hideHelp(),).option('--external-url <url>',@@ -1416,6 +1649,15 @@ export function startCommand(getConfig: () => Config): Command {process.exit(2);}+ // `--project-dir` names the throwaway root of the ephemeral single-file+ // shape and means nothing outside it. Fail loud rather than silently+ // ignore — a user pointing it at a real project must not believe the+ // server is rooted there.+ if (opts.projectDir !== undefined && opts.singleFile === undefined) {+ process.stderr.write("error: option '--project-dir' requires '--single-file'\n");+ process.exit(2);+ }+// `--mode=app` shortcuts the server boot and hands off to the// desktop app.if (opts.mode === 'app') {diff --git a/packages/server/src/index.ts b/packages/server/src/index.tsindex a0eb77175..d579ca5f0 100644--- a/packages/server/src/index.ts+++ b/packages/server/src/index.ts@@ -529,11 +529,13 @@ export {export { originGitHubHost } from './share/git-context.ts';export {createEphemeralProjectDir,+ EPHEMERAL_PROJECT_DIR_PREFIX,prepareSingleFileOpen,SingleFileNotAFileError,SingleFileNotFoundError,SingleFileNotMarkdownError,type SingleFileOpenPlan,+ seedEphemeralProjectDir,} from './single-file-open.ts';export {BUNDLE_IDS,diff --git a/packages/server/src/single-file-open.test.ts b/packages/server/src/single-file-open.test.tsindex f310b4e54..e21d89da4 100644--- a/packages/server/src/single-file-open.test.ts+++ b/packages/server/src/single-file-open.test.ts@@ -13,10 +13,12 @@ import { basename, join } from 'node:path';import { afterEach, describe, expect, test } from 'vitest';import {createEphemeralProjectDir,+ EPHEMERAL_PROJECT_DIR_PREFIX,prepareSingleFileOpen,SingleFileNotAFileError,SingleFileNotFoundError,SingleFileNotMarkdownError,+ seedEphemeralProjectDir,} from './single-file-open.ts';const cleanups: string[] = [];@@ -134,8 +136,23 @@ describe('createEphemeralProjectDir', () => {// spaces are valid YAML.expect(cfg).toContain(JSON.stringify(contentDir));// The throwaway dir is an `ok-ephemeral-*` mkdtemp under os.tmpdir, NOT the- // user's content dir.- expect(basename(projectDir).startsWith('ok-ephemeral-')).toBe(true);+ // user's content dir. The prefix doubles as the reap's provenance marker,+ // so the constant and the minted name must stay one and the same.+ expect(basename(projectDir).startsWith(EPHEMERAL_PROJECT_DIR_PREFIX)).toBe(true);expect(projectDir).not.toBe(contentDir);});});++describe('seedEphemeralProjectDir', () => {+ test('seeds .ok/config.yml + .gitignore into an existing dir and returns it', () => {+ const contentDir = tmp('sfo-content-');+ const bareDir = tmp('sfo-bare-');+ const returned = seedEphemeralProjectDir(bareDir, contentDir);+ expect(returned).toBe(bareDir);+ expect(existsSync(join(bareDir, '.ok', 'config.yml'))).toBe(true);+ expect(existsSync(join(bareDir, '.ok', '.gitignore'))).toBe(true);+ expect(readFileSync(join(bareDir, '.ok', 'config.yml'), 'utf-8')).toContain(+ JSON.stringify(contentDir),+ );+ });+});diff --git a/packages/server/src/single-file-open.ts b/packages/server/src/single-file-open.tsindex 11701fe2a..e8761d416 100644--- a/packages/server/src/single-file-open.ts+++ b/packages/server/src/single-file-open.ts@@ -138,19 +138,25 @@ function resolveProjectContentDir(projectRoot: string): string {}/**- * Create the throwaway `projectDir` for an ephemeral single-file session: an- * `os.tmpdir()` `mkdtemp` carrying a synthesized minimal `.ok/config.yml`- * (so the boot config gate passes) plus a `.ok/.gitignore` (so the- * boot hygiene warning stays quiet). The `.ok/local/` runtime state (lock,- * shadow, caches) lands here, never in the user's directory. The owner of- * the session lifecycle (the CLI browser path, or the desktop window) removes- * this directory on teardown.+ * Basename prefix of every throwaway ephemeral projectDir this module mints+ * (`mkdtemp` under `os.tmpdir()`). The CLI's idle-shutdown reap uses it as a+ * provenance check before recursively deleting a projectDir — a dir that is+ * not a direct `ok-ephemeral-*` child of the temp root is never a sanctioned+ * reap target, whatever flag value claimed it was.+ */+export const EPHEMERAL_PROJECT_DIR_PREFIX = 'ok-ephemeral-';++/**+ * Seed an existing directory as an ephemeral single-file projectDir: a+ * synthesized minimal `.ok/config.yml` (so the boot config gate passes) plus+ * a `.ok/.gitignore` (so the boot hygiene warning stays quiet). Writes+ * unconditionally — callers that might hand it a dir with a real config guard+ * with their own existence check first.** `contentDir` is written into `content.dir` for honesty, but the ephemeral* boot passes `contentDir` explicitly — config resolution does not drive it.*/-export function createEphemeralProjectDir(contentDir: string): string {- const projectDir = mkdtempSync(resolve(tmpdir(), 'ok-ephemeral-'));+export function seedEphemeralProjectDir(projectDir: string, contentDir: string): string {const okDir = resolve(projectDir, OK_DIR);mkdirSync(okDir, { recursive: true });// Minimal valid YAML config — empty would also parse to schema defaults, but@@ -165,3 +171,18 @@ export function createEphemeralProjectDir(contentDir: string): string {writeFileSync(resolve(okDir, '.gitignore'), 'local/\n', 'utf-8');return projectDir;}++/**+ * Create the throwaway `projectDir` for an ephemeral single-file session: an+ * `os.tmpdir()` `mkdtemp` seeded via `seedEphemeralProjectDir`. The+ * `.ok/local/` runtime state (lock, shadow, caches) lands here, never in the+ * user's directory. The owner of the session lifecycle (the CLI browser path,+ * the desktop window, or `bootStartServer` when it self-provisions for a+ * direct `ok start --single-file`) removes this directory on teardown.+ */+export function createEphemeralProjectDir(contentDir: string): string {+ return seedEphemeralProjectDir(+ mkdtempSync(resolve(tmpdir(), EPHEMERAL_PROJECT_DIR_PREFIX)),+ contentDir,+ );+}