copilot-operator 0.1.40 → 0.1.42

package/dist/src/plan/systemGuide.js

@@ -190,6 +190,46 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'Only for a session whose start was prepared before the run — a starting snapshot approved on the run panel — and chosen first then: the run starts from it as approved. Any other choice below drops it.',
                         doesBg: 'Само за сесия, чието начало е подготвено преди пускането — стартова снимка, одобрена в панела за пускане — и тогава е избрано първо: пускането тръгва от нея, както е одобрена. Всеки друг избор по-долу я отменя.',
                     },
+                    {
+                        key: 'startdlg.refresh',
+                        kind: 'button',
+                        en: 'Read the branches again',
+                        bg: 'Прочети клоновете отново',
+                        doesEn: 'Beside the window\'s first line: reads the repository again — the branch checked out, the branches and their commits — after a checkout or a pull made outside the bot; what was chosen stays chosen.',
+                        doesBg: 'До първия ред на прозореца: прочита хранилището отново — избрания клон, клоновете и комитите им — след checkout или pull, направени извън бота; избраното остава избрано.',
+                    },
+                    {
+                        key: 'startdlg.keepStarted',
+                        kind: 'radio',
+                        en: 'Keep: carry on {branch}',
+                        bg: 'Запази: продължи на {branch}',
+                        doesEn: 'For a session that has run already, chosen first: it carries on its own branch (named in the label). Above it the window says where that branch is now, where the session started, the branch on the remote, and warns when the repository is on another branch.',
+                        doesBg: 'За сесия, която вече е вървяла, избрано първо: продължава на собствения си клон (името е в надписа). Над него прозорецът казва къде е клонът сега, откъде е тръгнала сесията, клона в remote, и предупреждава, когато хранилището е на друг клон.',
+                    },
+                    {
+                        key: 'startdlg.useCurrent',
+                        kind: 'radio',
+                        en: 'The branch checked out now: {branch} ({commit})',
+                        bg: 'Клонът, избран в момента: {branch} ({commit})',
+                        doesEn: 'For a session that has run, when the repository is on another branch: the work starts from the branch checked out now. Like any other branch chosen for it, the tasks that run next start from it — a task run again too — and what already ran stays on its branches.',
+                        doesBg: 'За сесия, която вече е вървяла, когато хранилището е на друг клон: работата тръгва от клона, избран в момента. Както при всеки друг избран клон, задачите, които тръгнат оттук нататък, тръгват от него — и пуснатата отново задача — а изпълненото остава в своите клонове.',
+                    },
+                    {
+                        key: 'startdlg.goUnattendedOn',
+                        kind: 'button',
+                        en: 'Start without asking — on {where}',
+                        bg: 'Започни без питане — на {where}',
+                        doesEn: 'The window\'s start button when the run has one session: says the branch and commit the work starts on.',
+                        doesBg: 'Бутонът за старт на прозореца, когато пускането е на една сесия: казва клона и комита, от които тръгва работата.',
+                    },
+                    {
+                        key: 'startdlg.goStepOn',
+                        kind: 'button',
+                        en: 'Start, asking before each command — on {where}',
+                        bg: 'Започни, с питане преди всяка команда — на {where}',
+                        doesEn: 'The same, for a run that asks before each command.',
+                        doesBg: 'Същото, за пускане с питане преди всяка команда.',
+                    },
                     {
                         key: 'startdlg.local',
                         kind: 'radio',
@@ -404,6 +444,38 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'Nothing is sent: the session stops, its tasks stay queued.',
                         doesBg: 'Нищо не се изпраща: сесията спира, задачите ѝ остават на опашката.',
                     },
+                    {
+                        key: 'pm.note',
+                        kind: 'field',
+                        en: 'Note for the chat (optional when approving; says what to change when asking for another plan)',
+                        bg: 'Бележка за чата (по желание при одобрение; казва какво да се промени, когато искаш друг план)',
+                        doesEn: 'On a plan waiting for approval (plan first): sent to the chat with the answer — a condition for the work when approving, what to change when asking for another plan.',
+                        doesBg: 'На план, който чака одобрение („Първо план“): изпраща се на чата с отговора — условие за работата при одобрение, какво да се промени, когато искаш друг план.',
+                    },
+                    {
+                        key: 'pm.approve',
+                        kind: 'button',
+                        en: 'Approve and start the work',
+                        bg: 'Одобри и започни работата',
+                        doesEn: 'The plan is recorded as approved by the operator and the chat starts changing the code, following it.',
+                        doesBg: 'Планът се записва като одобрен от оператора и чатът започва да променя кода, като го следва.',
+                    },
+                    {
+                        key: 'pm.revise',
+                        kind: 'button',
+                        en: 'Ask for another plan',
+                        bg: 'Поискай друг план',
+                        doesEn: 'Needs the note: the chat makes a new version of the plan with it, still without changing anything, and the card comes back.',
+                        doesBg: 'Иска бележка: чатът прави нова версия на плана с нея, пак без да променя нищо, и картата се връща.',
+                    },
+                    {
+                        key: 'pm.stop',
+                        kind: 'button',
+                        en: 'Stop the task',
+                        bg: 'Спри задачата',
+                        doesEn: 'After a confirmation the task ends as stopped, with nothing changed; it can be run again.',
+                        doesBg: 'След потвърждение задачата приключва като спряна, без нищо променено; може да се пусне отново.',
+                    },
                 ],
             },
         ],
@@ -1193,6 +1265,22 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'Sessions with the same name here share one Copilot conversation; empty gives this one its own.',
                         doesBg: 'Сесиите с едно и също име тук споделят един разговор в Copilot; празно дава на тази собствен.',
                     },
+                    {
+                        key: 'pm.sessionSetting',
+                        kind: 'select',
+                        en: 'Plan first, for this session',
+                        bg: 'Първо план, за тази сесия',
+                        doesEn: 'Plan first for this session\'s tasks: "As in Settings", off, approved without asking, or approved by the operator; overrides Settings → Execution → Plan first.',
+                        doesBg: '„Първо план“ за задачите на тази сесия: „Както е в Настройки“, изключено, одобрява се без питане или от оператора; отменя Настройки → Изпълнение → Първо план.',
+                    },
+                    {
+                        key: 'pm.followSettings',
+                        kind: 'select',
+                        en: 'As in Settings',
+                        bg: 'Както е в Настройки',
+                        doesEn: 'The session follows Settings → Execution → Plan first.',
+                        doesBg: 'Сесията следва Настройки → Изпълнение → Първо план.',
+                    },
                     {
                         key: 'session.run',
                         kind: 'button',
@@ -1708,6 +1796,14 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'In the edit, with version control on: the commit message\'s subject and body.',
                         doesBg: 'В редакцията, с включен контрол на версиите: заглавието и тялото на комита.',
                     },
+                    {
+                        key: 'fup.button',
+                        kind: 'button',
+                        en: 'Continue with a new prompt',
+                        bg: 'Продължи с нов prompt',
+                        doesEn: 'On a task card that failed or blocked on its work: the same dialog as on the register\'s row — how it ended, a new prompt, and the task carries on from where it got to in its chat and on its branch.',
+                        doesBg: 'На карта на задача, провалена или блокирана по работата: същият прозорец като на реда в регистъра — как е завършила, нов prompt, и задачата продължава оттам, докъдето е стигнала, в чата и на клона си.',
+                    },
                     {
                         key: 'task.continue',
                         kind: 'button',
@@ -1804,6 +1900,22 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'The exact first message that opened the task.',
                         doesBg: 'Точното първо съобщение, с което е започнала задачата.',
                     },
+                    {
+                        key: 'pm.taskApproved',
+                        kind: 'disclosure',
+                        en: 'Plan (version {n}, approved)',
+                        bg: 'План (версия {n}, одобрен)',
+                        doesEn: 'The plan the work follows (plan first): what was already there, the approach, steps, files, how it shows the work is done, risks; who approved it and the comments that asked for earlier versions to change.',
+                        doesBg: 'Планът, който работата следва („Първо план“): какво вече има, подход, стъпки, файлове, как ще покаже, че е готово, рискове; кой го е одобрил и коментарите, поискали промени в по-ранни версии.',
+                    },
+                    {
+                        key: 'pm.taskWaiting',
+                        kind: 'disclosure',
+                        en: 'Plan (version {n}, waiting for approval)',
+                        bg: 'План (версия {n}, чака одобрение)',
+                        doesEn: 'The same, open while the plan waits on its approval card at the top of every page.',
+                        doesBg: 'Същото, отворено, докато планът чака на картата си за одобрение най-горе на всяка страница.',
+                    },
                     {
                         key: 'task.finalReply',
                         kind: 'disclosure',
@@ -2312,6 +2424,37 @@ export const SYSTEM_GUIDE = [
                     },
                 ],
             },
+            {
+                headingKey: 'fup.title',
+                en: 'Continue “{title}” with a new prompt',
+                bg: 'Продължи „{title}“ с нов prompt',
+                controls: [
+                    {
+                        key: 'fup.original',
+                        kind: 'disclosure',
+                        en: 'The task’s prompt as it stands',
+                        bg: 'Prompt-ът на задачата, какъвто е',
+                        doesEn: 'Shows the task\'s own prompt, which stays as it is: the new one is added to it.',
+                        doesBg: 'Показва собствения prompt на задачата, който остава какъвто е: новият се добавя към него.',
+                    },
+                    {
+                        key: 'fup.prompt',
+                        kind: 'field',
+                        en: 'New prompt',
+                        bg: 'Нов prompt',
+                        doesEn: 'What to do now, in the operator\'s words: what was wrong and what to do instead. Required. It wins where it and the task\'s prompt disagree.',
+                        doesBg: 'Какво да направи сега, с думите на оператора: какво е било грешно и какво да направи вместо това. Задължително. Надделява, където то и prompt-ът на задачата си противоречат.',
+                    },
+                    {
+                        key: 'fup.save',
+                        kind: 'button',
+                        en: 'Queue it to continue with this prompt',
+                        bg: 'Върни в опашката да продължи с този prompt',
+                        doesEn: 'Queues the task to carry on with the prompt, in its chat and on its branch; the dialog then offers "Run this task".',
+                        doesBg: 'Връща задачата в опашката да продължи с prompt-а, в чата и на клона ѝ; после прозорецът предлага „Пусни тази задача“.',
+                    },
+                ],
+            },
             {
                 headingKey: null,
                 en: 'On every task row, in every view',
@@ -2421,6 +2564,14 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'On a row that failed or blocked on its work: says what happens to the chat, branch and record, then starts a new attempt of that task alone; the rest of the queue stays.',
                         doesBg: 'На ред, провален или блокиран по работата: казва какво става с чата, клона и записа, после пуска нов опит само за тази задача; останалите в опашката остават.',
                     },
+                    {
+                        key: 'fup.button',
+                        kind: 'button',
+                        en: 'Continue with a new prompt',
+                        bg: 'Продължи с нов prompt',
+                        doesEn: 'The way on after a task failed or blocked on its work: opens a dialog that shows how it ended (the reason, the checks that did not pass, what the review found) and takes a new prompt. Queued with it, the task carries on from where it got to — its own chat and branch, the failed attempt\'s work in the tree — and the chat is told how it ended and why, then given the prompt, which is added to the task\'s own. Saving does not start it; the dialog then offers "Run this task". Recommend this when the operator wants to keep the work and correct it.',
+                        doesBg: 'Пътят напред, когато задача се е провалила или блокирала по работата: отваря прозорец, който показва как е завършила (причината, проверките, които не минаха, какво откри рецензията) и приема нов prompt. Върната с него в опашката, задачата продължава оттам, докъдето е стигнала — собственият ѝ чат и клон, с работата на неуспешния опит в дървото — а чатът научава как и защо е завършила и получава prompt-а, който се добавя към собствения на задачата. Запазването не я пуска; после прозорецът предлага „Пусни тази задача“. Препоръчвай го, когато операторът иска да запази работата и да я поправи.',
+                    },
                     {
                         key: 'reg.continueHere',
                         kind: 'button',
@@ -2429,13 +2580,21 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'On a row stopped by a limit from the settings (minutes, messages, reply wait, rounds of fixing), by the bot stopping or by the operator: says what happens to the chat, branch and files, then starts that task alone in its chat.',
                         doesBg: 'На ред, спрян от лимит в настройките (минути, съобщения, чакане на отговор, кръгове поправки), от спрял бот или от оператора: казва какво става с чата, клона и файловете, после пуска само тази задача в чата ѝ.',
                     },
+                    {
+                        key: 'reg.continueHerePrompt',
+                        kind: 'field',
+                        en: 'New prompt (optional)',
+                        bg: 'Нов prompt (по желание)',
+                        doesEn: 'In the "Continue where it stopped" panel: a new prompt to carry on with, optional — added to the task, and the chat does it as it carries on.',
+                        doesBg: 'В панела „Продължи откъдето спря“: нов prompt, с който да продължи, по желание — добавя се към задачата и чатът го изпълнява, докато продължава.',
+                    },
                     {
                         key: 'reg.fixPrompt',
                         kind: 'button',
                         en: 'Fix the prompt and queue it again',
                         bg: 'Поправи prompt-а и върни в опашката',
-                        doesEn: 'On a row that did not end done, its session idle: rewrite the task\'s text and queue it again. Saving does not start it; the same dialog then asks "Run it now?" with the "Run this task" choices and buttons.',
-                        doesBg: 'На ред, който не е завършил готов, при спряна сесия: пренапишете текста на задачата и я върнете в опашката. Запазването не я пуска; после същият прозорец пита „Да я пусна ли сега?“ с изборите и бутоните на „Пусни тази задача“.',
+                        doesEn: 'On a row that did not end done, its session idle: rewrite the task\'s text and queue it again — it starts over from where the task first began, the failed attempt\'s work set aside on its branch (to keep that work and go on from it: "Continue with a new prompt"). Saving does not start it; the same dialog then asks "Run it now?" with the "Run this task" choices and buttons.',
+                        doesBg: 'На ред, който не е завършил готов, при спряна сесия: пренапишете текста на задачата и я върнете в опашката — тя започва отначало оттам, откъдето е тръгнала първия път, а работата на неуспешния опит остава в неговия клон (за да я запазите и да продължите от нея: „Продължи с нов prompt“). Запазването не я пуска; после същият прозорец пита „Да я пусна ли сега?“ с изборите и бутоните на „Пусни тази задача“.',
                     },
                     {
                         key: 'runq.later',
@@ -3354,6 +3513,38 @@ export const SYSTEM_GUIDE = [
                         doesEn: 'It runs without anyone reading it. Only on a machine where that is acceptable.',
                         doesBg: 'Изпълнява се, без някой да я е прочел. Само на машина, където това е приемливо.',
                     },
+                    {
+                        key: 'pm.setting',
+                        kind: 'select',
+                        en: 'Plan first',
+                        bg: 'Първо план',
+                        doesEn: 'Each task first looks at the code without changing anything and makes a plan; the work starts once the plan is approved, and the review checks the work followed it. A run that does not ask approves the plan itself, so it never waits.',
+                        doesBg: 'Всяка задача първо разглежда кода, без да променя нищо, и прави план; работата започва, когато планът е одобрен, а прегледът проверява дали работата го следва. Пускане, което не пита, одобрява плана само, така че никога не чака.',
+                    },
+                    {
+                        key: 'pm.off',
+                        kind: 'select',
+                        en: 'Off — the work starts at once',
+                        bg: 'Изключено — работата започва веднага',
+                        doesEn: 'No plan: the task starts changing the code in its first reply, as before.',
+                        doesBg: 'Без план: задачата започва да променя кода от първия си отговор, както досега.',
+                    },
+                    {
+                        key: 'pm.auto',
+                        kind: 'select',
+                        en: 'On — the plan is approved without asking',
+                        bg: 'Включено — планът се одобрява без питане',
+                        doesEn: 'The runner approves the plan as soon as it is complete and records that it did.',
+                        doesBg: 'Runner-ът одобрява плана веднага щом е пълен и записва, че го е направил.',
+                    },
+                    {
+                        key: 'pm.approveMode',
+                        kind: 'select',
+                        en: 'On — I approve the plan when the run asks before each command',
+                        bg: 'Включено — аз одобрявам плана, когато пускането пита преди всяка команда',
+                        doesEn: 'In a run that asks before each command, the plan waits on a card at the top of every page; an unattended run approves it itself and says why.',
+                        doesBg: 'При пускане с питане преди всяка команда планът чака на карта най-горе на всяка страница; пускане без надзор го одобрява само и казва защо.',
+                    },
                 ],
             },
         ],

package/dist/src/protocol/parser.js

@@ -142,11 +142,33 @@ export function normaliseProse(value) {
             });
         }
     }
+    // A plan's prose, in plan mode: read as text whatever shape it came in, as the fields above are.
+    if (out.plan && typeof out.plan === 'object' && !Array.isArray(out.plan)) {
+        const plan = { ...out.plan };
+        for (const key of ['existing', 'approach', 'verification', 'risks']) {
+            if (key in plan && plan[key] !== undefined && typeof plan[key] !== 'string') {
+                plan[key] = proseOf(plan[key]);
+                coerced.push(`plan.${key}`);
+            }
+        }
+        for (const key of ['steps', 'files']) {
+            if (typeof plan[key] === 'string') {
+                // One item per line, its numbering or bullet taken off: "1. add the writer\n2. add the route".
+                plan[key] = plan[key]
+                    .split(/\r?\n/)
+                    .map((l) => l.replace(/^\s*(?:\d+[.)]|[-*•])\s+/, '').trim())
+                    .filter(Boolean);
+                coerced.push(`plan.${key}`);
+            }
+        }
+        out.plan = plan;
+    }
     return { value: out, coerced };
 }
 /** What each field must look like, said in the message that asks for a reformatted reply. */
 const FIELD_SHAPES = [
-    [/^status$/, '"status" is one of "continue", "done", "blocked"'],
+    [/^status$/, '"status" is one of "continue", "done", "blocked" — and "plan", in plan mode only'],
+    [/^plan(\.|$)/, '"plan" is {"existing": "…", "approach": "…", "steps": ["…"], "files": ["…"], "verification": "…", "risks": "…"} with plain strings'],
     [/^steps(\.|$)/, '"steps" is a list of {"id": 1, "type": "command", "cmd": "the command"} ("shell", "expect", "timeoutSec" optional)'],
     [/^tried(\.|$)/, '"tried" is a list of plain strings, one sentence per approach'],
     [/^deviations(\.|$)/, '"deviations" is a list of {"instruction": "…", "did": "…", "why": "…"} with plain strings'],
@@ -210,10 +232,12 @@ export function parseReply(markdown, opts) {
             // model that writes "Край" under an explanation of why it cannot finish has ended the
             // task, not completed it, and reading that as `done` would file a failure as a success.
             const blocked = reply.status === 'blocked';
+            // A plan waits for its approval: the stop word in it does not end the task.
+            const plan = reply.status === 'plan';
             return {
                 ok: true,
                 reply: { ...reply, steps },
-                done: reply.status === 'done' || (markerHit && hasSummary && !blocked),
+                done: reply.status === 'done' || (markerHit && hasSummary && !blocked && !plan),
                 blocked,
                 json: text.trim(),
                 ...(prose.coerced.length > 0 ? { coerced: prose.coerced } : {}),

package/dist/src/protocol/replySchema.js

@@ -90,6 +90,21 @@ export const DisputeSchema = z.object({
     /** What shows it: the command run and what came back, quoted. */
     evidence: z.string().trim().min(1),
 });
+/** A list item that arrived as an object or a number: read as its text, since nothing in a plan is run. */
+const asText = (v) => typeof v === 'string' ? v : v && typeof v === 'object' ? Object.values(v).map((x) => (typeof x === 'string' ? x : JSON.stringify(x))).join(' — ') : String(v ?? '');
+/**
+ * The plan of a task in plan mode (see `PlanMode` in session/model.ts): what is already there, how the
+ * task will be done, its stages, the files it touches, how the result will be shown to work, and the
+ * risks. Prose, never run; a list item in another shape is read as its text.
+ */
+export const PlanSchema = z.object({
+    existing: z.string().trim().min(1, 'plan.existing must say what is already in the project that the task touches: the files, functions and behaviour you found.'),
+    approach: z.string().trim().min(1, 'plan.approach must say how you mean to do the task.'),
+    steps: z.array(z.preprocess(asText, z.string().trim().min(1))).min(1, 'plan.steps must list the stages, in order.'),
+    files: z.array(z.preprocess(asText, z.string().trim().min(1))).default([]),
+    verification: z.string().trim().min(1, 'plan.verification must say how you will show the result works.'),
+    risks: z.string().optional(),
+});
 export const ReplySchema = z
     .object({
     /**
@@ -105,8 +120,13 @@ export const ReplySchema = z
      * costing a message, a reply and a report, and ending in a timeout that says nothing about
      * why. A task that stops with "I tried these three things and this is in the way" is a
      * result. A task that runs out of iterations is not.
+     *
+     * `plan` — in plan mode only: here is the plan, made from what I read; no steps with it, and no change
+     * made yet. See `PlanSchema`.
      */
-    status: z.enum(['continue', 'done', 'blocked']),
+    status: z.enum(['continue', 'done', 'blocked', 'plan']),
+    /** Required when `status` is `plan`. */
+    plan: PlanSchema.optional(),
     steps: z.array(StepSchema).default([]),
     notes: z.string().optional(),
     /**
@@ -138,8 +158,12 @@ export const ReplySchema = z
         'Send at least one step, or set status to "done" or "blocked".',
 })
     .refine((r) => r.status === 'continue' || r.steps.length === 0, {
-    message: 'status "done" and status "blocked" both end the task, so they cannot carry steps. ' +
-        'Send the steps with status "continue" first, then end.',
+    message: 'status "done", "blocked" and "plan" cannot carry steps: "done" and "blocked" end the task, and "plan" waits for the plan to be approved. ' +
+        'Send the steps with status "continue".',
+})
+    .refine((r) => r.status !== 'plan' || !!r.plan, {
+    message: 'status "plan" requires a "plan" object: { "existing": what is already there, "approach": how, "steps": [the stages], ' +
+        '"files": [the files you will create or change], "verification": how you will show it works, "risks": optional }.',
 })
     .refine((r) => r.status !== 'done' || (r.summary ?? '').trim().length >= MIN_SUMMARY_CHARS, {
     message: 'status "done" requires a real summary: several sentences explaining what was done, ' +
@@ -190,7 +214,7 @@ export function describeDeviations(deviations) {
  * because forgetting to repeat is more common than meaning to retract.
  */
 export function resolveDeviations(existing, status, incoming) {
-    if (status !== 'continue' && incoming.length > 0)
+    if (status !== 'continue' && status !== 'plan' && incoming.length > 0)
         return mergeDeviations([], incoming);
     return mergeDeviations(existing, incoming);
 }

package/dist/src/session/compose.js

@@ -11,7 +11,7 @@ const TASK_HEADER = '## Task';
  * and a note that is empty simply leaves nothing behind.
  */
 function runnerBlock(input) {
-    const notes = [input.workDirNote, input.readOnlyNote, input.scopeNote, input.approachesNote, input.vcsNote, input.shellNote].map((n) => (n ?? '').trim()).filter((n) => n.length > 0);
+    const notes = [input.workDirNote, input.readOnlyNote, input.scopeNote, input.approachesNote, input.vcsNote, input.shellNote, input.planNote].map((n) => (n ?? '').trim()).filter((n) => n.length > 0);
     return notes.length > 0 ? `${notes.join('\n\n')}\n\n` : '';
 }
 /**
@@ -52,6 +52,8 @@ function level2Block(level2) {
  * the steps it had just asked for actually ran.
  */
 function whyItStopped(c) {
+    if (c.how === 'failed')
+        return describeEnding(c.fromAttempt, c.ended, c.stoppedBecause);
     if (c.how === 'interrupted') {
         const where = c.interruption ? `\n\n${describeInterruption(c.interruption)}\n\n` : ' ';
         return ('The runner stopped unexpectedly while this task was in progress — the program was closed, the machine went off or it ' +
@@ -71,6 +73,33 @@ function whyItStopped(c) {
     const which = c.limit ? ` of ${LIMIT_WORDS[c.limit.setting](c.limit.value)}` : '';
     return `It stopped because the runner's limit${which} was reached${why} — not because anything failed. The files are as you left them.`;
 }
+/**
+ * How an attempt ended without the work being done, in the words the chat is sent: its status and the
+ * runner's reason, the checks that did not pass, what the independent review found, and the attempt's
+ * own summary. The chat that carries it on needs the why as much as the what (2026-10-13).
+ */
+export function describeEnding(fromAttempt, ended, reason) {
+    const status = ended?.status ?? 'failed';
+    const why = (ended?.reason ?? reason ?? '').trim();
+    const lines = [`The previous attempt (attempt ${fromAttempt}) did not succeed: it ended ${status}${why ? ` — ${why}` : '.'}`];
+    if (ended?.failedChecks?.length) {
+        lines.push('', 'The checks that did not pass:');
+        for (const c of ended.failedChecks)
+            lines.push(`- ${c.name}: ${c.detail}`);
+    }
+    if (ended?.findings?.length) {
+        lines.push('', 'What the independent review found:');
+        for (const f of ended.findings)
+            lines.push(`- ${f.what}${f.where ? ` (${f.where})` : ''}: ${f.evidence}`);
+    }
+    if (ended?.summary)
+        lines.push('', `That attempt's own summary: ${ended.summary}`);
+    return lines.join('\n');
+}
+/** The operator's new prompt, as its own section of the message. */
+function instructionSection(text) {
+    return `## New instruction from the operator\n\nAdded to the task above, not in place of it; where the two disagree, this wins.\n\n${text.trim()}`;
+}
 /** Each limit from the settings, as the chat is told about it. See `TaskLimit`. */
 const LIMIT_WORDS = {
     maxRunMinutes: (n) => `${n} minutes per task`,
@@ -87,23 +116,49 @@ export function composeOpening(input) {
      * again — sending it would read as a new task and start the work over. Only when the
      * conversation was lost does the task go out in full, with a line saying it is a continuation.
      */
+    const instruction = input.instruction?.text.trim() ? input.instruction : undefined;
     if (input.continuing && input.contractAlreadySent) {
-        const message = `Continue task ${input.taskNumber}: ${input.taskTitle.trim() || 'untitled'}, in this same conversation. ` +
+        const title = input.taskTitle.trim() || 'untitled';
+        /*
+         * After a failure, with the operator's new prompt: told how it ended and why, that its files are
+         * there, and what to do now — not "carry on from your plan", which is the plan that failed.
+         */
+        if (input.continuing.how === 'failed' && instruction) {
+            const message = `Continue task ${input.taskNumber}: ${title}, in this same conversation, with a new instruction from the operator.\n\n` +
+                `${whyItStopped(input.continuing)}\n\n` +
+                `The files are as that attempt left them, and what it changed is in your working tree. Do not start over: look at ` +
+                `what is there first, keep what is right, and do what the instruction below says. The assignment is the one you ` +
+                `were given above, with the instruction added to it. Verify the result as for any task. Step numbering restarts at 1.\n\n` +
+                `${instructionSection(instruction.text)}\n\n` +
+                `${runnerBlock(input)}`.trimEnd();
+            return { messages: [message], firstMessage: message };
+        }
+        const message = `Continue task ${input.taskNumber}: ${title}, in this same conversation. ` +
             `${whyItStopped(input.continuing)} ` +
             `Do not start over and do not repeat work that is done: start from ` +
             `your plan, say in \`notes\` which stages are done and which one you are on, and carry on. ` +
-            `The assignment is the one you were given above; it has not changed. Step numbering restarts at 1.\n\n` +
+            (instruction
+                ? `The assignment is the one you were given above, with the operator's instruction below added to it. Step numbering restarts at 1.\n\n${instructionSection(instruction.text)}\n\n`
+                : `The assignment is the one you were given above; it has not changed. Step numbering restarts at 1.\n\n`) +
             `${runnerBlock(input)}`.trimEnd();
         return { messages: [message], firstMessage: message };
     }
     const continuationLine = input.continuing
-        ? `\n\nThis continues an earlier attempt at this task. ${whyItStopped(input.continuing)} ` +
-            `Look at what is already done before changing anything, and carry on from there.`
+        ? `\n\nThis continues an earlier attempt at this task. ${whyItStopped(input.continuing)}` +
+            (input.continuing.how === 'failed'
+                ? `\n\nWhat that attempt changed is in your working tree. Look at it before changing anything, keep what is right, and do what the instruction below says.`
+                : ` Look at what is already done before changing anything, and carry on from there.`) +
+            (instruction ? `\n\n${instructionSection(instruction.text)}` : '')
         : input.buildsOn
             ? `\n\nThis task was done once already (attempt ${input.buildsOn.fromAttempt}), and that work is in your ` +
                 `working tree. The text above is a new instruction for it: look at what is there first, build on it, and ` +
-                `change or undo it only where the new instruction asks. Verify the result as for any task.`
-            : '';
+                `change or undo it only where the new instruction asks. Verify the result as for any task.` +
+                (instruction ? `\n\n${describeEnding(instruction.fromAttempt, instruction.ended)}\n\n${instructionSection(instruction.text)}` : '')
+            : instruction
+                ? // The attempt it follows never reached a conversation: what is known of its ending, then the prompt.
+                    `\n\nAn earlier attempt at this task never reached this conversation. ${describeEnding(instruction.fromAttempt, instruction.ended)}` +
+                        `\n\n${instructionSection(instruction.text)}`
+                : '';
     if (!input.contractAlreadySent) {
         const taskMessage = `${runnerBlock(input)}${level2Block(input.level2)}\n\n${taskBlock}${continuationLine}`;
         return {

package/dist/src/session/exports.js

@@ -137,6 +137,7 @@ export function buildPlanExport(scope) {
                 onFailure: s.onFailure ?? 'stop',
                 level2: split.level2,
                 conversationGroup: shared ? '' : (s.conversationGroup ?? ''),
+                ...(s.planMode ? { planMode: s.planMode } : {}),
                 vcs: {
                     enabled: s.vcs?.enabled ?? false,
                     repoDir: s.vcs?.repoDir ?? '',

package/dist/src/session/model.js

@@ -12,6 +12,44 @@ export function tidyVcsPlan(plan) {
         return undefined;
     return { ...(branch ? { branch } : {}), ...(commitMessage ? { commitMessage } : {}) };
 }
+const clipText = (s, n) => {
+    const t = (s ?? '').trim();
+    if (!t)
+        return undefined;
+    return t.length > n ? `${t.slice(0, n)}…` : t;
+};
+/**
+ * How a task's latest attempt ended, for the next one to be told: its status and reason, its own
+ * summary, the checks that did not pass and what the independent review found — clipped, since it
+ * goes into a chat message.
+ */
+export function endingOf(t) {
+    const failedChecks = (t.checkResults ?? []).filter((c) => !c.passed).slice(0, 10).map((c) => ({ name: c.name, detail: clipText(c.detail, 400) ?? '' }));
+    const findings = t.review?.verdict === 'fail'
+        ? (t.review.findings ?? []).slice(0, 10).map((f) => ({ what: clipText(f.what, 400) ?? '', ...(f.where ? { where: clipText(f.where, 200) } : {}), evidence: clipText(f.evidence, 400) ?? '' }))
+        : [];
+    const reason = clipText(t.reason, 2000);
+    const summary = clipText(t.summary, 2000);
+    return {
+        status: t.status,
+        ...(reason ? { reason } : {}),
+        ...(summary && summary !== reason ? { summary } : {}),
+        ...(t.stopCode ? { stopCode: t.stopCode } : {}),
+        ...(failedChecks.length > 0 ? { failedChecks } : {}),
+        ...(findings.length > 0 ? { findings } : {}),
+    };
+}
+/**
+ * Whether a task can be carried on with a new prompt after it failed: it ended failed or blocked on its
+ * work. Not one that contradicted itself — it never started its work, and its way on is the fix of the
+ * contradiction. A task that stopped at a limit or was stopped is continued anyway (`isContinuable`),
+ * with a new prompt or without.
+ */
+export function canFollowUp(t) {
+    return (t.status === 'failed' || t.status === 'blocked') && t.stopCode !== 'contract-conflict';
+}
+/** The longest new prompt taken: it goes into one chat message beside the task. */
+export const MAX_INSTRUCTION_CHARS = 20_000;
 /**
  * Whether "Continue" may carry a task on where it stopped, in its chat and on its branch.
  *

package/dist/src/session/store.js

@@ -11,7 +11,7 @@ import { mkdir, readFile, writeFile, readdir, rename, rm } from 'node:fs/promise
 import { existsSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { join, resolve } from 'node:path';
-import { isContinuable, newId, tidyVcsPlan } from './model.js';
+import { endingOf, isContinuable, MAX_INSTRUCTION_CHARS, newId, tidyVcsPlan } from './model.js';
 /** A task the runner is inside of. It cannot be edited, deleted, or left behind at startup. */
 const ACTIVE_STATUSES = ['running', 'waiting-approval'];
 /**
@@ -107,6 +107,7 @@ export const TASK_FIELD_ON_RERUN = {
     leftovers: 'archived',
     environment: 'archived',
     handoff: 'archived',
+    plan: 'archived',
     interruption: 'cleared',
     finalReply: 'cleared',
     firstMessage: 'cleared',
@@ -525,12 +526,35 @@ export class SessionStore {
      */
     async continueTask(sessionId, taskId, 
     /** Where an attempt the operator stopped had got to, read from its run folder by the caller. */
-    stoppedAt) {
+    stoppedAt, 
+    /**
+     * The operator's new prompt (2026-10-13): what carries a task that failed or blocked on from where
+     * it got to, and may come with any other Continue. See `TaskContinuation.instruction`.
+     */
+    instruction) {
         const current = (await this.getSession(sessionId))?.tasks.find((x) => x.id === taskId);
         if (!current)
             throw new Error(`Task ${taskId} does not exist in session ${sessionId}.`);
+        const text = instruction?.trim() || undefined;
+        if (text && text.length > MAX_INSTRUCTION_CHARS)
+            throw new Error(`The new prompt is ${text.length} characters; it can be at most ${MAX_INSTRUCTION_CHARS}.`);
         if (!isContinuable(current)) {
-            throw new Error('Only a task that stopped before it finished, or at a limit from the settings, can be continued; run this one again instead.');
+            if (current.status === 'failed' || current.status === 'blocked') {
+                if (current.stopCode === 'contract-conflict') {
+                    throw new Error('This task never started its work: it contradicts itself. Fix the contradiction ("Fix the contradiction"), then run it.');
+                }
+                if (!text)
+                    throw new Error('A task that failed is carried on with a new prompt: say what to do now. To run it again as it is, use "Run again".');
+                // The task as it ended, before the attempt is archived: what the chat is told about it.
+                return await this.rerunTask(sessionId, taskId, {}, {
+                    fromAttempt: current.attempt ?? 1,
+                    stoppedBecause: current.reason,
+                    how: 'failed',
+                    instruction: text,
+                    ended: endingOf(current),
+                });
+            }
+            throw new Error('Only a task that stopped before it finished, at a limit from the settings, or that failed can be continued; run this one again instead.');
         }
         const how = current.status === 'limit-reached' || current.limit ? 'limit' : current.interruption ? 'interrupted' : 'stopped';
         return await this.rerunTask(sessionId, taskId, {}, {
@@ -539,6 +563,7 @@ export class SessionStore {
             how,
             ...(current.limit ? { limit: current.limit } : {}),
             ...(current.interruption ? { interruption: current.interruption } : how === 'stopped' && stoppedAt ? { interruption: stoppedAt } : {}),
+            ...(text ? { instruction: text } : {}),
         });
     }
     /**
@@ -595,6 +620,7 @@ export class SessionStore {
                     inputsRestored: t.inputsRestored,
                     artifactsKept: t.artifactsKept,
                     vcs: t.vcs,
+                    plan: t.plan,
                 },
             ];
             // An edit is applied only after the old attempt has been put beyond its reach.
@@ -627,6 +653,7 @@ export class SessionStore {
             // marks itself again after this, in the runner.
             t.stats = undefined;
             t.handoff = undefined;
+            t.plan = undefined;
             t.scopeReverted = undefined;
             t.treeChanged = undefined;
             t.inputsRestored = undefined;