copilot-operator 0.1.8 → 0.1.10

package/dist/src/api/main.js

@@ -7,109 +7,7 @@
  * commands on this machine. Exposing it on a network interface would hand that to anyone who
  * could reach the port.
  */
-import 'reflect-metadata';
-import { NestFactory } from '@nestjs/core';
-import { join } from 'node:path';
-import { AppModule } from './app.module.js';
-import { OperatorService } from './operator.service.js';
-import { ensureApiToken, localApiGuard } from './security.js';
-import { secureDataDir } from './dataAcl.js';
-import { pruneRuns } from '../session/retention.js';
-import { mkdir, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { installLayout } from '../config/layout.js';
-const PORT = Number(process.env.COP_API_PORT ?? 4000);
-const WEB_ORIGIN = process.env.COP_WEB_ORIGIN ?? 'http://localhost:3210';
-async function main() {
-    const app = await NestFactory.create(AppModule, { logger: ['error', 'warn', 'log'] });
-    // A plan pasted from a chat carries every task's text at once, which the 100 KB default
-    // refuses with a message about entity size that says nothing about plans.
-    app.useBodyParser('json', { limit: '5mb' });
-    app.enableCors({
-        origin: [WEB_ORIGIN, WEB_ORIGIN.replace('localhost', '127.0.0.1')],
-        /*
-         * The one header the page has to be able to read.
-         *
-         * A browser hands script only a handful of response headers across origins, and
-         * `content-disposition` is not among them unless it is named here. The UI is on
-         * `localhost:3210` and this is on `127.0.0.1:4000`, so every fetch is cross-origin: without
-         * this, a download built from a blob cannot find out what the file is called, and the
-         * carefully composed `copilot-operator-bundle-2-tasks-2-sessions-<stamp>.json` arrives as
-         * whatever the client guessed. The plain `<a download>` exports never noticed, because the
-         * browser reads the header itself for those and never shows it to the page.
-         */
-        exposedHeaders: ['content-disposition'],
-    });
-    app.setGlobalPrefix('api');
-    /*
-     * Who may drive this. Mounted before routing so it covers every route including the SSE stream,
-     * and so that no controller has to remember. See `security.ts` for why "it is only on localhost"
-     * was never the whole answer — a page in the operator's ordinary browser and any other process
-     * on the machine were both callers all along.
-     */
-    const layout = installLayout();
-    const dataDir = layout.dataDir;
-    await mkdir(dataDir, { recursive: true });
-    if (layout.mode === 'package') {
-        /*
-         * The records folder sits inside the project, so it must be invisible to the project's git:
-         * version control refuses to branch on a tree with untracked files, and the records are not
-         * the project's work. A `.gitignore` of `*` inside the folder says so without touching the
-         * project's own .gitignore.
-         */
-        const ignore = join(layout.homeDir, '.gitignore');
-        if (!existsSync(ignore))
-            await writeFile(ignore, '*\n', 'utf8');
-    }
-    // Before the token is read: a token any local account can read guards nothing. See `dataAcl.ts`.
-    const acl = secureDataDir(dataDir);
-    if (!acl.ok) {
-        console.error(`copilot-operator api will not start: ${acl.reason}`);
-        process.exit(1);
-    }
-    const token = await ensureApiToken(dataDir);
-    // The dev UI's origin, and this process's own for the interface it serves itself.
-    const allowedOrigins = [WEB_ORIGIN, WEB_ORIGIN.replace('localhost', '127.0.0.1'), `http://127.0.0.1:${PORT}`, `http://localhost:${PORT}`];
-    app.use(localApiGuard({ token, port: PORT, allowedOrigins, servesInterface: layout.webDir !== null }));
-    if (layout.webDir) {
-        // The prebuilt interface, from the package: one process, one port, no dev server.
-        app.useStaticAssets(layout.webDir, { extensions: ['html'], index: 'index.html' });
-    }
-    await app.listen(PORT, '127.0.0.1');
-    // Close whatever the previous process left open before anyone can look at it, rather than
-    // waiting for the first request to trigger it.
-    const ops = app.get(OperatorService);
-    await ops.bootstrap();
-    /*
-     * runs/ holds every step's raw output and, on a failure, a screenshot of the signed-in page —
-     * as much the bot's records as data/ is, and until 2026-09-27 left with whatever permissions its
-     * parent folder had. Narrowed the same way, and pruned to the configured retention.
-     */
-    const cfg = await ops.settings.load();
-    await mkdir(cfg.resolved.runsDir, { recursive: true });
-    const runsAcl = secureDataDir(cfg.resolved.runsDir);
-    if (!runsAcl.ok) {
-        console.error(`copilot-operator api will not start: ${runsAcl.reason}`);
-        process.exit(1);
-    }
-    for (const [name, dir] of [['data', dataDir], ['runs', cfg.resolved.runsDir]]) {
-        if (/onedrive/i.test(dir) || /^\\\\/.test(dir)) {
-            console.warn(`  warning: the ${name} folder (${dir}) is under OneDrive or on a network share; keep the bot's records on a local disk (COP_DATA_DIR, runsDir)`);
-        }
-    }
-    const pruned = await pruneRuns(cfg.resolved.runsDir, cfg.runsRetentionDays);
-    if (pruned.length > 0)
-        console.log(`  removed ${pruned.length} run folder(s) older than ${cfg.runsRetentionDays} days (runsRetentionDays)`);
-    if (layout.webDir) {
-        console.log(`copilot-operator is running for ${layout.projectRoot}`);
-        console.log(`  open http://127.0.0.1:${PORT}/ in your browser`);
-        console.log(`  records are kept in ${layout.homeDir}`);
-    }
-    else {
-        console.log(`copilot-operator api listening on http://127.0.0.1:${PORT}/api  (web origin ${WEB_ORIGIN})`);
-        console.log(`  requests need the token in ${join(dataDir, 'api-token')}; npm start hands it to the UI`);
-    }
-}
+import { startApi } from './server.js';
 /*
  * A stray rejection must not end a run.
  *
@@ -126,7 +24,7 @@ process.on('unhandledRejection', (reason) => {
 process.on('uncaughtException', (error) => {
     console.error('[api] uncaught exception (the run continues):', error.stack ?? error.message);
 });
-main().catch((e) => {
+startApi().catch((e) => {
     console.error(e.message);
     process.exit(1);
 });

package/dist/src/api/operator.controller.js

@@ -10,7 +10,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Body, Controller, Delete, Get, Param, Post, Put, Query, Res, Sse, NotFoundException, BadRequestException } from '@nestjs/common';
+import { Body, Controller, Delete, Get, Inject, Param, Post, Put, Query, Res, Sse, NotFoundException, BadRequestException } from '@nestjs/common';
 import { Observable } from 'rxjs';
 import { OperatorService } from './operator.service.js';
 function fail(e) {
@@ -37,6 +37,13 @@ function contentDisposition(fileName) {
 }
 let OperatorController = class OperatorController {
     ops;
+    /*
+     * Named explicitly rather than read from the parameter's type. Nest normally learns what to inject
+     * from the metadata `tsc` emits for a decorated class, and that metadata exists only when the code
+     * was compiled by `tsc`: run through tsx or any other esbuild-based loader — which is how every
+     * check in test/ runs, including the ones that start this API — the type is gone and `ops` arrived
+     * as undefined, so every route failed with a TypeError. With the token named, both ways work.
+     */
     constructor(ops) {
         this.ops = ops;
     }
@@ -491,6 +498,9 @@ let OperatorController = class OperatorController {
     tasks() {
         return this.ops.taskRegistry();
     }
+    metrics() {
+        return this.ops.metrics();
+    }
     // --- helpers for the UI -----------------------------------------------------------------
     dirs(root, gitignore) {
         if (!root)
@@ -1030,6 +1040,12 @@ __decorate([
     __metadata("design:paramtypes", []),
     __metadata("design:returntype", Promise)
 ], OperatorController.prototype, "tasks", null);
+__decorate([
+    Get('metrics'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], OperatorController.prototype, "metrics", null);
 __decorate([
     Get('dirs'),
     __param(0, Query('root')),
@@ -1054,6 +1070,7 @@ __decorate([
 ], OperatorController.prototype, "preview", null);
 OperatorController = __decorate([
     Controller(),
+    __param(0, Inject(OperatorService)),
     __metadata("design:paramtypes", [OperatorService])
 ], OperatorController);
 export { OperatorController };

package/dist/src/api/operator.service.js

@@ -17,9 +17,9 @@ import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { installLayout } from '../config/layout.js';
-import { SessionStore, DEFAULT_VCS, DEFAULT_REVIEW } from '../session/store.js';
+import { SessionStore, DEFAULT_VCS, DEFAULT_REVIEW, applyTaskPatch } from '../session/store.js';
 import { EventBus } from '../session/events.js';
-import { newId, tidyVcsPlan } from '../session/model.js';
+import { newId } from '../session/model.js';
 import { runSession, openBrowser, queuedToRun } from '../orchestrator/taskRunner.js';
 import { buildExport } from '../session/exportRecord.js';
 import { buildDebugExport } from '../session/debugExport.js';
@@ -45,7 +45,9 @@ import { pickFolder } from './folderPicker.js';
 import { findEdgeUsingProfile } from '../transport/profileLock.js';
 import { assessIsolation, readIsolationSignals, unattendedIsolationRefusal } from '../exec/isolation.js';
 import { unattendedPrecondition } from '../exec/policy.js';
-import { CopilotTransport } from '../transport/copilotTransport.js';
+import { createTransport } from '../transport/chatTransport.js';
+import { composeHandoff } from '../session/handoff.js';
+import { computeMetrics } from '../session/metrics.js';
 import { resolveDesktopDir, desktopIsSynced } from '../context/contextFiles.js';
 import { saveAndReveal } from './saveToDesktop.js';
 import { Settings } from './settings.js';
@@ -115,6 +117,11 @@ let OperatorService = class OperatorService {
                 t.vcs = vcs;
                 t.reason = `${t.reason ?? ''} What it had changed is committed on ${vcs.branch} as ${vcs.commit?.slice(0, 8)}.`.trim();
             }
+            // The same fixed-shape ending a task the runner finished gets; the steps the bot never
+            // reached are the interruption's own record of them.
+            t.handoff = composeHandoff(t, (interruption?.steps ?? [])
+                .filter((x) => x.state !== 'finished')
+                .map((x) => ({ command: x.command ?? `step ${x.id}`, why: x.state === 'cut' ? 'cut off when the bot stopped' : 'not reached before the bot stopped' })));
         });
         const ended = settled.tasks.find((t) => t.id === taskId);
         if (!ended)
@@ -296,16 +303,7 @@ let OperatorService = class OperatorService {
         return await this.store.updateTask(sessionId, taskId, (t) => {
             if (t.status !== 'queued')
                 throw new Error('Only a queued task can be edited.');
-            if (patch.title !== undefined)
-                t.title = patch.title;
-            if (patch.level2 !== undefined)
-                t.level2 = patch.level2;
-            if (patch.prompt !== undefined)
-                t.prompt = patch.prompt;
-            if (patch.vcsPlan !== undefined)
-                t.vcsPlan = tidyVcsPlan(patch.vcsPlan);
-            if (patch.checks !== undefined)
-                t.checks = patch.checks.filter((c) => c.name.trim() !== '');
+            applyTaskPatch(t, patch);
         });
     }
     async deleteTask(sessionId, taskId) {
@@ -1952,7 +1950,7 @@ let OperatorService = class OperatorService {
             throw new Error('The model list is already being read.');
         this.readingModels = true;
         const cfg = await this.settings.load();
-        const transport = new CopilotTransport({
+        const transport = createTransport({
             profileDir: cfg.resolved.profileDir,
             transportDir: join(cfg.resolved.runsDir, '_models'),
             chatUrl: cfg.copilot.url,
@@ -1983,6 +1981,11 @@ let OperatorService = class OperatorService {
      * what is still ahead; doing the flattening here keeps that split honest, because the
      * queue position is only knowable from the session's own list.
      */
+    /** How well the bot is doing, added up from every task on record. See `session/metrics.ts`. */
+    async metrics() {
+        await this.init();
+        return computeMetrics(await this.store.listSessions());
+    }
     async taskRegistry() {
         await this.init();
         const sessions = await this.store.listSessions();
@@ -2022,6 +2025,8 @@ let OperatorService = class OperatorService {
                     deviations: t.deviations?.length || undefined,
                     disputes: t.disputes?.length || undefined,
                     readOnly: t.readOnly || undefined,
+                    scope: t.scope?.length ? t.scope : undefined,
+                    stopCode: t.stopCode,
                     autoRetries: t.autoRetries || undefined,
                     attempt: t.attempt,
                     changedFiles: t.vcs?.commit && t.vcs.baseCommit ? (t.vcs.files?.length ?? 0) : undefined,

package/dist/src/api/server.js

@@ -0,0 +1,114 @@
+/**
+ * The API server: routes, the guard in front of them, the data folder's permissions, recovery of
+ * whatever the previous process left running. See `main.ts` for the process around it.
+ */
+import 'reflect-metadata';
+import { NestFactory } from '@nestjs/core';
+import { join } from 'node:path';
+import { AppModule } from './app.module.js';
+import { OperatorService } from './operator.service.js';
+import { ensureApiToken, localApiGuard } from './security.js';
+import { secureDataDir } from './dataAcl.js';
+import { pruneRuns } from '../session/retention.js';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { installLayout } from '../config/layout.js';
+/**
+ * Everything `main` used to do, as a function that returns the running server instead of owning the
+ * process. `main.ts` calls it and turns a failure into an exit code; the end-to-end checks call it
+ * with a scripted chat in place (see `transport/chatTransport.ts`) and close it when they are done.
+ * A refusal to start is thrown rather than ending the process, so a check that trips one is told why.
+ */
+export async function startApi(opts = {}) {
+    const PORT = opts.port ?? Number(process.env.COP_API_PORT ?? 4000);
+    const WEB_ORIGIN = opts.webOrigin ?? process.env.COP_WEB_ORIGIN ?? 'http://localhost:3210';
+    const log = opts.quiet ? () => undefined : (line) => console.log(line);
+    const app = await NestFactory.create(AppModule, { logger: opts.quiet ? ['error', 'warn'] : ['error', 'warn', 'log'] });
+    // A plan pasted from a chat carries every task's text at once, which the 100 KB default
+    // refuses with a message about entity size that says nothing about plans.
+    app.useBodyParser('json', { limit: '5mb' });
+    app.enableCors({
+        origin: [WEB_ORIGIN, WEB_ORIGIN.replace('localhost', '127.0.0.1')],
+        /*
+         * The one header the page has to be able to read.
+         *
+         * A browser hands script only a handful of response headers across origins, and
+         * `content-disposition` is not among them unless it is named here. The UI is on
+         * `localhost:3210` and this is on `127.0.0.1:4000`, so every fetch is cross-origin: without
+         * this, a download built from a blob cannot find out what the file is called, and the
+         * carefully composed `copilot-operator-bundle-2-tasks-2-sessions-<stamp>.json` arrives as
+         * whatever the client guessed. The plain `<a download>` exports never noticed, because the
+         * browser reads the header itself for those and never shows it to the page.
+         */
+        exposedHeaders: ['content-disposition'],
+    });
+    app.setGlobalPrefix('api');
+    /*
+     * Who may drive this. Mounted before routing so it covers every route including the SSE stream,
+     * and so that no controller has to remember. See `security.ts` for why "it is only on localhost"
+     * was never the whole answer — a page in the operator's ordinary browser and any other process
+     * on the machine were both callers all along.
+     */
+    const layout = installLayout();
+    const dataDir = layout.dataDir;
+    const webDir = opts.webDir ?? layout.webDir;
+    await mkdir(dataDir, { recursive: true });
+    if (layout.mode === 'package') {
+        /*
+         * The records folder sits inside the project, so it must be invisible to the project's git:
+         * version control refuses to branch on a tree with untracked files, and the records are not
+         * the project's work. A `.gitignore` of `*` inside the folder says so without touching the
+         * project's own .gitignore.
+         */
+        const ignore = join(layout.homeDir, '.gitignore');
+        if (!existsSync(ignore))
+            await writeFile(ignore, '*\n', 'utf8');
+    }
+    // Before the token is read: a token any local account can read guards nothing. See `dataAcl.ts`.
+    const acl = secureDataDir(dataDir);
+    if (!acl.ok)
+        throw new Error(`copilot-operator api will not start: ${acl.reason}`);
+    const token = await ensureApiToken(dataDir);
+    // The dev UI's origin, and this process's own for the interface it serves itself.
+    const allowedOrigins = [WEB_ORIGIN, WEB_ORIGIN.replace('localhost', '127.0.0.1'), `http://127.0.0.1:${PORT}`, `http://localhost:${PORT}`];
+    app.use(localApiGuard({ token, port: PORT, allowedOrigins, servesInterface: webDir !== null }));
+    if (webDir) {
+        // The prebuilt interface, from the package: one process, one port, no dev server.
+        app.useStaticAssets(webDir, { extensions: ['html'], index: 'index.html' });
+    }
+    await app.listen(PORT, '127.0.0.1');
+    // Close whatever the previous process left open before anyone can look at it, rather than
+    // waiting for the first request to trigger it.
+    const ops = app.get(OperatorService);
+    await ops.bootstrap();
+    /*
+     * runs/ holds every step's raw output and, on a failure, a screenshot of the signed-in page —
+     * as much the bot's records as data/ is, and until 2026-09-27 left with whatever permissions its
+     * parent folder had. Narrowed the same way, and pruned to the configured retention.
+     */
+    const cfg = await ops.settings.load();
+    await mkdir(cfg.resolved.runsDir, { recursive: true });
+    const runsAcl = secureDataDir(cfg.resolved.runsDir);
+    if (!runsAcl.ok) {
+        await app.close();
+        throw new Error(`copilot-operator api will not start: ${runsAcl.reason}`);
+    }
+    for (const [name, dir] of [['data', dataDir], ['runs', cfg.resolved.runsDir]]) {
+        if (/onedrive/i.test(dir) || /^\\\\/.test(dir)) {
+            console.warn(`  warning: the ${name} folder (${dir}) is under OneDrive or on a network share; keep the bot's records on a local disk (COP_DATA_DIR, runsDir)`);
+        }
+    }
+    const pruned = await pruneRuns(cfg.resolved.runsDir, cfg.runsRetentionDays);
+    if (pruned.length > 0)
+        log(`  removed ${pruned.length} run folder(s) older than ${cfg.runsRetentionDays} days (runsRetentionDays)`);
+    if (layout.webDir) {
+        log(`copilot-operator is running for ${layout.projectRoot}`);
+        log(`  open http://127.0.0.1:${PORT}/ in your browser`);
+        log(`  records are kept in ${layout.homeDir}`);
+    }
+    else {
+        log(`copilot-operator api listening on http://127.0.0.1:${PORT}/api  (web origin ${WEB_ORIGIN})`);
+        log(`  requests need the token in ${join(dataDir, 'api-token')}; npm start hands it to the UI`);
+    }
+    return { app, port: PORT, token, dataDir, close: () => app.close() };
+}

package/dist/src/config/schema.js

@@ -370,6 +370,11 @@ export const RunConfigSchema = z.object({
          * of turns" is not.
          */
         maxStalledIterations: z.number().int().positive().default(2),
+        /*
+         * Rounds in a row that end with the same error while no file changes, before the task is
+         * stopped as blocked with that diagnosis (orchestrator/progress.ts). Only with a repository.
+         */
+        maxNoProgressRounds: z.number().int().min(2).default(3),
         /**
          * How many times a task may be sent back because an independent review found problems.
          *

package/dist/src/exec/checks.js

@@ -21,6 +21,7 @@ import { runStep } from './runner.js';
 import { resolveShell } from './shells.js';
 import { repoState, workingTreePaths } from '../vcs/git.js';
 import { findSuspicious, suspiciousDetail } from '../vcs/commitHygiene.js';
+import { integrityDetail, scanChanges } from '../vcs/contentIntegrity.js';
 /**
  * The check the runner adds on its own whenever it is about to commit.
  *
@@ -28,6 +29,10 @@ import { findSuspicious, suspiciousDetail } from '../vcs/commitHygiene.js';
  * work: it is what a commit should never carry, whatever the task was.
  */
 export const COMMIT_CLEAN_CHECK = { name: 'nothing installed, built, logged or secret is committed', expect: 'commit-clean' };
+/** Its sibling for what is inside the files: encoding damage, stray bytes, credentials. See `contentIntegrity.ts`. */
+export const CONTENT_CLEAN_CHECK = { name: 'the text written is clean: encoding, line endings, no credentials', expect: 'content-clean' };
+/** The checks the runner adds by itself before a commit, rather than ones a plan wrote. */
+export const RUNNER_CHECK_KINDS = new Set(['commit-clean', 'content-clean']);
 const DEFAULT_CHECK_TIMEOUT_MS = 10 * 60 * 1000;
 /** How much of a command's output travels back to the chat with a failure. */
 const OUTPUT_KEPT = 4000;
@@ -63,6 +68,18 @@ export async function runCheck(check, index, opts) {
             ? pass('nothing in the working tree looks like tool output or secrets')
             : fail(suspiciousDetail(found), { output: found.map((s) => `${s.path}\t${s.reason}`).join('\n') });
     }
+    if (check.expect === 'content-clean') {
+        const dir = (opts.repoDir ?? '').trim();
+        if (!dir)
+            return pass('no repository is set for this session, so nothing is committed');
+        const state = await repoState(dir).catch(() => null);
+        if (!state?.isRepo)
+            return pass(`${dir} is not a git repository, so nothing is committed`);
+        const found = await scanChanges(dir, await workingTreePaths(dir), opts.baseCommit);
+        return found.length === 0
+            ? pass('the changed files are clean UTF-8 text with one kind of line ending and no credentials')
+            : fail(integrityDetail(found), { output: found.map((f) => `${f.path}\t${f.kind}\t${f.detail}`).join('\n') });
+    }
     /*
      * Where this check really runs, decided once. The command runs here and a file check's relative
      * path is resolved against it — the same folder for both, so the path confined is the path read.

package/dist/src/orchestrator/contract.js

@@ -0,0 +1,58 @@
+/**
+ * Whether a task can be satisfied at all, decided before anything is sent to the chat.
+ *
+ * A task is a contract: a prompt, the checks that say when it is done, and what it may change
+ * (`readOnly`, `scope`). The three are written at different times — a plan, an edit, a new prompt on
+ * a finished task — and they can end up contradicting each other: an audit made read-only that
+ * still carries the old "the file now says X" check; a task scoped to its tests that must change
+ * the config to pass. Run as it is, such a task spends its rounds and ends blocked on a check the
+ * chat could never have met. This names the contradiction instead, before the first message.
+ *
+ * Only what can be known without running anything is judged: the flags against each other, and
+ * the file checks against the tree as it is now. A file check that already passes needs no change;
+ * one that fails needs its file changed, which a read-only task, or a scope that leaves the file
+ * out, forbids. Command checks are not judged: whether a command will pass depends on work the
+ * task is allowed to do elsewhere.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { inScope } from '../vcs/scope.js';
+async function fileCheckPassesNow(check, cwd) {
+    const path = resolve(cwd, (check.cwd ?? '').trim() || '.', (check.file ?? '').trim());
+    const info = await stat(path).catch(() => null);
+    const exists = !!info?.isFile();
+    if (check.expect === 'file-exists')
+        return { passes: exists, path };
+    if (check.expect === 'file-missing')
+        return { passes: !exists, path };
+    const text = exists ? await readFile(path, 'utf8').catch(() => '') : '';
+    return { passes: exists && text.includes(check.value ?? ''), path };
+}
+/** Each contradiction in the task, as a sentence; empty when it can be satisfied. */
+export async function contractConflicts(task, cwd, repoDir) {
+    const out = [];
+    const scope = task.scope ?? [];
+    if (task.readOnly && scope.length > 0) {
+        out.push(`It is read-only, which allows no change, and also scoped to ${scope.join(', ')}, which allows changes there.`);
+    }
+    if (!task.readOnly && scope.length === 0)
+        return out;
+    const checks = [
+        ...(task.checks ?? []),
+        ...(task.reviewChecks ?? []).filter((rc) => rc.state === 'active').map((rc) => rc.check),
+    ].filter((c) => c.expect === 'file-exists' || c.expect === 'file-missing' || c.expect === 'file-contains');
+    for (const check of checks) {
+        const { passes, path } = await fileCheckPassesNow(check, cwd);
+        if (passes)
+            continue;
+        const rel = relative(resolve(repoDir), path).replace(/\\/g, '/');
+        const inside = rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+        if (task.readOnly) {
+            out.push(`The check "${check.name}" fails now and can only pass if ${rel || path} changes, but the task is read-only.`);
+        }
+        else if (inside && !inScope(rel, scope)) {
+            out.push(`The check "${check.name}" fails now and can only pass if ${rel} changes, but the task's scope (${scope.join(', ')}) leaves that file out.`);
+        }
+    }
+    return out;
+}

package/dist/src/orchestrator/progress.js

@@ -0,0 +1,106 @@
+/**
+ * Whether a task is still getting anywhere, judged from what happened rather than from what the
+ * chat says about it.
+ *
+ * The runner already stops two kinds of loop: the same command sent again with the same result
+ * (`maxCommandRepeats`), and a whole round of steps it refused (`maxStalledIterations`). What those
+ * miss is the loop in which every round looks new: a different command each time that fails the
+ * same way while no file changes; changes made in one round and undone in the next, over and over;
+ * "done" said again with the same checks failing and nothing touched since they were reported. Each
+ * of those ran until the iteration limit and ended "limit reached" with a reason that explained
+ * nothing. Here each is recognised and ends the task `blocked` with a diagnosis saying which one it
+ * was and what the evidence is, so the operator knows what to change before running it again.
+ *
+ * "No file changed" is read from the working tree (`treeFingerprint` in git.ts), so these signals
+ * are only on when the session works in a git repository. Without one this watches nothing and
+ * the older guards still apply.
+ */
+/** The failure a round ended with, reduced to what stays the same when only the wording changes. */
+export function failureSignature(results) {
+    if (results.length === 0)
+        return null;
+    // A round in which anything ran and succeeded made progress of some kind.
+    if (results.some((r) => r.outcome === 'completed' && r.exitCode === 0))
+        return null;
+    const failed = results.filter((r) => r.outcome === 'completed' && r.exitCode !== 0);
+    if (failed.length === 0)
+        return null;
+    return failed
+        .map((r) => {
+        const text = (r.stderr.trim() || r.stdout.trim()).slice(-600);
+        // Numbers are masked (times, line numbers, process ids) and space collapsed: a different
+        // command that dies of the same error still reads the same.
+        return text.toLowerCase().replace(/\d+/g, '#').replace(/\s+/g, ' ').trim();
+    })
+        .sort()
+        .join('\n');
+}
+export class ProgressWatch {
+    limits;
+    trees = [];
+    oscillations = 0;
+    lastFailure = null;
+    sameFailure = 1;
+    lastChecks = null;
+    constructor(limits) {
+        this.limits = limits;
+    }
+    /**
+     * After a round of steps. `tree` is the working tree's fingerprint after it, or null when there is
+     * no repository to read. Returns why the task should stop, or null to go on.
+     */
+    afterRound(tree, results) {
+        if (tree === null)
+            return null;
+        const previous = this.trees.at(-1);
+        const beforeThat = this.trees.at(-2);
+        if (beforeThat !== undefined && tree === beforeThat && tree !== previous) {
+            this.oscillations += 1;
+            if (this.oscillations >= this.limits.oscillations) {
+                return (`no progress: the files went back to how they were two rounds earlier ${this.oscillations} times — ` +
+                    'changes made in one round and undone in the next. The task was stopped rather than left to run out of iterations. ' +
+                    'The two approaches it switches between are in the iteration reports; decide between them in the prompt.');
+            }
+        }
+        this.trees.push(tree);
+        const signature = failureSignature(results);
+        if (signature === null) {
+            this.lastFailure = null;
+            this.sameFailure = 1;
+            return null;
+        }
+        if (this.lastFailure && this.lastFailure.signature === signature && this.lastFailure.tree === tree) {
+            this.sameFailure += 1;
+        }
+        else {
+            this.sameFailure = 1;
+        }
+        this.lastFailure = { signature, tree };
+        if (this.sameFailure >= this.limits.noProgress) {
+            const example = signature.split('\n')[0].slice(-240);
+            return (`no progress: ${this.sameFailure} rounds in a row ended with the same error and no file changed, ` +
+                `though the commands differed. The error: "${example}". The task was stopped rather than left to run out of iterations; ` +
+                'the cause is probably outside what the chat can change — read the last report.');
+        }
+        return null;
+    }
+    /**
+     * After "done" was answered with failing checks. Returns why the task should stop when this is the
+     * same failure as last time with nothing changed in between.
+     */
+    afterFailedChecks(tree, failing) {
+        if (tree === null)
+            return null;
+        const key = failing
+            .map((f) => `${f.name}\u0000${f.detail.toLowerCase().replace(/\d+/g, '#')}`)
+            .sort()
+            .join('\n');
+        const same = this.lastChecks && this.lastChecks.key === key && this.lastChecks.tree === tree;
+        this.lastChecks = { key, tree };
+        if (!same)
+            return null;
+        return (`no progress: "done" was said again with the same ${failing.length} check(s) failing ` +
+            `(${failing.map((f) => f.name).join(', ')}) and no file changed since they were reported. ` +
+            'The task was stopped rather than spend its remaining check rounds the same way.');
+    }
+}