copilot-operator 0.1.0

package/dist/src/plan/importPlan.js

@@ -0,0 +1,202 @@
+import { DEFAULT_MIRROR, DEFAULT_VCS } from '../session/store.js';
+import { availableShells, detectShells } from '../exec/shells.js';
+/** The heading under which a task's acceptance bar reaches Copilot. English, like level 1. */
+const EXPECTED_HEADER = '### Expected result';
+/** The heading the session's goal gets when it opens the level-2 instructions. */
+const GOAL_HEADER = '## Goal of this session';
+/**
+ * The heading the operator's persona gets when it opens a task's level 2.
+ *
+ * A way of working, not a character, so it is headed by what it is for rather than by a name —
+ * the operator's persona is nameless on purpose, so that it can be swapped for another when a
+ * different kind of work needs a different approach.
+ */
+export const PERSONA_HEADER = '## How to carry out this work';
+/**
+ * The line that closes the persona, written out rather than inferred.
+ *
+ * The persona is free text the operator wrote, and it may carry headings and rules of its own, so
+ * "up to the next heading" would cut it wherever it happened to use one. The plan export has to lift
+ * it back out exactly — an exported plan imported again must get the persona that is in the field at
+ * that moment, not the old one and the new one stacked — and an explicit end is the only thing that
+ * makes that exact. It reads as a plain aside to the model that sees it.
+ */
+export const PERSONA_END = '(end of how to carry out this work)';
+/** The persona as it opens a task's level 2, or nothing when there is none. */
+export function personaBlock(persona) {
+    const body = persona.trim();
+    return body ? `${PERSONA_HEADER}\n\n${body}\n\n${PERSONA_END}` : '';
+}
+/**
+ * A level 2 with any persona block at its head taken off.
+ *
+ * Used both ways round: by the plan export, so the file it writes is the plan without the approach
+ * that happened to be in force, and by `composeLevel2`, so a plan that already carries a persona —
+ * hand-written, or exported from somewhere that did not strip it — gets the current one instead of a
+ * second one.
+ */
+export function withoutPersona(level2) {
+    const text = level2.trimStart();
+    if (!text.startsWith(PERSONA_HEADER))
+        return level2;
+    const end = text.indexOf(PERSONA_END);
+    if (end < 0)
+        return level2;
+    return text.slice(end + PERSONA_END.length).replace(/^\s+/, '');
+}
+/**
+ * The text of one task as Copilot will receive it.
+ *
+ * The prompt and the acceptance bar are joined here rather than in the schema so that the
+ * stored task is exactly what was sent: a task that can be re-read a month later and matched
+ * against its summary, with no second document to consult.
+ */
+export function composePrompt(task) {
+    const prompt = task.prompt.trim();
+    const expected = task.expected.trim();
+    if (!expected)
+        return prompt;
+    return `${prompt}\n\n${EXPECTED_HEADER}\n\n${expected}`;
+}
+/**
+ * Level 2 for one task: the operator's persona first, then its own instructions if it has any,
+ * otherwise the session's, goal first.
+ *
+ * The persona goes on every task, whichever branch the rest takes, because it is how *all* of this
+ * work is carried out — a task with instructions of its own replaces the session's instructions,
+ * not the approach. It is written in here rather than sent separately so that it travels with every
+ * task: level 2 is repeated with each task in the conversation, and a long conversation loses its
+ * early turns, which is where a once-sent persona would have been. It sits inside level 2 and so
+ * under level 1, which it cannot change — the persona is the operator's approach, not a way round
+ * the runner's contract.
+ */
+export function composeLevel2(session, task, persona = '') {
+    const rest = level2Without(session, task);
+    const block = personaBlock(persona);
+    if (!block)
+        return rest;
+    return rest ? `${block}\n\n${rest}` : block;
+}
+/** The task's own level 2 if it has any, otherwise the session's, goal first — persona excluded. */
+function level2Without(session, task) {
+    const own = withoutPersona(task.level2).trim();
+    if (own)
+        return own;
+    const shared = withoutPersona(session.level2).trim();
+    const goal = session.goal.trim();
+    if (!goal)
+        return shared;
+    return shared ? `${GOAL_HEADER}\n\n${goal}\n\n${shared}` : `${GOAL_HEADER}\n\n${goal}`;
+}
+/**
+ * What makes two tasks the same task, for the purpose of spotting a plan imported twice.
+ *
+ * The title and the text that would actually be sent. Not the level 2, and not the branch or
+ * the commit message: those can be edited on the session afterwards, and a plan re-pasted
+ * with a better commit subject is still the same plan being imported a second time.
+ */
+export function taskSignature(task) {
+    return `${task.title.trim()}\u0000${task.prompt.trim()}`;
+}
+/** The same, for a whole session as the plan describes it. */
+export function plannedSessionSignature(session) {
+    return session.tasks.map((t) => taskSignature({ title: t.title, prompt: composePrompt(t) })).join('\u0001');
+}
+/**
+ * Checks that name a shell this machine has not got.
+ *
+ * A warning rather than a refusal, which is the line this importer already draws: a plan is
+ * refused for what is wrong with the document and warned about for what is wrong with running
+ * it here. The document is fine — `shell: "pwsh"` is a legal thing for a plan to ask for — and
+ * the same plan is correct on the machine it was written for, so refusing it would be refusing
+ * the wrong thing. But a check that asks for an interpreter this machine cannot start will end
+ * its task on a configuration error rather than on the work, and the moment to hear that is now,
+ * while the queue is still sitting in front of somebody, and not four tasks into a run.
+ *
+ * One line per missing shell, not one per check: the fix is the same for all of them.
+ */
+function unavailableShellWarnings(plan) {
+    const inventory = detectShells();
+    const here = availableShells(inventory);
+    const asked = new Map();
+    for (const session of plan.sessions) {
+        for (const task of session.tasks) {
+            for (const check of task.checks) {
+                if (!check.shell || inventory.found[check.shell])
+                    continue;
+                asked.set(check.shell, [...(asked.get(check.shell) ?? []), `"${check.name}" in "${task.title}"`]);
+            }
+        }
+    }
+    return [...asked].map(([shell, checks]) => {
+        const named = checks.slice(0, 3).join(', ');
+        return (`${checks.length} check(s) ask to run in ${shell}, which is not installed on this machine: ${named}` +
+            `${checks.length > 3 ? `, and ${checks.length - 3} more` : ''}. ` +
+            `They will end their task with a configuration error rather than run. Install ${shell}, or edit those checks to ` +
+            `use one of the shells that are here${here.length > 0 ? ` (${here.join(', ')})` : ''}.`);
+    });
+}
+/**
+ * Creates everything the plan describes.
+ *
+ * `defaultModel` is what a session starts on when the plan does not name one, which keeps an
+ * imported session behaving like one made by hand in the UI.
+ */
+export async function importPlan(store, plan, defaultModel = '', defaultReviewModel = '', 
+/** The operator's persona at the moment of import, written into every task's level 2. */
+persona = '') {
+    const sessions = [];
+    const warnings = [...unavailableShellWarnings(plan)];
+    /*
+     * One conversation for the whole plan, when it asked for that.
+     *
+     * The group is named after the plan, or after the moment of import when the plan has no name,
+     * because the name is what a session in the UI is shown and typed against later. A session
+     * that named its own group keeps it: a plan may want most of its sessions together and one
+     * of them apart.
+     */
+    const sharedGroup = plan.conversation === 'shared'
+        ? (plan.plan.trim() || `plan-${new Date().toISOString().slice(0, 16).replace(/[:T-]/g, '')}`).slice(0, 60)
+        : '';
+    for (const planned of plan.sessions) {
+        const mirror = { ...DEFAULT_MIRROR, ...(planned.mirror ?? {}) };
+        if (mirror.enabled && !mirror.rootDir.trim()) {
+            mirror.enabled = false;
+            warnings.push(`Session "${planned.name}" asked for project files without a root folder, so file attachment was left off.`);
+        }
+        const created = await store.createSession(planned.name, mirror);
+        const vcs = { ...DEFAULT_VCS, ...(planned.vcs ?? {}) };
+        vcs.branchPrefix = vcs.branchPrefix.trim() || DEFAULT_VCS.branchPrefix;
+        vcs.repoDir = vcs.repoDir.trim();
+        const group = planned.conversationGroup.trim() || sharedGroup;
+        await store.updateSession(created.id, (s) => {
+            s.onFailure = planned.onFailure;
+            // Absent means reviewed, which is the default everywhere else too.
+            // The reviewing model follows the same rule as the working one: the plan's word, else
+            // the standing default, else the session's own.
+            s.review = { enabled: planned.review?.enabled !== false, model: (planned.review?.model || defaultReviewModel).trim() };
+            s.conversationGroup = group || undefined;
+            s.model = (planned.model || defaultModel).trim() || undefined;
+            s.planName = plan.plan.trim() || undefined;
+            s.vcs = vcs;
+        });
+        const titles = [];
+        for (const task of planned.tasks) {
+            const added = await store.addTask(created.id, {
+                title: task.title,
+                level2: composeLevel2(planned, task, persona),
+                prompt: composePrompt(task),
+                // Kept even when version control is off for this session: the operator may turn it on
+                // afterwards, and throwing away a name the plan chose would make that a worse session
+                // than the same one imported a minute later.
+                vcsPlan: task.vcs,
+                checks: task.checks,
+                reviewEnabled: task.review,
+                readOnly: task.readOnly || undefined,
+            });
+            titles.push(added.title);
+        }
+        sessions.push({ id: created.id, name: created.name, tasks: titles.length, titles });
+    }
+    return { sessions, taskCount: sessions.reduce((n, s) => n + s.tasks, 0), warnings };
+}

package/dist/src/plan/schema.js

@@ -0,0 +1,483 @@
+/**
+ * The shape of a plan: sessions and their tasks, as one JSON document.
+ *
+ * The document is not written by hand. The user takes a brief (see `brief.ts`) to whatever
+ * chat model they like, that model interviews them about the work, and it answers with a
+ * document in this shape. So the schema has two audiences at once: the importer, which needs
+ * it to be exact, and a language model, which needs the refusals to say what to fix. That is
+ * why nothing here fails with "invalid input" — every issue comes back with a path into the
+ * document and a sentence that can be pasted straight back into the chat.
+ *
+ * Unknown fields are kept out of the imported data but do not fail the import. A model that
+ * adds `"description"` to a task has not misunderstood the format badly enough to be worth
+ * sending the user back to the chat; it is reported as a warning instead.
+ */
+import { z } from 'zod';
+export const PLAN_VERSION = 1;
+/**
+ * Version control, exactly as a session stores it, and required on every session.
+ *
+ * Required because this is the one decision in a plan that cannot be given a safe default. On
+ * means the runner branches and commits and there is a way back from every task; off means the
+ * files are changed where they lie and there is not. Guessing either way produces a plan that
+ * looks fine and is wrong about the thing that matters most, so the model writing the plan has
+ * to ask, and a document that skips the question is refused with the question in it.
+ */
+const VcsInput = z
+    .object({
+    enabled: z.boolean({
+        error: 'vcs.enabled must be true or false. Ask the user whether the runner should make a branch before each task and a commit after it; there is no default for this.',
+    }),
+    repoDir: z.string().trim().default(''),
+    branchMode: z
+        .enum(['per-task', 'per-session'], {
+        error: 'branchMode must be "per-task" (every task starts from the same commit) or "per-session" (one branch, tasks build on each other).',
+    })
+        .optional(),
+    commitOnFinish: z.boolean().optional(),
+    branchPrefix: z.string().optional(),
+    /** The name of the one branch a per-session run works on. Ignored in per-task mode. */
+    branchName: z.string().optional(),
+}, {
+    error: 'Every session needs a "vcs" object saying whether the runner does version control for it and, when it does, which git repository to work in. Ask the user both questions and write the answers here.',
+})
+    .superRefine((vcs, ctx) => {
+    if (vcs.enabled && !vcs.repoDir.trim()) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['repoDir'],
+            message: 'Version control is on for this session, so "repoDir" must be the absolute path of the git repository to work in. Ask the user which folder that is; do not guess one.',
+        });
+    }
+});
+/**
+ * One condition that has to hold before the task is allowed to end.
+ *
+ * The kinds are deliberately few and deliberately mechanical. This runner has no language
+ * model of its own, so a check it cannot decide by running something and comparing is a check
+ * it would have to take on trust — which is the thing the check exists to replace.
+ */
+export const CheckInput = z
+    .object({
+    name: z.string().trim().min(3, 'A check needs a name saying what it is checking.'),
+    expect: z.enum([
+        'exit-zero',
+        'exit-nonzero',
+        'output-contains',
+        'output-omits',
+        'output-matches',
+        'file-exists',
+        'file-missing',
+        'file-contains',
+    ], {
+        error: 'expect must be one of: exit-zero, exit-nonzero, output-contains, output-omits, output-matches, ' +
+            'file-exists, file-missing, file-contains.',
+    }),
+    run: z.string().trim().optional(),
+    /**
+     * The shell to run it in. Left out is the usual answer and the better one.
+     *
+     * A check that names a shell is asking for that shell and nothing else: on a machine without
+     * it the check does not quietly run somewhere else, it ends its task with a configuration
+     * error saying what is missing. Left out, it takes whatever the machine has, in the order
+     * pwsh, powershell, cmd. See `exec/shells.ts`.
+     */
+    shell: z.enum(['pwsh', 'powershell', 'cmd']).optional(),
+    cwd: z.string().trim().optional(),
+    file: z.string().trim().optional(),
+    value: z.string().optional(),
+})
+    .superRefine((check, ctx) => {
+    const needsCommand = check.expect.startsWith('exit-') || check.expect.startsWith('output-');
+    const needsFile = check.expect.startsWith('file-');
+    const needsValue = check.expect === 'output-contains' || check.expect === 'output-omits' ||
+        check.expect === 'output-matches' || check.expect === 'file-contains';
+    if (needsCommand && !check.run?.trim()) {
+        ctx.addIssue({ code: 'custom', path: ['run'], message: `"${check.expect}" is about a command, so "run" is required.` });
+    }
+    if (needsFile && !check.file?.trim()) {
+        ctx.addIssue({ code: 'custom', path: ['file'], message: `"${check.expect}" is about a file, so "file" is required.` });
+    }
+    if (needsValue && !check.value?.trim()) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['value'],
+            message: `"${check.expect}" needs the text it is looking for, in "value".`,
+        });
+    }
+    if (check.expect === 'output-matches' && check.value) {
+        try {
+            new RegExp(check.value);
+        }
+        catch (e) {
+            ctx.addIssue({ code: 'custom', path: ['value'], message: `not a valid regular expression: ${e.message}` });
+        }
+    }
+});
+/**
+ * Whether the work is checked by a second, independent conversation.
+ *
+ * Optional, and on when it is left out — which is the point of leaving it out. A plan that says
+ * nothing about reviewing still gets reviewed; a plan that wants a particular model for the
+ * review, or wants it off for a session of read-only checks, says so here.
+ */
+const ReviewInput = z.object({
+    enabled: z.boolean().optional(),
+    /** The model the review runs on. Empty means the session's own. A different one is better. */
+    model: z.string().trim().optional(),
+});
+/** What one task carries into git: the names, not the outcome. */
+const TaskVcsInput = z.object({
+    branch: z.string().trim().optional(),
+    commitMessage: z.string().trim().optional(),
+});
+/** The project files copied into the chat. Absent means none, which is the default. */
+const MirrorInput = z.object({
+    enabled: z.boolean().optional(),
+    rootDir: z.string().optional(),
+    includeDirs: z.array(z.string()).optional(),
+    excludeDirs: z.array(z.string()).optional(),
+    respectGitignore: z.boolean().optional(),
+    includeEnvFiles: z.boolean().optional(),
+});
+const TaskInput = z.object({
+    title: z
+        .string()
+        .trim()
+        .min(3, 'A task needs a title of at least 3 characters.')
+        .max(120, 'Keep the title under 120 characters; the detail belongs in "prompt".'),
+    prompt: z
+        .string()
+        .trim()
+        .min(30, 'A task needs a real instruction, not a few words. Say what to do, where, and with what.'),
+    /**
+     * What must work once the task is done.
+     *
+     * Separate from the prompt because it is the thing the operator reads the summary against.
+     * The importer appends it to the prompt under its own heading, so Copilot receives one text
+     * and the record still shows which half was the instruction and which was the bar.
+     */
+    expected: z.string().trim().default(''),
+    /** Level 2 for this task alone. Falls back to the session's. */
+    level2: z.string().trim().default(''),
+    /**
+     * The branch this task works on and the commit it ends with.
+     *
+     * Both are names for work that has not happened yet, which is exactly what a plan is good
+     * at: the model writing it knows what the task is for. Neither is required, and neither is
+     * trusted — the branch name is slugified and prefixed like any other, and the runner still
+     * decides when to branch and when to commit.
+     */
+    vcs: TaskVcsInput.optional(),
+    /**
+     * What must be true before this task is allowed to end.
+     *
+     * `expected` says it for a person to read; this says it so the runner can decide it. When
+     * there are checks, Copilot reporting the task as done is not the end of it: they are run,
+     * and a failure goes back to the chat to be fixed.
+     */
+    checks: z.array(CheckInput).default([]),
+    /**
+     * Turns the independent review off for this one task.
+     *
+     * Worth using sparingly: a task whose whole output is a report somebody reads, or a scaffold
+     * with nothing to run yet, gains little from a reviewer. Everything that produces something
+     * usable gains a lot.
+     */
+    review: z.boolean().optional(),
+    /**
+     * A task that must not change files: an audit, a smoke test, a report.
+     *
+     * Written as a flag rather than as a sentence in the prompt because a sentence is advice.
+     * A smoke-test task told in prose to change nothing renamed the page's labels when a
+     * reviewer asked it to. With the flag, the runner fails the task if the working tree has
+     * changed when it ends, whatever the summary says, and commits the change on the task's
+     * branch so nothing is lost and the next task starts clean.
+     */
+    readOnly: z.boolean().default(false),
+});
+const SessionInput = z.object({
+    name: z
+        .string()
+        .trim()
+        .min(2, 'A session needs a name.')
+        .max(80, 'Keep the session name short; it becomes part of every branch name.'),
+    /** What the whole session is for. Becomes the opening of its level 2. */
+    goal: z.string().trim().default(''),
+    /** The chat model, by the exact name the picker shows. Empty leaves the chat alone. */
+    model: z.string().trim().default(''),
+    /** Whether the tasks are one chain (`stop`) or independent checks (`continue`). */
+    onFailure: z
+        .enum(['stop', 'continue'], {
+        error: 'onFailure must be "stop" (the tasks are one chain) or "continue" (the tasks are independent).',
+    })
+        .default('stop'),
+    /** Level 2 for every task in the session, unless a task overrides it. */
+    level2: z.string().trim().default(''),
+    /**
+     * A name that makes this session share one Copilot conversation with the others that carry
+     * the same name. Empty means it gets a conversation of its own.
+     */
+    conversationGroup: z.string().trim().default(''),
+    vcs: VcsInput,
+    review: ReviewInput.optional(),
+    mirror: MirrorInput.optional(),
+    tasks: z.array(TaskInput).min(1, 'A session with no tasks would import as an empty queue.'),
+});
+export const PlanSchema = z.object({
+    version: z.literal(PLAN_VERSION, `This importer reads version ${PLAN_VERSION} plans. Set "version": ${PLAN_VERSION}.`),
+    /** A name for the whole document, shown while importing. */
+    plan: z.string().trim().default(''),
+    /** Anything the model wants on the record: assumptions, open questions, ordering. */
+    notes: z.string().trim().default(''),
+    /**
+     * What a run across these sessions does when a whole session fails.
+     *
+     * The same question the sessions ask about their own tasks, one level up. It is here rather
+     * than only in the run panel because it is a property of the work: whether session 2 is
+     * worth running after session 1 failed is something the plan knows and the operator would
+     * otherwise have to remember.
+     */
+    onFailure: z
+        .enum(['stop', 'continue'], {
+        error: 'The plan-level onFailure must be "stop" (a failed session stops the rest) or "continue" (the sessions are independent of each other).',
+    })
+        .default('stop'),
+    /**
+     * Whether the sessions of this plan talk to Copilot in one conversation or in their own.
+     *
+     * `per-session` is the default and the usual answer: a session is a conversation. `shared`
+     * puts all of them in one chat, which is what you want when they are one piece of work split
+     * into parts that need to see each other's history — and what you do not want when they are
+     * unrelated, because then every session inherits a context that has nothing to do with it.
+     */
+    conversation: z
+        .enum(['per-session', 'shared'], {
+        error: 'conversation must be "per-session" (each session gets its own chat) or "shared" (all of them in one).',
+    })
+        .default('per-session'),
+    sessions: z.array(SessionInput).min(1, 'A plan needs at least one session.'),
+});
+/**
+ * Finds the JSON inside whatever the user pasted.
+ *
+ * Chat models wrap answers in prose and fenced code blocks, and asking the user to clean that
+ * up by hand is asking them to do the one part of this that a computer is good at. A fenced
+ * block wins if there is one; otherwise the text from the first brace to the last is tried.
+ */
+export function extractJson(text) {
+    const trimmed = (text ?? '').trim();
+    const fenced = /```(?:json|jsonc)?\s*\n([\s\S]*?)\n?```/i.exec(trimmed);
+    if (fenced?.[1]?.trim())
+        return fenced[1].trim();
+    const first = trimmed.indexOf('{');
+    const last = trimmed.lastIndexOf('}');
+    if (first >= 0 && last > first)
+        return trimmed.slice(first, last + 1);
+    return trimmed;
+}
+/** `["sessions", 0, "tasks", 1, "prompt"]` as `sessions[0].tasks[1].prompt`. */
+function pathOf(parts) {
+    return parts.reduce((acc, p) => (typeof p === 'number' ? `${acc}[${p}]` : acc ? `${acc}.${String(p)}` : String(p)), '');
+}
+/**
+ * The keys of an object schema, read from the schema rather than listed by hand.
+ *
+ * The list used to be written out here, and it drifted: `readOnly` was added to the task
+ * schema and not to the list, so every plan that used it was told "readOnly is not part of the
+ * format and was ignored" — while the importer applied it. A warning that contradicts what
+ * happens is worse than none. Reading the shape cannot drift.
+ */
+function keysOf(schema, fallback = []) {
+    const shape = schema.shape;
+    return shape ? Object.keys(shape) : fallback;
+}
+const KNOWN_KEYS = {
+    plan: keysOf(PlanSchema),
+    session: keysOf(SessionInput),
+    task: keysOf(TaskInput),
+    check: keysOf(CheckInput, ['name', 'expect', 'run', 'shell', 'cwd', 'file', 'value']),
+    vcs: keysOf(VcsInput),
+    taskVcs: keysOf(TaskVcsInput),
+    review: keysOf(ReviewInput),
+    mirror: keysOf(MirrorInput),
+};
+function unknownKeys(value, kind, where, out) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return;
+    for (const key of Object.keys(value)) {
+        if (!KNOWN_KEYS[kind].includes(key)) {
+            out.push(`${where}.${key} is not part of the format and was ignored.`);
+        }
+    }
+}
+/** Fields a model invented, walked by hand because the schema drops them silently. */
+function collectWarnings(raw) {
+    const out = [];
+    if (!raw || typeof raw !== 'object')
+        return out;
+    unknownKeys(raw, 'plan', 'plan', out);
+    const sessions = raw.sessions;
+    if (!Array.isArray(sessions))
+        return out;
+    sessions.forEach((s, i) => {
+        unknownKeys(s, 'session', `sessions[${i}]`, out);
+        const session = s;
+        unknownKeys(session.vcs, 'vcs', `sessions[${i}].vcs`, out);
+        unknownKeys(session.review, 'review', `sessions[${i}].review`, out);
+        unknownKeys(session.mirror, 'mirror', `sessions[${i}].mirror`, out);
+        if (Array.isArray(session.tasks)) {
+            session.tasks.forEach((t, j) => {
+                unknownKeys(t, 'task', `sessions[${i}].tasks[${j}]`, out);
+                unknownKeys(t?.vcs, 'taskVcs', `sessions[${i}].tasks[${j}].vcs`, out);
+                const checks = t?.checks;
+                if (Array.isArray(checks)) {
+                    checks.forEach((c, k) => unknownKeys(c, 'check', `sessions[${i}].tasks[${j}].checks[${k}]`, out));
+                }
+            });
+        }
+    });
+    return out;
+}
+/**
+ * Two sessions with the same name are legal but almost never meant, and by the time anyone
+ * notices there are two identical rows in the list and two sets of branches in the
+ * repository. Said out loud at import time, it costs the user one glance.
+ */
+function duplicateNameWarnings(plan) {
+    const seen = new Map();
+    const out = [];
+    for (const s of plan.sessions) {
+        const key = s.name.toLowerCase();
+        const n = (seen.get(key) ?? 0) + 1;
+        seen.set(key, n);
+        if (n === 2)
+            out.push(`Two sessions are both called "${s.name}". They will be created as two separate sessions.`);
+    }
+    return out;
+}
+export function summarise(plan) {
+    return {
+        plan: plan.plan,
+        notes: plan.notes,
+        checkCount: plan.sessions.reduce((n, s) => n + s.tasks.reduce((m, t) => m + t.checks.length, 0), 0),
+        onFailure: plan.onFailure,
+        conversation: plan.conversation,
+        sessions: plan.sessions.map((s) => ({
+            name: s.name,
+            tasks: s.tasks.map((t) => t.title),
+            model: s.model,
+            onFailure: s.onFailure,
+            repoDir: s.vcs?.repoDir ?? '',
+        })),
+        taskCount: plan.sessions.reduce((n, s) => n + s.tasks.length, 0),
+    };
+}
+/**
+ * Reads a pasted document and says either what it means or what is wrong with it.
+ *
+ * Never throws. Every way this can fail — not JSON at all, the wrong version, a task with no
+ * prompt — is an answer the user is meant to see and hand back to the chat model.
+ */
+export function checkPlan(text) {
+    const source = extractJson(text ?? '');
+    if (!source.trim()) {
+        return { ok: false, warnings: [], issues: [{ path: '', message: 'There is nothing here to import.' }] };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(source);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            warnings: [],
+            issues: [
+                {
+                    path: '',
+                    message: `This is not valid JSON: ${e.message}. ` +
+                        'A common cause is a comment, a trailing comma, or a curly quote the chat inserted.',
+                },
+            ],
+        };
+    }
+    const warnings = collectWarnings(raw);
+    const parsed = PlanSchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, warnings, issues: parsed.error.issues.map((i) => ({ path: pathOf(i.path), message: i.message })) };
+    }
+    const weak = weakCheckIssues(parsed.data);
+    if (weak.length)
+        return { ok: false, warnings, issues: weak };
+    return {
+        ok: true,
+        plan: parsed.data,
+        warnings: [...warnings, ...duplicateNameWarnings(parsed.data), ...indexCheckWarnings(parsed.data)],
+        summary: summarise(parsed.data),
+    };
+}
+/**
+ * A check that asks the git index whether a file the task creates is there can never pass.
+ *
+ * The runner commits after the task, so during the task a new file is untracked and
+ * `git ls-files` does not list it — and the task is forbidden to `git add`. A plan wrote
+ * exactly that check ("the seed rule set is tracked") and the task ended blocked after three
+ * honest attempts, with the work complete and the file on disk. `file-exists` is the check
+ * that was meant; the negative form (`output-omits` on `ls-files`, "node_modules is not
+ * tracked") is fine and stays silent.
+ */
+function indexCheckWarnings(plan) {
+    const out = [];
+    plan.sessions.forEach((s, i) => {
+        s.tasks.forEach((t, j) => {
+            t.checks.forEach((c, k) => {
+                if (c.expect !== 'output-contains' && c.expect !== 'output-matches')
+                    return;
+                if (!/\bgit\b[^|;&]*\bls-files\b/i.test(c.run ?? ''))
+                    return;
+                out.push(`sessions[${i}].tasks[${j}].checks[${k}]: "${c.name}" asks git ls-files to list a file. A file the task creates is ` +
+                    'untracked until the runner commits after the task, and the task may not git add, so this check cannot pass. ' +
+                    'Use "file-exists" for a file the task writes; the index is right only for what earlier tasks committed.');
+            });
+        });
+    });
+    return out;
+}
+/**
+ * A task whose every check would pass with the task's work not done is refused.
+ *
+ * `file-exists` proves a file, not what is in it; a bare exit code of a test run is 0 when there are
+ * no tests at all, and 0 again with only the old ones. A plan built entirely from those can finish
+ * "done" with nothing proven, and it did: twice in a row the planning model wrote "npm test exits 0"
+ * against five acceptance criteria — the second time after the brief had named this very trap — and
+ * both times the operator had to catch it and dictate the fix. The brief teaches the rule; this is
+ * the part that does not depend on a model having learned it. It is an error rather than a warning
+ * because errors are what the operator copies back to the chat with one button, and the brief tells
+ * the chat to fix exactly those.
+ *
+ * Only tasks that have checks are judged: a task with none (a read-only report, a task with nothing
+ * to run) was allowed before and is not what this is about. `exit-nonzero` is not weak — it proves a
+ * refusal — and anything that reads output or file contents is where proof can live.
+ */
+const WEAK_EXPECT = new Set(['file-exists', 'file-missing', 'exit-zero']);
+function weakCheckIssues(plan) {
+    const out = [];
+    plan.sessions.forEach((s, i) => {
+        s.tasks.forEach((t, j) => {
+            if (!t.checks.length || !t.checks.every((c) => WEAK_EXPECT.has(c.expect)))
+                return;
+            out.push({
+                path: `sessions[${i}].tasks[${j}].checks`,
+                message: `every check of "${t.title}" would pass with the task's work not done: a file that exists proves the file, not what is in it, ` +
+                    'and a test run exits 0 with no tests at all. Add a check that reads output or contents only the finished work produces — ' +
+                    'name each test after its acceptance criterion and use "output-contains" on the test runner\'s output for that test passing ' +
+                    '(with node --test, the line starts with ✔), or "output-matches" on the count of passing tests.',
+            });
+        });
+    });
+    return out;
+}
+/** The issues as a block the user can hand back to the chat model without editing it. */
+export function describeIssues(issues) {
+    return issues.map((i) => (i.path ? `- ${i.path}: ${i.message}` : `- ${i.message}`)).join('\n');
+}