copilot-operator 0.1.13 → 0.1.16

package/dist/src/cli.js

@@ -4,13 +4,12 @@
  *
  *   cop login                 sign in once; the Edge profile is reused afterwards
  *   cop doctor [run.yaml]     check the machine before trusting a run to it
- *   cop mirror <run.yaml>     refresh the Desktop folder without touching the chat
  *   cop run <run.yaml>        the loop
  *   cop chat                  print the last run's conversation link
  */
 import { Command } from 'commander';
 import { existsSync, readFileSync } from 'node:fs';
-import { mkdir, rm } from 'node:fs/promises';
+import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { installLayout } from './config/layout.js';
 import { spawn, spawnSync } from 'node:child_process';
@@ -20,31 +19,67 @@ import { loadConfig, expandPath } from './config/schema.js';
 import { CopilotTransport } from './transport/copilotTransport.js';
 import { runSession } from './orchestrator/taskRunner.js';
 import { SessionStore } from './session/store.js';
+import { settingsOf, SettingsUnusableError } from './api/settings.js';
+import { PolicyLockUnusableError } from './config/lockedPolicy.js';
 import { EventBus } from './session/events.js';
 import { terminalAuthorizer, unattendedAuthorizer } from './exec/authorizer.js';
 import { unattendedPrecondition } from './exec/policy.js';
-import { mirrorProject, describeMirror, listSelectableDirs } from './context/projectMirror.js';
-import { isOwnCheckout } from './exec/workDir.js';
-import { defaultExportDir, desktopIsSynced, resolveDesktopDir } from './context/contextFiles.js';
+import { botRootDir, isOwnCheckout } from './exec/workDir.js';
+import { desktopIsSynced, resolveDesktopDir } from './context/desktopDir.js';
 import { Url } from './transport/locators.js';
 import { findEdgeUsingProfile } from './transport/profileLock.js';
 import { assessIsolation, readIsolationSignals } from './exec/isolation.js';
+/**
+ * The version of the copilot-operator that is running, from its own package.json.
+ *
+ * It was a literal, '0.1.0', and stayed that through thirteen releases, so a bug report's
+ * `cop --version` named a version that never had the bug. Read where the code is — `src/` under
+ * tsx, `dist/src/` in a clone, `node_modules/copilot-operator/dist/src/` once installed — so it
+ * cannot drift from what npm installed. botRootDir() falls back to the working directory when it
+ * finds no package.json of ours, and that one is the user's project's: its version is not ours to
+ * print, so the name is checked and anything else says "unknown".
+ */
+function ownVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(botRootDir(), 'package.json'), 'utf8'));
+        if (pkg.name === 'copilot-operator' && typeof pkg.version === 'string' && pkg.version)
+            return pkg.version;
+    }
+    catch {
+        // No readable package.json: say so rather than guess.
+    }
+    return 'unknown';
+}
 const program = new Command();
 program
     .name('cop')
     .description('Runs a task loop with Microsoft 365 Copilot on a Windows machine.')
-    .version('0.1.0');
+    .version(ownVersion());
 const DEFAULT_PROFILE = expandPath('~/AppData/Local/copilot-operator/edge-profile', process.cwd());
 program
     .command('start')
-    .description('start copilot-operator for this project: the API and the web interface, on 127.0.0.1')
+    .description("start copilot-operator for this project on 127.0.0.1: the API, and the web interface the package ships (a clone's interface comes from npm start)")
     .option('--port <port>', 'the port to listen on', '4000')
-    .option('--open', 'open the interface in the default browser once it is up')
+    .option('--open', 'open the interface in the default browser once it is up (an installed package; not in a clone)')
     .action(async (opts) => {
     process.env.COP_API_PORT = String(Number(opts.port) || 4000);
+    /*
+     * A clone's API serves no web interface (see `installLayout`): its interface is the dev server
+     * `npm start` runs, which builds the token into its page. So `cop start` in a clone is the API
+     * alone, and it says so before anything else rather than leave the operator looking for a page;
+     * and --open is not followed there, because the page it would open on this port answers a
+     * browser with 401.
+     */
+    const clone = installLayout().mode === 'checkout';
+    if (clone) {
+        console.log("cop start in a clone of copilot-operator starts the API only: a clone's web interface comes from npm start, which runs the API and the interface together.");
+        if (opts.open) {
+            console.log('--open is not followed in a clone: this port serves no page there and would answer the browser with 401. npm run dev starts both and opens the interface.');
+        }
+    }
     // The API runs in this process; importing it starts it. See src/api/main.ts.
     await import('./api/main.js');
-    if (opts.open) {
+    if (opts.open && !clone) {
         const url = `http://127.0.0.1:${process.env.COP_API_PORT}/`;
         const deadline = Date.now() + 30_000;
         while (Date.now() < deadline) {
@@ -178,7 +213,7 @@ program
         replyTimeoutMs: 60_000,
         signInTimeoutMs: 15 * 60_000,
         humanWaitMs: 15 * 60_000,
-        onEvent: (e, d) => process.stdout.write(`  ${e}${d && Object.keys(d).length ? ' ' + JSON.stringify(d) : ''}
+        onEvent: (e, d) => process.stdout.write(`  ${e}${d && Object.keys(d).length ? ' ' + JSON.stringify(d) : ''}
 `),
     });
     await transport.open();
@@ -252,7 +287,8 @@ program
     say(ping.status === 0, ping.status === 0
         ? `npm reaches ${registry}`
         : `npm cannot reach ${registry} — behind a proxy, set it for npm (npm config set proxy / https-proxy) or HTTPS_PROXY; every plan starts with npm install`);
-    const dataDir = installLayout().dataDir;
+    const layout = installLayout();
+    const dataDir = layout.dataDir;
     const readJson = (file) => {
         try {
             return JSON.parse(readFileSync(join(dataDir, file), 'utf8'));
@@ -261,36 +297,63 @@ program
             return null;
         }
     };
-    const settings = readJson('settings.json');
     /*
-     * Where the bot is running, which is the only thing that actually contains a command once it
-     * runs. Reported here rather than left to the README, because a machine that ignored the
-     * recommendation looked exactly like one that had followed it. The claim is the operator's;
-     * `doctor` only says what it can see and where the two disagree. See `exec/isolation.ts`.
+     * The settings, read the way the API reads them: a file that is there and cannot be used is the
+     * problem to report, since the API will not start on it, not a file to take for empty. Taken for
+     * empty, doctor said "isolation: none" and "no default model is set" of a file that may say
+     * otherwise, and never that it was broken. The checks below that read it wait until it is mended.
+     *
+     * Read by the API's own `Settings` and loaded as the API loads them before it opens its port,
+     * which reads the policy locks too. Parsed and checked here on its own, the file was all doctor
+     * looked at: a lock that did not parse stopped `npm start` while doctor said "Ready.".
      */
-    const posture = assessIsolation(settings?.execution?.isolation ?? 'none', readIsolationSignals());
-    say(posture.warnings.length === 0, `isolation: ${posture.claim}, running as ${posture.signals.user}${posture.signals.elevated === true ? ' (ELEVATED)' : ''}`);
-    for (const concern of posture.warnings)
-        say(false, `  ${concern}`);
-    const models = readJson('models.json');
-    const copilot = settings?.copilot ?? {};
-    const wanted = [
-        ['default model', (copilot.defaultModel ?? '').trim()],
-        ['default review model', (copilot.defaultReviewModel ?? '').trim()],
-    ].filter(([, name]) => name !== '');
-    if (wanted.length === 0) {
-        console.log('  note  no default model is set; sessions leave the chat on whatever it shows');
+    const store = settingsOf(layout);
+    let settings = null;
+    try {
+        const value = await store.raw();
+        await store.load();
+        settings = value;
     }
-    else if (!models?.options?.length) {
-        console.log(`  note  ${wanted.map(([w, n]) => `${w} "${n}"`).join(', ')} set, but the picker has never been read here — read it from the Settings page before trusting them`);
+    catch (e) {
+        if (e instanceof SettingsUnusableError)
+            say(false, `${e.path} ${e.problem}; the API will not start until it is mended or deleted`);
+        // Not the operator's to delete: an administrator placed it (see `PolicyLockUnusableError`).
+        else if (e instanceof PolicyLockUnusableError)
+            say(false, `${e.path} ${e.problem}; the API will not start until it is mended`);
+        else
+            say(false, `the settings in ${join(dataDir, 'settings.json')} could not be loaded (${e.message}); the API will not start until that is put right`);
     }
-    else {
-        const names = new Set(models.options.map((o) => o.name));
-        for (const [what, name] of wanted) {
-            say(names.has(name), names.has(name) ? `${what} "${name}" is in the picker read on this machine` : `${what} "${name}" is not in the picker read on this machine (${models.options.length} option(s)) — the run would fall back to whatever the chat shows`);
+    if (settings) {
+        /*
+         * Where the bot is running, which is the only thing that actually contains a command once it
+         * runs. Reported here rather than left to the README, because a machine that ignored the
+         * recommendation looked exactly like one that had followed it. The claim is the operator's;
+         * `doctor` only says what it can see and where the two disagree. See `exec/isolation.ts`.
+         */
+        const posture = assessIsolation(settings.execution?.isolation ?? 'none', readIsolationSignals());
+        say(posture.warnings.length === 0, `isolation: ${posture.claim}, running as ${posture.signals.user}${posture.signals.elevated === true ? ' (ELEVATED)' : ''}`);
+        for (const concern of posture.warnings)
+            say(false, `  ${concern}`);
+        const models = readJson('models.json');
+        const copilot = settings.copilot ?? {};
+        const wanted = [
+            ['default model', (copilot.defaultModel ?? '').trim()],
+            ['default review model', (copilot.defaultReviewModel ?? '').trim()],
+        ].filter(([, name]) => name !== '');
+        if (wanted.length === 0) {
+            console.log('  note  no default model is set; sessions leave the chat on whatever it shows');
+        }
+        else if (!models?.options?.length) {
+            console.log(`  note  ${wanted.map(([w, n]) => `${w} "${n}"`).join(', ')} set, but the picker has never been read here — read it from the Settings page before trusting them`);
         }
-        if (wanted.length === 2 && wanted[0][1] === wanted[1][1]) {
-            console.log('  note  the review runs on the same model as the work; a different one catches more');
+        else {
+            const names = new Set(models.options.map((o) => o.name));
+            for (const [what, name] of wanted) {
+                say(names.has(name), names.has(name) ? `${what} "${name}" is in the picker read on this machine` : `${what} "${name}" is not in the picker read on this machine (${models.options.length} option(s)) — the run would fall back to whatever the chat shows`);
+            }
+            if (wanted.length === 2 && wanted[0][1] === wanted[1][1]) {
+                console.log('  note  the review runs on the same model as the work; a different one catches more');
+            }
         }
     }
     const edgeUsers = findEdgeUsingProfile(DEFAULT_PROFILE);
@@ -309,7 +372,7 @@ program
     const desktop = resolveDesktopDir();
     say(existsSync(desktop), `Desktop at ${desktop}`);
     console.log(`  ${desktopIsSynced() ? 'ok  ' : 'note'}  Desktop ${desktopIsSynced() ? 'is' : 'is NOT'} backed up by OneDrive` +
-        `${desktopIsSynced() ? '' : ' — the mirror folder will stay on this machine only'}`);
+        `${desktopIsSynced() ? '' : ' — logs saved there stay on this machine only'}`);
     if (configPath) {
         try {
             const cfg = await loadConfig(configPath);
@@ -322,9 +385,6 @@ program
             const profileExists = existsSync(cfg.resolved.profileDir);
             console.log(`  ${profileExists ? 'ok  ' : 'note'}  browser profile ${cfg.resolved.profileDir}` +
                 `${profileExists ? '' : ' — run "cop login" first'}`);
-            if (cfg.projectMirror.enabled) {
-                say(existsSync(cfg.resolved.mirrorRootDir), `project root ${cfg.resolved.mirrorRootDir}`);
-            }
         }
         catch (e) {
             say(false, e.message);
@@ -334,17 +394,6 @@ program
     console.log(problems.length === 0 ? 'Ready.' : `${problems.length} problem(s) to fix first.`);
     process.exitCode = problems.length === 0 ? 0 : 1;
 });
-program
-    .command('dirs')
-    .description('list the directories of a project that can be selected for the mirror')
-    .argument('<projectRoot>')
-    .action(async (root) => {
-    const dirs = await listSelectableDirs(root);
-    if (dirs.length === 0)
-        console.log('(no selectable directories found)');
-    for (const d of dirs)
-        console.log(d);
-});
 program
     .command('models')
     .description('read the chat\'s model picker and print what it offers right now')
@@ -394,38 +443,6 @@ program
         await transport.close();
     }
 });
-program
-    .command('mirror')
-    .description('refresh the Desktop folder from the project, without touching the chat')
-    .argument('<config>', 'path to run.yaml')
-    .action(async (configPath) => {
-    const cfg = await loadConfig(configPath);
-    if (!cfg.projectMirror.enabled) {
-        console.log('projectMirror.enabled is false in this config; nothing to do.');
-        return;
-    }
-    const targetDir = cfg.resolved.mirrorTargetDir ?? defaultExportDir();
-    await mkdir(targetDir, { recursive: true });
-    const result = await mirrorProject({
-        rootDir: cfg.resolved.mirrorRootDir,
-        includeDirs: cfg.projectMirror.includeDirs,
-        excludeDirs: cfg.projectMirror.excludeDirs,
-        targetDir,
-        separator: cfg.projectMirror.separator,
-        txtMode: cfg.projectMirror.txtMode,
-        respectGitignore: cfg.projectMirror.respectGitignore,
-        ignoreDirs: cfg.projectMirror.ignoreDirs,
-        includeEnvFiles: cfg.projectMirror.includeEnvFiles,
-        maxFileBytes: cfg.projectMirror.maxFileBytes,
-    });
-    console.log(`${targetDir}`);
-    console.log(describeMirror(result));
-    for (const s of result.skipped)
-        console.log(`  skipped ${s.relPath}: ${s.reason}`);
-    if (!desktopIsSynced()) {
-        console.log('note: the Desktop is not backed up by OneDrive, so these copies stay local.');
-    }
-});
 program
     .command('run')
     .description('run one task from a run.yaml: creates a session, runs it, prints the summary')
@@ -456,14 +473,8 @@ program
     }
     const store = new SessionStore(cfg.resolved.dataDir, cfg.resolved.level1Path);
     await store.init();
-    const session = await store.createSession(cfg.copilot.label, {
-        enabled: cfg.projectMirror.enabled,
-        rootDir: cfg.resolved.mirrorRootDir ?? '',
-        includeDirs: cfg.projectMirror.includeDirs,
-        excludeDirs: cfg.projectMirror.excludeDirs,
-        respectGitignore: cfg.projectMirror.respectGitignore,
-        includeEnvFiles: cfg.projectMirror.includeEnvFiles,
-    });
+    // No project folder of its own: its commands run in `execution.cwd`. See `workingDirFor`.
+    const session = await store.createSession(cfg.copilot.label);
     await store.updateSession(session.id, (s) => {
         s.onFailure = cfg.execution.continueOnFailure ? 'continue' : 'stop';
     });
@@ -495,14 +506,14 @@ program
     console.log('');
     console.log(`task "${done?.title}": ${done?.status} after ${done?.iterations ?? 0} iteration(s)`);
     if (done?.summary)
-        console.log(`
-Summary:
+        console.log(`
+Summary:
 ${done.summary}`);
     if (done?.reason)
-        console.log(`
+        console.log(`
 Reason: ${done.reason}`);
     if (final?.chat)
-        console.log(`
+        console.log(`
 chat: ${final.chat.name} — ${final.chat.url}`);
     if (done?.runId)
         console.log(`log: ${join(cfg.resolved.runsDir, done.runId, 'task-log.txt')}`);
@@ -522,8 +533,8 @@ program
         return;
     }
     const c = withChat.chat;
-    console.log(`${c.name}
-${c.url}
+    console.log(`${c.name}
+${c.url}
 session ${withChat.id}, ${withChat.tasks.length} task(s), created ${c.createdAt}`);
 });
 program.parseAsync(process.argv).catch((e) => {

package/dist/src/config/handWritten.js

@@ -0,0 +1,36 @@
+/**
+ * The text of a file a person writes by hand to configure this program: `data/settings.json`, a
+ * `policy.lock.json`, a `run.yaml` and the files it names.
+ *
+ * Windows writes such a file in more than one encoding, and each is the file its writer meant.
+ * Notepad and Windows PowerShell's `Set-Content -Encoding utf8` put a UTF-8 byte-order mark in
+ * front of it; Windows PowerShell 5.1's `>` and `Out-File`, without an `-Encoding`, write UTF-16,
+ * little-endian, with its own mark. Read as UTF-8 and nothing else, the first was refused as "not
+ * valid JSON" over a character nobody can see, and the second over two replacement characters and
+ * a NUL between every letter, of a file that looks right in Notepad. So the mark, where there is
+ * one, says how the rest is encoded, and is not part of the text. A file without one is UTF-8, as
+ * everything this program writes is.
+ */
+import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+export function decodeHandWritten(bytes) {
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
+        return bytes.subarray(3).toString('utf8');
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe)
+        return bytes.subarray(2).toString('utf16le');
+    if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+        // Node decodes UTF-16 only little-endian, so a big-endian file has each pair of bytes swapped
+        // first, in a copy. A last odd byte is half a character and cannot be one.
+        const body = Buffer.from(bytes.subarray(2, bytes.length - (bytes.length % 2)));
+        return body.swap16().toString('utf16le');
+    }
+    return bytes.toString('utf8');
+}
+/** `readFile(path, 'utf8')` for a hand-written file: the same errors, the text by its mark. */
+export async function readHandWritten(path) {
+    return decodeHandWritten(await readFile(path));
+}
+/** The same, for the command line's synchronous checks. */
+export function readHandWrittenSync(path) {
+    return decodeHandWritten(readFileSync(path));
+}

package/dist/src/config/layout.js

@@ -43,8 +43,6 @@ function isInside(dir, root) {
 }
 export function installLayout(env = process.env, cwd = process.cwd(), botRoot = botRootDir()) {
     const promptsDir = join(botRoot, 'prompts');
-    const shippedWeb = join(botRoot, 'dist', 'web');
-    const webDir = existsSync(join(shippedWeb, 'index.html')) ? shippedWeb : null;
     const packaged = projectOfPackage(botRoot);
     if (packaged) {
         // A dev dependency serves the project around it; a global or npx install serves wherever it
@@ -52,6 +50,7 @@ export function installLayout(env = process.env, cwd = process.cwd(), botRoot =
         const owner = isInside(cwd, packaged) ? packaged : cwd;
         const projectRoot = resolve(env.COP_PROJECT_ROOT ?? owner);
         const homeDir = join(projectRoot, HOME_FOLDER);
+        const shippedWeb = join(botRoot, 'dist', 'web');
         return {
             mode: 'package',
             botRoot,
@@ -60,7 +59,7 @@ export function installLayout(env = process.env, cwd = process.cwd(), botRoot =
             homeDir,
             dataDir: resolve(env.COP_DATA_DIR ?? join(homeDir, 'data')),
             runsDir: join(homeDir, 'runs'),
-            webDir,
+            webDir: existsSync(join(shippedWeb, 'index.html')) ? shippedWeb : null,
         };
     }
     const projectRoot = resolve(env.COP_PROJECT_ROOT ?? cwd);
@@ -72,6 +71,16 @@ export function installLayout(env = process.env, cwd = process.cwd(), botRoot =
         homeDir: projectRoot,
         dataDir: resolve(env.COP_DATA_DIR ?? join(projectRoot, 'data')),
         runsDir: join(projectRoot, 'runs'),
-        webDir,
+        /*
+         * A clone's API never serves the prebuilt interface, even with one built in it. `build:package`
+         * (run by every `npm pack`) and `check:ui` both leave `dist/web/index.html` behind, and serving
+         * it made the API of `npm start` hand the token, as a cookie, to anything on the machine that
+         * asked for `/`: a second way to the token beside the dev server, and one nobody chose. A
+         * clone's interface is the dev server, and `npm start` builds the token into its page, so that
+         * port is as open to this machine as a package's is; see the honest limit in `api/security.ts`.
+         * The browser checks that want the built interface on the API's own port pass it to `startApi`
+         * by name.
+         */
+        webDir: null,
     };
 }

package/dist/src/config/lockedPolicy.js

@@ -26,8 +26,8 @@
  * one task and never put back — and it gives a security team a single artefact to point at.
  */
 import { z } from 'zod';
-import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { readHandWritten } from './handWritten.js';
 export const POLICY_LOCK_FILE = 'policy.lock.json';
 export const PolicyLockSchema = z
     .object({
@@ -36,9 +36,12 @@ export const PolicyLockSchema = z
     denyPatterns: z.array(z.string()).optional(),
     /** `true` treats the claim `none-accepted` as `none`: unattended runs need real isolation here. */
     requireIsolation: z.boolean().optional(),
-    /** `false` switches the Desktop mirror off, whatever the settings say. */
+    /**
+     * Still read, so a lock written for an earlier version is not refused; they lock nothing now.
+     * The project was once copied to the Desktop and attached to the chat, and these switched that,
+     * and its `.env` files, off. That feature was removed on 2026-09-30.
+     */
     allowDesktopMirror: z.boolean().optional(),
-    /** `false` keeps `.env` files out of every mirror and every attachment. */
     allowEnvFiles: z.boolean().optional(),
     /** A ceiling on `execution.passEnv`: the only variables a step may be given beyond the fixed set. */
     passEnv: z.array(z.string()).optional(),
@@ -98,16 +101,6 @@ export function applyPolicyLock(policy, lock) {
         next.isolation = 'none';
         changes.push('isolation "none-accepted" treated as "none" (the lock requires real isolation for unattended runs)');
     }
-    if (lock.allowDesktopMirror === false && (next.mirrorToDesktop || next.projectMirrorEnabled)) {
-        next.mirrorToDesktop = false;
-        next.projectMirrorEnabled = false;
-        changes.push('the Desktop mirror switched off by the lock');
-    }
-    if (lock.allowEnvFiles === false && (next.includeEnvFiles || next.mirrorIncludeEnvFiles)) {
-        next.includeEnvFiles = false;
-        next.mirrorIncludeEnvFiles = false;
-        changes.push('.env files kept out of every mirror by the lock');
-    }
     if (lock.passEnv && next.passEnv) {
         // Not `intersect`: an empty operator list here means "nothing extra", the tightest setting.
         const allowed = lowerSet(lock.passEnv);
@@ -122,9 +115,9 @@ export function applyPolicyLock(policy, lock) {
 /**
  * Reads `policy.lock.json` from a directory, or null when there is none.
  *
- * A file that is present but malformed is an error and not a shrug: a deployment that meant to
- * lock something down and mistyped it must not silently run unlocked, because the one thing worse
- * than no lock is a lock everybody believes in.
+ * A file that is present but malformed, or that cannot be read, is an error and not a shrug: a
+ * deployment that meant to lock something down and mistyped it must not silently run unlocked,
+ * because the one thing worse than no lock is a lock everybody believes in.
  */
 export async function readPolicyLock(baseDir) {
     return await readPolicyLockAt(join(baseDir, POLICY_LOCK_FILE));
@@ -139,7 +132,7 @@ export function machineLockPath(env = process.env) {
     const base = env.ProgramData ?? env.PROGRAMDATA;
     return base ? join(base, 'copilot-operator', POLICY_LOCK_FILE) : null;
 }
-/** Every lock that applies: the machine-wide one, then the install's own. Each is malformed-fatal. */
+/** Every lock that applies: the machine-wide one, then the install's own. Each is fatal when it is there and unusable. */
 export async function readPolicyLocks(baseDir, env = process.env) {
     const out = [];
     const machine = machineLockPath(env);
@@ -153,24 +146,65 @@ export async function readPolicyLocks(baseDir, env = process.env) {
         out.push(local);
     return out;
 }
+/**
+ * A policy lock that is there and cannot be used: it cannot be read, it is not JSON, or it is not a
+ * lock.
+ *
+ * Its own class for the reason `SettingsUnusableError` has one (see `api/settings.ts`). Every
+ * configuration passes through `resolveConfig`, which reads the locks, so every request that reads
+ * the settings meets a broken one, not only the saves; as a plain error it was "Internal server
+ * error" wherever a route did not wrap its errors — the System page, the Defaults page, the Project
+ * page and the model picker among them, the pages the operator opens to find out what is wrong. The
+ * server answers this one the same way on every route, with this message (see `server.ts`).
+ */
+export class PolicyLockUnusableError extends Error {
+    path;
+    problem;
+    constructor(path, 
+    /** What is wrong, said of the file: "is not valid JSON: …". */
+    problem) {
+        // The way out goes in the same message, as it does for the settings file. Unlike that file,
+        // this one is not the operator's to delete in passing: it is somebody's decision about this
+        // machine, and the one thing a broken lock must not do is read as no lock at all.
+        super(`${path} ${problem}\nNothing that reads the settings runs until it is mended: a policy lock that cannot be read as one ` +
+            'is never taken for no lock. Whoever administers this machine placed it; mend it there, or remove it if no lock was meant.');
+        this.path = path;
+        this.problem = problem;
+        this.name = 'PolicyLockUnusableError';
+    }
+}
+/**
+ * Whether a failed read means the file is not there. Only then is there no lock: ENOENT, or
+ * ENOTDIR, where a part of the path is a file and so nothing can be below it.
+ */
+function lockIsAbsent(e) {
+    const code = e.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
 async function readPolicyLockAt(path) {
     let text;
     try {
-        text = await readFile(path, 'utf8');
+        text = await readHandWritten(path);
     }
-    catch {
-        return null;
+    catch (e) {
+        // Any other failure is a lock that is there and cannot be read, and is refused as a broken
+        // one is. Every failure was taken for no lock: a lock whose folder an administrator protected
+        // and left this account no read on (EPERM), a folder where the file should be (EISDIR), a
+        // file another program held for a moment (EBUSY), and the "confirm only" it held was gone.
+        if (lockIsAbsent(e))
+            return null;
+        throw new PolicyLockUnusableError(path, `could not be read (${e.message})`);
     }
     let value;
     try {
         value = JSON.parse(text);
     }
     catch (e) {
-        throw new Error(`${path} is not valid JSON: ${e.message}`);
+        throw new PolicyLockUnusableError(path, `is not valid JSON: ${e.message}`);
     }
     const parsed = PolicyLockSchema.safeParse(value);
     if (!parsed.success) {
-        throw new Error(`${path} is not a valid policy lock:\n${parsed.error.issues.map((i) => `  ${i.path.join('.') || '(root)'}: ${i.message}`).join('\n')}`);
+        throw new PolicyLockUnusableError(path, `is not a valid policy lock:\n${parsed.error.issues.map((i) => `  ${i.path.join('.') || '(root)'}: ${i.message}`).join('\n')}`);
     }
     return parsed.data;
 }