cawdev-cli 1.0.7-beta → 1.0.9-beta

package/README.md

@@ -5,4 +5,9 @@ and spawning processes are Node's home turf, and a file with no dependencies is
 one you can read before running it against your repositories.
 visit https://cawdev.com to learn more
 
-https://github.com/4dali/cawdev-cli
+https://github.com/4dali/cawdev-cli
+## jira/
+
+`jira/import.mjs` brings a Jira Cloud project's issues, epics, sprints and
+comments into a cawdev project, once and again without duplicates (R337). Run from a checkout; see
+"Leaving Jira" in GUIDE.md. Its tests: `node --test "tools/jira/*.test.mjs"`.

package/lib/finish-check.mjs

@@ -0,0 +1,178 @@
+// A finished run is committed and pushed — R345.
+//
+// R325's run ended FINISHED with a file modified and its branch never pushed,
+// and the next run in that checkout refused to start on top of it. Nothing
+// between a coding session's last turn and FINISHED looked at the checkout:
+// the merge run did (`finishMerge`), an ordinary CODE run did not, on either
+// door — the daemon's `finish` or the session's own `report done`.
+//
+// Two answers, one per door, both reading `leftOver`:
+//   - `report done` refuses while anything is left and says what, so the
+//     session — which knows what the files are — commits them in its own turn;
+//   - the daemon, when it is the one ending the run, `settleBranch`es: commits
+//     what is left and pushes, or reports why it could not, which the caller
+//     turns into FAILED with the checkout held (R80) instead of a FINISHED
+//     that strands the next run.
+//
+// No `--force`, ever, and nothing committed that looks like a credential: a
+// finish that pushes a key is worse than one that leaves a file behind.
+
+import { execFile } from 'node:child_process';
+import { findSecret } from './secrets.mjs';
+
+/** The profiles whose run is a branch somebody will build on. */
+export const COMMITS_ITS_WORK = new Set(['CODE']);
+
+/** How many paths a refusal or a summary names; the count still tells the truth. */
+const NAMED = 10;
+
+function runGit(cwd, args) {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (failure, stdout, stderr) => {
+      if (failure) {
+        failure.message = (stderr || failure.message).trim();
+        reject(failure);
+      } else {
+        resolve(stdout);
+      }
+    });
+  });
+}
+
+/**
+ * What a run left in its checkout that is not on the remote: uncommitted
+ * paths, and how many commits on `branch` no remote ref contains — the work a
+ * push would carry. Measured against EVERY remote ref, not `origin/<branch>`,
+ * so a branch the remote has never seen but whose commits are all on `main`
+ * (a run stopped at its plan gate) is not "unpushed work", and a checkout
+ * with no remote at all has nothing to push. `null` when the directory is not
+ * a git checkout we can read: nothing to judge is not a failure to judge.
+ */
+export async function leftOver(cwd, branch, { git = runGit } = {}) {
+  if (!cwd || !branch) return null;
+  let status;
+  try {
+    status = await git(cwd, ['status', '--porcelain', '--untracked-files=all']);
+  } catch {
+    return null;
+  }
+  const dirty = status.split('\n').map((line) => line.slice(3).trim()).filter(Boolean);
+  const current = (await git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']).catch(() => '')).trim();
+  const remote = (await git(cwd, ['remote']).catch(() => '')).split('\n')[0]?.trim() || null;
+  const exists = await git(cwd, ['rev-parse', '--verify', '-q', `refs/heads/${branch}`])
+    .then(() => true, () => false);
+  let ahead = 0;
+  if (remote && exists) {
+    const counted = await git(cwd, ['rev-list', '--count', branch, '--not', '--remotes'])
+      .catch(() => '0');
+    ahead = Number(counted.trim()) || 0;
+  }
+  return { dirty, ahead, remote, onBranch: current === branch, branch };
+}
+
+/** Whether anything is left — what both doors ask first. */
+export function isUnfinished(left) {
+  return Boolean(left) && (left.dirty.length > 0 || left.ahead > 0);
+}
+
+function named(paths) {
+  const shown = paths.slice(0, NAMED).map((path) => `\`${path}\``).join(', ');
+  return paths.length > NAMED ? `${shown} and ${paths.length - NAMED} more` : shown;
+}
+
+/**
+ * What `report done` says instead of finishing — to the session, which can fix
+ * it. Names the files and the commits, and says what "done" means here.
+ */
+export function notDoneYet(left) {
+  const what = [];
+  if (!left.onBranch && left.dirty.length) {
+    what.push(`the checkout is not on \`${left.branch}\``);
+  }
+  if (left.dirty.length) {
+    what.push(`${left.dirty.length} uncommitted file(s): ${named(left.dirty)}`);
+  }
+  if (left.ahead > 0) {
+    what.push(`${left.ahead} commit(s) on \`${left.branch}\` that ${left.remote} has not seen`);
+  }
+  return `Not finished yet — the run is still open. A finished run is committed and pushed, `
+    + `and this one has ${what.join('; ')}. Commit what belongs to this work on `
+    + `\`${left.branch}\` (discard what does not), \`git push\`, then report done again. If `
+    + 'something stops you, report blocked and say what.';
+}
+
+/**
+ * Commits what the session left and pushes the branch — the daemon's door.
+ *
+ * Returns `{ ok: true, note }` when the branch is clean and on the remote (the
+ * note says what was done on the session's behalf, or is null when nothing
+ * was), and `{ ok: false, reason }` otherwise, in words for the run's summary.
+ * Never forces; a remote that has moved is a reason, not something to win.
+ */
+export async function settleBranch(cwd, branch, { git = runGit, push, label = 'cawdev' } = {}) {
+  const left = await leftOver(cwd, branch, { git });
+  if (!left || !isUnfinished(left)) {
+    return { ok: true, note: null };
+  }
+  if (!left.onBranch && left.dirty.length) {
+    return {
+      ok: false,
+      reason: `The checkout is not on ${branch}, so the daemon did not commit or push anything `
+        + 'for it. The work is held in the checkout.',
+    };
+  }
+
+  let committed = [];
+  if (left.dirty.length) {
+    await git(cwd, ['add', '-A']);
+    const staged = await git(cwd, ['diff', '--cached']).catch(() => '');
+    const secret = findSecret(staged);
+    if (secret) {
+      await git(cwd, ['reset', '-q']).catch(() => null);
+      return {
+        ok: false,
+        reason: `The session left ${left.dirty.length} uncommitted file(s) (${named(left.dirty)}), `
+          + `and the change contains what looks like ${secret.name}, so the daemon did not `
+          + 'commit it. The work is held in the checkout: commit what belongs, or discard it.',
+      };
+    }
+    try {
+      await git(cwd, ['commit', '-q', '-m', `${label}: what the session left uncommitted`,
+        '-m', `Committed by the cawdev daemon as the run finished (R345): ${left.dirty.join(', ')}`]);
+      committed = left.dirty;
+    } catch (failure) {
+      await git(cwd, ['reset', '-q']).catch(() => null);
+      return {
+        ok: false,
+        reason: `The session left ${left.dirty.length} uncommitted file(s) (${named(left.dirty)}) and `
+          + `committing them failed: ${failure.message.split('\n')[0]}. The work is held in the checkout.`,
+      };
+    }
+  }
+
+  if (!left.remote) {
+    return {
+      ok: true,
+      note: committed.length
+        ? `The session left ${committed.length} file(s) uncommitted (${named(committed)}); the `
+          + 'daemon committed them. This checkout has no remote, so nothing was pushed.'
+        : null,
+    };
+  }
+  const pushed = await push(cwd, branch);
+  if (!pushed.ok) {
+    return {
+      ok: false,
+      reason: `${branch} could not be pushed: ${String(pushed.result).split('\n')[0]}`
+        + (committed.length ? ` (the daemon had committed ${named(committed)} first)` : '')
+        + '. The work is held in the checkout.',
+    };
+  }
+  return {
+    ok: true,
+    note: committed.length
+      ? `The session left ${committed.length} file(s) uncommitted (${named(committed)}); the `
+        + `daemon committed them and pushed ${branch}.`
+      : `The daemon pushed ${branch}, which the session had committed and not pushed.`,
+  };
+}

package/lib/roadmap-format.mjs

@@ -95,9 +95,9 @@ export function issueSectionOf(entry) {
  * Issues, rendered as their own file.
  *
  * Sorted by severity inside each section, critical first, because that IS the
- * question the file is read to answer. `renderRoadmap` sorts by number, which
- * on a roadmap is chronological and useful and here would bury a critical
- * defect behind six minor ones filed after it.
+ * question the file is read to answer. Within a severity the order is the one
+ * given — R335: the server's, which is the board's, a person's by dragging.
+ * `Array.prototype.sort` is stable, so a tie keeps it.
  */
 export function renderIssues(entries, { preamble }) {
   const rank = { CRITICAL: 0, MEDIUM: 1, MINOR: 2 };
@@ -108,8 +108,7 @@ export function renderIssues(entries, { preamble }) {
     bySection.get(section).push(entry);
   }
   for (const list of bySection.values()) {
-    list.sort((a, b) =>
-      (rank[a.severity] ?? 3) - (rank[b.severity] ?? 3) || a.number - b.number);
+    list.sort((a, b) => (rank[a.severity] ?? 3) - (rank[b.severity] ?? 3));
   }
 
   const ordered = [
@@ -225,6 +224,40 @@ export function parseRoadmap(text) {
         entry.severity = severity[1].trim();
         continue;
       }
+      const priority = /^Priority:\s*(.+)$/.exec(line.trim());
+      if (priority) {
+        entry.priority = priority[1].trim().toUpperCase();
+        if (!['HIGHEST', 'HIGH', 'MEDIUM', 'LOW', 'LOWEST'].includes(entry.priority)) {
+          problems.push(`${block.heading}: Priority "${priority[1].trim()}" is not one of highest, high, medium, low, lowest.`);
+        }
+        continue;
+      }
+      // R351. The date shape is checked here, where the line is read: a
+      // `Due:` that is not a date is a hand edit, and --live would otherwise
+      // report it as drift from a database that never held it.
+      const due = /^Due:\s*(.+)$/.exec(line.trim());
+      if (due) {
+        entry.due = due[1].trim();
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.due) || Number.isNaN(Date.parse(entry.due))) {
+          problems.push(`${block.heading}: Due "${due[1].trim()}" is not a date written 2026-11-01.`);
+        }
+        continue;
+      }
+      // R358. The version the card means to ship in; a free string, as `Version:` is.
+      const target = /^Target:\s*(.+)$/.exec(line.trim());
+      if (target) {
+        entry.targetVersion = target[1].trim();
+        continue;
+      }
+      const estimate = /^Estimate:\s*(.+)$/.exec(line.trim());
+      if (estimate) {
+        const n = Number(estimate[1].trim());
+        entry.estimate = n;
+        if (!Number.isInteger(n) || n <= 0) {
+          problems.push(`${block.heading}: Estimate "${estimate[1].trim()}" is not a positive whole number.`);
+        }
+        continue;
+      }
       const development = /^Development:\s*(.+)$/.exec(line.trim());
       if (development) {
         entry.development = statusFromDisplay(development[1].trim());
@@ -255,6 +288,16 @@ export function parseRoadmap(text) {
         entry.afterRefs = tokens.map(({ ref }) => ref);
         continue;
       }
+      const parent = /^Parent:\s*(\S+)\s*$/.exec(line.trim());
+      if (parent) {
+        // R336. One ref, always written in full (R300, i12). A token that is
+        // not a card is left as ordinary body text rather than eaten.
+        const token = parseRefToken(parent[1]);
+        if (token) {
+          entry.parentRef = token.ref;
+          continue;
+        }
+      }
       const tags = /^Tags:\s*(.+)$/.exec(line.trim());
       if (tags) {
         // R315. Already normalised by the server (lowercase, no `#`) by the
@@ -262,6 +305,13 @@ export function parseRoadmap(text) {
         entry.tags = tags[1].split(/[,\s]+/).map((t) => t.trim()).filter(Boolean);
         continue;
       }
+      const assignee = /^Assignee:\s*(\S+)$/.exec(line.trim());
+      if (assignee) {
+        // R331. A username only: the email is for a tooltip and never leaves
+        // the platform in a file.
+        entry.assignee = { username: assignee[1] };
+        continue;
+      }
       // R315. Computed, never stored, and never sent by import.mjs — the same
       // arrangement as `Development:` above. Kept as the exact text so a file
       // parsed and re-rendered without asking the API again is still a fixed
@@ -304,7 +354,8 @@ export function parseRoadmap(text) {
     entries.push(entry);
   }
 
-  entries.sort((left, right) => left.number - right.number);
+  // File order, not number order — R335: a section's order is a person's, and
+  // the importer's third pass sends it back to the server as written.
   return { entries, problems };
 }
 
@@ -341,6 +392,45 @@ function* splitBlocks(text) {
   if (entry) yield entry;
 }
 
+/** The ref of the card this one sits under, from either shape — R336. */
+function parentRefOf(entry) {
+  const ref = entry.parent?.ref ?? entry.parentRef;
+  return ref ? (parseRefToken(ref)?.ref ?? null) : null;
+}
+
+/**
+ * Files each child directly after its parent, within one section — R336.
+ *
+ * Pure. A child keeps its place among its siblings (they stay in the order
+ * given), and a child whose parent is in some other section stays exactly
+ * where it was: the file groups by section first, and an epic spread over
+ * phases is still one epic by its `Parent:` lines.
+ */
+export function nestUnderParents(list) {
+  const refs = new Map(list.map((entry) => [entryRef(entry), entry]));
+  const nestedUnder = (entry) => {
+    const parent = parentRefOf(entry);
+    const card = parent && refs.get(parent);
+    // A parent that is itself a child is bad data; leave the child where it is
+    // rather than lose it behind a card that is not a root.
+    return card && !parentRefOf(card) ? parent : null;
+  };
+  const children = new Map();
+  for (const entry of list) {
+    const parent = nestedUnder(entry);
+    if (parent) {
+      if (!children.has(parent)) children.set(parent, []);
+      children.get(parent).push(entry);
+    }
+  }
+  const out = [];
+  for (const entry of list) {
+    if (nestedUnder(entry)) continue;
+    out.push(entry, ...(children.get(entryRef(entry)) ?? []));
+  }
+  return out;
+}
+
 /**
  * Writes entries as ROADMAP.md's entry sections.
  *
@@ -350,7 +440,9 @@ function* splitBlocks(text) {
  */
 export function renderRoadmap(entries, { preamble, sectionOrder = [] }) {
   const bySection = new Map();
-  for (const entry of [...entries].sort((left, right) => left.number - right.number)) {
+  // In the order given, not sorted — R335: the server's order is the board's
+  // and the file's order is what an import rebuilds ranks from.
+  for (const entry of entries) {
     const section = sectionOf(entry);
     if (!bySection.has(section)) bySection.set(section, []);
     bySection.get(section).push(entry);
@@ -368,7 +460,7 @@ export function renderRoadmap(entries, { preamble, sectionOrder = [] }) {
   const parts = [preamble.trimEnd(), ''];
   for (const section of ordered) {
     parts.push('---', '', `## ${section}`, '');
-    for (const entry of bySection.get(section)) {
+    for (const entry of nestUnderParents(bySection.get(section))) {
       parts.push(renderEntry(entry), '');
     }
   }
@@ -420,6 +512,25 @@ function renderEntry(entry) {
     lines.push(`Severity: ${entry.severity}`);
   }
 
+  // R335. MEDIUM is the default and is not written, so a card nobody has
+  // prioritised reads as it did before the field existed.
+  if (entry.priority && entry.priority !== 'MEDIUM') {
+    lines.push(`Priority: ${entry.priority}`);
+  }
+
+  // R351. Two facts, written only when the card carries them, after the
+  // priority: when, then how big.
+  if (entry.due) {
+    lines.push(`Due: ${entry.due}`);
+  }
+  if (entry.estimate != null && entry.estimate > 0) {
+    lines.push(`Estimate: ${entry.estimate}`);
+  }
+  // R358. Where it means to ship; dropped once it has, because `Version:` then says.
+  if (entry.targetVersion && !entry.version) {
+    lines.push(`Target: ${entry.targetVersion}`);
+  }
+
   // Each status writes only what it currently claims. A MERGED entry keeps its
   // branch in the database as history, but the file must not print it: the
   // branch is expected to be deleted, and `--live` would then be reading a claim
@@ -469,10 +580,21 @@ function renderEntry(entry) {
       .map(({ ref }) => ref);
     lines.push(`After: ${written.join(', ')}`);
   }
+  {
+    // R336. The API gives `parent` as {number, ref, title}; the parser gives
+    // `parentRef`. Always the full ref, and no line at all without a parent, so
+    // no existing card's text changes.
+    const parent = parentRefOf(entry);
+    if (parent) lines.push(`Parent: ${parent}`);
+  }
   if (entry.tags?.length) {
     // R315. Sorted, so the export does not churn on the set's own order.
     lines.push(`Tags: ${[...entry.tags].sort().join(', ')}`);
   }
+  if (entry.assignee?.username) {
+    // R331. Nothing for a card with nobody, so today's files stay byte-identical.
+    lines.push(`Assignee: ${entry.assignee.username}`);
+  }
   const origin = originWord(entry.origin);
   if (origin) {
     lines.push(`Origin: ${origin}`);

package/mcp/README.md

@@ -163,7 +163,7 @@ what you are allowed to do.
 | `roadmap_list` | Entries, optionally by status. `brief` omits bodies — use it to survey. |
 | `roadmap_get` | One entry in full: its body, **the plan agreed for it**, and the discussion on it. |
 | `roadmap_create` | Create an entry; the platform allocates its permanent number. |
-| `roadmap_update` | Title, body, section, related ids, and the cards it starts coding after (`after` — R181). |
+| `roadmap_update` | Title, body, section, related ids, the cards it starts coding after (`after` — R181), when it is due and how big it is (`due` — R351: an ISO date, `""` clears; `estimate`: a positive number, `0` clears), the version it is meant for (`targetVersion` — R358, `""` clears; since R362 it must be one the project defined under Project settings → Versions, and any other name is refused), and who it is assigned to (`assignee` — R331: a username, `""` clears; `roadmap_list`/`issue_list` take `assignee` too, and `me` means the token's owner). |
 | `roadmap_comment` | Say something *beside* an entry rather than inside it. |
 | `roadmap_set_status` | Move an entry, carrying whatever the status requires. |
 | `roadmap_decline` | Decline with a reason. The only exit. |
@@ -183,7 +183,7 @@ token gets a refusal saying so.
 | Tool | What it does |
 |---|---|
 | `task_current` | The entry you are working on, its branch, everything already said and asked on this run, **and every earlier run on the same card**. **Call it first**, and again whenever you are unsure where you are. |
-| `report` | `progress` as often as useful; `done` when finished, naming the branch and any PR; `blocked` when a person must resolve something. `done` and `blocked` end the run. |
+| `report` | `progress` as often as useful; `done` when finished, naming the branch and any PR; `blocked` when a person must resolve something. `done` and `blocked` end the run; on a coding run `done` is refused until everything is committed and pushed (R345). |
 | `ask_user` | Ask the person who started the run, and wait. Blocks up to ten minutes, then hands back a `question_id`. |
 | `await_answer` | Resume waiting for a question `ask_user` handed back. |
 | `ask_group` | Ask a **round** — up to twelve questions that belong together, under one title. Blocks until every one of them has been answered, then hands back a `group_id`. |
@@ -216,6 +216,11 @@ answers — they can always write their own.
 After `report done` or `report blocked`, the run is over and your token has
 expired with it. There is nothing further to do.
 
+On a coding run, `report done` is **refused** while the checkout has
+uncommitted files or commits the remote has not seen (R345) — the answer names
+them. Commit what belongs to the work (discard what does not), `git push`, and
+report done again; `report blocked` if something stops you.
+
 ### When something you need is not allowed (R51)
 
 You will not usually notice this happening. When you call a tool no rule covers

package/mcp/server.mjs

@@ -22,6 +22,7 @@ import {
   withinCeiling,
 } from '../lib/tool-rules.mjs';
 import { findDestructive, withinScope } from '../lib/secrets.mjs';
+import { COMMITS_ITS_WORK, isUnfinished, leftOver, notDoneYet } from '../lib/finish-check.mjs';
 
 const NAME = 'cawdev';
 const VERSION = '0.1.0';
@@ -421,6 +422,12 @@ const TOOLS = [
             'DECLINED',
           ],
         },
+        assignee: {
+          type: 'string',
+          description:
+            'Only cards assigned to this person — a username, or "me" for the owner of this ' +
+            'token. An unknown username is refused.',
+        },
         brief: { type: 'boolean', description: 'Omit bodies. Default true.' },
       },
     },
@@ -432,6 +439,7 @@ const TOOLS = [
       // R257. The API refuses a number with no sprint behind it, naming the
       // sprints there are; that sentence is passed through as the tool error.
       if (args.sprint) query.set('sprint', String(args.sprint));
+      if (args.assignee) query.set('assignee', args.assignee);
       query.set('brief', String(brief));
 
       const entries = await api(config, `/api/projects/${slug}/roadmap?${query}`);
@@ -672,6 +680,38 @@ const TOOLS = [
             'Free words — lowercase, letters/digits/./_/-, up to 32 characters, at least one ' +
             'letter, at most 12. The leading # is optional and stripped.',
         },
+        assignee: {
+          type: 'string',
+          description:
+            'A username — the person responsible for the card. Leave out for nobody. Refused, naming the ' +
+            'person, unless they hold WRITER or more on the project and are not disabled.',
+        },
+        priority: {
+          type: 'string',
+          enum: ['HIGHEST', 'HIGH', 'MEDIUM', 'LOW', 'LOWEST'],
+          description:
+            'How much it matters; it does not reorder the board. Leave out for MEDIUM.',
+        },
+        due: {
+          type: 'string',
+          description: 'When it is due, written 2026-11-01. A fact on the card; it moves nothing. Leave out for none.',
+        },
+        estimate: {
+          type: 'integer',
+          minimum: 1,
+          description: "How big it is, in the team's own unit (points, days — the platform does not say). Leave out for none.",
+        },
+        targetVersion: {
+          type: 'string',
+          description: 'The version it is meant to ship in — one the project DEFINED under Project settings → Versions (R362); any other name is refused. The release corrects it if it lands elsewhere. Leave out for none.',
+        },
+        parent: {
+          type: 'string',
+          description:
+            'The card this one sits under (an epic), e.g. "R300". One level only: the parent ' +
+            'must be the same kind and have no parent itself, and this card must have no ' +
+            'children. An open card cannot be filed under a SHIPPED or DECLINED one.',
+        },
       },
       required: ['title'],
     },
@@ -681,7 +721,7 @@ const TOOLS = [
         method: 'POST',
         body: pick(args, [
           'title', 'body', 'status', 'branch', 'merge', 'version', 'reason', 'section', 'related',
-          'after', 'sprint', 'tags',
+          'after', 'sprint', 'tags', 'assignee', 'priority', 'due', 'estimate', 'targetVersion', 'parent',
         ]),
       });
       return `Created ${refOf(entry)} in ${slug}.\n\n${formatEntry(entry, {})}`;
@@ -703,6 +743,10 @@ const TOOLS = [
           type: 'string',
           enum: ['NEW', 'CONFIRMED', 'IN_DEVELOPMENT', 'MERGED', 'SHIPPED', 'DECLINED'],
         },
+        assignee: {
+          type: 'string',
+          description: 'Only issues assigned to this person — a username, or "me".',
+        },
         brief: { type: 'boolean', description: 'Drop the bodies.' },
       },
     },
@@ -711,6 +755,7 @@ const TOOLS = [
       const query = new URLSearchParams();
       if (args.status) query.set('status', args.status);
       if (args.brief) query.set('brief', 'true');
+      if (args.assignee) query.set('assignee', args.assignee);
       const suffix = query.toString() ? `?${query}` : '';
       const issues = await api(config, `/api/projects/${slug}/issues${suffix}`);
       if (!issues.length) {
@@ -748,6 +793,18 @@ const TOOLS = [
             'Free words — lowercase, letters/digits/./_/-, up to 32 characters, at least one ' +
             'letter, at most 12. The leading # is optional and stripped.',
         },
+        assignee: {
+          type: 'string',
+          description:
+            'A username — the person responsible for the card. Leave out for nobody. Refused, naming the ' +
+            'person, unless they hold WRITER or more on the project and are not disabled.',
+        },
+        priority: {
+          type: 'string',
+          enum: ['HIGHEST', 'HIGH', 'MEDIUM', 'LOW', 'LOWEST'],
+          description:
+            'How much it matters; it does not reorder the board. Leave out for MEDIUM.',
+        },
       },
       required: ['title', 'severity'],
     },
@@ -755,7 +812,7 @@ const TOOLS = [
       const slug = await resolveProject(config, args.project);
       const issue = await api(config, `/api/projects/${slug}/issues`, {
         method: 'POST',
-        body: pick(args, ['title', 'body', 'severity', 'status', 'related', 'tags']),
+        body: pick(args, ['title', 'body', 'severity', 'status', 'related', 'tags', 'assignee', 'priority']),
       });
       return `Filed ${refOf(issue)} in ${slug}.\n\n${formatEntry(issue, {})}`;
     },
@@ -793,8 +850,8 @@ const TOOLS = [
   {
     name: 'roadmap_update',
     description:
-      'Edit an entry\'s title, body, section, sprint, tags, related refs or the cards it starts ' +
-      'after. Use roadmap_set_status to move it.',
+      'Edit an entry\'s title, body, section, sprint, tags, parent, related refs or the cards it ' +
+      'starts after. Use roadmap_set_status to move it.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -833,6 +890,37 @@ const TOOLS = [
           description:
             'Free words — same rule as roadmap_create. Leave out to leave them alone; [] clears them.',
         },
+        assignee: {
+          type: 'string',
+          description:
+            'A username — the person responsible for the card. Leave out to leave it alone; "" takes the card off them. Refused, naming the ' +
+            'person, unless they hold WRITER or more on the project and are not disabled.',
+        },
+        priority: {
+          type: 'string',
+          enum: ['HIGHEST', 'HIGH', 'MEDIUM', 'LOW', 'LOWEST'],
+          description:
+            'How much it matters; it does not reorder the board. Leave out for MEDIUM (leave out to leave it alone).',
+        },
+        due: {
+          type: 'string',
+          description: 'When it is due, written 2026-11-01. Leave out to leave it alone; "" clears it.',
+        },
+        estimate: {
+          type: 'integer',
+          minimum: 0,
+          description: "How big it is, in the team's own unit. Leave out to leave it alone; 0 clears it.",
+        },
+        targetVersion: {
+          type: 'string',
+          description: 'The version it is meant to ship in — one the project defined (R362); any other name is refused. Leave out to leave it alone; "" clears it.',
+        },
+        parent: {
+          type: 'string',
+          description:
+            'The card this one sits under (an epic), e.g. "R300". "" takes the card out of its ' +
+            'parent; leave out to leave it alone. Same rules as roadmap_create.',
+        },
       },
       required: ['number'],
     },
@@ -841,7 +929,10 @@ const TOOLS = [
       const entry = await api(config, `/api/projects/${slug}/roadmap/${args.number}`, {
         method: 'PATCH',
         // pick keeps a present 0, which is how a card leaves its sprint.
-        body: pick(args, ['title', 'body', 'section', 'related', 'after', 'sprint', 'tags']),
+        body: pick(args, [
+          'title', 'body', 'section', 'related', 'after', 'sprint', 'tags', 'assignee', 'priority',
+          'due', 'estimate', 'targetVersion', 'parent',
+        ]),
       });
       return `Updated ${refOf(entry)}.\n\n${formatEntry(entry, {})}`;
     },
@@ -1105,8 +1196,22 @@ const TOOLS = [
         `run:     ${run.state}${run.runnerName ? ` on ${run.runnerName}` : ''}`,
         `started by ${run.startedByEmail}`,
         '',
-        formatEntry(entry, { comments, plan: plans?.[0] ?? null }),
       );
+      // R336. The epic this card was cut from, so a session sees the context.
+      // Its own try, like the history above: a parent that cannot be read (a
+      // 404, no grant) costs the paragraph and never the call.
+      if (entry.parent) {
+        const epic = await api(config, `/api/projects/${project}/roadmap/${entry.parent.ref}`)
+          .catch(() => null);
+        if (epic) {
+          lines.push(
+            `This card is part of ${entry.parent.ref} — ${epic.title}:`,
+            epicExcerpt(epic.body),
+            '',
+          );
+        }
+      }
+      lines.push(formatEntry(entry, { comments, plan: plans?.[0] ?? null }));
 
       // What happened the other times. A session is told the entry and the
       // branch but not that two previous runs on this card failed, which is
@@ -1181,7 +1286,9 @@ const TOOLS = [
     description:
       'Say what is happening. `progress` as often as useful; `done` when the work is finished, ' +
       'naming the branch and any PR; `blocked` when something stops you that a person must ' +
-      'resolve. done and blocked also end the run — you do not need a separate step.',
+      'resolve. done and blocked also end the run — you do not need a separate step. On a ' +
+      'coding run, done is refused while the checkout has uncommitted files or unpushed ' +
+      'commits: commit and push first.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1192,6 +1299,21 @@ const TOOLS = [
     },
     handler: async (config, args) => {
       const { runId, project } = await requireRun(config);
+
+      // R345: a finished run is committed and pushed. Asked HERE, before the
+      // message is posted, because this is the one moment the session that
+      // made the files is still there to say what they are — the daemon's own
+      // check at the end can only commit them blind or hold them.
+      if (args.kind === 'done') {
+        const run = await api(config, `/api/projects/${project}/runs/${runId}`).catch(() => null);
+        if (run && run.branch && COMMITS_ITS_WORK.has(run.profile)) {
+          const left = await leftOver(process.env.CAWDEV_WORKSPACE ?? process.cwd(), run.branch);
+          if (isUnfinished(left)) {
+            return notDoneYet(left);
+          }
+        }
+      }
+
       const message = await api(config, `/api/projects/${project}/runs/${runId}/messages`, {
         method: 'POST',
         body: { kind: args.kind.toUpperCase(), body: args.body },
@@ -2107,6 +2229,15 @@ function originWord(origin) {
   }
 }
 
+/** The first 600 characters of an epic's body, cut at a word — R336. */
+function epicExcerpt(body) {
+  const text = (body ?? '').trim();
+  if (text.length <= 600) return text;
+  const cut = text.slice(0, 600);
+  const space = cut.lastIndexOf(' ');
+  return `${(space > 0 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
 function formatEntry(entry, { brief, comments, plan }) {
   const lines = [`${refOf(entry)} — ${entry.title}`, `  status: ${entry.statusDisplay}`];
   if (entry.branch) lines.push(`  branch: ${entry.branch}`);
@@ -2117,6 +2248,17 @@ function formatEntry(entry, { brief, comments, plan }) {
   // R315. Sorted for the same reason the export is: a reader's shape must not
   // depend on the set's own insertion order.
   if (entry.tags?.length) lines.push(`  tags: ${[...entry.tags].sort().map((t) => `#${t}`).join(' ')}`);
+  // R331. A username, never the email.
+  if (entry.assignee) lines.push(`  assignee: ${entry.assignee.username}`);
+  // R335. Not printed at MEDIUM, as the export does not write it.
+  if (entry.priority && entry.priority !== 'MEDIUM') {
+    lines.push(`  priority: ${entry.priority}`);
+  }
+  // R351. Both printed only when the card carries them, as the export does.
+  if (entry.due) lines.push(`  due: ${entry.due}`);
+  if (entry.estimate) lines.push(`  estimate: ${entry.estimate}`);
+  // R358. Printed until the card ships; `version` says where it did.
+  if (entry.targetVersion && !entry.version) lines.push(`  target: ${entry.targetVersion}`);
   // R257. Always printed when the card has one, so a reader's shape does not
   // depend on which tool printed the card; a closed sprint says so.
   if (entry.sprint) {
@@ -2142,6 +2284,14 @@ function formatEntry(entry, { brief, comments, plan }) {
         .join(', ')}`,
     );
   }
+  // R336. The epic this card sits under, and the cards under this one.
+  if (entry.parent) lines.push(`  parent: ${entry.parent.ref} — ${entry.parent.title}`);
+  if (entry.children?.length) {
+    const progress = entry.progress ? `${entry.progress.done} of ${entry.progress.total} done — ` : '';
+    lines.push(
+      `  children: ${progress}${entry.children.map((c) => `${c.ref} (${c.status})`).join(', ')}`,
+    );
+  }
   // Said in a survey, where the comments themselves are not fetched: an entry
   // with an argument attached should be visibly different from one without,
   // even in a list. Omitted at zero rather than written as "comments: 0".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cawdev-cli",
-  "version": "1.0.7-beta",
+  "version": "1.0.9-beta",
   "description": "cawdev's terminal client and runner daemon — zero dependencies, on purpose",
   "type": "module",
   "bin": {

package/runner/README.md

@@ -131,7 +131,7 @@ is for scripts and for a machine with no daemon to attach to:
 
 ```
 cawdev config                          a menu, the same Select widget as everywhere else
-cawdev config add-project              serve one more project you can write to
+cawdev config add-project              serve one more project you can write to, or create one
 cawdev config add-workspace            another checkout for a project already served
 cawdev config remove-project <slug>    stop serving a project; its checkouts stay on disk
 cawdev config agent enable|disable <claude|agy|codex>
@@ -146,6 +146,18 @@ travels beside the secret since this card, and a machine set up before it
 falls back to a lookup by label the first time this runs, after which it
 remembers.
 
+**Add a project lists what you can serve, and ends with "Create a new project on
+cawdev".** The list is shown even when one project is left — the screen names
+what it is about to clone. Creating asks for a name (the slug is cawdev's,
+`<username>-<name>`, and is shown before anything is made), the git URL — blank
+when the checkout is already on this machine, whose `origin` is then the
+repository — and where the checkout goes. The clone happens first and the
+project is created on cawdev (`POST /api/projects`) only after one last
+confirmation, so a clone that fails leaves nothing on the platform. Then it is
+served like any added project, and the rest of the console's setup walk —
+rules, members, the CTO Interview — is linked at
+`<url>/projects/<slug>/setup`.
+
 **What takes effect when** (R294). Three settings a running daemon takes
 without a restart — `agentCommands`, `grantable`, `acceptsRulesFromConsole`,
 the `HOT_SWAPPABLE` list in `tools/lib/runner-config.mjs`, spelled once —
@@ -1098,6 +1110,27 @@ settled TEST stage to scan after. The log line is
 `quality: <branch> gate OK · 0 new problems`, or `quality: could not scan
 <branch>: <why>`.
 
+## A finished run is committed and pushed (R345)
+
+Whatever the project's rules say, a coding run (`CODE`) reaches `FINISHED`
+only with a clean checkout and its branch's commits on the remote. Two doors,
+one check (`tools/lib/finish-check.mjs`):
+
+- **`report done` refuses** while anything is left and tells the session what —
+  the uncommitted files by name, the commits the remote has not seen — so the
+  session that made them commits what belongs and pushes, in its own turn.
+- **When the daemon ends the run** (the lifecycle's last stage, or a session
+  that exited without reporting) it settles the branch itself: commits what is
+  left as `<card>: what the session left uncommitted`, pushes without force,
+  and says so in the summary. It does **not** commit anything that looks like a
+  credential, and it does not win a push the remote refuses — either is a
+  `FAILED` run with the reason in its summary and the checkout held, so
+  *Carry on*, *Commit* or *Discard* decide, not the next run.
+
+Before this, R325's run finished with a file modified and nothing pushed, and
+the next run in that checkout refused to start on top of it. A checkout with no
+remote commits what is left and asks nothing of a push.
+
 ## What a project's rules can ask of it (R40)
 
 A project may decide that a finished run **pushes its branch**, **opens a pull

package/runner/attach.mjs

@@ -765,7 +765,7 @@ export function configMenu(file, runner = {}, gone = new Set()) {
     kind: 'config',
     title: `this machine — ${runner.name ?? file.name ?? 'cawdev'}`,
     rows: [
-      { id: 'add-project', label: 'Add a project', hint: `${serving}${pending}` },
+      { id: 'add-project', label: 'Add a project — or create one on cawdev', hint: `${serving}${pending}` },
       { id: 'add-workspace', label: 'Add a workspace to a project', hint: checkouts || 'no projects to add one to' },
       ...[...new Set([...KNOWN_AGENTS, ...agents])].map((command) => (agents.includes(command)
         ? { id: `agent:${command}`, label: `Disable ${command}`, hint: 'spawned here now' }
@@ -2632,7 +2632,7 @@ export class Attached {
    * comes back absolute; configure.mjs inspects it again before acting.
    */
   async askPath({ question, suggestions, slug, gitUrl, inspect = inspectPath }) {
-    this.say(`  ${this.ink.text(question)}`);
+    // The question is the picker's title; printing it as well put it on screen twice.
     const rows = [];
     for (const each of suggestions) {
       const seen = await inspect(each.path, { gitUrl });

package/runner/cawdev.mjs

@@ -60,7 +60,7 @@ const USAGE = `
 
   cawdev config                          a menu: add a project, add a
                                           workspace, agents, console rules
-  cawdev config add-project              serve one more project you can write to
+  cawdev config add-project              serve one more project you can write to, or create one
   cawdev config add-workspace            another checkout for a project you
                                           already serve — R47's concurrency
   cawdev config remove-project <slug>    stop serving a project (its checkouts
@@ -464,7 +464,7 @@ export async function pickAction(ask, say, pick = askOne) {
   const picked = await pick(ask, say, new Select({
     title: 'What do you want to change on this machine?',
     rows: [
-      { id: 'add-project', label: 'Add a project' },
+      { id: 'add-project', label: 'Add a project — or create one on cawdev' },
       { id: 'add-workspace', label: 'Add a workspace to a project' },
       { id: 'remove-project', label: 'Stop serving a project' },
       { id: 'agent-enable', label: `Enable an agent (${KNOWN_AGENTS.join(' / ')})` },

package/runner/configure.mjs

@@ -181,13 +181,22 @@ async function settleCheckout({ path, slug, gitUrl, ask, say, ink, clone, inspec
   await cloneAside(ask, clone, gitUrl, path);
 }
 
+/** The row of Add a project that makes a new project rather than picking one. */
+export const CREATE_A_PROJECT = 'create:new';
+
 /**
- * Add one project this session can serve to an already-configured machine.
+ * Add one project this session can serve to an already-configured machine —
+ * or CREATE one on cawdev and serve it, from the same list.
  *
  * Clones it, then widens the existing token's grants to cover it — via
  * {@link resolveTokenId}, or by minting a fresh token when that comes back
  * empty (an older machine's first run through this command, which is also
  * what teaches it the id for next time).
+ *
+ * The list is ALWAYS shown, one project or six: going straight to "where
+ * should cawdev live?" when one was left answered a question nobody had been
+ * asked, about a project the screen never named. Its last row is "Create a
+ * new project on cawdev", see {@link askForANewProject}.
  */
 export async function addProject({
   configPath, file, url, session: given = null,
@@ -206,30 +215,37 @@ export async function addProject({
   const already = new Set(slugsOf(file));
   const projects = servable(await session.request('/api/projects'))
     .filter((project) => !already.has(project.slug));
-  if (!projects.length) {
-    throw new Error('Every project you can serve is already configured on this machine.');
-  }
 
-  let project = projects[0];
-  if (projects.length > 1) {
-    const picked = await pick(ask, say, new Select({
-      title: 'Which project should this machine also serve?',
-      rows: projects.map((candidate) => ({
+  const picked = await pick(ask, say, new Select({
+    title: projects.length
+      ? 'Which project should this machine also serve?'
+      : 'Every project you can serve is already here — create a new one?',
+    rows: [
+      ...projects.map((candidate) => ({
         id: candidate.slug, label: candidate.name, hint: candidate.slug,
       })),
+      { id: CREATE_A_PROJECT, label: 'Create a new project on cawdev', hint: `on ${url} — a name and its git repository` },
+    ],
+  }));
+
+  let project;
+  let path;
+  if (picked.row.id === CREATE_A_PROJECT) {
+    ({ project, path } = await askForANewProject({
+      file, url, session, ask, say, ink, pick, askPath, inspect, clone,
     }));
+  } else {
     project = projects.find((candidate) => candidate.slug === picked.row.id);
+    path = await askPath({
+      ask, say, pick, inspect,
+      question: `Where should ${project.slug} live on this machine?`,
+      suggestions: suggestProjectPaths(file, project.slug),
+      slug: project.slug,
+      gitUrl: project.gitUrl ?? null,
+    });
+    await settleCheckout({ path, slug: project.slug, gitUrl: project.gitUrl ?? null, ask, say, ink, clone, inspect });
   }
 
-  const path = await askPath({
-    ask, say, pick, inspect,
-    question: `Where should ${project.slug} live on this machine?`,
-    suggestions: suggestProjectPaths(file, project.slug),
-    slug: project.slug,
-    gitUrl: project.gitUrl ?? null,
-  });
-  await settleCheckout({ path, slug: project.slug, gitUrl: project.gitUrl ?? null, ask, say, ink, clone, inspect });
-
   const grants = {};
   for (const slug of [...already, project.slug]) {
     grants[slug] = ['runner:operate'];
@@ -250,9 +266,71 @@ export async function addProject({
 
   await write(configPath, next);
   say(`  ${ink.success('✓')} ${ink.muted('Now serving')} ${ink.text(project.slug)} ${ink.muted('at')} ${ink.accent(path)}`);
+  if (project.created) {
+    // The rest of the console's setup walk — rules, members, the brief — is
+    // decisions about the project, not about this machine, and lives there.
+    say(`  ${ink.muted('The rest of its setup (rules, members, the CTO Interview):')} ${ink.accent(`${url}/projects/${project.slug}/setup`)}`);
+  }
   return next;
 }
 
+/**
+ * "Create a new project on cawdev": a name, the repository, the checkout —
+ * and only then the project, so a clone that fails leaves nothing on the
+ * platform. The slug is the SERVER's (R290, `<username>-<name>`); it is shown
+ * before anything is made and the answer to the POST is what is used.
+ *
+ * An empty git URL is allowed when the path is already a checkout: its
+ * `origin` is the repository, which is the commonest case — somebody with the
+ * code on their disk who wants cawdev to know about it.
+ */
+async function askForANewProject({ file, url, session, ask, say, ink, pick, askPath, inspect, clone }) {
+  const name = String(await ask.line('  Name of the new project ')).trim();
+  if (!name) {
+    throw new Error('A project needs a name. Nothing changed.');
+  }
+  const suggested = await session.request(`/api/projects/slug-suggestion?name=${encodeURIComponent(name)}`)
+    .then((answer) => answer?.slug)
+    .catch(() => null);
+  const slug = suggested || name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'project';
+  say(`  ${ink.muted('It will be')} ${ink.text(slug)} ${ink.muted('on')} ${ink.accent(url)}`);
+
+  const typedUrl = String(await ask.line(
+    '  Its git repository URL — blank if the checkout is already on this machine ',
+  )).trim();
+  const path = await askPath({
+    ask, say, pick, inspect,
+    question: `Where should ${slug} live on this machine?`,
+    suggestions: suggestProjectPaths(file, slug),
+    slug,
+    gitUrl: typedUrl || null,
+  });
+
+  let gitUrl = typedUrl || null;
+  if (!gitUrl) {
+    const seen = await inspect(path, { gitUrl: null });
+    if (seen.kind !== 'checkout' || !seen.remote) {
+      throw new Error(`${path} is ${describe(seen, slug)} — with no git URL, the path must be a checkout `
+        + 'with an origin. Nothing changed.');
+    }
+    gitUrl = seen.remote;
+    say(`  ${ink.muted('Its repository, from that checkout\'s origin:')} ${ink.accent(gitUrl)}`);
+  }
+  await settleCheckout({ path, slug, gitUrl, ask, say, ink, clone, inspect });
+
+  if (!await confirm(ask, `Create ${name} on ${url}`)) {
+    throw new Error(`Nothing created on cawdev; the checkout at ${path} stays.`);
+  }
+  let created;
+  try {
+    created = await session.request('/api/projects', { method: 'POST', body: { name, gitUrl } });
+  } catch (failure) {
+    throw new Error(`cawdev refused to create ${name}: ${failure.message}. The checkout at ${path} stays.`);
+  }
+  say(`  ${ink.success('✓')} ${ink.muted('Created')} ${ink.text(created.name ?? name)} ${ink.muted('as')} ${ink.text(created.slug)}`);
+  return { project: { ...created, created: true }, path };
+}
+
 /** Add another checkout for a project this machine already serves — R47. */
 export async function addWorkspace({
   configPath, file,

package/runner/runner.mjs

@@ -52,6 +52,7 @@ import {
   drivingPath, isAlive, killedByRestart, leftBehind, memoryMaxOf, probeScope, readDriving,
   restartSummary, scoped, snapshotOf, writeDriving,
 } from './restart.mjs';
+import { COMMITS_ITS_WORK, settleBranch } from '../lib/finish-check.mjs';
 
 // --- configuration -----------------------------------------------------------
 
@@ -6771,7 +6772,7 @@ async function walkLifecycle(config, run, runToken, cwd, baseCommit, workspace,
         const why = `Stopped at the ${stage.stage} gate: ${decision.reason}. Nothing was `
           + 'refused — start the run again when somebody can read it.';
         await skipRest(config, run, lifecycle, at + 1, why);
-        await finish(config, run, 'FINISHED', why);
+        await finish(config, run, 'FINISHED', why, cwd);
         return;
       }
       if (attempt === 1) {
@@ -6780,7 +6781,7 @@ async function walkLifecycle(config, run, runToken, cwd, baseCommit, workspace,
         // stages after it, and stages left PENDING on a run that is over read
         // as a lifecycle still going.
         await skipRest(config, run, lifecycle, at + 1, why);
-        await finish(config, run, 'FINISHED', why);
+        await finish(config, run, 'FINISHED', why, cwd);
         return;
       }
       // Refused once: the reason is the point of refusing, so it goes into the
@@ -6817,7 +6818,7 @@ async function walkLifecycle(config, run, runToken, cwd, baseCommit, workspace,
   const current = await api(config, `/api/projects/${run.projectSlug}/runs/${run.id}`)
     .catch(() => null);
   if (current?.live) {
-    await finish(config, run, 'FINISHED', last?.text ?? 'The lifecycle finished.');
+    await finish(config, run, 'FINISHED', last?.text ?? 'The lifecycle finished.', cwd);
   }
   await settleActions(config, run, cwd);
 }
@@ -7968,7 +7969,7 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
           const summary = signal
             ? `The agent was terminated (${signal}).`
             : `The agent exited with code ${code} without reporting. ${lastText}`.trim();
-          await finish(config, run, code === 0 ? 'FINISHED' : 'FAILED', summary);
+          await finish(config, run, code === 0 ? 'FINISHED' : 'FAILED', summary, cwd);
         }
         // R112. A STAGE ending is not the RUN ending. The loop decides that —
         // it is the only thing that knows whether there is another stage — and
@@ -8613,7 +8614,7 @@ async function spawnAntigravity(config, run, runToken, cwd, baseCommit, resume,
         .catch(() => null);
       if (current?.live && !stage) {
         await finish(config, run, code === 0 && result?.status === 'SUCCESS' ? 'FINISHED' : 'FAILED',
-          text);
+          text, cwd);
       }
       // R112: not between stages — see the same line on the Claude Code path.
       if (!stage) {
@@ -8917,7 +8918,7 @@ async function spawnCodex(config, run, runToken, cwd, baseCommit, resume, projec
       const current = await api(config, `/api/projects/${run.projectSlug}/runs/${run.id}`)
         .catch(() => null);
       if (current?.live && !stage) {
-        await finish(config, run, code === 0 && ended && !failed ? 'FINISHED' : 'FAILED', text);
+        await finish(config, run, code === 0 && ended && !failed ? 'FINISHED' : 'FAILED', text, cwd);
       }
       // R112: not between stages — see the same line on the Claude Code path.
       if (!stage) {
@@ -8976,7 +8977,32 @@ function reportStageUsage(config, run, stageName, totals) {
     log(`  could not record what the ${stageName} stage used: ${failure.message}`));
 }
 
-async function finish(config, run, state, summary) {
+/**
+ * Ends a run on the platform.
+ *
+ * R345: a coding run reaches FINISHED only committed and pushed. Given the
+ * checkout, a FINISHED for a profile that commits its work settles the branch
+ * first — commits what the session left (unless it looks like a credential),
+ * pushes without force — and becomes FAILED, with the reason in the summary
+ * and the checkout held for Carry on (R80), when that cannot be done. Before
+ * this, R325's run finished with a file modified and nothing pushed, and the
+ * next run in that checkout refused to start on top of it.
+ */
+async function finish(config, run, state, summary, cwd = null) {
+  if (state === 'FINISHED' && cwd && run.branch && COMMITS_ITS_WORK.has(run.profile)) {
+    const settled = await settleBranch(cwd, run.branch, {
+      push: pushBranch,
+      label: run.entryRef ?? 'cawdev',
+    }).catch((failure) => ({ ok: false, reason: `Checking the branch failed: ${failure.message}` }));
+    if (!settled.ok) {
+      log(`  not finished: ${settled.reason}`);
+      state = 'FAILED';
+      summary = `${settled.reason}\n\n${summary ?? ''}`.trim();
+    } else if (settled.note) {
+      log(`  ${settled.note}`);
+      summary = `${summary ?? ''}\n\n${settled.note}`.trim();
+    }
+  }
   await api(config, `/api/projects/${run.projectSlug}/runs/${run.id}/transition`, {
     method: 'POST',
     body: { state, summary },