ctxr-cli 0.32.0 → 0.34.0

package/templates/skills/ctxr-capture-circleback/sweep.mjs

@@ -73,7 +73,17 @@ function recentMeetings() {
   return meetings.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
 }
 
-/** Circleback ids already in the default branch, and in each open pull request's diff. */
+/** Where the runner keeps its review worktree: a fixed path, so a later run finds and clears it. */
+function reviewWorktreePath(root) {
+  return path.join(tmpdir(), `ctxr-capture-circleback-${path.basename(root)}`);
+}
+
+/**
+ * Circleback ids already in the default branch, in each open pull request's diff, and in the store's other
+ * local worktrees, tracked or not: an agent's session that captured a meeting but has not pushed yet is work
+ * in flight, not a gap. The runner's own review worktree is left out, or what an earlier run rendered there
+ * would count as present and a meeting whose pull request was closed unmerged could never be captured again.
+ */
 function presence(root, settings) {
   run('git', ['fetch', '-q', 'origin'], { cwd: root });
   const onMain = new Set(
@@ -87,7 +97,19 @@ function presence(root, settings) {
     const diff = run('gh', ['pr', 'diff', String(pr.number)], { cwd: root, check: false });
     for (const match of diff.matchAll(/circleback\/([A-Za-z0-9_-]+)/g)) if (!inPullRequest.has(match[1])) inPullRequest.set(match[1], pr.number);
   }
-  return { onMain, inPullRequest };
+  const inWorktree = new Map();
+  const own = path.resolve(reviewWorktreePath(root));
+  for (const entry of run('git', ['worktree', 'list', '--porcelain'], { cwd: root, check: false }).split('\n')) {
+    if (!entry.startsWith('worktree ')) continue;
+    const worktree = entry.slice('worktree '.length);
+    if (path.resolve(worktree) === own) continue;
+    const found = run('git', ['grep', '--untracked', '-I', '-h', '-o', '-E', 'circleback/[A-Za-z0-9_-]+'], { cwd: worktree, check: false });
+    for (const match of found.split('\n').filter(Boolean)) {
+      const id = match.slice('circleback/'.length);
+      if (!onMain.has(id) && !inWorktree.has(id)) inWorktree.set(id, worktree);
+    }
+  }
+  return { onMain, inPullRequest, inWorktree };
 }
 
 /**
@@ -96,7 +118,7 @@ function presence(root, settings) {
  * first, because an agent running unattended may not be allowed to delete it.
  */
 function prepareWorktree(root, settings) {
-  const worktree = path.join(tmpdir(), `ctxr-capture-circleback-${path.basename(root)}`);
+  const worktree = reviewWorktreePath(root);
   run('git', ['worktree', 'remove', '--force', worktree], { cwd: root, check: false });
   rmSync(worktree, { recursive: true, force: true });
   run('git', ['worktree', 'prune'], { cwd: root });
@@ -171,7 +193,7 @@ function main() {
   const settings = JSON.parse(readFileSync(path.join(HERE, 'settings.json'), 'utf8'));
   const root = storeRoot();
   const otherTags = new Set(settings.other_tags);
-  const { onMain, inPullRequest } = presence(root, settings);
+  const { onMain, inPullRequest, inWorktree } = presence(root, settings);
   const meetings = recentMeetings();
   const now = Date.now();
   const ageDays = (meeting) => (now - Date.parse(meeting.createdAt)) / 86_400_000;
@@ -181,13 +203,17 @@ function main() {
   const untagged = [];
   const multiStore = [];
   const declined = [];
+  const unpushed = [];
   let present = 0;
   for (const meeting of meetings) {
     const tags = tagNames(meeting);
     const isLocked = (meeting.notes ?? '').includes(LOCKED_NOTICE);
-    const here = onMain.has(meeting.id) || inPullRequest.has(meeting.id);
+    const here = onMain.has(meeting.id) || inPullRequest.has(meeting.id) || inWorktree.has(meeting.id);
     const others = [...tags].filter((tag) => otherTags.has(tag));
     if (tags.has(settings.tag) && here) present += 1;
+    if (tags.has(settings.tag) && inWorktree.has(meeting.id) && !onMain.has(meeting.id) && !inPullRequest.has(meeting.id)) {
+      unpushed.push(`${line(meeting)} (in ${inWorktree.get(meeting.id)})`);
+    }
     if (tags.size === 0 && !here) untagged.push(`${line(meeting)}${isLocked ? ' (locked)' : ageDays(meeting) >= URGENT_DAYS ? ' (URGENT, locks soon)' : ''}`);
     if (tags.has(settings.tag) && others.length > 0) multiStore.push(`${line(meeting)} (also ${others.join(', ')})`);
     if (tags.has(settings.decline_tag) && ageDays(meeting) <= DECLINE_REPORT_DAYS) declined.push(line(meeting));
@@ -197,7 +223,7 @@ function main() {
   }
 
   const report = [
-    `Store tag \`${settings.tag}\`. Meetings in the last ${LOOKBACK_DAYS} days: ${meetings.length}. Already in this store or an open pull request: ${present}.`,
+    `Store tag \`${settings.tag}\`. Meetings in the last ${LOOKBACK_DAYS} days: ${meetings.length}. Already in this store, an open pull request or a local worktree: ${present}.`,
     ...section('TO CAPTURE — date | id | title', owed.map(line)),
   ];
   if (owed.length > 0) {
@@ -214,6 +240,7 @@ function main() {
     }
   }
   report.push(
+    ...section('UNPUSHED — captured in a local worktree but not on the default branch or in an open pull request; land that work', unpushed),
     ...section(`LOCKED — tagged \`${settings.tag}\`, never captured, no longer readable in full`, locked),
     ...section('UNTAGGED', untagged),
     ...section('TAGGED FOR MORE THAN ONE STORE', multiStore),

package/templates/skills/ctxr-capture-circleback.md

@@ -17,12 +17,13 @@ It needs Circleback's command-line tool (`cb`) signed in, plus `git` and `gh`. A
 start and puts its report in your prompt; then skip to step 2.
 
 The runner reads every meeting from the last 35 days with its tags, and compares them with this store's default
-branch and its open pull requests. A meeting is owed when it carries this store's tag, does not carry the decline
-tag, carries no other store's tag, is not already in the store or an open pull request, and can still be read in
-full. For each owed meeting it prepares a review-branch worktree and writes the record into `__INBOX_PATH__` there:
-the meeting's metadata and attendees, Circleback's action items and summary (marked as the service's derivation),
-and the transcript verbatim, with `source_type` and `source_id` stamped. It never writes the recording URL, which is
-a signed, expiring link and so a credential.
+branch, its open pull requests, and the store's other local worktrees, uncommitted files included. A meeting is owed
+when it carries this store's tag, does not carry the decline tag, carries no other store's tag, is in none of those
+places, and can still be read in full. A meeting found only in a local worktree is someone's capture in flight: it
+is listed under UNPUSHED rather than captured again. For each owed meeting it prepares a review-branch worktree and
+writes the record into `__INBOX_PATH__` there: the meeting's metadata and attendees, Circleback's action items and
+summary (marked as the service's derivation), and the transcript verbatim, with `source_type` and `source_id`
+stamped. It never writes the recording URL, which is a signed, expiring link and so a credential.
 
 The report is authoritative. Do not work the list out again yourself, and do not rebuild the files it wrote. If it
 prints `COLLECTION FAILED`, report that line and stop.
@@ -52,6 +53,8 @@ Give the counts (retrieved, already present), the pull request link, and the run
 they are:
 
 - **LOCKED**: tagged for this store but no longer readable in full, so it cannot be captured.
+- **UNPUSHED**: captured in a local worktree but not yet on the default branch or in a pull request. That work
+  needs landing; nothing here captures it again.
 - **UNTAGGED**, **TAGGED FOR MORE THAN ONE STORE** and **DECLINED IN THE LAST 8 DAYS**, when the runner prints them.
 
 If nothing was owed and every section is empty, say "Nothing missing".

package/templates/skills/ctxr-connection-finding.md

@@ -13,5 +13,8 @@ to synthesize an entity's current state from its sources, use `ctxr-rollup`.
 5. To find the most-referenced notes, run `ctxr graph query hubs`; to find unlinked ones,
    `ctxr graph query orphans`; `ctxr graph query clusters` and `ctxr graph query bridges` show the
    cluster structure and the notes that span it.
-6. Report what the graph says — it enumerates structure and ranks nothing; judgment about which links
+6. When the store mounts other stores under `shared/`, the graph carries their notes under `shared/<name>/`.
+   Link from this store into a mount with a path link, such as `[[shared/<name>/<path>]]`.
+   A filename link resolves only inside the store that holds the note. A note in a mount never resolves a link back into this store.
+7. Report what the graph says — it enumerates structure and ranks nothing; judgment about which links
    matter is yours.

package/templates/skills/ctxr-land.md

@@ -1,6 +1,11 @@
 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. `ctxr land` does the landing. This skill decides when to run it.
 
+For a pull request on a mounted store under `shared/<name>`, run every step from that mount, not from this store.
+Why: the mount's own `contexture.yaml` names its approval rules and its canonical clone.
+A pull request that is one part of a session of this store is different: land it from this store, with the
+whole session, as step 4 says. Why: this store lands the session's parts in order.
+
 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
@@ -17,13 +22,27 @@ covers what surrounds both and is not repeated here. `ctxr land` does the landin
      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:
+4. Land.
+   - A pull request with an approval from the page: run `ctxr land <number>`.
+   - A pull request 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.
+   - A session with an approval from the page: run `ctxr land --pending` from this store. Why: it lands each
+     approved session of this store, and it reads the decision itself.
+   - A session with an explicit go: run `ctxr land --session <session> --confirm` from this store. `<session>`
+     is this store's session worktree name. Why: the command lands the parts in mounted stores first, then
+     this store's part.
+   - Treat a pull request as a session when `ctxr review list` names a session for it. Never land the parts
+     of a session one at a time. Why: the command stops at the first part that does not land, so a stop never
+     removes a note before its copy lands.
+   The command catches the branch up with `__DEFAULT_BRANCH__` and merges. It re-reads state to confirm that
+   the forge reports the pull request merged. It 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. For a session, the command also reports the session's state, the
+   part that stopped it, and the parts it did not try.
+   - A session `retrying`: report the part and the reason. Do nothing else. Why: a later run tries again.
+   - A session `blocked` by a part closed without merging: report that part. Ask the operator to reopen it, or
+     to close the session's other parts.
    - `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.

package/templates/skills/ctxr-placement.md

@@ -2,6 +2,16 @@ Decide where a note lives BEFORE writing it, and say why: the caller wants the r
 this location over its sibling, what would promote it) so they can push back — not a
 folder name. Answer the questions in order; stop early only when the content clearly resolves.
 
+## 0. Which store?
+
+Skip this step when the store mounts no other stores under `shared/`. `AGENTS.md` lists the mounts.
+
+- Ask who may read the note before you ask where it goes.
+- Place the note in this store by default. Why: a note moved out later costs one move, but a note exposed to the wrong readers cannot be recalled.
+- Place it in a mounted store only when every reader of that store may read it. Why: everyone who can clone a store reads all of it.
+- For a note in a mounted store, answer the questions below against that store's own taxonomy. Its own `AGENTS.md` lists its layers.
+- Write it in a session started inside that mount, as `ctxr-session-lifecycle` describes.
+
 __LAYER_STEP__
 
 ## 2. Which location within the layer?

package/templates/skills/ctxr-rollup.md

@@ -6,6 +6,9 @@ Run `ctxr rollup stale` (or `--for <entity>` for one) to find entities worth re-
 entity note whose backlinks have moved since its last synthesis, or which has never been rolled up at
 all; use it instead of guessing from memory which entities are out of date.
 
+An entity under `shared/<name>/` belongs to a mounted store. Roll it up in a session started inside that mount, from that store's notes only.
+Why: a rollup that quotes this store's notes would show them to every reader of the mount.
+
 1. Resolve, never create. `<entity>` is a path or a note name; several candidates → list them and ask.
    When a location has more than one plausible hub, prefer the shorter-named, undated one. If no entity
    note exists, STOP and say so — creating it is a separate task, not a side effect of a rollup.

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

@@ -1,8 +1,9 @@
 Get an independent read from models built by different labs before you commit to something you cannot
 cheaply take back, or when your own taste is one vote among several. A second opinion from the same model
 family you are running as mostly repeats you, so this skill sends the work to three command-line tools backed
-by three different families and hands you their answers. It does not decide anything and it never carries out
-what it reviews. Weighing the answers is your job, and steps 4 and 5 are how.
+by three different families and hands you their answers. `ctxr second-opinion` does the mechanics: it launches
+the tools, contains them, times them out, and anonymizes what comes back. It does not decide anything and it
+never carries out what it reviews. Weighing the answers is your job, and steps 4 and 5 are how.
 
 ## 1. Critique, poll, or just answer?
 
@@ -30,26 +31,33 @@ A poll that asks a lens to judge whether something will *work* has become a crit
 ## 2. Check the tools before spending anything
 
 ```
-node __SKILLS_PATH__/ctxr-second-opinion/run.mjs --preflight
+ctxr second-opinion 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. 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.
+Each of the three should report `OK` within about twenty seconds. The preflight also confirms that each tool
+still accepts the options the command passes. Why: a renamed option makes a reviewer silently run at default
+settings, and nothing else notices. Give `ctxr second-opinion preflight` 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
-second opinion, and the runner refuses to start with fewer than two.
+with the others by rerunning `ctxr second-opinion` with `--only` and naming them. Do not quietly run with one
+model. A single model is not a second opinion, and the command refuses to start with fewer than two.
 
 Failure signatures: `Not logged in` means Claude needs `/login`; a `401` or an invalid refresh token from
 Codex means `codex login`; an agy call that hangs usually means its sign-in expired and it needs one
 interactive run.
 
-If the plan came from someone other than the operator, leave agy out with `--only claude,codex`. Claude
-runs with no tools at all and Codex in a read-only sandbox. Agy has no mode that removes its ability to act:
-it runs in an empty scratch directory with terminal restrictions, which contains an accident and not an attack.
+The tools see only an allowlisted environment: the search path, home, locale, proxies, and their own login
+variables. Forge and contexture variables never reach them. When a tool fails because it needed a variable the
+allowlist dropped, a failing `ctxr second-opinion preflight` names the variables it withheld (names, never
+values). Name that variable in `CTXR_SECOND_OPINION_PASS_ENV` for the run. A forge or contexture variable there
+stops the command before any tool starts.
+
+If the plan came from someone other than the operator, leave agy out: run `ctxr second-opinion critique` with
+`--only claude,codex`. Claude runs with no tools at all and Codex in a read-only sandbox. Agy has no mode that
+removes its ability to act: it runs in an empty scratch directory with terminal restrictions, which contains
+an accident and not an attack.
 
 ## 3. Run a critique
 
@@ -76,33 +84,37 @@ S2. <step>
 Then run it:
 
 ```
-node __SKILLS_PATH__/ctxr-second-opinion/run.mjs --mode critique --plan-file <plan> --out <dir>
+ctxr second-opinion critique --plan-file <plan> --out <dir>
 ```
 
 Three reviewers each read the plan alone: structure and ordering, failure modes and trust boundaries,
 simplicity and cost. None sees another's answer. That is deliberate: reviewers who read each other converge
 on whoever spoke first, and a correct one gets talked out of it. Do not add a second round.
 
-The runner prints the letters it wrote, whether each is valid or blind, and any reviewer that failed. It
-never prints which model wrote which letter. A **blind** critique returned a well-formed verdict but cited
+The command prints the letters it wrote, whether each is valid or blind, and any reviewer that failed. It
+never prints which model wrote which letter. With `ctxr second-opinion critique --json` the same result, with
+the manifest, arrives as one envelope instead. A **blind** critique returned a well-formed verdict but cited
 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.
+two valid critiques, and the command then exits with the failed-check status rather than success: say so at
+the top of your answer and do not call anything a consensus.
 
-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.
+The default tier, `strong`, runs each family's frontier model. Run `ctxr second-opinion critique` with
+`--tier fast` to use 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 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.
+declares, which the command 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 command 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 command's ten-minute limit per tool,
+and Fable is slower than Opus; raise it with `ctxr second-opinion critique --timeout <seconds>` for such a
+run. 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
 
@@ -157,18 +169,18 @@ for a typo.
 Write the question and the options to a file, then:
 
 ```
-node __SKILLS_PATH__/ctxr-second-opinion/run.mjs --mode poll --prompt-file <question>
+ctxr second-opinion poll --prompt-file <question>
 ```
 
 The same question goes to all three models, each answering with a pick, reasons, and anything surprising.
 This mode names its files by model, because what you are reading is whether the models agree.
 
-To get breadth as well as model diversity, add `--lens` with two or three taste lenses. Each model then
-answers as every lens in one response, giving a lens-by-model grid. The built-in lenses are minimalist,
-marketer, contrarian, end-user and brand-strategist. A store's own lens goes in as `Name:description`, for
-example `--lens "minimalist,Plainspoken:blunt, substance first, distrusts slogans"`. A description may contain
-commas: a comma starts the next lens only when what follows is a built-in lens name or begins `Name:`. So a
-description must not contain a colon. Choose lenses that pull in different
+To get breadth as well as model diversity, run `ctxr second-opinion poll` with `--lens` and two or three taste
+lenses. Each model then answers as every lens in one response, giving a lens-by-model grid. The built-in
+lenses are minimalist, marketer, contrarian, end-user and brand-strategist. A store's own lens goes in as
+`Name:description`, for example `--lens "minimalist,Plainspoken:blunt, substance first, distrusts slogans"`.
+A description may contain commas: a comma starts the next lens only when what follows is a built-in lens name
+or begins `Name:`. So a description must not contain a colon. Choose lenses that pull in different
 directions; if two would obviously agree, drop one.
 
 Read a lens grid on both axes. Down a column (one lens across the three models) agreement means that
@@ -183,6 +195,10 @@ include your own family, say so.
 
 - A reviewer that timed out, exited non-zero, or returned no verdict is `failed` and carries its cause in
   the manifest. Report it. Do not rerun that one reviewer on a different model to fill the gap.
+- The command's status says which kind of trouble it is. Success means at least two valid answers. The
+  failed-check status means it ran and the result is partial, or the preflight found a tool down. The usage
+  status means nothing ran: an argument was wrong, fewer than two tools were named, or the pass-through
+  variable named a forge or contexture variable.
 - 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

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

@@ -1,7 +1,10 @@
 Every write lands via a session worktree and a reviewed pull request; nothing commits to the default
 branch (`__DEFAULT_BRANCH__`). This skill covers what surrounds a session — starting one, re-scanning before
-any plan, resolving conflicts, and sequencing several pull requests. `ctxr-submit` and `ctxr-land` are
-the two verbs at the seams; their steps are not repeated here.
+any plan, resolving conflicts, sequencing several pull requests, and removing a session. `ctxr-submit` and
+`ctxr-land` are the two verbs at the seams; their steps are not repeated here.
+
+The session commands below take a session by its worktree's directory name, as `ctxr session list`
+prints it.
 
 ## Start
 
@@ -38,15 +41,38 @@ 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.
+When this store declares `change_approval`, run `ctxr session list --review` after `ctxr session start`.
+It reports each session with its open pull request and 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.
+  Why: the decider has no other way to reach an agent. Submitting that session again updates the same pull
+  request.
 - `blocked`: landing stopped, and the row names the reason. Offer to resolve it. For `conflict`, follow the
   conflict playbook below, and then `ctxr-land`.
+- `unknown`: the forge could not be reached. Say so once, and read the decisions again later.
 - Report nothing for the other states. Why: they need no work from a session.
 
+## Mounted stores
+
+Skip this section when the store mounts no other stores under `shared/`.
+
+- After you bring the canonical clone up to date, run `ctxr shared-stores sync`. It clones a missing mount and fast-forwards the others.
+- Report a mount that sync left alone, with its reason. Do not reset, stash or force it. Why: local work in a mount is somebody's session.
+- To write into a mount for the work of this store's session, change into `shared/<name>`. Run `ctxr session start --joins <session>` there, with this store's session name. Why: the mount's session then joins this one, and one decision covers both pull requests.
+- The command refuses outside a mount, or for a session this store does not have. Report the refusal. Do not start a plain session instead.
+- When the work has no session in this store, run `ctxr session start` in the mount. Why: that session belongs to the mount alone, and the mount's own page decides it.
+- Write only the mount's files in the mount's session. Why: each store's pull request holds only that store's changes.
+- A change that touches this store and a mount is one session. It has one pull request in each store.
+
+To move a note from this store into a mount:
+
+1. List the links the note carries. Find each target that stays in this store.
+2. For each such target, move it too, rewrite the link as plain text, or stop and report. Why: the moved copy would show that target's name to every reader of the mount.
+3. In the mount, start a session with `ctxr session start --joins <session>`. Add the note there.
+4. In this store's session, delete the original. Rewrite links to it as path links, such as `[[shared/<name>/<path>]]`.
+5. Submit both parts with `ctxr-submit`. One approval covers them. Landing merges the mount's part first, then this store's part. Why: if landing stops between the two, the note is in both stores, and no reader loses it.
+6. Tell the operator that the move cannot be undone for past readers. Why: the note stays in the mount's history and in every reader's clone.
+
 ## Between turns
 
 A session is not a turn. The worktree persists across as many exchanges as the work takes, and ending a
@@ -60,18 +86,23 @@ signal to wrap up will submit into the middle of a conversation that had more co
 ## Re-scan before any plan
 
 Re-scan whenever state may have moved under you — before presenting a plan, before running `ctxr-submit`,
-after any gap in the conversation: `git fetch origin`, `git status --short`, `git diff --stat`,
-`git diff --cached --stat`, `git ls-files --others --exclude-standard`,
-`git log --oneline origin/__DEFAULT_BRANCH__..HEAD`. State moves under you while you work; a plan that grows
-between scans is normal. Name the delta from the previous scan rather than silently folding new work into
-old buckets.
+after any gap in the conversation: `ctxr session status <session>`. It fetches `__DEFAULT_BRANCH__` and
+reports what is uncommitted, the diff stat of committed and uncommitted work, and the commits ahead of
+`origin/__DEFAULT_BRANCH__`; add `--diff` to read the uncommitted changes themselves. Run from inside the
+session's worktree, it needs no name. State moves under you while you work; a plan that grows between
+scans is normal. Name the delta from the previous scan rather than silently folding new work into old
+buckets.
 
 ## Conflict playbook
 
-From the session worktree: `git fetch origin && git rebase origin/__DEFAULT_BRANCH__`. For each conflicting
-file inspect both sides (`git show`), understand what each represents, and produce a version that keeps
-both meanings — never take one side blindly. `git add <file>`, `GIT_EDITOR=true git rebase --continue`,
-then `git push --force-with-lease origin <branch>` (aborts if the remote moved underneath you). Never
+From the session: `ctxr session rebase <session>`. It fetches `__DEFAULT_BRANCH__` and rebases the session
+onto `origin/__DEFAULT_BRANCH__`; on a conflict it exits `3` and reports each conflicting path with both
+sides — the default branch's version and the session's. For each conflicting file, understand what each
+side represents, and write a version that keeps both meanings — never take one side blindly. Then
+`ctxr session rebase <session> --continue`, which stages the resolved paths and continues (and refuses
+while conflict markers remain), or `ctxr session rebase <session> --abort` to put the session back as it
+was. While a rebase is in progress, `ctxr session submit` is refused. Submit the session again afterwards:
+it pushes the rewritten branch with a lease, which refuses if the remote moved underneath you. Never
 resolve on the default branch.
 
 ## Multi-PR sequencing
@@ -84,22 +115,18 @@ time regardless — sequence those.
 ## Reclaiming
 
 Scope with `ctxr session list` — it reports every worktree and branch this store recognizes as a session,
-whichever checkout you run it from. Reclaiming is always an explicit go, never automatic; never claim a
-worktree or branch was removed without having run the command yourself.
-
-Establish that the pull request actually merged before removing anything, and get that from the forge —
-`gh pr view <branch> --json state` reporting `MERGED` — not from git. If the store squash-merges (GitHub's
-default), the squashed commit is not the branch's tip, so git's ancestry test calls a landed branch
-unmerged forever: `git log <default>..<branch>` never empties and `git branch -d` never succeeds. Reading
-a refusal there as "unmerged work" strands every session the store has ever landed.
-
-With `MERGED` confirmed: `git worktree remove <path>`, then `git branch -d <branch>` — run from outside
-that worktree (no command can remove the directory it is running from — `git worktree list` names the
-canonical clone first). Leave the worktree removal unforced: it refuses on uncommitted work, and that
-refusal is real, so stop and look rather than reaching for `--force`. If `git branch -d` refuses on a
-pull request the forge says is merged, that is the squash case above, and `git branch -D` is the correct
-finish — the forge, not the ancestry graph, is what established the work is safe.
-
-To deliberately discard a session instead — abandoning unmerged work — `git worktree remove --force <path>`
-then `git branch -D <branch>`. State plainly, before running it, that this destroys any uncommitted or
-unmerged work in that worktree; it needs its own explicit go, distinct from the merged-and-clean case above.
+whichever checkout you run it from, with whether each holds uncommitted changes and how many commits it
+carries ahead. Reclaiming is always an explicit go, never automatic; never claim a worktree or branch was
+removed without having run the command yourself.
+
+`ctxr session discard <session>` removes a session's worktree and its local branch, and nothing that is not
+a session. Run it from outside that worktree. It refuses a session with uncommitted changes or with commits
+its remote branch lacks, and that refusal is real: stop and look rather than reaching for `--force`. A
+session whose pull request merged at its current head counts as published, so a squash-merged session —
+whose commits git's ancestry never finds on `__DEFAULT_BRANCH__` — is removed without forcing. It leaves the
+remote branch and any pull request as they are.
+
+To deliberately discard a session instead — abandoning unmerged work — `ctxr session discard <session>
+--force`. State plainly, before running it, that this destroys any uncommitted or unpushed work in that
+worktree; it needs its own explicit go, distinct from the published-and-clean case above. Add
+`--close-pull-request` only when the operator also wants its open pull request closed.