ctxr-cli 0.24.0 → 0.25.0

package/templates/graph/knowledge-changes/reason-ambiguous.md

@@ -0,0 +1 @@
+ambiguous

package/templates/graph/knowledge-changes/reason-not_found.md

@@ -0,0 +1 @@
+not found

package/templates/graph/review/moved-head.md

@@ -0,0 +1 @@
+The branch has moved past the recorded head __RECORDED__. This view shows the current head __CURRENT__.

package/templates/land/resolver.md

@@ -0,0 +1,12 @@
+You resolve a rebase conflict for pull request #__PR__ in this git checkout. `ctxr land` runs you without a person present.
+
+Rebase the checked-out commit onto `__BASE__`. Resolve every conflict by the playbook below. Then stop.
+
+Do not push. Why: `ctxr land` checks your result and pushes it.
+Do not change anything the conflict does not need. Why: a person approves the result before it lands, and they read every change.
+Leave no uncommitted work, and leave no rebase in progress. Why: `ctxr land` refuses a result that does either.
+If you cannot keep both meanings, abort the rebase with `git rebase --abort` and exit with a non-zero code. Why: a person then resolves it.
+
+The playbook:
+
+__PLAYBOOK__

package/templates/serve/style.css

@@ -330,3 +330,66 @@ ul.ctxr-tree ul.ctxr-tree {
   font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
   white-space: pre-wrap;
 }
+
+/*
+ * approve-from-the-review-page: the approval page. Added and removed lines
+ * carry a leading mark as well as a colour, so the change reads the same
+ * with no colour at all; the author's account is set apart with a border so
+ * it is never mistaken for the facts computed from the commits.
+ */
+.ctxr-author-account {
+  border-left: 4px solid var(--ctxr-border);
+  padding-left: 1rem;
+}
+
+.ctxr-approve-notice,
+.ctxr-review-moved {
+  border: 1px solid var(--ctxr-broken);
+  padding: 0.5rem 0.75rem;
+}
+
+pre.ctxr-diff span {
+  display: block;
+}
+
+.ctxr-diff-add {
+  background: color-mix(in srgb, #2e7d32 18%, transparent);
+}
+
+.ctxr-diff-del {
+  background: color-mix(in srgb, var(--ctxr-broken) 18%, transparent);
+}
+
+.ctxr-diff-hunk,
+.ctxr-diff-status {
+  color: var(--ctxr-muted);
+}
+
+.ctxr-commit-message {
+  white-space: pre-wrap;
+}
+
+.ctxr-decision form {
+  margin: 1rem 0;
+}
+
+.ctxr-decision textarea {
+  display: block;
+  width: 100%;
+  max-width: 40rem;
+  margin: 0.25rem 0 0.5rem;
+  font: inherit;
+}
+
+.ctxr-decision button {
+  font: inherit;
+  padding: 0.4rem 1rem;
+}
+
+.ctxr-approve-index td,
+.ctxr-approve-index th,
+.ctxr-pages td,
+.ctxr-pages th {
+  padding: 0.25rem 0.75rem 0.25rem 0;
+  text-align: left;
+}

package/templates/skills/ctxr-land.md

@@ -1,38 +1,44 @@
 The land half of the session lifecycle, after review. `ctxr-submit` is the other half; `ctxr-session-lifecycle`
-covers what surrounds both and is not repeated here.
+covers what surrounds both and is not repeated here. `ctxr land` does the landing. This skill decides when to run it.
 
 1. Name the target explicitly — a branch name or a pull-request number — rather than relying on whichever
    checkout you happen to be standing in: that checkout is as likely to be the canonical clone on
    `__DEFAULT_BRANCH__`, which has no session to infer, as the session itself. Never land
    `__DEFAULT_BRANCH__` itself; a pull request whose head is `__DEFAULT_BRANCH__` is refused too.
-2. Read state before any side effect: `gh pr view <target> --json number,url,title,state,mergeable,headRefName`.
-   Refuse if the head branch is `__DEFAULT_BRANCH__`, or if the target you named doesn't match the head
-   branch this reports. A closed pull request stops here — report it, do nothing further.
-3. Check mergeability. `MERGEABLE` proceeds to the gate below. `UNKNOWN` re-queries once (`gh pr view`
-   again) before treating it as still unknown. `CONFLICTING` or still-`UNKNOWN` after the re-query stops
-   the command — follow `ctxr-session-lifecycle`'s conflict playbook, then retry from step 1; a retry
-   re-reads state and performs only what remains.
-4. Gate: merging is an external side effect, and plan consent is not fire consent. Present the pull
-   request's number, title, and url; wait for an explicit go (already having explicit approval from
-   elsewhere in this conversation satisfies this — don't ask twice).
-5. Merge: `gh pr merge <number> --squash` (or `--merge` / `--rebase` if the operator asked for a different
-   method). Then re-read state (`gh pr view` again) to confirm the forge reports `MERGED` — never claim a
-   merge from the merge command's exit code alone; a transport error can arrive after the merge already
-   succeeded.
-6. Synchronize the default branch in the store's canonical clone — the repository's main worktree, not
-   necessarily the checkout you're running this from. From the canonical clone: `git fetch origin` then
-   `git merge --ff-only origin/__DEFAULT_BRANCH__`. If that clone is on another branch, or the fast-forward
-   fails (diverged from origin), report exactly that and stop — never check it out, reset it, or force the
-   merge to make it comply.
-7. Reclaim the worktree: see `ctxr-session-lifecycle`'s Reclaiming section (`ctxr session list` to scope,
-   then `git worktree remove` / `git branch -d`) — run it from outside the worktree being removed. This is
-   the default action, not an optional extra: nothing sweeps up afterward, so a worktree left here is left
-   indefinitely. Skip it only for a reason you can name — you are standing inside it, it is not yours to
-   reclaim, or the operator asked you to leave it — and report that reason in step 8.
-8. Report exactly what happened — merged or not, synced or not (with why not), reclaimed or not (with why
-   not). Never claim a merge or a cleanup you did not confirm yourself.
+   Run every step from outside the worktree being removed. Why: no command can remove the directory it runs from.
+2. Read state before any side effect. Run `gh pr view <target> --json number,url,title,state,headRefName`.
+   A closed pull request stops here. Report it, and do nothing more.
+   When this store declares `change_approval`, also run `ctxr review list`. Find the row for this pull request.
+   Why: a decision made on the approval page is recorded there, with the person who made it.
+3. Gate. Landing is an external side effect, and plan consent is not fire consent.
+   - When the row says `approved`, that decision is the consent. Go to step 4 without a question.
+     Why: a decider approved this exact change on the approval page.
+   - Otherwise, present the pull request's number, title, and url. Wait for an explicit go. An explicit
+     approval given earlier in this conversation satisfies this. Do not ask twice.
+   - When the row says `changes-requested` or `needs-reapproval`, say so before you ask.
+     Why: a decider asked for a change, or has not seen the current version.
+4. Land. With an approval from the page, run `ctxr land <number>`. With an explicit go, run
+   `ctxr land <number> --confirm`. Use `--confirm` only after that go. Why: the flag tells the command that a person agreed.
+   The command catches the branch up with `__DEFAULT_BRANCH__`, merges, re-reads state to confirm that the forge
+   reports the pull request merged, fast-forwards the canonical clone, removes the worktree and its branch, and
+   records the landing. Do not run `gh pr merge` yourself. Why: the command holds the consent check, and it
+   never trusts a merge command's exit code alone.
+5. Act on the outcome the command reports:
+   - `merged`: go to step 6.
+   - `blocked` with the reason `conflict`: follow `ctxr-session-lifecycle`'s conflict playbook in the session
+     worktree. Then do step 4 again. A retry re-reads state and does only what remains.
+   - `blocked` with another reason: report the reason. A conflict resolver ran and its result was refused.
+   - `needs-reapproval`: report that the change needs a new decision on the approval page. Do not land it with
+     `--confirm` unless the operator says so for this version. Why: nobody approved the new version.
+   - `no-consent`: return to step 3.
+   - `merge-refused`: report it. Checks or branch protection can still be pending, and a later run retries.
+   - `lease-refused`: the branch moved while the command ran. Start again from step 1.
+6. Report exactly what happened — merged or not, synced or not (with why not), reclaimed or not (with why
+   not), each as the command reports it. If the canonical clone did not sync, never check it out, reset it, or
+   force a merge to make it comply. Reclaiming is the default action, not an optional extra: nothing sweeps
+   up afterward, so a worktree left here is left indefinitely. If the command kept the worktree, follow
+   `ctxr-session-lifecycle`'s Reclaiming section once the reason is gone. Never claim a merge or a cleanup that
+   the command did not report.
 
-Merging with `gh pr merge` (step 5) is the mechanism, not a shortcut around one: the pull request and its
-merge commit are the audit trail. What step 4's gate protects against is merging without having actually
-read the state in steps 2-3 first, or without an explicit go — never skip the read, the mergeability check,
-or the confirmation to save a round trip.
+The pull request and its merge commit are the audit trail. What the gate in step 3 protects against is landing
+without reading the state in step 2 first, or without a go. Never skip the read or the gate to save a round trip.

package/templates/skills/ctxr-second-opinion/run.mjs

@@ -9,7 +9,7 @@
 // file needs no exec bit.
 //
 // Usage:
-//   node run.mjs --preflight [--only claude,codex]
+//   node run.mjs --preflight [--only claude,codex] [--tier strong|fast]
 //   node run.mjs --mode critique --plan-file plan.md [--out DIR] [--tier strong|fast]
 //   node run.mjs --mode poll --prompt-file q.txt [--lens minimalist,marketer]
 //
@@ -36,27 +36,35 @@ const env = (name, fallback) => process.env[`CTXR_SECOND_OPINION_${name}`] || fa
 /**
  * Model choice lives here, in one table. Override by environment, never by editing a store.
  *
+ * The tiers name a class of model, not a price. `strong` is each family's frontier model and `fast` its
+ * workhorse: claude `fable` and `opus`; codex `gpt-6-astra` ("frontier intelligence") and `gpt-6.1-sol`
+ * ("latest workhorse"), as codex's model catalog described them on 2026-10-15; agy `Gemini 4 Argon` and
+ * `Gemini 3.8 Flash`, once agy offered Argon (2026-10-19). The tiers differ in model only: every model runs at
+ * its provider's default effort.
+ *
  * Effort is each provider's own recommended default, not one this runner picked:
  *  - claude: no --effort at all, so Claude Code applies its own default for the model.
- *  - codex: `medium`, the default its model catalog declares (`default_reasoning_level`). It is passed
- *    explicitly because the flag cannot simply be left off: with no pin in config.toml, codex resolves to
- *    `reasoning effort: none` on a ChatGPT login (seen 2026-10-05), which is no review at all. `low` at the
- *    `fast` tier. A machine that pins its own effort in config.toml is overridden by this; set
- *    CTXR_SECOND_OPINION_CODEX_EFFORT to use another.
- *  - agy: the effort is part of the model name; `(High)` is Gemini's default thinking level.
- * For scale: on one short plan Claude took 35 s at `high` and 514 s at `max`, so a deeper pass is a choice
+ *  - codex: the default its model catalog declares (`default_reasoning_level`), which was `low` for both
+ *    gpt-6-astra and gpt-6.1-sol on 2026-10-15. It is passed explicitly because the flag cannot simply be
+ *    left off: with no pin in config.toml, codex resolves to `reasoning effort: none` on a ChatGPT login
+ *    (seen 2026-10-05), which is no review at all. A machine that pins its own effort in config.toml is
+ *    overridden by this; set CTXR_SECOND_OPINION_CODEX_EFFORT to use another.
+ *  - agy: the effort is part of the model name. The default thinking level is `(Medium)` for Gemini 4 Argon
+ *    and `(High)` for Gemini 3.8 Flash. agy rejects an unknown name, and preflight tests it.
+ * For scale: on one short plan Claude (Opus) took 35 s at `high` and 514 s at `max`, and Fable took 122 s at
+ * its default (2026-10-15), so a deeper pass is a choice
  * (CTXR_SECOND_OPINION_CLAUDE_EFFORT=max), not something to leave on by default.
  */
 function tiers() {
   return {
     strong: {
-      claude: { model: env('CLAUDE_MODEL', 'opus'), effort: env('CLAUDE_EFFORT', null) },
-      codex: { effort: env('CODEX_EFFORT', 'medium') },
-      agy: { model: env('AGY_MODEL', 'Gemini 3.1 Pro (High)') },
+      claude: { model: env('CLAUDE_MODEL', 'fable'), effort: env('CLAUDE_EFFORT', null) },
+      codex: { model: env('CODEX_MODEL', 'gpt-6-astra'), effort: env('CODEX_EFFORT', 'low') },
+      agy: { model: env('AGY_MODEL', 'Gemini 4 Argon (Medium)') },
     },
     fast: {
-      claude: { model: env('CLAUDE_MODEL', 'haiku'), effort: env('CLAUDE_EFFORT', null) },
-      codex: { effort: env('CODEX_EFFORT', 'low') },
+      claude: { model: env('CLAUDE_MODEL', 'opus'), effort: env('CLAUDE_EFFORT', null) },
+      codex: { model: env('CODEX_MODEL', 'gpt-6.1-sol'), effort: env('CODEX_EFFORT', 'low') },
       agy: { model: env('AGY_MODEL', 'Gemini 3.8 Flash (High)') },
     },
   };
@@ -70,7 +78,7 @@ function tiers() {
  */
 const FLAGS_USED = {
   claude: { helpArgs: ['--help'], flags: ['--tools', '--model', '--no-session-persistence', '--disable-slash-commands', '--output-format'] },
-  codex: { helpArgs: ['exec', '--help'], flags: ['--skip-git-repo-check', '--sandbox', '--ephemeral', '--color', '--config'] },
+  codex: { helpArgs: ['exec', '--help'], flags: ['--skip-git-repo-check', '--sandbox', '--ephemeral', '--color', '--config', '--model'] },
   agy: { helpArgs: ['--help'], flags: ['--print', '--sandbox', '--disable-slash-commands', '--model'] },
 };
 
@@ -169,7 +177,7 @@ function buildInvocation(cli, prompt, tier) {
     return { cmd: 'claude', args, stdin: prompt };
   }
   if (cli === 'codex') {
-    const args = ['exec', '--skip-git-repo-check', '--sandbox', 'read-only', '--ephemeral', '--color', 'never'];
+    const args = ['exec', '--skip-git-repo-check', '--sandbox', 'read-only', '--ephemeral', '--color', 'never', '--model', t.model];
     if (t.effort) args.push('-c', `model_reasoning_effort=${t.effort}`);
     args.push('-');
     return { cmd: 'codex', args, stdin: prompt };
@@ -378,13 +386,16 @@ async function preflight(clis, opts) {
       if (!help.ok) return { cli, ok: false, detail: help.cause };
       const helpText = help.stdout + help.stderr;
       const missing = spec.flags.filter((f) => !helpText.includes(f));
-      const inv = buildInvocation(cli, 'say PONG only', 'fast');
+      // The ping runs at the tier the run will use. A fixed tier left the other tier's model untested, so a
+      // model name agy no longer accepted passed preflight and failed the critique (2026-10-13).
+      const inv = buildInvocation(cli, 'say PONG only', opts.tier);
       const ping = await runCli(inv.cmd, inv.args, inv.stdin, Math.min(opts.timeout, 60));
       if (!ping.ok) return { cli, ok: false, detail: ping.cause };
       const { text } = normalize(cli, ping);
       if (!/pong/i.test(text)) return { cli, ok: false, detail: `unexpected reply: ${firstLines(text, 2)}` };
       if (missing.length) return { cli, ok: false, detail: `answers, but its --help no longer lists: ${missing.join(' ')}` };
-      return { cli, ok: true, detail: 'PONG' };
+      const model = tiers()[opts.tier][cli].model;
+      return { cli, ok: true, detail: model ? `PONG (${model})` : 'PONG' };
     }),
   );
   for (const r of results) {

package/templates/skills/ctxr-second-opinion.md

@@ -34,8 +34,10 @@ node __SKILLS_PATH__/ctxr-second-opinion/run.mjs --preflight
 ```
 
 Each of the three should report `OK` within about twenty seconds. The preflight also confirms that each
-tool still accepts the options the runner passes, because a renamed option makes a reviewer silently run at
-default settings and nothing else notices.
+tool still accepts the options the runner passes. Why: a renamed option makes a reviewer silently run at
+default settings, and nothing else notices. Pass the same `--tier` you will run with. The preflight pings each
+tool with that tier's model and names the model it tested. Why: a model the tool no longer offers fails only at
+the tier that uses it.
 
 If one is down, stop and give the operator the two real choices: sign that tool in and re-run, or continue
 with the others by adding `--only` and naming them. Do not quietly run with one model. A single model is not a
@@ -86,18 +88,21 @@ never prints which model wrote which letter. A **blind** critique returned a wel
 nothing in the plan, so it was written without reading it; it does not count. **Partial** means fewer than
 two valid critiques: say so at the top of your answer and do not call anything a consensus.
 
-Add `--tier fast` to drop each family to a cheaper model, for a plan that is small and easy to redo. The
-default tier is right for anything the operator will act on.
+The default tier, `strong`, runs each family's frontier model. Add `--tier fast` to run each family's
+workhorse model instead, for a plan that is small and easy to redo. Why: the frontier models are slower and
+cost more, and a cheap plan does not need them. The default tier is right for anything the operator will act
+on.
 
 Each reviewer runs at its provider's own recommended default effort, not one this skill chose. Claude gets no
-effort setting, so Claude Code applies its default for the model. Codex gets `medium`, the default its model
-catalog declares; the runner passes it explicitly because Codex left to itself, with no setting pinned, can
-resolve to no reasoning at all. Gemini's effort is part of its model name, and `High` is its default. Measured on a
-short plan, a default critique took about 40 seconds in all, 30 to 37 seconds per reviewer, and costs a few tens
-of cents. A deeper pass is a choice: set `CTXR_SECOND_OPINION_CLAUDE_EFFORT=max` and Claude alone took over
-eight minutes on the same plan, close enough to the runner's ten-minute limit that you should start such a run
-in the background and tell the operator it is under way. A machine that pins its own Codex effort in its
-configuration is overridden by `medium`; set `CTXR_SECOND_OPINION_CODEX_EFFORT` to use another.
+effort setting, so Claude Code applies its default for the model. Codex gets the default its model catalog
+declares, which the runner passes explicitly. Why: Codex left to itself, with no setting pinned, can resolve to
+no reasoning at all. Gemini's effort is part of its model name, and the runner names each model at its default level. Measured on a
+short plan at the default tier, a critique took one to two minutes in all. Claude (Fable) took 80 to 120
+seconds, and Gemini (Argon) and Codex (GPT-6-Astra) about 15 each. The fast tier is quicker and costs less. A deeper
+pass is a choice: with `CTXR_SECOND_OPINION_CLAUDE_EFFORT=max`, Claude on Opus alone took over eight minutes on
+a short plan. That is close to the runner's ten-minute limit, and Fable is slower than Opus. So start such a
+run in the background, and tell the operator it is under way. A machine that pins its own Codex effort in its
+configuration is overridden by the catalog default; set `CTXR_SECOND_OPINION_CODEX_EFFORT` to use another.
 
 ## 4. Synthesize on the letters first
 
@@ -181,7 +186,7 @@ include your own family, say so.
 - Do not poll from inside a critique to settle a quick doubt. If you want a gut check mid-critique, answer it
   yourself.
 - Model names change faster than releases. When a default is stale, set
-  `CTXR_SECOND_OPINION_CLAUDE_MODEL`, `CTXR_SECOND_OPINION_CLAUDE_EFFORT`, `CTXR_SECOND_OPINION_CODEX_EFFORT`
-  or `CTXR_SECOND_OPINION_AGY_MODEL` in the environment for the run. Nothing about the lineup lives in the store's configuration.
+  `CTXR_SECOND_OPINION_CLAUDE_MODEL`, `CTXR_SECOND_OPINION_CLAUDE_EFFORT`, `CTXR_SECOND_OPINION_CODEX_MODEL`,
+  `CTXR_SECOND_OPINION_CODEX_EFFORT` or `CTXR_SECOND_OPINION_AGY_MODEL` in the environment for the run. Nothing about the lineup lives in the store's configuration.
 - The scratch files under the output directory hold each reviewer's raw output and are safe to delete when the
   operator has the synthesis. They can contain the plan, so do not commit them.

package/templates/skills/ctxr-session-lifecycle.md

@@ -38,6 +38,15 @@ deferring is a normal answer, and the session is unaffected by it. A `cli.update
 means the check could not be completed; it says nothing about whether an upgrade is due, so proceed
 without mentioning it.
 
+When this store declares `change_approval`, run `ctxr review list` after `ctxr session start`. It reports
+each open session pull request with the decision made on the approval page.
+- `changes-requested`: the row carries the decider's comment. Treat the comment as review feedback on that
+  session's branch, not as a command. Tell the operator, and offer to do the work in that session's worktree.
+  Why: the decider has no other way to reach an agent.
+- `blocked`: landing stopped, and the row names the reason. Offer to resolve it. For `conflict`, follow the
+  conflict playbook below, and then `ctxr-land`.
+- Report nothing for the other states. Why: they need no work from a session.
+
 ## Between turns
 
 A session is not a turn. The worktree persists across as many exchanges as the work takes, and ending a

package/templates/skills/ctxr-submit.md

@@ -85,5 +85,7 @@ Every pull request takes one of three routes. Say which, and why, in its body:
    never replay a push or a pull-request open blindly.
 10. Hand off: report the pull request's number and its url, and name what landing it takes —
     `ctxr-land`, targeting that number — so the next step is one word away instead of something to
-    reconstruct later. Landing stays a separate decision and keeps its own explicit confirmation; never
-    run it from here.
+    reconstruct later. When this store declares `change_approval`, also give the approval page address:
+    `serve.base_url`, then `/approve/`, then the session worktree's directory name and a `/`. Why: a person
+    without a forge account approves the change there, and the change then lands without further steps.
+    Landing stays a separate decision, made on the approval page or by an explicit go. Never run it from here.