@erclx/canon 4.115.0 → 4.117.0

package/src/commands/sessions.ts

@@ -10,6 +10,11 @@ import {
   type SessionReport,
   selfOf,
 } from '@/sessions/resolve'
+import {
+  type Behind,
+  exportSession,
+  importSession,
+} from '@/sessions/transfer/bundle'
 import {
   intro,
   logInfo,
@@ -19,6 +24,7 @@ import {
   pipeOutput,
   plural,
 } from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
 
 interface ListCommandOptions {
   readonly json?: boolean
@@ -144,6 +150,222 @@ export function register(program: Command): void {
     .action(async (opts: ListCommandOptions) => {
       process.exitCode = await runList(opts)
     })
+
+  sessions
+    .command('export')
+    .description(
+      'Pack a session transcript, its side folder, and a manifest into one local bundle',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .argument('<id>', 'The sessionId to export')
+    .option(
+      '--out <path>',
+      'Write the bundle here rather than under .canon/tmp/session-export/',
+    )
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the bundle was written',
+        '  1  refused, with the reason on stderr and in the record',
+        '',
+        'The bundle is a gzip tarball on local disk and is never uploaded. It',
+        'holds whatever tool output passed through the session, so treat it as',
+        'private. Export runs no skill: write and push a handoff first where one',
+        'is wanted, and the manifest reports whether one was found and pushed.',
+        '',
+        'Refusal reasons: "not-found" (no transcript carries the id) and',
+        '"no-archive" (this Bun has no Bun.Archive).',
+        '',
+        'Examples:',
+        '  canon sessions export <id>',
+        '  canon sessions export <id> --out ~/session.tar.gz --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (id: string, opts: ExportCommandOptions) => {
+      process.exitCode = await runExport(id, opts)
+    })
+
+  sessions
+    .command('import')
+    .description(
+      'Place an exported session under this machine so claude can resume it',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .argument('<bundle>', 'The bundle an export wrote')
+    .option(
+      '--root <path>',
+      'The repository to resume in. Defaults to the main worktree',
+    )
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the session was placed, with any lag reported in "behind"',
+        '  1  refused, with the reason on stderr and in the record',
+        '',
+        'Refusal reasons: "not-a-bundle", "other-repository" (the origin',
+        'differs), "exists" (the transcript or side folder is already there),',
+        '"live-here" (the id is live on this machine), "write-failed" (a',
+        'write failed partway), and "no-archive". A failure partway removes',
+        'every file this run placed, and names any it could not remove.',
+        '',
+        '"behind" lists "repository-behind" when this checkout lacks the',
+        'exported HEAD, and "records-behind" when the records history lacks',
+        'the exported records commit, which canon records pull brings.',
+        '',
+        'Examples:',
+        '  canon sessions import session.tar.gz',
+        '  canon sessions import session.tar.gz --root ~/repos/canon --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (bundle: string, opts: ImportCommandOptions) => {
+      process.exitCode = await runImport(bundle, opts)
+    })
+}
+
+interface ExportCommandOptions {
+  readonly out?: string
+  readonly json?: boolean
+}
+
+interface ImportCommandOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
+/**
+ * Whether a session id is live in the local roster. An unreadable roster
+ * answers false, since the roster is advisory here and the manifest says so.
+ */
+async function isLiveHere(id: string): Promise<boolean> {
+  const report = await resolveSessions()
+  return (
+    report.kind === 'resolved' &&
+    report.sessions.some((session) => session.sessionId === id)
+  )
+}
+
+function writeRecord(json: boolean | undefined, record: object): void {
+  if (json) process.stdout.write(`${JSON.stringify(record)}\n`)
+}
+
+async function runExport(
+  id: string,
+  opts: ExportCommandOptions,
+): Promise<number> {
+  const outcome = await exportSession({
+    id,
+    out: opts.out ? resolve(opts.out) : undefined,
+    isLive: isLiveHere,
+  })
+
+  intro('canon sessions export')
+
+  if (!outcome.ok) {
+    logStep('Refused')
+    logWarn(outcome.message)
+    outro()
+    writeRecord(opts.json, { ...outcome, sessionId: id })
+    return 1
+  }
+
+  const { manifest } = outcome
+  logStep('Bundle')
+  logInfo(`Wrote ${outcome.path}`)
+  logInfo(`${plural(outcome.files.length, 'side file')} beside the transcript`)
+
+  if (manifest.live) {
+    logWarn(
+      'The session is live, so the copy stops at its last whole line and resuming elsewhere forks it.',
+    )
+  }
+
+  logStep('Handoff')
+  if (manifest.handoff === null) {
+    logInfo(
+      'No compact note since the session began, so resume the transcript.',
+    )
+  } else if (manifest.handoffCommitted) {
+    logInfo(`${manifest.handoff} is in the records history. Prefer it.`)
+  } else {
+    logWarn(
+      `${manifest.handoff} is not in the records history yet. Run canon records push so the other machine can pull it.`,
+    )
+  }
+  outro()
+
+  writeRecord(opts.json, {
+    ok: true,
+    path: outcome.path,
+    sessionId: id,
+    files: outcome.files,
+    manifest,
+  })
+  return 0
+}
+
+const BEHIND_REMEDIES: Record<Behind, string> = {
+  'repository-behind':
+    'This checkout lacks the exported HEAD. Fetch and check out the branch before resuming.',
+  'records-behind':
+    'The records history lacks the exported commit. Run canon records pull to bring the handoff.',
+}
+
+async function runImport(
+  bundle: string,
+  opts: ImportCommandOptions,
+): Promise<number> {
+  const root = opts.root ? resolve(opts.root) : await mainWorktreeRoot()
+  const outcome = await importSession({
+    bundle: resolve(bundle),
+    root,
+    isLive: isLiveHere,
+  })
+
+  intro('canon sessions import')
+
+  if (!outcome.ok) {
+    logStep('Refused')
+    logWarn(outcome.message)
+    outro()
+    writeRecord(opts.json, outcome)
+    return 1
+  }
+
+  logStep('Placed')
+  logInfo(outcome.transcript)
+  logInfo(
+    `Folder ${outcome.folder}, derived from ${root}. --continue looks there, and --resume finds the id in any folder.`,
+  )
+  for (const lag of outcome.behind) logWarn(BEHIND_REMEDIES[lag])
+
+  logStep('Resume')
+  logInfo(
+    outcome.manifest.recommend === 'handoff'
+      ? `Recommended: the handoff at ${outcome.manifest.handoff}, since the transcript carries the source machine's absolute paths.`
+      : 'Recommended: the transcript, since no handoff was written since the session began.',
+  )
+  for (const route of outcome.routes) logInfo(route)
+  outro()
+
+  writeRecord(opts.json, {
+    ok: true,
+    sessionId: outcome.manifest.sessionId,
+    folder: outcome.folder,
+    transcript: outcome.transcript,
+    files: outcome.files,
+    behind: outcome.behind,
+    routes: outcome.routes,
+    manifest: outcome.manifest,
+  })
+  return 0
 }
 
 async function runList(opts: ListCommandOptions): Promise<number> {

package/src/commands/teach.ts

@@ -393,9 +393,16 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
         'Reads a JSON array of blocks from stdin, each a heading, paragraph,',
-        'list, or raw block, and renders it through the same components the',
-        'fixture lesson is generated from. Content the three cannot express',
-        'takes type raw, carrying its own html verbatim, unescaped.',
+        'list, refs, or raw block, and renders it through the same components',
+        'the fixture lesson is generated from. Content the structured blocks',
+        'cannot express takes type raw, carrying its own html verbatim,',
+        'unescaped.',
+        '',
+        'A paragraph takes an optional cites array of reference numbers,',
+        'rendered as footnote markers after its text. The one refs block',
+        'lists { title, url?, note? } items numbered from 1, and a cite that',
+        'resolves to no item, a cite on a lede, or a second refs block is',
+        'refused. A url must be http or https.',
         '',
         'Takes no topic and no --root: the verb is a stateless transform,',
         'reading nothing off a workspace on disk.',
@@ -799,6 +806,7 @@ function reportNav(
         lessons: outcome.lessons,
         reference: outcome.reference,
         skipped: outcome.skipped,
+        unresolved: outcome.unresolved,
       })}\n`,
     )
     return 0
@@ -821,6 +829,13 @@ function reportNav(
     }
   }
 
+  if (outcome.unresolved.length > 0) {
+    logStep('Lesson references naming no lesson')
+    for (const reference of outcome.unresolved) {
+      logWarn(`${reference.file}: lesson ${reference.lesson}`)
+    }
+  }
+
   outro()
   return 0
 }

package/src/context/audit.ts

@@ -4,7 +4,7 @@ import { BARE_NAME, IGNORE_MARKER } from '@/context/citations'
 import type { AuditedFolder } from '@/context/folders'
 import type { NarrationTerms } from '@/context/narration'
 import { type BodyLine, bodyLines, maskDisplayed } from '@/markdown/scan'
-import { renderedHeight } from '@/markdown/structure'
+import { documentHeight } from '@/markdown/structure'
 import { isStubSeed } from '@/seed-marker'
 
 /**
@@ -214,9 +214,10 @@ export interface EntryReport {
   readonly rel: string
   /**
    * Rendered lines across the whole file, counting frontmatter and fenced
-   * blocks. It shares `renderedHeight` with the depth checkpoint in
-   * `src/markdown/structure.ts`, since the two sit in one section of the
-   * standard and a reader compares them.
+   * blocks. It counts through `documentHeight` in `src/markdown/structure.ts`,
+   * which shares `renderedHeight` with the depth checkpoint and with the
+   * document ceiling, since all three sit beside each other in the standard
+   * and a reader compares them.
    *
    * Fences are counted here and excluded there. The depth measure skips one so
    * an example cannot break the run around it, and a file measure has no run to
@@ -646,10 +647,7 @@ export function measureEntry(
 
   return {
     rel,
-    lines: source
-      .replace(/\n$/, '')
-      .split('\n')
-      .reduce((sum, text) => sum + renderedHeight(text), 0),
+    lines: documentHeight(source),
     catalogTables: catalogTables(lines),
     provenance: governsContent ? provenance(lines) : [],
     narration: governsContent && terms ? narration(lines, terms) : [],

package/src/gate/measures.ts

@@ -13,6 +13,9 @@ import {
   measureArchitecture,
 } from '@/context/architecture'
 import { listRepositoryFiles } from '@/git-files'
+import { ceilingFindings } from '@/markdown/ceiling'
+import { resolveMarkdown } from '@/markdown/files'
+import { CHECKPOINTS } from '@/markdown/structure'
 import {
   isShippedCorpus,
   REFERENCE_MARKER,
@@ -21,6 +24,7 @@ import {
   type ShippedReference,
 } from '@/shipped/references'
 import { surfaceDir } from '@/surface-root'
+import { plural } from '@/ui'
 import {
   README_PARAPHRASE_MARKER,
   readmeCitationsIn,
@@ -273,6 +277,62 @@ export const architectureRecord: Measure = async (ctx) => {
   }
 }
 
+/**
+ * Every tracked markdown document against the whole-document ceiling.
+ *
+ * Report-only for now: a document past the ceiling warns and the stage still
+ * passes, since the corpus carried dozens past it when the stage landed. The
+ * flip to a failure is a separate change once the count reads zero, and it
+ * replaces the warn path rather than sitting beside it.
+ *
+ * Read in-process rather than through `canon markdown audit`, whose exit code
+ * stays bans and dead links only. The plan and groundwork skills run that audit
+ * on a gitignored record, and a gating length there would fail every long plan.
+ */
+export const documentCeiling: Measure = async (ctx) => {
+  const scope = await resolveMarkdown(ctx.root, [])
+  if (scope.kind === 'unavailable') {
+    return {
+      emissions: [],
+      unmeasured: 'git could not list the tree, so no document was measured.',
+    }
+  }
+
+  const documents = scope.files.flatMap((rel) => {
+    try {
+      return [{ rel, source: readFileSync(join(ctx.root, rel), 'utf8') }]
+    } catch {
+      return []
+    }
+  })
+  const findings = ceilingFindings(documents)
+  const over = findings.filter((finding) => finding.exempt === null)
+  const exempt = findings.length - over.length
+  const ceiling = CHECKPOINTS.ceiling
+
+  if (over.length === 0) {
+    const exemptNote = exempt > 0 ? `, ${exempt} exempt` : ''
+    return {
+      emissions: [
+        info(
+          `No document past the ${ceiling}-line ceiling across ${plural(documents.length, 'markdown file')}${exemptNote}`,
+        ),
+      ],
+    }
+  }
+
+  return {
+    emissions: [
+      ...over.map((finding) =>
+        warn(`${finding.rel}  ${finding.renderedLines} rendered lines`),
+      ),
+      info(
+        `${plural(over.length, 'document')} past the ${ceiling}-line ceiling, ${exempt} exempt. Reported only, so the push is not held.`,
+      ),
+    ],
+  }
+}
+
 /**
  * A second run of the records move should rewrite nothing, and the count is
  * only knowable once the folders themselves have landed.

package/src/gate/stages.ts

@@ -3,6 +3,7 @@ import {
   auditSet,
   captureStamps,
   clientCommandCitations,
+  documentCeiling,
   markdownBans,
   type Measure,
   pluginManifests,
@@ -333,9 +334,11 @@ export const STAGES: readonly Stage[] = [
     checks: [{ kind: 'measure', measure: unreferencedRules }],
   },
   {
-    // Only the citation half of the audit gates. Length, depth, table, and
+    // Only the citation half of the audit gates. Its length, depth, table, and
     // index findings are judgment thresholds, and failing a push on one would
-    // make the stage something to route around.
+    // make the stage something to route around. The one length reading that
+    // will gate is the whole-document ceiling, which the Document ceiling stage
+    // below owns rather than this audit.
     id: 'context-citations',
     label: 'Context citations',
     checks: [
@@ -355,6 +358,13 @@ export const STAGES: readonly Stage[] = [
     label: 'Architecture record',
     checks: [{ kind: 'measure', measure: architectureRecord }],
   },
+  {
+    // Unscoped, since any branch can grow any document. It warns and passes
+    // until the corpus sits under the ceiling, then flips to a failure.
+    id: 'document-ceiling',
+    label: 'Document ceiling',
+    checks: [{ kind: 'measure', measure: documentCeiling }],
+  },
   {
     // A rule citing a file that moved fails silently. The consumed-copy drift
     // stage passes an authored rule and its copy that are wrong together, and

package/src/markdown/ceiling.ts

@@ -0,0 +1,70 @@
+import { basename } from 'node:path'
+import { bodyLines } from '@/markdown/scan'
+import { CHECKPOINTS, documentHeight } from '@/markdown/structure'
+
+/**
+ * The marker exempting one document from the ceiling, written as a whole line
+ * outside a fence and naming a reason.
+ *
+ * The whole line rather than anywhere on it, so a standard quoting the marker
+ * inside a code span to document it does not exempt itself. A marker with no
+ * reason does not count, for the reason `isMarked` in `src/exempt-marker.ts`
+ * gives: a bare token reads as a line that meant to say something and did not.
+ */
+const EXEMPT_MARKER = /^<!--\s*canon-length-exempt:[ \t]*(\S.*?)\s*-->$/
+
+/**
+ * A changelog is exempt by name because the release tool rewrites it and would
+ * not keep a marker in place. A committed list of exempt paths was the
+ * alternative, and it turns every rename into a second edit with nothing to
+ * check the list against the tree.
+ */
+const CHANGELOG = 'CHANGELOG.md'
+const CHANGELOG_REASON = 'CHANGELOG.md is written by the release tool'
+
+export interface CeilingDocument {
+  readonly rel: string
+  readonly source: string
+}
+
+export interface CeilingFinding {
+  readonly rel: string
+  readonly renderedLines: number
+  /** The stated reason, or null where the document is not exempt. */
+  readonly exempt: string | null
+}
+
+/** The reason a document is exempt from the ceiling, or null where it is not. */
+export function lengthExemption(rel: string, source: string): string | null {
+  if (basename(rel) === CHANGELOG) return CHANGELOG_REASON
+
+  for (const line of bodyLines(source)) {
+    if (line.fenced) continue
+    const match = EXEMPT_MARKER.exec(line.text.trim())
+    if (match) return match[1]
+  }
+
+  return null
+}
+
+/**
+ * Every document past the ceiling, longest first, exempt ones included with
+ * their reason so a report can count them rather than hide them.
+ */
+export function ceilingFindings(
+  documents: readonly CeilingDocument[],
+): CeilingFinding[] {
+  return documents
+    .map(({ rel, source }) => ({
+      rel,
+      renderedLines: documentHeight(source),
+      source,
+    }))
+    .filter(({ renderedLines }) => renderedLines > CHECKPOINTS.ceiling)
+    .map(({ rel, renderedLines, source }) => ({
+      rel,
+      renderedLines,
+      exempt: lengthExemption(rel, source),
+    }))
+    .sort((a, b) => b.renderedLines - a.renderedLines)
+}

package/src/markdown/structure.ts

@@ -116,6 +116,7 @@ export const CHECKPOINTS = {
   cadence: 3,
   spread: 5,
   opener: 2,
+  ceiling: 300,
 } as const
 
 /**
@@ -167,6 +168,11 @@ export interface Checkpoints {
   readonly spread: number
   /** Times one opening word may open a sentence in a paragraph before it is a pattern. */
   readonly opener: number
+  /**
+   * Rendered lines a whole document may reach, read by the Document ceiling
+   * gate stage rather than by any exit code of the audit.
+   */
+  readonly ceiling: number
 }
 
 export interface BulletFinding {
@@ -247,6 +253,22 @@ export function renderedHeight(text: string, width = RENDER_WIDTH): number {
   return Math.max(1, Math.ceil(visibleText(text).length / width))
 }
 
+/**
+ * Height a whole source occupies once wrapped, frontmatter and fenced blocks
+ * included.
+ *
+ * Nothing is excluded because a session pays for every line it loads, which is
+ * what separates this from the depth measure. The context audit's length
+ * reading and the document ceiling both count through here, so the two report
+ * one unit.
+ */
+export function documentHeight(source: string, width = RENDER_WIDTH): number {
+  return source
+    .replace(/\n$/, '')
+    .split('\n')
+    .reduce((sum, text) => sum + renderedHeight(text, width), 0)
+}
+
 /**
  * Reports whether a run is the peer list the standard exempts.
  *

package/src/records/backup.ts

@@ -318,7 +318,7 @@ function failed(action: string, result: GitResult): BackupRefused {
  * as written passes a records origin that publishes the payload through the
  * other protocol.
  */
-function remoteIdentity(url: string): string {
+export function remoteIdentity(url: string): string {
   return url
     .trim()
     .toLowerCase()

package/src/sandbox/census.ts

@@ -69,7 +69,7 @@ export function listSkills(root: string): string[] {
 /**
  * Maps a scenario to the skill it drives, trying two spellings in order.
  *
- * `<category>-<command>` is the rule `canon/context/sandbox/coverage.md` states, and it
+ * `<category>-<command>` is the rule `canon/context/sandbox/coverage/census.md` states, and it
  * alone pairs 29 of 54 skills. The bare `<command>` fallback is what reaches the
  * rest: `claude/target-setup.sh` drives the `target-setup` skill, not a `claude-target-setup` that
  * does not exist. Stating one spelling and shipping two is what let the audit

package/src/sessions/registry.ts

@@ -48,19 +48,23 @@ export interface SessionRecord {
 }
 
 /**
- * Resolves the folder holding one file per session.
+ * Resolves the client's configuration directory, which holds both the session
+ * registry and the projects folder a transcript lives in.
  *
  * `CLAUDE_CONFIG_DIR` comes first because a client honouring it writes its
  * records nowhere near the home directory, and a read that ignored it would
  * report an empty roster on a machine running sessions.
  */
-export function registryDir(): string {
+export function claudeConfigDir(): string {
   const configured = process.env.CLAUDE_CONFIG_DIR
-  const base =
-    configured && configured.length > 0
-      ? configured
-      : join(homedir(), '.claude')
-  return join(base, 'sessions')
+  return configured && configured.length > 0
+    ? configured
+    : join(homedir(), '.claude')
+}
+
+/** Resolves the folder holding one file per session. */
+export function registryDir(): string {
+  return join(claudeConfigDir(), 'sessions')
 }
 
 /**