@ctrl-spc/cs 0.7.13 → 0.7.14

package/dist/panel3/checkout.js

@@ -14,7 +14,7 @@
  * two owners of it is how two answers are born.
  */
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { configDir, readCodebasePaths } from '../config.js';
 function isDirectory(path) {
@@ -413,6 +413,8 @@ export function commitCardWork(folder,
 // Name the codebase and branch in failures, without exposing a local path.
 describe) {
     try {
+        if (gitOperationInProgress(folder))
+            throw pathFree('A Git operation is still in progress on this card. Use recover_landing to finish the approved recovery before landing.');
         git(folder, ['add', '-A']);
         if (git(folder, ['status', '--porcelain']).length > 0) {
             git(folder, ['commit', '--no-verify', '-m', 'Work from this card']);
@@ -447,28 +449,118 @@ export function mergeIntoBase(source, branch, base, codebaseName) {
        The worktree holding the base may be the person's own checkout, and the
        step below would abort on failure. So a conflicted merge already sitting
        there stops this before anything is attempted. */
-    if (existsSync(join(holder, '.git', 'MERGE_HEAD')) || existsSync(join(holder, 'MERGE_HEAD'))) {
-        throw pathFree(`A merge is already in progress in the copy of ${codebaseName} holding ${base} on this `
+    let inProgress;
+    try {
+        inProgress = gitOperationInProgress(holder);
+    }
+    catch {
+        throw pathFree(`Could not inspect ${codebaseName}'s ${base} on this machine. Nothing was merged; check that working copy before retrying.`);
+    }
+    if (inProgress) {
+        throw pathFree(`A Git operation is already in progress in the copy of ${codebaseName} holding ${base} on this `
             + `machine. Nothing was done, and this card's work is still on ${branch}.`);
     }
     try {
         git(holder, ['merge', '--no-edit', branch]);
     }
     catch {
+        const conflicts = git(holder, ['diff', '--name-only', '--diff-filter=U']).length > 0;
         /* ITS OWN TRY, SO A FAILED ABORT CANNOT REPLACE THE COMPOSED FAILURE with
            git's own text, which names a folder. */
+        if (gitOk(holder, ['rev-parse', '--verify', 'MERGE_HEAD'])) {
+            try {
+                git(holder, ['merge', '--abort']);
+            }
+            catch {
+                throw pathFree(`The merge in ${codebaseName} could not be rolled back. ${base} needs recovery before retrying; this card's branch is preserved.`);
+            }
+        }
+        throw Object.assign(pathFree(`This card's work will not go back onto ${base} in ${codebaseName} cleanly. Nothing was `
+            + `merged, ${base} is where it was, and the work is still on ${branch}.`), { mergeConflicts: conflicts });
+    }
+}
+function gitOperationInProgress(folder) {
+    return ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'rebase-merge', 'rebase-apply', 'sequencer']
+        .some(name => existsSync(git(folder, ['rev-parse', '--path-format=absolute', '--git-path', name])));
+}
+const reconciliationMessage = (card) => `CTRL+SPC: reconcile ${card.branch} with ${card.base}`;
+/** Git owns the durable recovery state. Its merge message identifies our merge;
+ * a user's in-progress operation is never continued or aborted by recovery. */
+export function ownsReconciliation(card) {
+    if (!gitOk(card.folder, ['rev-parse', '--verify', 'MERGE_HEAD']))
+        return false;
+    try {
+        const message = git(card.folder, ['rev-parse', '--path-format=absolute', '--git-path', 'MERGE_MSG']);
+        return readFileSync(message, 'utf8').split('\n')[0] === reconciliationMessage(card);
+    }
+    catch {
+        throw pathFree('Could not read this card’s merge recovery state. Its working copy needs recovery on this machine.');
+    }
+}
+function checkCardBranch(card) {
+    if (git(card.folder, ['branch', '--show-current']) !== card.branch || card.branch === card.base) {
+        throw pathFree('The card is no longer on its assigned branch. Restore its working copy before retrying the approved merge.');
+    }
+}
+/** Prepare only the card's working copy. The sandboxed agent resolves ordinary
+ * files; the product keeps ownership of the index, merge state, and base branch. */
+export function prepareCardReconciliation(card) {
+    try {
+        checkCardBranch(card);
+        if (gitOperationInProgress(card.folder)) {
+            if (!ownsReconciliation(card))
+                throw pathFree('Another Git operation is already in progress on this card. It was left untouched.');
+        }
+        else {
+            if (git(card.folder, ['status', '--porcelain']).length > 0) {
+                throw pathFree('The card has uncommitted changes. Preserve and verify them before retrying the approved merge with recover_landing(action="finish").');
+            }
+            try {
+                git(card.folder, ['merge', '--no-commit', '--no-ff', '-m', reconciliationMessage(card), `refs/heads/${card.base}`]);
+            }
+            catch (error) {
+                if (!ownsReconciliation(card))
+                    throw error;
+            }
+        }
+        const conflicts = git(card.folder, ['diff', '--name-only', '--diff-filter=U']);
+        return { conflicts: conflicts ? conflicts.split('\n').length : 0 };
+    }
+    catch (error) {
+        if (error?.pathFree)
+            throw error;
+        throw pathFree(`Could not prepare merge recovery on ${card.branch}. The work remains on its branch; retry recovery on this machine.`);
+    }
+}
+/** Called only after the owner reports verification under the active token. */
+export function finishCardReconciliation(card) {
+    try {
+        checkCardBranch(card);
+        if (!gitOperationInProgress(card.folder))
+            return;
+        if (!ownsReconciliation(card))
+            throw pathFree('Another Git operation is already in progress on this card. It was left untouched.');
+        // Stage resolved edits, including deletions. Refuse remaining conflict
+        // markers before committing, even though staging clears Git's U entries.
+        git(card.folder, ['add', '-A']);
         try {
-            git(holder, ['merge', '--abort']);
+            git(card.folder, ['diff', '--cached', '--check']);
+        }
+        catch {
+            throw pathFree('The resolution still contains conflict markers or whitespace errors. Fix the files, verify the result, and retry recover_landing(action="finish"). Nothing was merged onto the base.');
         }
-        catch { /* nothing to abort */ }
-        throw pathFree(`This card's work will not go back onto ${base} in ${codebaseName} cleanly. Nothing was `
-            + `merged, ${base} is where it was, and the work is still on ${branch}.`);
+        git(card.folder, ['commit', '--no-edit']);
+    }
+    catch (error) {
+        if (error?.pathFree)
+            throw error;
+        throw pathFree(`Could not finish merge recovery on ${card.branch}. The resolution is preserved; retry recovery on this machine.`);
     }
 }
 export function settleCardWorktree(folder) {
     // Completion is not permission to commit. Preserve unfinished Git work,
     // including staged and untracked files, for the person to review or resume.
-    if (git(folder, ['status', '--porcelain']).length > 0)
+    if (gitOperationInProgress(folder) || git(folder, ['status', '--porcelain']).length > 0)
         return false;
     // Only ignored build/dependency files can remain in a clean copy.
     removeWorktree(folder);

package/dist/panel3/prompt.js

@@ -380,6 +380,9 @@ const LANDING_LINES = {
         'The product writes the question and both answers, and it performs the merge itself if they',
         'choose to put the work back. Landing is the product\'s job and never yours: never merge and',
         'never push.',
+        'If that approved merge needs recovery, call recover_landing(action="prepare"). Resolve and verify',
+        'the files, write_report(work_complete=true), then recover_landing(action="finish"). Approval persists;',
+        'do not ask again or request broader Git permissions. The product handles the Git updates.',
     ],
     branch: [
         'Finished work in this codebase stays on its branch. Nothing is pushed and nothing is merged.',
@@ -862,7 +865,18 @@ export const landingOutcomeContext = (landing) => {
             ...head,
             `They chose to put this work back, and the product has merged ${landing.branch} onto `
                 + `${landing.base} on this machine. It is done and it is not yours to do.`,
-            'Say so plainly in your reply, name the branch it went onto, and finish the card.',
+            'Record completion with write_report(work_complete=true), then say so plainly in your reply, name the branch it went onto, and finish the card.',
+        ];
+    }
+    if (landing.outcome === 'reconciling') {
+        return [
+            ...head,
+            `The merge is already approved. Nothing has landed onto ${landing.base} yet.`,
+            `The product brought ${landing.base} into this card's branch ${landing.branch} for recovery; ${landing.conflicts} files are marked as conflicted.`,
+            'Resolve the files in your current working copy, preserve both the assignment and current base changes, and verify the combined result.',
+            'Use read-only Git commands to inspect it. The product owns Git metadata: do not stage, commit, merge or rebase yourself, and do not ask for wider filesystem access.',
+            'After verification, call write_report(work_complete=true), then recover_landing(action="finish"). If the base advances and new conflicts appear, resolve and verify again.',
+            'After a restart, recover_landing(action="prepare") resumes the same recovery without discarding your edits. Do not ask for the same merge approval again.',
         ];
     }
     if (landing.outcome === 'leave') {
@@ -883,13 +897,7 @@ export const landingOutcomeContext = (landing) => {
             'offer leaves it with them.',
         ];
     }
-    /* ═══ IT DOES NOT SAY "DO NOT FINISH THE CARD", BECAUSE THE AGENT CANNOT
-       OBEY THAT. ═══ The card reads done the moment the owner replies, by
-       `panel3_answer`, and nothing an agent writes changes it. Telling it
-       otherwise would be a rule that can only be broken. What it can do is say
-       plainly that the work did not go back and where it still is, which is what
-       the person needs; C3 replaces this relay with a question, and a question is
-       what keeps the card open. */
+    // A non-conflict refusal still needs a truthful outcome and a concrete next action.
     return [
         ...head,
         'They chose to put this work back and the product could not do it:',

package/dist/panel3/run.js

@@ -138,10 +138,10 @@ import { ASK_CONTENT_COLUMNS, attachmentLine, gitRulesFor, loadAttachments, load
 import { forgetSecrets, redactSecrets } from './secrets.js';
 import { sayListening, sayPollingProblem, stopListening } from './presence.js';
 import { selectedHarness } from './coordinator.js';
-import { baseBranchState, checkoutForCodebase, commitCardWork, detectBaseProtection, folderIsBranch, hasCheckoutForCodebase, mergeIntoBase, releaseBaseBranch, settleCardWorktree, worktreeForCard, worktreesOnThisMachine, } from './checkout.js';
+import { baseBranchState, checkoutForCodebase, commitCardWork, detectBaseProtection, folderIsBranch, hasCheckoutForCodebase, mergeIntoBase, releaseBaseBranch, settleCardWorktree, worktreeForCard, ownsReconciliation, prepareCardReconciliation, finishCardReconciliation, worktreesOnThisMachine, } from './checkout.js';
 import { harness, startAgent } from './spawn.js';
 import { establishOwnerSession, listOwnerSessionIds, OWNER_SESSION_GRACE_MS, readOwnerSession, removeOwnerSession, validSessionUuid, writeOwnerSession, } from './session.js';
-import { startToolsServer, PANEL3_IMAGES_BUCKET } from './tools.js';
+import { startToolsServer, processActivationIsCurrent, PANEL3_IMAGES_BUCKET } from './tools.js';
 import { listPanel3CodexOwnerHomeIds, removePanel3CodexOwnerHome, } from '../codex-home.js';
 import { getMachineIdentity, scratchDir } from '../config.js';
 import { listCodebases } from '../codebases.js';
@@ -242,19 +242,9 @@ export async function landingOffer(client, askId) {
         return 'unclear';
     return selected[0] === LAND ? 'land' : selected[0] === LEAVE ? 'leave' : 'unclear';
 }
-/**
- * ═══ THE PRODUCT PERFORMS THE LANDING, HERE, BEFORE THE AGENT THAT WILL SPEAK
- *     ABOUT IT STARTS. ═══
- *
- * Not a tool, because a tool means an agent decides whether a yes takes effect,
- * and an agent that finishes the card instead leaves a person who clicked yes
- * with nothing. Not the poll's sweep, because the sweep cannot tell the agent
- * what it did.
- *
- * ═══ AND A FAILURE DOES NOT END THE RUN. ═══ The agent has to be started to
- * tell the person, so what happened is returned as the sentence it will be
- * handed rather than written to `failed_because`.
- */
+/** The initial approved landing is automatic. Conflict recovery returns here
+ * after the owner resolves and verifies the files through recover_landing.
+ * Failures are reported to the agent so the card can continue truthfully. */
 export function landCardWork(where, outcome) {
     const card = where.card;
     if (outcome !== 'land')
@@ -270,22 +260,80 @@ export function landCardWork(where, outcome) {
         };
     }
     try {
-        /* THE COMMIT FIRST, AND ITS ABSENCE IS NOT A FAILURE. Between the answer and
-           this re-arm every run on the card has ended, so the sweep may already have
-           committed the copy and taken it away; `workingDirectory` has just rebuilt
-           it from the branch, and the only difference is that there is nothing left
-           to commit. */
+        if (ownsReconciliation(card)) {
+            return { outcome: 'reconciling', branch: card.branch, base: card.base, ...prepareCardReconciliation(card) };
+        }
+        // A repeated activation may recreate an already-committed working copy;
+        // in that case the commit helper has nothing left to do.
         commitCardWork(card.folder, `${card.codebaseName}'s copy of this card on branch ${card.branch}`);
         mergeIntoBase(card.source, card.branch, card.base, card.codebaseName);
         return { outcome: 'landed', branch: card.branch, base: card.base };
     }
     catch (error) {
+        if (error?.mergeConflicts) {
+            try {
+                return { outcome: 'reconciling', branch: card.branch, base: card.base, ...prepareCardReconciliation(card) };
+            }
+            catch (recoveryError) {
+                error = recoveryError;
+            }
+        }
         return {
             outcome: 'refused',
             because: error instanceof Error ? error.message : String(error),
         };
     }
 }
+/** Recovery uses the current owner's recorded approval, never model-supplied
+ * paths or refs. Recheck it before resolving a working copy or mutating Git. */
+export async function recoverLanding(client, machineId, runId, processToken, action) {
+    if (!await processActivationIsCurrent(client, runId, processToken)) {
+        throw new Error('This activation no longer owns the card. Nothing was merged.');
+    }
+    const runs = await returned(client.from('panel3_runs').select('card_id, machine_id, level, completion_requested_token')
+        .eq('id', runId).eq('process_token', processToken), 'read', 'the merge recovery owner');
+    const run = runs[0];
+    if (!run || run.level !== 2 || run.machine_id !== machineId) {
+        throw new Error('Merge recovery must run with this card’s conversation owner on its assigned machine. Nothing was merged.');
+    }
+    const offers = await returned(client.from('panel3_asks').select('id, run_id').eq('card_id', run.card_id)
+        .eq('offers_landing', true).order('created_at', { ascending: false }).limit(1), 'read', 'the latest merge approval');
+    const offer = offers[0];
+    if (!offer || offer.run_id !== runId || await landingOffer(client, offer.id) !== 'land') {
+        throw new Error('The latest ending choice does not approve a merge. Nothing was merged; use offer_ending after the work is verified.');
+    }
+    if (action === 'finish' && run.completion_requested_token !== processToken) {
+        throw new Error('Resolve and verify the work, then call write_report(work_complete=true) before finishing merge recovery.');
+    }
+    const activeWork = await returned(client.from('panel3_runs').select('id').eq('card_id', run.card_id).neq('id', runId)
+        .or('ended_at.is.null,pid.not.is.null'), 'read', 'other processes on this card');
+    if (activeWork.length > 0)
+        throw new Error('Wait for the other agents on this card to exit before recovering its merge. Nothing was merged.');
+    // Preparation or a failed retry is more work, not a completed assignment.
+    // Consume the completion marker so every new resolution must be verified.
+    let clearCompletion = client.from('panel3_runs')
+        .update({ completion_requested_token: null, completion_summary: null })
+        .eq('id', runId).eq('process_token', processToken).eq('state', 'running').is('ended_at', null);
+    if (action === 'finish')
+        clearCompletion = clearCompletion.eq('completion_requested_token', processToken);
+    const cleared = await returned(clearCompletion.select('id'), 'update', 'the merge recovery activation');
+    if (cleared.length !== 1 || !await processActivationIsCurrent(client, runId, processToken)) {
+        throw new Error('The card’s activation or verified work changed. Refresh the card, settle its work, and report verification again before retrying. Nothing was merged.');
+    }
+    const where = await workingDirectory(client, runId, 2, true);
+    const card = where.card;
+    if (!card || card.landing !== 'main') {
+        throw new Error('This card is not configured to merge onto its base branch. Nothing was merged.');
+    }
+    if (!await processActivationIsCurrent(client, runId, processToken)) {
+        throw new Error('This activation no longer owns the card. Nothing was merged.');
+    }
+    if (action === 'prepare') {
+        return { outcome: 'reconciling', branch: card.branch, base: card.base, ...prepareCardReconciliation(card) };
+    }
+    finishCardReconciliation(card);
+    return landCardWork(where, 'land');
+}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * ═══ NOTHING IN THIS FILE STAMPS A COLUMN FROM THIS MACHINE'S CLOCK ANY MORE,
@@ -3040,7 +3088,7 @@ export async function run(args, injected, signal, lifecycle) {
         const child = await startChild(current(), tools, machineId, parentRunId, brief, codebase, processToken, choice);
         hold(child.runId, child.settled);
         return { runId: child.runId };
-    });
+    }, (runId, processToken, action) => recoverLanding(current(), machineId, runId, processToken, action));
     out(`daemon   machine ${machineId}`);
     out(`tools    ${tools.urlFor('<run-id>')}`);
     out(once ? 'mode     one poll' : `mode     polling every ${POLL_INTERVAL_MS / 1000}s, Ctrl-C to stop`);

package/dist/panel3/tools.js

@@ -126,7 +126,7 @@ import { z } from 'zod';
 import { returned } from './client.js';
 import { readableWriteError, FIREWALL_WRITING_RULE } from '../firewall.js';
 import { rememberSecret, redactArgs } from './secrets.js';
-import { workBrief } from './prompt.js';
+import { workBrief, landingOutcomeContext } from './prompt.js';
 import { listCodexModels } from './codex-models.js';
 /* The harness this daemon spawns with, which is the process this server runs
    in. It is what `panel3_runs.harness` is written from at spawn, so reading it
@@ -2030,6 +2030,26 @@ const TOOLS = [
                 + 'Nobody will be asked again.';
         },
     },
+    {
+        name: 'recover_landing',
+        levels: [2],
+        description: 'Recover a merge the person already approved. The product manages Git metadata; you resolve '
+            + 'and verify ordinary files in this card’s working copy. Use prepare to bring the current base '
+            + 'into the card branch, including after a restart or a Git permission failure. Resolve conflicts '
+            + 'and run checks, record write_report(work_complete=true), then use finish to retry landing. '
+            + 'No new approval is needed. Never change the sandbox or ask the person to reopen with Git access. '
+            + 'After landing succeeds, record completion again and reply. If recovery fails, report the exact remaining action.',
+        input: { action: z.enum(['prepare', 'finish']) },
+        handler: async (caller, args) => {
+            if (!caller.isOwner || caller.level !== 2 || !caller.processToken) {
+                throw new Error('Only the current conversation owner can recover its approved merge.');
+            }
+            if (!caller.recoverLanding)
+                throw new Error('Merge recovery is unavailable on this companion. Update and restart the companion on this card’s machine, then retry in this card.');
+            const { action } = args;
+            return landingOutcomeContext(await caller.recoverLanding(caller.runId, caller.processToken, action)).join('\n');
+        },
+    },
     /**
      * ═══ THE AGENT ASKS FOR THE OFFER; THE PRODUCT WRITES IT. ═══
      *
@@ -2051,7 +2071,8 @@ const TOOLS = [
         levels: [2],
         description: 'Offer the person the ending for this card: put the finished work onto the main branch, or '
             + 'leave it on its branch. Call this when the card\'s work is DONE and the codebase lands on '
-            + 'the main branch. First record verified completion with write_report(work_complete=true). '
+            + 'the main branch. If the person already approved a merge that needs recovery, use recover_landing instead of asking again. '
+            + 'First record verified completion with write_report(work_complete=true). '
             + 'Use say for progress; this tool cannot announce work you intend to do. You do not write the question or the answers and you never merge anything: '
             + 'the product composes both, and it performs the merge itself if they choose to put the work '
             + 'back. Say in one sentence what was done, in their words. After this call, stop immediately: '
@@ -2824,7 +2845,7 @@ const TOOLS = [
                 await whileRunning(client.rpc('panel3_request_completion', {
                     p_run_id: runId, p_process_token: processToken, p_summary: report,
                 }), runId, 'declare completion of');
-                return 'Completion recorded. If the finished work needs an ending choice, call offer_ending; otherwise give your final answer and exit. Done waits until all processes have exited.';
+                return 'Completion recorded. If an already-approved merge is awaiting recovery, call recover_landing(action="finish"); if the finished work needs its first ending choice, call offer_ending; otherwise give your final answer and exit. Done waits until all processes have exited.';
             }
             await whileRunning(processToken === undefined
                 ? client.from('panel3_runs').update({ report }).eq('id', runId)
@@ -3341,6 +3362,8 @@ export function toolShape(name) {
 function toolAvailable(tool, level, isOwner) {
     if (isOwner && tool.name === 'escalate')
         return false;
+    if (tool.name === 'recover_landing' && !isOwner)
+        return false;
     return tool.levels.includes(level) || (level === 2 && isOwner && workflowToolForName(tool.name) !== undefined);
 }
 function toolNamed(name) {
@@ -3431,7 +3454,7 @@ export async function processActivationIsCurrent(client, runId, processToken) {
  * below goes through the signed-in user's own token, so guessing a run id would
  * still only ever reach that user's own record.
  */
-export async function startToolsServer(client, dispatch) {
+export async function startToolsServer(client, dispatch, recoverLanding) {
     const { data, error } = await client.auth.getUser();
     if (error)
         throw new Error(`could not start the tools server: ${error.message}`);
@@ -3550,7 +3573,7 @@ export async function startToolsServer(client, dispatch) {
         };
         const server = buildServer({
             client, userId, runId, cardId: run.card_id, level: run.level,
-            processToken, isOwner, dispatch,
+            processToken, isOwner, dispatch, recoverLanding,
         });
         await server.connect(transport);
         await transport.handleRequest(req, res, body);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.7.13",
+  "version": "0.7.14",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"