cawdev-cli 1.0.6-beta → 1.0.8-beta

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,14 @@ 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;
+      }
       const development = /^Development:\s*(.+)$/.exec(line.trim());
       if (development) {
         entry.development = statusFromDisplay(development[1].trim());
@@ -262,6 +269,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 +318,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 };
 }
 
@@ -350,7 +365,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);
@@ -420,6 +437,12 @@ 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}`);
+  }
+
   // 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
@@ -473,6 +496,10 @@ function renderEntry(entry) {
     // 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), 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,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'],
     },
@@ -681,7 +701,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',
         ]),
       });
       return `Created ${refOf(entry)} in ${slug}.\n\n${formatEntry(entry, {})}`;
@@ -703,6 +723,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 +735,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 +773,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 +792,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, {})}`;
     },
@@ -833,6 +870,18 @@ 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).',
+        },
       },
       required: ['number'],
     },
@@ -841,7 +890,7 @@ 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']),
       });
       return `Updated ${refOf(entry)}.\n\n${formatEntry(entry, {})}`;
     },
@@ -1181,7 +1230,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 +1243,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 },
@@ -1651,9 +1717,13 @@ async function decide(config, args) {
     }
     // EXPIRED, or the poll gave up before the platform expired it. Same answer
     // either way, and the difference is on the run for whoever reads it later.
+    // R339: a person may still allow it late, and if they do the session is
+    // sent a message saying so — so this says to carry on, not to stop.
     return deny(
-      `Nobody answered this permission request in time. Do not retry it in a loop: report ` +
-        `blocked, say exactly what you needed to run and why, and let a person allow it.`,
+      `Nobody answered this permission request in time. Do not retry it in a loop. Carry on ` +
+        `with whatever does not need it; if a person allows it later you will be sent a ` +
+        `message saying so, and may run it then. If nothing else can be done without it, ` +
+        `report blocked and say exactly what you needed to run and why.`,
     );
   } catch (failure) {
     return deny(
@@ -1806,9 +1876,10 @@ function skillServers() {
 /**
  * Waits for somebody to decide, for as long as the platform will hold it open.
  *
- * Bounded a little beyond the platform's own expiry so the two cannot both be
- * waiting on each other: if the sweep is late, this gives up and denies, which
- * is the same answer the sweep would have produced.
+ * R339: the platform's wait is the project's setting now, and may be never,
+ * so this has no deadline of its own: it returns when the request stops being
+ * PENDING — allowed, refused, or expired by the platform's sweep. A test may
+ * still bound it.
  */
 async function pollForDecision(config, project, runId, approvalId) {
   const deadline = Date.now() + approvalTimeoutSeconds() * 1000;
@@ -1831,10 +1902,10 @@ async function pollForDecision(config, project, runId, approvalId) {
   return null;
 }
 
-/** A little past the platform's own fifteen-minute expiry. Overridable for tests. */
+/** For ever: the platform decides when nobody is coming (R339). Overridable for tests. */
 function approvalTimeoutSeconds() {
   const configured = Number(process.env.CAWDEV_APPROVAL_TIMEOUT_SECONDS);
-  return Number.isFinite(configured) && configured > 0 ? configured : 960;
+  return Number.isFinite(configured) && configured > 0 ? configured : Infinity;
 }
 
 // There is no roadmap_delete or changelog_delete, and there will not be. The
@@ -2112,6 +2183,12 @@ 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}`);
+  }
   // 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) {

package/package.json

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

package/runner/README.md

@@ -68,6 +68,13 @@ page and waits for you to approve a code; after that it is remembered, and
 `/login` does it again on demand. No password is ever typed into the terminal —
 that belongs on a page your browser has told you the origin of.
 
+When the platform stops honouring that session — it expired, you signed out in
+the console, or your account went — the first request answered 401 says so
+once, the footer pins `session expired — /login to sign in again`, and the
+terminal drops to watching only until `/login` succeeds. The polls pick up again
+on their own after it. In advanced mode `/login` stays in advanced mode: the URL
+and the code are printed in the prompt window.
+
 ```
 cawdev                    the runner here, starting one if there is none
 cawdev --runner <name>    when this machine runs more than one
@@ -124,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>
@@ -139,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 —
@@ -222,7 +241,10 @@ move through the command list while one is open.
 | `/quit` | leave |
 
 **Typing `/` filters that list as you go**, each row with its description; arrows
-and `enter` pick one and `tab` completes as far as the matches agree. Guessing a
+and `enter` pick one and `tab` completes as far as the matches agree — then
+moves down the list, so `/lo` `tab` `tab` reaches `/login` past `/log`. A name
+typed in full is the first row, so `/log` `enter` runs `/log`. Advanced mode
+draws the same list above its prompt, six rows at a time. Guessing a
 command name and being told `no such command` is a step, and it is the step this
 removes.
 
@@ -1088,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
@@ -1200,6 +1243,39 @@ A run **`WAITING_ON_USER` is never swept.** That is the one state where nothing
 happening is correct: it is stalled on a person, who may reasonably take a day.
 Nor is a `PAUSED` or `USAGE_LIMITED` one (below) — there is no process to lose.
 
+### When the daemon itself was killed (R339)
+
+A daemon that dies and is restarted — by systemd, by `cawdev`, by hand — comes
+back with nothing in its hands, and the platform could only infer that five
+minutes later, as "its runner is alive but stopped driving it". So the daemon
+keeps a note of the runs it is driving (`~/.cawdev/driving/<runner id>.json`,
+rewritten when the set changes), and on boot the next one reads it: every run
+the dead daemon was driving that the platform still believes in is failed **at
+once** as `DAEMON_RESTARTED`, with the old and new pids and where to look for the
+cause. A session the old daemon left running is stopped first — only when its
+pid still runs the command it was spawned with. The workspace is held exactly as
+for a vanished runner, and a machine with **auto-resume** on carries such a run
+on by itself **once**; a second restart on the same run waits for a person,
+because a test suite that killed the daemon twice will kill it a third time.
+
+The usual cause on a small Linux box is memory: the session runs a test suite,
+the kernel's OOM killer picks the biggest process, and that is sometimes the
+daemon. `journalctl -k | grep -i "killed process"` says so. Two fixes, both on
+the machine:
+
+- **`"sessionMemoryMax": "6G"`** in `runner.config.json` spawns each agent
+  session under `systemd-run --scope -p MemoryMax=…` (a size systemd reads —
+  `6G`, `512M`, `75%`). A session that blows through it is killed on its own,
+  the ordinary "agent was terminated" failure, and the daemon stays up. Linux
+  only, and it needs a systemd manager for the user (`loginctl enable-linger
+  <user>` on a box with nobody logged in) or a daemon running as root; the
+  daemon probes once at boot and says in its log whether it applied. Needs a
+  restart to change.
+- **Protect the daemon and give the box room**: in the daemon's systemd unit,
+  `OOMScoreAdjust=-800` makes the kernel pick a test worker over the daemon;
+  and add swap (`fallocate -l 4G /swapfile && chmod 600 /swapfile && mkswap
+  /swapfile && swapon /swapfile`, plus its `/etc/fstab` line).
+
 ## When the usage limit hits (R73)
 
 Claude Code stops with a message naming the window — the five-hour one or the
@@ -1309,8 +1385,11 @@ your inbox and on the run, and waits for an answer. Allow it once, or allow it
 always here — which writes a rule on the project that every runner serving it
 inherits.
 
-Nobody answering is a decision too: after fifteen minutes the request expires
-and the session is told to report blocked rather than wait for ever.
+Nobody answering is a decision too: after the project's wait — fifteen minutes
+unless its Rules page says otherwise, and possibly never (R339) — the request
+expires and the session is told to carry on without it. Allowing it later still
+works: the grant lasts the rest of the run and the session is sent a message to
+try again. A stage gate never expires.
 
 You can still say in advance what a project may do, and for anything a session
 needs on every run that is the better answer — with `allowedTools`, which