@erclx/canon 5.44.0 → 5.46.0

package/src/records/backup.ts

@@ -107,9 +107,9 @@ export const EXCLUDED_ENTRIES = [
 /**
  * Whether a top-level name stays out of every push, at either root.
  *
- * `SCRATCH` is the legacy `.tmp` spelling, which a records index opened before
- * the move can still carry and which `EXCLUDED_ENTRIES` names at its `.canon`
- * spelling only.
+ * `SCRATCH` is the retired `.tmp` spelling. It is a guard rather than a lookup,
+ * keeping a stray `.tmp` out of a push, and `EXCLUDED_ENTRIES` names the
+ * `.canon` spelling only.
  */
 function isExcluded(name: string): boolean {
   return (

package/src/records/validate.ts

@@ -228,9 +228,9 @@ const PLAN_REQUIRED: readonly PlanSection[] = [
 ]
 
 /**
- * The files whose edit changes what a person sees, the set the `ui/a11y` rule
- * globs plus the other markup and style extensions a plan names. A plan touching
- * one owes a `Design references` section, so a set too wide forces it on every
+ * The files whose edit changes what a person sees, the set the `ui/a11y` and
+ * `ui/keyboard` rules glob plus the other markup and style extensions a plan
+ * names. A plan touching one owes a `Design references` section, so a set too wide forces it on every
  * plan and one too narrow lets a UI plan skip it.
  */
 const RENDERED_SURFACE = /\.(?:tsx|jsx|astro|vue|svelte|html|css|scss)$/

package/src/roots/record.ts

@@ -29,17 +29,22 @@ export type RecordRoot = (typeof RECORD_ROOTS)[number]
 export const CREATION_ROOT: RecordRoot = '.canon'
 
 /**
- * The deletable scratch folder, named at the spelling `.claude/` gives it.
+ * The deletable scratch folder, named at the spelling `.claude/` gave it.
  *
- * It is the one folder whose name differs by root, and callers name it at the
- * old spelling because `spell` is the only place the variant is decided. Inside
- * a dotted root the leading dot hides nothing already hidden and costs a bare
- * `ls` that omits the folder, so the move dropped it. Every other record folder
- * keeps its name, `.records.git` included, where the dot marks the mechanism
- * apart from a payload rather than hiding it.
+ * Scratch resolves at `.canon/tmp` only. The `.claude/.tmp` spelling is a
+ * migration source, named through `LEGACY_SCRATCH_REL` by the verbs that move
+ * it, and no lookup falls back to it. Callers still name the folder at this
+ * spelling because `spell` is the only place the variant is decided. Inside a
+ * dotted root the leading dot hides nothing already hidden and costs a bare
+ * `ls` that omits the folder, so the move dropped it. Every other record
+ * folder keeps its name, `.records.git` included, where the dot marks the
+ * mechanism apart from a payload rather than hiding it.
  */
 export const SCRATCH = '.tmp'
 
+/** The retired scratch location, read only as the source of a migration. */
+export const LEGACY_SCRATCH_REL = '.claude/.tmp' // canon-keep-record-root
+
 /** The scratch folder's name under `.canon/`. */
 const CANON_SCRATCH = 'tmp'
 
@@ -109,6 +114,8 @@ export function spell(root: RecordRoot, folder: string): string {
  * records it belongs to rather than at the creation default.
  */
 function rootOf(root: string, folder: string): RecordRoot {
+  if (folder === SCRATCH) return CREATION_ROOT
+
   return (
     RECORD_ROOTS.find((candidate) =>
       existsSync(join(root, candidate, spell(candidate, folder))),
@@ -147,7 +154,9 @@ export function recordDirs(
   folder: string,
   ...rest: string[]
 ): string[] {
-  return RECORD_ROOTS.map((candidate) =>
+  const candidates = folder === SCRATCH ? [CREATION_ROOT] : RECORD_ROOTS
+
+  return candidates.map((candidate) =>
     join(root, candidate, spell(candidate, folder), ...rest),
   )
 }

package/src/sessions/claim.ts

@@ -19,6 +19,12 @@ export interface ClaimReport {
   readonly refs: readonly string[]
   /** False when the session roster could not be read, so `claimed` covers the readings around it alone and cannot be trusted as a clean "unclaimed". */
   readonly sessionsReadable: boolean
+  /**
+   * Foreign-namespace records whose socket is gone. They read dead, so a branch
+   * one of them holds can read unclaimed, which a caller with a count above
+   * zero should treat as unverified.
+   */
+  readonly foreignDead: number
   /** False when the ref read failed, which is the same false clean under a different reading. */
   readonly refsReadable: boolean
 }
@@ -80,6 +86,7 @@ export async function checkClaim(
     sessions,
     refs: refs.refs,
     sessionsReadable: report.kind === 'resolved',
+    foreignDead: report.kind === 'resolved' ? report.foreignDead : 0,
     refsReadable: refs.readable,
   }
 }

package/src/sessions/live.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync, readlinkSync } from 'node:fs'
 import type { SessionRecord } from '@/sessions/registry'
 
 /**
@@ -7,13 +7,19 @@ import type { SessionRecord } from '@/sessions/registry'
  * `confirmed` means the running process was matched against the start time the
  * record stamped, so the pid belongs to the session that wrote the file.
  * `unverified` means the pid answers a signal probe and nothing more, which
- * cannot separate the original session from whatever inherited its pid.
+ * cannot separate the original session from whatever inherited its pid, or,
+ * for a `foreign` row, that its messaging socket still exists.
  */
 export type Confidence = 'confirmed' | 'unverified'
 
 export interface Liveness {
   readonly alive: boolean
   readonly confidence: Confidence
+  /**
+   * Set only when the record belongs to another pid namespace, so the pid was
+   * never probed. Absent rather than false on every other path.
+   */
+  readonly foreign?: true
 }
 
 export interface LivenessProbes {
@@ -21,6 +27,14 @@ export interface LivenessProbes {
   readonly procStartOf: (pid: number) => string | null
   /** Whether the pid answers at all, ignoring which process holds it. */
   readonly responds: (pid: number) => boolean
+  /**
+   * The reader's own pid namespace in `pid:[inode]` form, or null where it
+   * cannot be read. Optional so a caller with no use for the foreign branch,
+   * such as the gate's lock, states nothing and takes the pid path.
+   */
+  readonly ownDomain?: () => string | null
+  /** Whether the messaging socket a foreign record names still exists. */
+  readonly socketExists?: (path: string) => boolean
 }
 
 /**
@@ -51,7 +65,21 @@ function responds(pid: number): boolean {
   }
 }
 
-export const SYSTEM_PROBES: LivenessProbes = { procStartOf, responds }
+/** The link target reads `pid:[inode]`, which a record's `pidDomain` ends with. */
+function ownDomain(): string | null {
+  try {
+    return readlinkSync('/proc/self/ns/pid')
+  } catch {
+    return null
+  }
+}
+
+export const SYSTEM_PROBES: LivenessProbes = {
+  procStartOf,
+  responds,
+  ownDomain,
+  socketExists: existsSync,
+}
 
 /**
  * Decides whether a record describes a session that is still running.
@@ -62,13 +90,32 @@ export const SYSTEM_PROBES: LivenessProbes = { procStartOf, responds }
  * probe alone stands, and every surviving row is marked so a caller never reads
  * a recycled pid as a confirmed identity.
  *
- * It reads two fields and asks for no more, so a record that is not a session,
- * such as the gate's machine lock, carries the same proof.
+ * A record from another pid namespace is judged first, on its messaging
+ * socket, because its pid names nothing in this namespace and either probe
+ * would read an unrelated process or none. That answer is always `unverified`,
+ * since a crashed session leaves its socket behind.
+ *
+ * The pid and start time are the only fields the rest needs, so a record that
+ * is not a session, such as the gate's machine lock, carries the same proof and
+ * takes the pid path for want of a `pidDomain`.
  */
 export function liveness(
-  record: Pick<SessionRecord, 'pid' | 'procStart'>,
+  record: Pick<SessionRecord, 'pid' | 'procStart'> &
+    Partial<Pick<SessionRecord, 'pidDomain' | 'messagingSocketPath'>>,
   probes: LivenessProbes = SYSTEM_PROBES,
 ): Liveness {
+  const own = probes.ownDomain?.() ?? null
+  if (
+    own !== null &&
+    record.pidDomain !== undefined &&
+    !record.pidDomain.endsWith(own)
+  ) {
+    const socket = record.messagingSocketPath
+    const alive =
+      socket !== undefined && (probes.socketExists?.(socket) ?? false)
+    return { alive, confidence: 'unverified', foreign: true }
+  }
+
   const started = record.procStart
 
   if (started !== undefined && started.length > 0) {

package/src/sessions/registry.ts

@@ -45,6 +45,17 @@ export interface SessionRecord {
    * been handed to something else.
    */
   readonly procStart: string | undefined
+  /**
+   * The pid namespace the client stamped, ending in the `pid:[inode]` form that
+   * `/proc/self/ns/pid` reads as. A reader in another namespace cannot see the
+   * record's pid, so this is what tells a foreign row from a dead one.
+   */
+  readonly pidDomain: string | undefined
+  /**
+   * The socket the session listens on for messages. It is the only evidence of
+   * life a foreign-namespace reader can reach, since the pid is out of sight.
+   */
+  readonly messagingSocketPath: string | undefined
 }
 
 /**

package/src/sessions/resolve.ts

@@ -22,6 +22,12 @@ export interface ResolvedSession {
   readonly cwd: string
   readonly kind: string
   readonly status: string
+  /**
+   * What decided the row was live. `socket` means the record belongs to another
+   * pid namespace and only its messaging socket answered, so the row can be a
+   * crashed session's leftover and no start time backs it.
+   */
+  readonly via: 'pid' | 'socket'
   readonly startedAt: string | null
   /**
    * The stamp the record carries beside `status`, kept alongside the dwell it
@@ -64,6 +70,13 @@ export type SessionReport =
        * tells a caller whether the roster can be trusted as an identity.
        */
       readonly confidence: Confidence
+      /**
+       * Foreign-namespace records whose socket is gone. They read dead, but the
+       * reader could not check their pid, so an empty roster beside a count
+       * above zero is a roster that could not be checked rather than one that
+       * ended.
+       */
+      readonly foreignDead: number
       readonly sessions: readonly ResolvedSession[]
     }
 
@@ -167,6 +180,7 @@ function present(
   record: SessionRecord,
   located: Located,
   now: number,
+  via: ResolvedSession['via'],
 ): ResolvedSession {
   return {
     name: record.name,
@@ -175,6 +189,7 @@ function present(
     cwd: record.cwd,
     kind: record.kind ?? 'unknown',
     status: record.status ?? 'unknown',
+    via,
     startedAt:
       record.startedAt === undefined
         ? null
@@ -213,21 +228,33 @@ export async function resolveSessions(
 
   if (registry.kind === 'absent') return { kind: 'absent', dir: registry.dir }
 
-  const live: SessionRecord[] = []
+  const live: { record: SessionRecord; via: ResolvedSession['via'] }[] = []
   let confidence: Confidence = 'confirmed'
+  let foreignDead = 0
 
   for (const record of registry.records) {
     const state = liveness(record, probes)
-    if (!state.alive) continue
+    if (!state.alive) {
+      if (state.foreign) foreignDead += 1
+      continue
+    }
     if (state.confidence === 'unverified') confidence = 'unverified'
-    live.push(record)
+    live.push({ record, via: state.foreign ? 'socket' : 'pid' })
   }
 
   const sessions = await Promise.all(
-    live.map(async (record) => present(record, await find(record.cwd), now)),
+    live.map(async ({ record, via }) =>
+      present(record, await find(record.cwd), now, via),
+    ),
   )
 
-  return { kind: 'resolved', dir: registry.dir, confidence, sessions }
+  return {
+    kind: 'resolved',
+    dir: registry.dir,
+    confidence,
+    foreignDead,
+    sessions,
+  }
 }
 
 /** The environment slice the caller's own identity is read from. */

package/src/tasks/closes.ts

@@ -0,0 +1,136 @@
+import { readFile } from 'node:fs/promises'
+import {
+  fenceMask,
+  readOutcomes,
+  readPendingBranches,
+  readPullRequest,
+} from '@/tasks/archive'
+import {
+  openTask,
+  type RecordRefused,
+  type RecordSelector,
+} from '@/tasks/record'
+
+/**
+ * Why a task does or does not close its issues. `last-slice` is the only
+ * reason that closes. The rest mirror the conditions `archiveTask` applies at
+ * merge time, so an issue closes exactly when the task archives.
+ */
+export type ClosingReason =
+  | 'earlier-slice'
+  | 'last-slice'
+  | 'lookup-failed'
+  | 'no-issues'
+  | 'no-outcomes'
+  | 'open-outcomes'
+  | 'pending-branch'
+
+export interface Closure {
+  readonly issues: readonly number[]
+  readonly closing: boolean
+  readonly reason: ClosingReason
+}
+
+export interface TaskClosure extends Closure {
+  readonly ok: true
+  readonly stem: string
+  readonly path: string
+}
+
+export type ClosureOutcome = TaskClosure | RecordRefused
+
+const ISSUE_LINE = /^Issue:[ \t]*(#\d+(?:[ \t]*,[ \t]*#\d+)*)[ \t]*$/
+
+/**
+ * Reads every `Issue:` line outside a fence, each a bare `#NNN` or a comma
+ * list of them. A line carrying anything else, such as the older bare-path
+ * form, names no issue rather than the numbers that happened to parse, since a
+ * wrong number would close an unrelated issue.
+ */
+export function readIssues(text: string): readonly number[] {
+  const lines = text.split('\n')
+  const fenced = fenceMask(lines)
+  const issues = new Set<number>()
+
+  for (const [index, line] of lines.entries()) {
+    if (fenced[index]) continue
+
+    const match = ISSUE_LINE.exec(line)
+    if (!match) continue
+
+    for (const entry of match[1].split(',')) {
+      issues.add(Number(entry.trim().slice(1)))
+    }
+  }
+
+  return [...issues]
+}
+
+/**
+ * Decides whether the pull request for `branches` closes the task's issues.
+ * `branches` is the working branch and every name it carried, since a rename
+ * leaves the `Pending branch:` marker under the old one. Any other pending
+ * branch is a slice still to ship, so the task stays open behind it.
+ */
+export function decideClosing(
+  text: string,
+  branches: readonly string[],
+  pulls: readonly number[] | null = [],
+): Closure {
+  const issues = readIssues(text)
+  if (issues.length === 0) {
+    return { issues, closing: false, reason: 'no-issues' }
+  }
+
+  const listed = readPullRequest(text)
+  const last = listed.at(-1)
+
+  // A failed lookup cannot rule out that this branch is an earlier slice, and
+  // closing early is the unsafe direction. With nothing recorded yet there is
+  // no earlier slice to confuse it with, so that case still closes.
+  if (pulls === null && listed.length > 0) {
+    return { issues, closing: false, reason: 'lookup-failed' }
+  }
+
+  if (
+    last !== undefined &&
+    pulls !== null &&
+    !pulls.includes(last) &&
+    pulls.some((number) => listed.includes(number))
+  ) {
+    return { issues, closing: false, reason: 'earlier-slice' }
+  }
+
+  const others = readPendingBranches(text).filter(
+    (branch) => !branches.includes(branch),
+  )
+  if (others.length > 0) {
+    return { issues, closing: false, reason: 'pending-branch' }
+  }
+
+  const { open, closed, cut } = readOutcomes(text)
+  if (open.length > 0) {
+    return { issues, closing: false, reason: 'open-outcomes' }
+  }
+
+  if (closed.length === 0 && cut.length === 0) {
+    return { issues, closing: false, reason: 'no-outcomes' }
+  }
+
+  return { issues, closing: true, reason: 'last-slice' }
+}
+
+/** Resolves the task through the same selector `pull-request` takes. */
+export async function readClosure(
+  root: string,
+  selector: RecordSelector,
+  branches: readonly string[],
+  pulls: readonly number[] | null = [],
+): Promise<ClosureOutcome> {
+  const opened = await openTask(root, selector)
+  if ('ok' in opened) return opened
+
+  const text = await readFile(opened.path, 'utf8')
+
+  return { ok: true, ...opened, ...decideClosing(text, branches, pulls) }
+}

package/src/tasks/record.ts

@@ -400,7 +400,7 @@ async function resolveStem(
   return matched[0]
 }
 
-async function openTask(
+export async function openTask(
   root: string,
   selector: RecordSelector,
 ): Promise<{ readonly stem: string; readonly path: string } | RecordRefused> {

package/src/tooling/inject.ts

@@ -16,6 +16,8 @@ import {
 import {
   applyScripts,
   collectDeps,
+  declaresInstalls,
+  minimalPackage,
   readPackage,
   serializePackage,
 } from '@/tooling/package'
@@ -156,15 +158,22 @@ export async function pruneGitignore(
 
 /**
  * Installs missing dev dependencies, fills package scripts, and merges
- * gitignore entries. A target with no package.json gets the gitignore alone,
- * plus a warning naming every install it skipped, since seeding a package.json
- * would pick a package manager and a project name on the target's behalf.
+ * gitignore entries. A target with no package.json gets a minimal one first
+ * when the chain installs anything. A package.json that exists but cannot be
+ * parsed is never rewritten, and the install is skipped with a warning.
  */
 export async function injectManifest(
   chain: readonly Manifest[],
   target: string,
 ): Promise<void> {
   const packagePath = join(target, 'package.json')
+
+  if (!existsSync(packagePath) && declaresInstalls(chain)) {
+    logStep('Writing package.json')
+    await writeFile(packagePath, serializePackage(minimalPackage(target)))
+    logAdd('package.json')
+  }
+
   const pkg = readPackage(packagePath)
 
   if (pkg) {
@@ -192,14 +201,22 @@ export async function injectManifest(
 
   await injectGitignore(chain, target)
 
-  if (!pkg) warnSkippedInstalls(chain, target)
+  if (!pkg) warnUnreadablePackage(chain, target)
 }
 
-function warnSkippedInstalls(chain: readonly Manifest[], target: string): void {
+/**
+ * Only an existing package.json that fails to parse reaches here with installs
+ * pending, since an absent one was written above. It is left untouched.
+ */
+function warnUnreadablePackage(
+  chain: readonly Manifest[],
+  target: string,
+): void {
+  if (!declaresInstalls(chain)) return
+
   const deps = collectDeps(chain, {}).map((dep) => dep.spec)
   const skipped = applyScripts({}, chain)
   const scripts = [...new Set([...skipped.added, ...skipped.overridden])]
-  if (deps.length === 0 && scripts.length === 0) return
 
   logStep('Skipped installs')
   if (deps.length > 0) {
@@ -208,5 +225,7 @@ function warnSkippedInstalls(chain: readonly Manifest[], target: string): void {
   if (scripts.length > 0) {
     logWarn(`Scripts not added: ${scripts.join(', ')}`)
   }
-  logWarn(`No package.json: run 'bun init' in ${target}, then sync again`)
+  logWarn(
+    `package.json is not valid JSON: fix it in ${target}, then sync again`,
+  )
 }

package/src/tooling/package.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
+import { basename } from 'node:path'
 import type { Manifest } from '@/tooling/manifest'
 
 export interface PackageJson {
@@ -28,6 +29,37 @@ export function readPackage(path: string): PackageJson | undefined {
   }
 }
 
+/**
+ * Whether the chain asks for any dev dependency or script, which is what makes
+ * a missing package.json worth writing. A stack that installs nothing, such as
+ * the one `canon claude` drives, leaves a project without a manifest alone.
+ */
+export function declaresInstalls(chain: readonly Manifest[]): boolean {
+  if (collectDeps(chain, {}).length > 0) return true
+
+  const scripts = applyScripts({}, chain)
+  return scripts.added.length > 0 || scripts.overridden.length > 0
+}
+
+/**
+ * The manifest a sync writes into a folder that has none. The name is the
+ * folder's, reduced to the characters npm accepts, so it is never empty or
+ * invalid.
+ */
+export function minimalPackage(target: string): PackageJson {
+  const name = basename(target)
+    .toLowerCase()
+    .replace(/[^a-z0-9-._]/g, '-')
+    .replace(/^[._]+/, '')
+    .slice(0, 214)
+
+  return {
+    name: name === '' ? 'project' : name,
+    version: '0.0.0',
+    type: 'module',
+  }
+}
+
 export function serializePackage(pkg: PackageJson): string {
   return `${JSON.stringify(pkg, null, 2)}\n`
 }

package/src/tooling/read.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { PROJECT_ROOT } from '@/roots/project'
+import { configFiles, type Manifest, seedFiles } from '@/tooling/manifest'
 
 /**
  * Spells the package root in a report where every other root spells a
@@ -11,6 +12,8 @@ import { PROJECT_ROOT } from '@/roots/project'
 const PACKAGE_LABEL = '<canon>'
 
 export interface ReferenceRoot {
+  /** The root whose `tooling/` this searches, as the manifest loader takes it. */
+  readonly root: string
   /** Absolute `tooling/` directory to search. */
   readonly dir: string
   /** How a report spells a copy found under this root. */
@@ -19,6 +22,8 @@ export interface ReferenceRoot {
 
 export interface ResolvedReference {
   readonly path: string
+  /** The root that won, so the manifest is read from the same copy. */
+  readonly root: string
   /** The label of the root that won, joined to the stack and filename. */
   readonly source: string
 }
@@ -36,8 +41,9 @@ function toolingSourceDir(root: string): string {
  */
 export function referenceRoots(root: string): ReferenceRoot[] {
   return [
-    { dir: toolingSourceDir(root), label: 'tooling' },
+    { root, dir: toolingSourceDir(root), label: 'tooling' },
     {
+      root: PROJECT_ROOT,
       dir: toolingSourceDir(PROJECT_ROOT),
       label: join(PACKAGE_LABEL, 'tooling'),
     },
@@ -49,10 +55,10 @@ export function resolveReference(
   root: string,
   stack: string,
 ): ResolvedReference | undefined {
-  for (const { dir, label } of referenceRoots(root)) {
+  for (const { root: owner, dir, label } of referenceRoots(root)) {
     const path = join(dir, stack, 'reference.md')
     if (existsSync(path)) {
-      return { path, source: join(label, stack, 'reference.md') }
+      return { path, root: owner, source: join(label, stack, 'reference.md') }
     }
   }
 
@@ -62,3 +68,40 @@ export function resolveReference(
 export function readReference(reference: ResolvedReference): string {
   return readFileSync(reference.path, 'utf8')
 }
+
+function codeList(items: readonly string[]): string {
+  return items.map((item) => `- \`${item}\``).join('\n')
+}
+
+/**
+ * The sections the verb prints after a stack's reference, read from its
+ * manifest so no reference keeps a hand list that drifts from it. A stack lists
+ * its own files and groups alone, since a parent's print under the parent's
+ * reference, and a section with nothing to list prints no heading.
+ */
+export function renderStackSections(manifest: Manifest): string {
+  const sections: string[] = []
+  const configs = configFiles(manifest)
+  const seeds = seedFiles(manifest)
+
+  if (configs.length > 0 || seeds.length > 0) {
+    const sync = ['## Sync']
+    if (configs.length > 0) {
+      sync.push('Sync keeps these current, from `configs/`:', codeList(configs))
+    }
+    if (seeds.length > 0) {
+      sync.push('Sync copies these once, from `seeds/`:', codeList(seeds))
+    }
+    sections.push(sync.join('\n\n'))
+  }
+
+  if (manifest.gitignore.length > 0) {
+    const groups = manifest.gitignore.map(
+      ({ header, entries }) =>
+        `- \`${header}\`: ${entries.map((entry) => `\`${entry}\``).join(', ')}`,
+    )
+    sections.push(`## Gitignore\n\n${groups.join('\n')}`)
+  }
+
+  return sections.map((section) => `\n${section}\n`).join('')
+}