@forwardimpact/libwiki 0.2.28 → 0.2.30

package/src/audit/scopes.js

@@ -4,6 +4,8 @@ import { parseClaims } from "../active-claims.js";
 import { countLines, countWords } from "../budget.js";
 import { parseStatusRowId } from "../status.js";
 import {
+  CARRY_SURFACE_H1_RE,
+  CARRY_SURFACE_NAME_RE,
   PRIORITY_INDEX_HEADING,
   WEEKLY_LOG_NAME_RE,
   WEEKLY_LOG_PART_NAME_RE,
@@ -75,6 +77,11 @@ function loadFile(filePath, fs) {
   const base = path.basename(filePath);
   const weekMatch =
     base.match(WEEKLY_LOG_NAME_RE) || base.match(WEEKLY_LOG_PART_NAME_RE);
+  const carryMatch = base.match(CARRY_SURFACE_NAME_RE);
+  let agentPrefix;
+  if (weekMatch) agentPrefix = weekMatch[1];
+  else if (carryMatch) agentPrefix = carryMatch[1];
+  else agentPrefix = base.replace(/\.md$/, "");
   return {
     path: filePath,
     text,
@@ -83,7 +90,7 @@ function loadFile(filePath, fs) {
     h2s,
     lines: countLines(text),
     words: countWords(text),
-    agentPrefix: weekMatch ? weekMatch[1] : base.replace(/\.md$/, ""),
+    agentPrefix,
   };
 }
 
@@ -101,6 +108,17 @@ function classifyFile(filePath, fs) {
     return { kind: "weekly-log-part", subject: loadFile(filePath, fs) };
   }
   const subject = loadFile(filePath, fs);
+  // Carry surface: a `<agent>-carries.md` whose H1 matches the Carry H1 RE.
+  // Both axes must match (filename prefix and H1), mirroring the summary
+  // classifier. The two H1 REs end in distinct literals (`— Carries` vs
+  // `— Summary`) so the branches cannot cross-capture regardless of order;
+  // a name-match + H1-miss is left unclassified, like a malformed summary.
+  if (CARRY_SURFACE_NAME_RE.test(base)) {
+    if (CARRY_SURFACE_H1_RE.test(subject.firstLine)) {
+      return { kind: "carry-surface", subject };
+    }
+    return null;
+  }
   // Files that do not match a summary or weekly-log shape are left
   // unclassified: stray files are not audited.
   if (!SUMMARY_H1_RE.test(subject.firstLine)) return null;
@@ -119,6 +137,18 @@ function readOptional(filePath, fs) {
   };
 }
 
+// MEMORY.md carries the same line/word budget rules as the prose surfaces, so
+// its subject needs the `lines`/`words` counters those check builders read.
+// Counted off the canonical budget.js pair, like every other budgeted surface.
+function loadMemory(filePath, fs) {
+  const base = readOptional(filePath, fs);
+  return {
+    ...base,
+    lines: countLines(base.text),
+    words: countWords(base.text),
+  };
+}
+
 /**
  * Parse the rows inside STATUS.md's fenced block into audit subjects. Lines
  * outside the ``` fence (header prose) and blank lines are skipped. Each row
@@ -219,6 +249,7 @@ const SCOPE_RESOLVERS = {
   "weekly-log-main": (ctx) => ctx.subjects["weekly-log-main"],
   "weekly-log-part": (ctx) => ctx.subjects["weekly-log-part"],
   "metrics-csv": (ctx) => ctx.subjects["metrics-csv"],
+  "carry-surface": (ctx) => ctx.subjects["carry-surface"],
   memory: (ctx) => [ctx.memory],
   "claims-row": (ctx) =>
     parseClaims(ctx.memory.text).map((c) => ({ ...c, path: ctx.memory.path })),
@@ -322,6 +353,7 @@ export function buildContext({ wikiRoot, today, fs, subprocess }) {
     "weekly-log-main": [],
     "weekly-log-part": [],
     "metrics-csv": [],
+    "carry-surface": [],
   };
   for (const file of listMdFiles(wikiRoot, fs)) {
     const classified = classifyFile(file, fs);
@@ -334,7 +366,7 @@ export function buildContext({ wikiRoot, today, fs, subprocess }) {
     wikiRoot,
     today,
     subjects,
-    memory: readOptional(path.join(wikiRoot, "MEMORY.md"), fs),
+    memory: loadMemory(path.join(wikiRoot, "MEMORY.md"), fs),
     status: readOptional(path.join(wikiRoot, "STATUS.md"), fs),
     storyboard: loadStoryboard(wikiRoot, today, fs),
     admission: buildAdmission(wikiRoot, fs, subprocess),

package/src/budget-gate.js

@@ -0,0 +1,193 @@
+// Post-landing, pre-push budget re-validation on the size (word/line) axis.
+//
+// The wiki landing flow re-runs the audit's budget predicates over the
+// outgoing tree between landing and push, and refuses a push that introduces
+// or deepens a per-file budget breach this writer's push would publish. The
+// gate reuses the audit's budget rules by reference: it resolves the rule
+// objects named by `BUDGET_RULE_IDS` and calls each rule's own `check` (the
+// over-cap predicate) plus the same `countWords` / `countLines` the audit
+// builds its subjects from. It never re-defines a budget, never routes through
+// the `runRules` engine (which drops the numeric value and emits nothing under
+// cap), and never edits — it refuses, keeping commits local.
+
+import path from "node:path";
+import { BUDGET_RULE_IDS, RULES } from "./audit/rules.js";
+import { buildContext, resolveScope } from "./audit/scopes.js";
+import { countLines, countWords } from "./budget.js";
+
+/**
+ * Resolve `BUDGET_RULE_IDS` to their rule objects in `RULES`, tagging each with
+ * the count axis its id implies. Throws if a named id is missing from `RULES`,
+ * so a rule rename surfaces here rather than silently dropping a predicate.
+ * @returns {Array<{id: string, scope: string, axis: 'words'|'lines', check: Function}>}
+ */
+export function budgetRules() {
+  const byId = new Map(RULES.map((r) => [r.id, r]));
+  return [...BUDGET_RULE_IDS].map((id) => {
+    const rule = byId.get(id);
+    if (!rule) throw new Error(`budget-gate: unknown budget rule id '${id}'`);
+    return {
+      id,
+      scope: rule.scope,
+      axis: id.endsWith("word-budget") ? "words" : "lines",
+      check: rule.check,
+    };
+  });
+}
+
+/**
+ * Enumerate which wiki files are budgeted, by reusing the audit's
+ * classification. Subjects carry an absolute `path`, so each is reduced to the
+ * `<file>` half of `git show <ref>:<file>` relative to `wikiRoot`. No count is
+ * read off the working-dir subject — only the file identity and its scope.
+ * @param {object} ctx - An audit context from `buildContext`.
+ * @param {string} wikiRoot - The wiki clone directory the paths are relative to.
+ * @returns {Array<{relPath: string, scope: string}>}
+ */
+export function budgetedFiles(ctx, wikiRoot) {
+  const scopes = new Set(budgetRules().map((r) => r.scope));
+  const files = [];
+  for (const scope of scopes) {
+    for (const subject of resolveScope(scope, ctx)) {
+      files.push({ relPath: path.relative(wikiRoot, subject.path), scope });
+    }
+  }
+  return files;
+}
+
+/**
+ * Measure the budget predicates for the tree at `ref`. Reads each budgeted
+ * file's blob via the cwd-bound `showFile`, counts it once with the audit's
+ * counters, then for every budget rule on that file's scope records the axis
+ * value and whether the rule's own `check` flags it over cap. An absent path
+ * at the ref counts as 0 (matching the audit's "missing counts as empty"
+ * posture); an unreadable ref makes `showFile` throw, which propagates.
+ * @param {(ref: string, file: string) => Promise<string|null>} showFile
+ * @param {string} ref - The tree-ish to measure (e.g. "HEAD", a SHA).
+ * @param {Array<{relPath: string, scope: string}>} budgeted
+ * @returns {Promise<Map<string, Map<string, {value: number, overCap: boolean}>>>}
+ *   relPath → ruleId → { value, overCap }.
+ */
+export async function measureRef(showFile, ref, budgeted) {
+  const rules = budgetRules();
+  const result = new Map();
+  for (const { relPath, scope } of budgeted) {
+    const text = (await showFile(ref, relPath)) ?? "";
+    const counts = { words: countWords(text), lines: countLines(text) };
+    const perRule = new Map();
+    for (const rule of rules) {
+      if (rule.scope !== scope) continue;
+      perRule.set(rule.id, {
+        value: counts[rule.axis],
+        overCap: rule.check(counts) != null,
+      });
+    }
+    result.set(relPath, perRule);
+  }
+  return result;
+}
+
+/**
+ * Compare the outgoing tree against the two push-input baselines and return the
+ * per-file/per-predicate refusal delta. For each (file, rule) the baseline is
+ * the worse (higher) of the session-base and origin-tip values, treating an
+ * absent measurement as 0. A predicate refuses iff the outgoing value is over
+ * cap AND strictly exceeds that baseline — so equal-or-better states pass, and
+ * a foreign breach the writer did not worsen passes. A `summary.*` breach on a
+ * file listed in `exemptSummaryFiles` is surfaced instead of refused — the
+ * memo-delivery seam, where blocking a delivery into deficient headroom would
+ * enforce a contradiction the memo-headroom measures exist to resolve.
+ *
+ * @param {object} args
+ * @param {Map<string, Map<string, {value: number, overCap: boolean}>>} args.outgoing
+ * @param {Map<string, Map<string, {value: number}>>|null} args.sessionBase - null when unborn.
+ * @param {Map<string, Map<string, {value: number}>>|null} args.originTip
+ * @param {string[]} [args.exemptSummaryFiles]
+ * @returns {{refusals: Array<object>, surfaced: Array<object>}}
+ *   Each entry: { file, ruleId, baseline, value }.
+ */
+export function revalidateBudgets({
+  outgoing,
+  sessionBase,
+  originTip,
+  exemptSummaryFiles = [],
+}) {
+  const exempt = new Set(exemptSummaryFiles);
+  const refusals = [];
+  const surfaced = [];
+  const baselineValue = (ref, relPath, ruleId) =>
+    ref?.get(relPath)?.get(ruleId)?.value ?? 0;
+  for (const [relPath, perRule] of outgoing) {
+    for (const [ruleId, { value, overCap }] of perRule) {
+      if (!overCap) continue;
+      const baseline = Math.max(
+        baselineValue(sessionBase, relPath, ruleId),
+        baselineValue(originTip, relPath, ruleId),
+      );
+      if (value <= baseline) continue;
+      const entry = { file: relPath, ruleId, baseline, value };
+      if (ruleId.startsWith("summary.") && exempt.has(relPath)) {
+        surfaced.push(entry);
+      } else {
+        refusals.push(entry);
+      }
+    }
+  }
+  return { refusals, surfaced };
+}
+
+/**
+ * Run the gate end to end over the outgoing tree. Builds the audit context,
+ * enumerates the budgeted files, measures the committed `HEAD` (what publishes)
+ * and the two push-input baselines through the one `measureRef` path, then
+ * computes the per-file/per-predicate delta. An unreadable baseline ref makes
+ * `showFile` throw, which aborts the gate WITHOUT refusing — the gate only
+ * refuses a regression it can prove, so a read failure surfaces (the push
+ * proceeds) rather than fabricating a value-0 baseline that would wrongly block
+ * a foreign pre-existing breach.
+ *
+ * @param {object} args
+ * @param {(ref: string, file: string) => Promise<string|null>} args.showFile
+ * @param {string} args.wikiRoot - The wiki clone directory.
+ * @param {string} args.today - ISO day for the audit context (weekly-log scope).
+ * @param {object} args.fs - Sync fs the audit context reads with.
+ * @param {string} args.headRef - The outgoing tree-ish (e.g. "HEAD").
+ * @param {string} args.originRef - The landed origin tip ref.
+ * @param {string} [args.sessionBaseSha] - Pre-fetch session base, or "" when unborn.
+ * @param {string[]} [args.exemptSummaryFiles] - Memo-delivery seam set.
+ * @returns {Promise<{refusals: Array<object>, surfaced: Array<object>}>}
+ */
+export async function runBudgetGate({
+  showFile,
+  wikiRoot,
+  today,
+  fs,
+  headRef,
+  originRef,
+  sessionBaseSha,
+  exemptSummaryFiles = [],
+}) {
+  const budgeted = budgetedFiles(
+    buildContext({ wikiRoot, today, fs }),
+    wikiRoot,
+  );
+  let outgoing;
+  let sessionBase = null;
+  let originTip = null;
+  try {
+    outgoing = await measureRef(showFile, headRef, budgeted);
+    if (sessionBaseSha) {
+      sessionBase = await measureRef(showFile, sessionBaseSha, budgeted);
+    }
+    originTip = await measureRef(showFile, originRef, budgeted);
+  } catch {
+    // Cannot prove a regression (unreadable ref) ⇒ do not refuse; fail-visible.
+    return { refusals: [], surfaced: [] };
+  }
+  return revalidateBudgets({
+    outgoing,
+    sessionBase,
+    originTip,
+    exemptSummaryFiles,
+  });
+}

package/src/cli-definition.js

@@ -10,6 +10,7 @@ import { runInboxCommand } from "./commands/inbox.js";
 import { runRotateCommand } from "./commands/rotate.js";
 import { runAuditCommand } from "./commands/audit.js";
 import { runFixCommand } from "./commands/fix.js";
+import { runLedgerCommand } from "./commands/ledger.js";
 
 /**
  * Build the `fit-wiki` libcli definition. Agent identity is never resolved from
@@ -105,7 +106,7 @@ export function createDefinition() {
           pr: { type: "string", description: "Optional PR id" },
           "expires-at": {
             type: "string",
-            description: "Override expiry ISO date (default claim+7d)",
+            description: "Override expiry ISO date (default claim+1d)",
           },
         },
       },
@@ -208,7 +209,7 @@ export function createDefinition() {
       {
         name: "refresh",
         description:
-          "Regenerate XmR and obstacle/experiment marker blocks in a storyboard",
+          "Regenerate storyboard XmR/marker blocks and clear expired MEMORY.md claims",
         args: ["storyboard-path"],
         argsUsage: "[storyboard-path]",
         handler: runRefreshCommand,
@@ -260,7 +261,15 @@ export function createDefinition() {
         name: "push",
         description: "Commit and push local wiki changes to the remote",
         handler: runPushCommand,
-        options: { ...wikiRootOpt },
+        options: {
+          ...wikiRootOpt,
+          paths: {
+            type: "string",
+            multiple: true,
+            description:
+              "Pathspec(s) limiting the write-set; omit to land the session's dirty set",
+          },
+        },
       },
       {
         name: "pull",
@@ -268,6 +277,47 @@ export function createDefinition() {
         handler: runPullCommand,
         options: { ...agentOpt, ...wikiRootOpt, ...todayOpt },
       },
+      {
+        name: "ledger",
+        description:
+          "Allocate collision-ledger ids at anchors and rebuild projections",
+        args: ["subcommand"],
+        argsUsage: "<allocate|rebuild|verify>",
+        handler: runLedgerCommand,
+        options: {
+          ...wikiRootOpt,
+          kind: {
+            type: "string",
+            description: "Allocation kind: occ | nm | fold | meta",
+          },
+          count: {
+            type: "string",
+            description: "How many ids to allocate (default 1)",
+          },
+          ids: {
+            type: "string",
+            description:
+              "Comma-separated ids to backfill an anchor for (instead of --count)",
+          },
+          event: {
+            type: "string",
+            description: "Durable key for the allocation (SHA or anchor id)",
+          },
+          note: {
+            type: "string",
+            description: "Free-text note for the anchor",
+          },
+          gapped: {
+            type: "boolean",
+            description:
+              "Render double-allocation losers as a gap, not a renumber",
+          },
+          issue: {
+            type: "string",
+            description: "Anchor issue number (default obstacle issue)",
+          },
+        },
+      },
     ],
     globalOptions: {
       help: { type: "boolean", short: "h", description: "Show this help" },

package/src/commands/claim.js

@@ -162,7 +162,9 @@ export async function runClaimCommand(ctx) {
     };
   }
   const today = options.today || currentDayIso(runtime);
-  const expires = options["expires-at"] || addDays(today, 7);
+  // Default expiry is claim+1 day: a claim is a short-lived "actively shipping
+  // this now" assertion, not a long lease. A run that outlives one day re-claims.
+  const expires = options["expires-at"] || addDays(today, 1);
   const memPath = memoryPath(runtime, options);
   const text = readMemory(runtime, memPath);
   const claim = {

package/src/commands/ledger.js

@@ -0,0 +1,208 @@
+import path from "node:path";
+import { resolveWikiRoot } from "../util/wiki-dir.js";
+import { renderAnchorBody, ANCHOR_KINDS } from "../ledger/anchor.js";
+import { readAnchors, DEFAULT_ANCHOR_ISSUE } from "../ledger/reader.js";
+import {
+  foldAnchors,
+  renderLedgerPage,
+  renderMemoryRow,
+  writeMemoryRowRegion,
+  readMemoryRowRegion,
+  extractProse,
+} from "../ledger/projection.js";
+
+const KIND_PREFIX = { occ: "#", nm: "NM", fold: "n=", meta: "M" };
+const LEDGER_FILE = "parallel-collision-ledger.md";
+const MEMORY_FILE = "MEMORY.md";
+
+/** Parse `owner/repo` from a remote URL (https or ssh form). */
+export function parseOwnerRepo(url) {
+  const m = url
+    .trim()
+    .replace(/\.wiki$/, "")
+    .match(/[/:]([^/:]+)\/([^/]+?)(?:\.wiki)?(?:\.git)?\/?$/);
+  if (!m) throw new Error(`ledger: cannot parse owner/repo from "${url}"`);
+  return { owner: m[1], repo: m[2].replace(/\.wiki$/, "") };
+}
+
+function nextFreeIds(fold, kind, count) {
+  const prefix = KIND_PREFIX[kind];
+  let max = 0;
+  for (const [label, record] of fold.assignments) {
+    if (record.anchor.kind !== kind) continue;
+    const n = Number.parseInt(label.replace(prefix, ""), 10);
+    if (Number.isFinite(n) && n > max) max = n;
+  }
+  const ids = [];
+  for (let i = 1; i <= count; i++) ids.push(`${prefix}${max + i}`);
+  return ids;
+}
+
+/** Read the ordered anchor sequence and fold it, resolving the repo slug. */
+async function loadFold({ gitClient, ghClient, wikiDir, issue }) {
+  const url = await gitClient.remoteGetUrl("origin", { cwd: wikiDir });
+  const { owner, repo } = parseOwnerRepo(url);
+  const anchors = await readAnchors(ghClient, {
+    owner,
+    repo,
+    issue,
+    cwd: wikiDir,
+  });
+  return { fold: foldAnchors(anchors), owner, repo };
+}
+
+async function allocate(env, options) {
+  const { runtime, ghClient } = env;
+  const kind = options.kind;
+  if (!ANCHOR_KINDS.has(kind)) {
+    return {
+      ok: false,
+      code: 2,
+      error: `ledger allocate: --kind must be one of ${[...ANCHOR_KINDS].join(", ")}`,
+    };
+  }
+  const event = options.event;
+  if (!event) {
+    return {
+      ok: false,
+      code: 2,
+      error: "ledger allocate: --event (SHA or anchor id) is required",
+    };
+  }
+  const { fold, owner, repo } = await loadFold(env);
+  // Backfill registers an anchor for ids that predate the anchor surface, named
+  // explicitly via --ids; their event keys already exist in history. A plain
+  // allocate mints the next free ids of the kind. The conflict detector at
+  // rebuild guards against double-registering an id that already has an anchor.
+  let ids;
+  if (options.ids) {
+    ids = options.ids
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const already = ids.filter((id) => fold.assignments.has(id));
+    if (already.length > 0) {
+      return {
+        ok: false,
+        code: 1,
+        error: `ledger allocate --backfill: already anchored: ${already.join(", ")}`,
+      };
+    }
+  } else {
+    const count = options.count ? Number.parseInt(options.count, 10) : 1;
+    ids = nextFreeIds(fold, kind, count);
+  }
+  const body = renderAnchorBody({ kind, ids, event, note: options.note ?? "" });
+  // The anchor publication is the allocation; no projection is written here.
+  // The printed ids are provisional — a rebuild over the published sequence is
+  // authoritative and resolves any concurrent interleave first-published-wins.
+  await ghClient.apiPost(
+    `repos/${owner}/${repo}/issues/${env.issue}/comments`,
+    { body },
+    { cwd: env.wikiDir },
+  );
+  runtime.proc.stdout.write(`${ids.join(" ")}\n`);
+  return { ok: true };
+}
+
+function readFileOrEmpty(runtime, filePath) {
+  return runtime.fsSync.existsSync(filePath)
+    ? runtime.fsSync.readFileSync(filePath, "utf-8")
+    : "";
+}
+
+function readLedgerPage(runtime, wikiDir) {
+  const ledgerPath = path.join(wikiDir, LEDGER_FILE);
+  return runtime.fsSync.existsSync(ledgerPath)
+    ? runtime.fsSync.readFileSync(ledgerPath, "utf-8")
+    : "";
+}
+
+/** Project the anchor record onto the ledger-page body, preserving cited prose. */
+async function project(env, options) {
+  const { runtime, wikiDir } = env;
+  const labelMode = options.gapped ? "gapped" : "renumber";
+  const { fold } = await loadFold(env);
+  const existing = readLedgerPage(runtime, wikiDir);
+  const prose = extractProse(existing);
+  const { body, missingProse } = renderLedgerPage(fold, prose, { labelMode });
+  return { fold, body, missingProse, existing };
+}
+
+async function rebuild(env, options) {
+  const { runtime, wikiDir } = env;
+  const { fold, body, missingProse } = await project(env, options);
+  runtime.fsSync.writeFileSync(path.join(wikiDir, LEDGER_FILE), body);
+  const memoryPath = path.join(wikiDir, MEMORY_FILE);
+  const memoryBody = readFileOrEmpty(runtime, memoryPath);
+  runtime.fsSync.writeFileSync(
+    memoryPath,
+    writeMemoryRowRegion(memoryBody, fold),
+  );
+  runtime.proc.stdout.write(
+    `rebuilt: ${fold.assignments.size} ids, ${fold.conflicts.length} double-allocation(s)\n`,
+  );
+  if (missingProse.length > 0) {
+    runtime.proc.stderr.write(
+      `warning: prose cites missing anchors: ${missingProse.join(", ")}\n`,
+    );
+  }
+  return { ok: true };
+}
+
+async function verify(env, options) {
+  const { runtime, wikiDir } = env;
+  const { fold, body, missingProse, existing } = await project(env, options);
+  const problems = [];
+  if (fold.conflicts.length > 0) {
+    problems.push(`${fold.conflicts.length} double-allocation(s)`);
+  }
+  if (missingProse.length > 0) {
+    problems.push(`prose citing missing anchors: ${missingProse.join(", ")}`);
+  }
+  if (existing.trim() !== body.trim()) {
+    problems.push("ledger page diverges from the anchor record");
+  }
+  const memoryBody = readFileOrEmpty(runtime, path.join(wikiDir, MEMORY_FILE));
+  const memoryRegion = readMemoryRowRegion(memoryBody);
+  if (memoryRegion === null) {
+    problems.push("MEMORY row region absent (run rebuild)");
+  } else if (memoryRegion.trim() !== renderMemoryRow(fold).trim()) {
+    problems.push("MEMORY row diverges from the anchor record");
+  }
+  if (problems.length === 0) {
+    runtime.proc.stdout.write("verify: clean\n");
+    return { ok: true };
+  }
+  runtime.proc.stderr.write(`verify: ${problems.join("; ")}\n`);
+  return { ok: false, code: 1 };
+}
+
+const SUBS = { allocate, rebuild, verify };
+
+/**
+ * `fit-wiki ledger <allocate|rebuild|verify>` — the allocation procedure that
+ * keeps identity off the merge-contested page. Allocation publishes an anchor
+ * comment to the obstacle issue with no projection write at allocation time;
+ * rebuild and verify project the anchor record onto the ledger page and MEMORY
+ * row, preserving anchor-cited prose.
+ */
+export async function runLedgerCommand(ctx) {
+  const { runtime, gitClient, ghClient } = ctx.deps;
+  const options = ctx.options ?? {};
+  const sub = ctx.args?.subcommand;
+  const handler = SUBS[sub];
+  if (!handler) {
+    return {
+      ok: false,
+      code: 2,
+      error: "ledger requires subcommand: allocate | rebuild | verify",
+    };
+  }
+  const wikiDir = resolveWikiRoot(runtime, options);
+  const issue = options.issue
+    ? Number.parseInt(options.issue, 10)
+    : DEFAULT_ANCHOR_ISSUE;
+  const env = { runtime, gitClient, ghClient, wikiDir, issue };
+  return handler(env, options);
+}

package/src/commands/refresh.js

@@ -10,8 +10,9 @@ import {
   TrackerQueryError,
   parseRepoSlug,
 } from "../issue-list-renderer.js";
+import { parseClaims, filterExpired, removeClaim } from "../active-claims.js";
 import { currentDayIso } from "../util/clock.js";
-import { resolveProjectRoot } from "../util/wiki-dir.js";
+import { resolveProjectRoot, resolveWikiRoot } from "../util/wiki-dir.js";
 
 function currentStoryboardRelPath(runtime) {
   return `wiki/storyboard-${yearMonth(currentDayIso(runtime))}.md`;
@@ -101,13 +102,42 @@ function readStoryboardOrNull(runtime, storyboardPath) {
   }
 }
 
-/** Re-render XmR chart blocks and issue-list blocks in a storyboard file. */
+// Drop every MEMORY.md `## Active Claims` row past its `expires_at`, writing the
+// trimmed table back in place. Refresh is the deterministic "freshen the wiki"
+// step, so clearing lapsed claims belongs here alongside the storyboard render;
+// it runs whether or not the storyboard has marker blocks to regenerate. The
+// write is local, mirroring the storyboard splice — the caller's push publishes
+// it. A missing wiki or claims table is a clean no-op.
+function clearExpiredClaims(runtime, options, today, logger) {
+  const memPath = path.join(resolveWikiRoot(runtime, options), "MEMORY.md");
+  if (!runtime.fsSync.existsSync(memPath)) return;
+  const text = runtime.fsSync.readFileSync(memPath, "utf-8");
+  const { expired } = filterExpired(parseClaims(text), today);
+  if (expired.length === 0) return;
+  let current = text;
+  for (const c of expired) {
+    const result = removeClaim(current, { agent: c.agent, target: c.target });
+    if (result.removed) current = result.text;
+  }
+  if (current !== text) {
+    runtime.fsSync.writeFileSync(memPath, current);
+    logger.info("refresh", `cleared ${expired.length} expired claim(s)`);
+  }
+}
+
+/**
+ * Re-render storyboard XmR/issue-list blocks and clear expired MEMORY.md claims.
+ */
 export async function runRefreshCommand(ctx) {
   const { runtime, gitClient } = ctx.deps;
   const options = ctx.options;
   const logger = createLogger("wiki", runtime);
   const projectRoot = resolveProjectRoot(runtime);
 
+  // Independent of the storyboard render below (and its early returns), so a
+  // wiki with no storyboard or no marker blocks still gets its claims swept.
+  clearExpiredClaims(runtime, options, currentDayIso(runtime), logger);
+
   const storyboardPath = path.resolve(
     projectRoot,
     ctx.args["storyboard-path"] || currentStoryboardRelPath(runtime),

package/src/commands/sync.js

@@ -19,9 +19,14 @@ export async function runPushCommand(ctx) {
   const { runtime, wikiSync } = ctx.deps;
   await wikiSync.inheritIdentity();
 
+  // A caller that knows its narrower write-set passes `--paths` (repeatable);
+  // the bare session-close invocation passes none and lands the session's own
+  // dirty set under per-session checkout isolation.
+  const paths = ctx.options?.paths?.length ? ctx.options.paths : undefined;
+
   let result;
   try {
-    result = await wikiSync.commitAndPush("wiki: update from session");
+    result = await wikiSync.commitAndPush("wiki: update from session", paths);
   } catch (err) {
     // Honest CLI contract (the honest-CLI contract): non-zero on any non-land push
     // failure, and on the ancestry guard's refusal (the ancestry guard). The Stop-hook