@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.14

package/src/boundary/policy.mjs

@@ -7,6 +7,9 @@ import { matchesPathPattern } from '../project/path-match.mjs'
 import { sanitizedGitEnvironment } from '../runtime/git-adapter.mjs'
 import {
   CHECK_AGGREGATE_MAX_BYTES,
+  canonicalDiffArgs,
+  gitOutputResult,
+  parseDiffSections,
   parsePushRefInput,
   resolveContentRules,
   scanPushUpdate,
@@ -358,17 +361,83 @@ function actorFindings({ policy, project, actor, gitExecutable, allowNetworkActo
   return findings
 }
 
-export function stagedPathsForProject(project, { gitExecutable = 'git' } = {}) {
+/**
+ * The index a pre-commit hook is judging. Git names it in GIT_INDEX_FILE (a
+ * temporary index under `git commit -a` or `git commit <paths>`, a linked
+ * worktree's own index, or `.git/index` relative to the work tree's top) and
+ * runs the hook at that top, though a chained hook may have moved. The work
+ * tree is found by Git's own discovery from where the hook runs; the hook's
+ * GIT_DIR is not used, because in a linked worktree Git exports it without a
+ * work tree, which would make any subdirectory look like the top. A work tree
+ * discovery cannot find is unresolved, and blocks. Returns null when no index
+ * is named.
+ */
+export function hookIndexFromEnvironment({ env = process.env, cwd = process.cwd(), gitExecutable = 'git' } = {}) {
+  const named = typeof env.GIT_INDEX_FILE === 'string' ? env.GIT_INDEX_FILE : ''
+  if (!named) return null
+  const workTree = gitPathOutput(cwd, ['rev-parse', '--show-toplevel'], sanitizedGitEnvironment(), gitExecutable)
+  const commonDir = gitPathOutput(cwd, ['rev-parse', '--git-common-dir'], sanitizedGitEnvironment(), gitExecutable)
+  return { workTree, indexFile: path.resolve(workTree ?? cwd, named), commonDir }
+}
+
+function gitPathOutput(cwd, args, env, gitExecutable = 'git') {
+  const result = spawnSync(gitExecutable, ['-C', cwd, ...args], { encoding: 'utf8', env })
+  const output = result.status === 0 ? String(result.stdout ?? '').replace(/\r?\n$/, '') : ''
+  return output ? nativeRealPath(path.resolve(cwd, output)) : null
+}
+
+// The file system's own spelling of a path, so a configured path that differs
+// only in case (macOS, Windows) still names the same repo.
+function nativeRealPath(value) {
+  try {
+    return fs.realpathSync.native(path.resolve(value))
+  } catch {
+    return path.resolve(value)
+  }
+}
+
+/**
+ * Where each managed repo's staged state is read. The repo the hook is
+ * committing is read from the hook's work tree and index: the managed repo
+ * configured at that work tree, or the one managed repo sharing its Git
+ * directory (a linked worktree of it). Every other repo is read as configured.
+ * When an index is named but no single managed repo is being committed, the
+ * guard cannot tell what it is judging, and says so.
+ */
+function stagedTargets(project, hookIndex, gitExecutable = 'git') {
+  const repos = managedRepos(project)
+  const targets = new Map(repos.map((repo) => [repo, { root: repo.path, indexFile: null }]))
+  if (!hookIndex) return { targets, unresolved: null }
+  let committing = hookIndex.workTree ? repos.filter((repo) => repo.path && nativeRealPath(repo.path) === hookIndex.workTree) : []
+  if (committing.length === 0 && hookIndex.commonDir) {
+    committing = repos.filter((repo) => repo.path && fs.existsSync(repo.path)
+      && gitPathOutput(repo.path, ['rev-parse', '--git-common-dir'], sanitizedGitEnvironment(), gitExecutable) === hookIndex.commonDir)
+  }
+  if (committing.length !== 1) return { targets, unresolved: hookIndex.workTree ?? '(an unresolved work tree)' }
+  targets.set(committing[0], { root: hookIndex.workTree, indexFile: hookIndex.indexFile })
+  return { targets, unresolved: null }
+}
+
+function stagedPathsResult(targets, { gitExecutable = 'git' } = {}) {
   const paths = []
-  for (const repo of managedRepos(project)) {
-    if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) continue
-    const result = spawnSync(gitExecutable, ['-C', repo.path, 'diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8', env: sanitizedGitEnvironment() })
-    if (result.status !== 0) continue
-    for (const rel of result.stdout.split('\n').map((line) => line.trim()).filter(Boolean)) {
-      paths.push({ repo: repo.name, repoRoot: repo.path, path: normalize(rel) })
+  const failures = []
+  for (const [repo, target] of targets) {
+    if (!target.root || !fs.existsSync(path.join(target.root, '.git'))) continue
+    // NUL-separated names are exact: a quoted name could never match a forbidden-path glob.
+    const result = gitOutputResult(target.root, ['diff', '--cached', '--name-only', '-z', '--no-relative', '--diff-filter=ACMR'], { gitExecutable, indexFile: target.indexFile })
+    if (!result.ok) {
+      failures.push({ repo, reason: result.code })
+      continue
+    }
+    for (const rel of result.stdout.split('\0').filter(Boolean)) {
+      paths.push({ repo: repo.name, repoRoot: target.root, path: normalize(rel) })
     }
   }
-  return paths
+  return { paths, failures }
+}
+
+export function stagedPathsForProject(project, { gitExecutable = 'git', hookIndex = null } = {}) {
+  return stagedPathsResult(stagedTargets(project, hookIndex, gitExecutable).targets, { gitExecutable }).paths
 }
 
 function forbiddenPathFindings({ policy, stagedPaths }) {
@@ -410,30 +479,14 @@ function isInitializationDefault(field, value) {
   return Array.isArray(defaults) && defaults.includes(value)
 }
 
+/** Diff sections with their hunks, read by the same parser as the content scan. */
 export function diffFileSections(diff) {
-  const files = []
-  let current = null
-  let hunk = null
-  for (const line of String(diff ?? '').split('\n')) {
-    if (line.startsWith('diff --git ')) {
-      const header = line.match(/^diff --git a\/(.*) b\/(.*)$/)
-      current = { path: header ? normalize(header[2]) : null, hunks: [], lines: [] }
-      files.push(current)
-      hunk = null
-      continue
-    }
-    if (!current) continue
-    current.lines.push(line)
-    if (line.startsWith('@@')) {
-      hunk = { added: [], removed: [] }
-      current.hunks.push(hunk)
-      continue
-    }
-    if (!hunk) continue
-    if (/^\+(?!\+)/.test(line)) hunk.added.push(line.slice(1))
-    else if (/^-(?!-)/.test(line)) hunk.removed.push(line.slice(1))
-  }
-  return files
+  return parseDiffSections(diff, { detail: true }).map((section) => ({
+    path: section.path,
+    hunks: section.hunks,
+    lines: section.lines,
+    incomplete: section.incomplete,
+  }))
 }
 
 export function semanticChangesInFile(file) {
@@ -456,26 +509,38 @@ export function semanticChangesInFile(file) {
   return changes
 }
 
-function semanticDiffFindings({ policy, project, gitExecutable = 'git' }) {
+function semanticDiffFindings({ targets, gitExecutable = 'git' }) {
   const findings = []
   const severity = 'error'
-  for (const repo of managedRepos(project)) {
-    if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) {
+  for (const [repo, target] of targets) {
+    if (!target.root || !fs.existsSync(path.join(target.root, '.git'))) {
       findings.push(unscannableRepoFinding(repo, 'configured path is absent or is not a Git checkout'))
       continue
     }
-    const result = spawnSync(gitExecutable, ['-C', repo.path, 'diff', '--cached', '--unified=0', '--', '*.md', '*.kg.json'], { encoding: 'utf8', env: sanitizedGitEnvironment() })
-    if (result.status !== 0) {
+    // --text: a document declared binary, or holding a NUL byte, still has its fields read.
+    const result = gitOutputResult(target.root, [...canonicalDiffArgs(['--cached'], ['--text']), '--', '*.md', '*.kg.json'], { gitExecutable, indexFile: target.indexFile })
+    if (!result.ok) {
       findings.push(unscannableRepoFinding(repo, 'git diff --cached failed'))
       continue
     }
     if (!result.stdout.trim()) continue
     for (const file of diffFileSections(result.stdout)) {
+      if (file.incomplete) {
+        findings.push(finding({
+          severity,
+          code: 'semantic-field-scan-incomplete',
+          repo: repo.name,
+          path: file.path,
+          message: `${repo.name}/${file.path ?? '(unknown path)'}: the staged diff could not be read, so its semantic fields were not checked`,
+          details: { reason: file.incomplete },
+        }))
+        continue
+      }
       const changes = semanticChangesInFile(file)
       if (!changes.length) continue
-      // The marker has to travel in the same file's diff as the change it approves —
-      // a marker elsewhere in the commit approves nothing.
-      if (REVIEW_MARKER_RE.test(file.lines.join('\n'))) continue
+      // The marker has to be added in the same file's diff as the change it approves:
+      // a marker elsewhere in the commit, a removed one, or one in a file name approves nothing.
+      if (file.hunks.some((hunk) => hunk.added.some((line) => REVIEW_MARKER_RE.test(line)))) continue
       const label = `${repo.name}/${file.path ?? '(unknown path)'}`
       findings.push(
         finding({
@@ -492,17 +557,17 @@ function semanticDiffFindings({ policy, project, gitExecutable = 'git' }) {
   return findings
 }
 
-function stagedContentFindings({ policy, project, gitExecutable = 'git' }) {
+function stagedContentFindings({ policy, targets, gitExecutable = 'git' }) {
   const rules = resolveContentRules(policy)
   const exceptions = asArray(policy?.contentRuleExceptions)
   const findings = []
   let totalBytes = 0
-  for (const repo of managedRepos(project)) {
-    if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) {
+  for (const [repo, target] of targets) {
+    if (!target.root || !fs.existsSync(path.join(target.root, '.git'))) {
       findings.push(unscannableRepoFinding(repo, 'configured path is absent or is not a Git checkout'))
       continue
     }
-    const result = scanStagedRepository({ repoRoot: repo.path, rules, exceptions, repo: repo.name, gitExecutable })
+    const result = scanStagedRepository({ repoRoot: target.root, rules, exceptions, repo: repo.name, gitExecutable, indexFile: target.indexFile })
     findings.push(...result.findings, ...result.diagnostics)
     totalBytes += result.bytes
     if (totalBytes > CHECK_AGGREGATE_MAX_BYTES) {
@@ -545,7 +610,7 @@ function repoForCwd(project, cwd) {
  * which reports without blocking, so an accepted usage elsewhere in the repo can
  * never strand unrelated work on the machine.
  */
-export function checkPushContent({ project, policy, repo, updates, cwd = process.cwd(), gitRunner = spawnSync } = {}) {
+export function checkPushContent({ project, policy, repo, updates, remote = null, cwd = process.cwd(), gitRunner = spawnSync } = {}) {
   const target = repo ?? repoForCwd(project, cwd)
   if (!target) {
     // Fail closed. This hook is only installed into managed repos, so failing to
@@ -563,15 +628,17 @@ export function checkPushContent({ project, policy, repo, updates, cwd = process
   const findings = []
   let totalBytes = 0
   for (const update of updates) {
-    const result = scanPushUpdate({ repoRoot: target.path, update, rules, exceptions, repo: target.name, gitRunner })
+    const result = scanPushUpdate({ repoRoot: target.path, update, rules, exceptions, repo: target.name, remote, gitRunner, maxBytes: CHECK_AGGREGATE_MAX_BYTES - totalBytes })
     findings.push(...result.findings, ...result.diagnostics)
     totalBytes += result.bytes
+    // The per-commit scan reports its own budget refusal; say it once.
+    if (result.diagnostics.some((item) => item.details?.reason === 'push-evidence-too-large')) break
     if (totalBytes > CHECK_AGGREGATE_MAX_BYTES) {
       findings.push(finding({
         severity: 'error',
         code: 'content-scan-incomplete',
         repo: target.name,
-        message: `push evidence exceeds the ${CHECK_AGGREGATE_MAX_BYTES}-byte aggregate limit`,
+        message: `push evidence exceeds the ${CHECK_AGGREGATE_MAX_BYTES}-byte aggregate limit; push it in smaller parts`,
       }))
       break
     }
@@ -665,7 +732,7 @@ function promotionFindings({ policy, project, graph }) {
   return findings
 }
 
-export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false, forceActorErrors = false, delegations = null, ownerKeys = null, now = Date.now() } = {}) {
+export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false, forceActorErrors = false, delegations = null, ownerKeys = null, now = Date.now(), hookIndex = null } = {}) {
   const validationErrors = validateBoundaryPolicy(policy, project)
   let graph = null
   const findings = validationErrors.map((message) => finding({ severity: 'error', code: 'boundary-policy-invalid', message }))
@@ -684,10 +751,18 @@ export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnl
   const operation = staged ? 'pre-commit' : 'boundary-check'
   findings.push(...actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors, operation, delegations: delegationList, ownerKeys, now }))
   if (staged) {
-    const stagedPaths = stagedPathsForProject(project, { gitExecutable })
-    findings.push(...forbiddenPathFindings({ policy, stagedPaths }))
-    findings.push(...semanticDiffFindings({ policy, project, gitExecutable }))
-    findings.push(...stagedContentFindings({ policy, project, gitExecutable }))
+    const { targets, unresolved } = stagedTargets(project, hookIndex, gitExecutable)
+    if (unresolved) {
+      findings.push(finding({
+        code: 'pre-commit-repo-unresolved',
+        message: `${unresolved} is not a repo declared in ${project?.configPath ?? 'the project config'}, or several declared repos share its Git directory; the pre-commit guard cannot tell what is being committed`,
+      }))
+    }
+    const listed = stagedPathsResult(targets, { gitExecutable })
+    findings.push(...listed.failures.map(({ repo, reason }) => unscannableRepoFinding(repo, `staged paths could not be listed (${reason})`)))
+    findings.push(...forbiddenPathFindings({ policy, stagedPaths: listed.paths }))
+    findings.push(...semanticDiffFindings({ targets, gitExecutable }))
+    findings.push(...stagedContentFindings({ policy, targets, gitExecutable }))
   }
   const errors = findings.filter((item) => item.severity === 'error')
   const warnings = findings.filter((item) => item.severity !== 'error')
@@ -715,7 +790,7 @@ export function runBoundaryCheckCommand(argv = process.argv.slice(2)) {
   // Owner keys are read only when a delegations document exists.
   const ownerKeys = sidecar.present && sidecar.document ? ownerKeysForCommand() : null
   let report = loaded.ok
-    ? checkBoundaryPolicy({ project, policy: loaded.policy, staged, stagedOnly, actor: firstString(args.actor), delegations: sidecar.document, ownerKeys })
+    ? checkBoundaryPolicy({ project, policy: loaded.policy, staged, stagedOnly, actor: firstString(args.actor), delegations: sidecar.document, ownerKeys, hookIndex: staged ? hookIndexFromEnvironment() : null })
     : { ok: false, mode: null, schema: BOUNDARY_POLICY_SCHEMA, graphCounts: null, findings: missingFindings, errors: missingFindings, warnings: [] }
   if (sidecarFindings.length) report = { ...report, ok: false, findings: [...sidecarFindings, ...report.findings], errors: [...sidecarFindings, ...report.errors] }
 
@@ -784,7 +859,7 @@ ATELIER_HOOK_PROJECT_CONFIG="$ATELIER_HOOK_REPO_ROOT"/${shellSingleQuote(portabl
   // pre-push reads the ref updates git writes to stdin and judges only that range;
   // pre-commit judges the staged diff. Neither scans the whole tree — that view is
   // `atelier boundary audit`, which reports without blocking.
-  const invocation = hookName === 'pre-push' ? `boundary push-check ${config}` : `boundary check --staged ${config}`
+  const invocation = hookName === 'pre-push' ? `boundary push-check ${config} --remote="\${1:-}"` : `boundary check --staged ${config}`
   return `#!/usr/bin/env bash
 # MNSTRY_ATELIER_BOUNDARY_GUARD ${hookName}
 set -euo pipefail
@@ -830,13 +905,17 @@ export function runBoundaryPushCheckCommand(argv = process.argv.slice(2), { stdi
     console.log('[boundary:push-check] no ref updates on stdin · nothing to judge')
     process.exit(0)
   }
-  const report = checkPushContent({ project, policy: loaded.policy, updates: parsed.updates, cwd: process.cwd() })
+  // The installed hook passes the remote Git names as its first argument.
+  const report = checkPushContent({ project, policy: loaded.policy, updates: parsed.updates, remote: firstString(args.remote), cwd: process.cwd() })
   if (args.json) {
     console.log(JSON.stringify(report, null, 2))
   } else {
     console.log(`[boundary:push-check] ${report.ok ? 'passed' : 'blocked'} · ${report.repo ?? 'unknown repo'} · ${report.errors.length} errors · ${report.warnings.length} warnings`)
-    for (const item of report.findings.slice(0, 50)) console.log(`${item.severity} ${item.rule ?? item.code}: ${item.message}`)
-    if (!report.ok && report.repo) {
+    for (const item of report.findings.slice(0, 50)) {
+      const also = item.commits?.length ? ` (also in commits ${item.commits.map((commit) => commit.slice(0, 12)).join(', ')})` : ''
+      console.log(`${item.severity} ${item.rule ?? item.code}: ${item.message}${also}`)
+    }
+    if (!report.ok && report.repo && report.errors.some((item) => item.code === 'content-rule-violation')) {
       console.log('')
       console.log('If this usage is intentional, declare it in the boundary policy:')
       console.log('  contentRuleExceptions: [{ rule, repo, paths: [...], reason: "why this is accepted" }]')

package/src/cli/run.mjs

@@ -150,6 +150,7 @@ Core commands:
   upgrade explain --plan          Explain saved changes and consent without writes.
   upgrade apply --plan --confirm   Apply the selected plan through commit hooks.
   upgrade status|recover          Inspect receipts or preview recovery.
+  upgrade closure --npm-root      Plan a consumer dependency-closure check; reads only, proves nothing.
   upgrade --dry-run               Plan a legacy package/template upgrade.
   upgrade --apply                 Apply a branch-based reviewable upgrade.
   lock check|write                Verify or create atelier.lock.json.
@@ -279,7 +280,7 @@ Assembles a local feedback report under ignored .atelier-local/feedback/ (mode 0
     announcements: `Usage: ${c} announcements list [--dir DIR] [--public-key FILE] | verify <file> [--public-key FILE] [--json] | show <file> [--public-key FILE]
 
 MNSTRY announcements are a pull-only channel: signed JSON documents under announcements/ in the repository. The trust anchor is always the committed MNSTRY key, or one you pass explicitly with --public-key; --dir changes only where documents are read from and never which key verifies them. Every run names the key and keyId it used. The kit never fetches anything — receiving announcements is the git pull you chose to run, and show refuses to print a body whose signature does not verify.`,
-    obsidian: `Usage: ${c} obsidian status|settings|location|scope|view|audience|mode|policy|service|open|uninstall|plugin|apply|conflicts|apply-policy|selection|proposals [--project atelier.project.json] [--data-root DIR] [--json] [--no-input]
+    obsidian: `Usage: ${c} obsidian status|settings|location|scope|view|audience|mode|policy|service|open|uninstall|plugin|apply|conflicts|apply-policy|selection|proposals [--project atelier.project.json | --personal-home DIR] [--data-root DIR] [--json] [--no-input]
 
   ${c} obsidian status
   ${c} obsidian settings
@@ -300,7 +301,7 @@ MNSTRY announcements are a pull-only channel: signed JSON documents under announ
   ${c} obsidian selection resolve ID | persist ID [allow-empty] | show ID | list
   ${c} obsidian proposals list | show OPERATION
 
-Every input is an argument. view add changes the project configuration, which you commit: it shows the change and how many notes the view would show, and asks a person at a terminal first (--yes answers beforehand); anyone else's command is their consent, and nothing is ever committed. With --json exactly one JSON document is printed, for a refusal too. status, settings, location show, scope, audience show, mode show, policy show, policy digest, plugin show and service status are read-only. open reports current only when the owned maintenance service ticked after the request, the view's trusted generation is the prepared one and reads back byte for byte, and the installed Obsidian meets the minimum version and answers for that vault; every other outcome is typed and exits 3. Reaching the installed app is never a default: open, service start and service unit need --adapter=obsidian-cli once for a workspace, which remembers it (never used under the test runner). service unit --install installs a login item on macOS (a launchd agent) or Linux (a systemd user unit) so maintenance starts when you log in, under a consent that covers startup; it runs the package installed in the project and is refused from a package runner's cache. Once installed, the service is started through it, and service start replaces a service of an earlier release. service unit --remove removes it and starts the service for this session only. uninstall removes the login item and stops the service, and keeps vaults, private state, the project file and Obsidian's vault list. Obsidian's own settings file is written only while no Obsidian runs, and every write is shown in open's answer: the view's vault is added to its list with a backup of the file as it was, its command line is turned on (cli: true), and for an Obsidian that never started the file is created. A running Obsidian that open cannot reach (its command line turned off, or no vault open) is quit and started again only with --restart-obsidian, which no other flag implies; otherwise open names that flag. --wait-ms bounds open's wait for maintenance's tick. The first start of the maintenance service records who allowed it: --consent-actor ID, or for a person at a terminal the account's name; --json, --no-input, CI or ATELIER_NONINTERACTIVE=1 mean nobody is at a terminal. Audiences (audience set me: only you, with the notes that carry no classification, which no other list shows), mode, the apply policy and what was decided are private machine settings, never project configuration and never a note. apply, conflicts, apply-policy, selection and proposals are contributed operations registered from modules shipped under src/runtime/obsidian/contributions/; the built-in names cannot be replaced. While no apply operation is registered every apply reports apply-unavailable. Exit codes: 0 done, 1 internal error, 2 refusal or usage, 3 ran and the answer is not success.`,
+Every input is an argument. view add changes the project configuration, which you commit: it shows the change and how many notes the view would show, and asks a person at a terminal first (--yes answers beforehand); anyone else's command is their consent, and nothing is ever committed. With --json exactly one JSON document is printed, for a refusal too. status, settings, location show, scope, audience show, mode show, policy show, policy digest, plugin show and service status are read-only. open reports current only when the owned maintenance service ticked after the request, the view's trusted generation is the prepared one and reads back byte for byte, and the installed Obsidian meets the minimum version and answers for that vault; every other outcome is typed and exits 3. Reaching the installed app is never a default: open, service start and service unit need --adapter=obsidian-cli once for a workspace, which remembers it (never used under the test runner). service unit --install installs a login item on macOS (a launchd agent) or Linux (a systemd user unit) so maintenance starts when you log in, under a consent that covers startup; it runs the package installed in the project and is refused from a package runner's cache. Once installed, the service is started through it, and service start replaces a service of an earlier release. service unit --remove removes it and starts the service for this session only. uninstall removes the login item and stops the service, and keeps vaults, private state, the project file and Obsidian's vault list. Obsidian's own settings file is written only while no Obsidian runs, and every write is shown in open's answer: the view's vault is added to its list with a backup of the file as it was, its command line is turned on (cli: true), and for an Obsidian that never started the file is created. A running Obsidian that open cannot reach (its command line turned off, or no vault open) is quit and started again only with --restart-obsidian, which no other flag implies; otherwise open names that flag. --wait-ms bounds open's wait for maintenance's tick. The first start of the maintenance service records who allowed it: --consent-actor ID, or for a person at a terminal the account's name; --json, --no-input, CI or ATELIER_NONINTERACTIVE=1 mean nobody is at a terminal. Audiences (audience set me: only you, with the notes that carry no classification, which no other list shows), mode, the apply policy and what was decided are private machine settings, never project configuration and never a note. apply, conflicts, apply-policy, selection and proposals are contributed operations registered from modules shipped under src/runtime/obsidian/contributions/; the built-in names cannot be replaced. While no apply operation is registered every apply reports apply-unavailable. --personal-home DIR, given instead of --project, follows the generation last confirmed in that private home of a personal workspace; nothing here confirms one, and while none is confirmed and current nothing is published and status, open and service start refuse with the reason. Who may see its vaults stays this machine's audience setting, none by default. Exit codes: 0 done, 1 internal error, 2 refusal or usage, 3 ran and the answer is not success.`,
     sync: `Usage:
   ${c} sync enroll --repo DIR [--project atelier.project.json] [--git ABSOLUTE_PATH]
   ${c} sync status --repo DIR

package/src/commands/obsidian.mjs

@@ -69,7 +69,7 @@ const PRODUCTION_ADAPTER = 'obsidian-cli'
 const MAX_POLICY_BYTES = 64 * 1024
 const AUDIENCE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
 
-export const USAGE = `Usage: atelier obsidian <operation> [--project atelier.project.json] [--data-root DIR] [--json] [--no-input]
+export const USAGE = `Usage: atelier obsidian <operation> [--project atelier.project.json | --personal-home DIR] [--data-root DIR] [--json] [--no-input]
 
   status                               Enablement, machine settings, service and per-view freshness. Read-only.
   settings                             What this machine remembers for this workspace, and how to change it. Read-only.
@@ -111,6 +111,11 @@ export const USAGE = `Usage: atelier obsidian <operation> [--project atelier.pro
                                        service publishes the view at once (with --adapter, one of an earlier release
                                        is replaced first).
 
+--personal-home DIR, given instead of --project, follows the generation last confirmed in that private home of a personal
+workspace (the personal-workspace module's selection); its views come from the overlay. Nothing here confirms one: while
+none is confirmed and current nothing is published, and status, open and service start refuse with the reason. service
+status and stop, unit --remove and uninstall find the service from the home alone. Who may see its vaults stays this
+machine's audience setting, none by default.
 Reaching the installed app needs --adapter=${PRODUCTION_ADAPTER} once for a workspace; it is remembered after that.
 Obsidian's own settings file (obsidian.json) is written only while no Obsidian runs: open adds the view's vault to its
 list, turns its command line on (cli: true), and creates the file for an Obsidian that never started; every write is
@@ -139,7 +144,7 @@ Exit codes: 0 done; 1 internal error; 2 refusal or usage; 3 ran, and the answer
 // spelling of `project`); a test holds it to that.
 export const FLAGS = Object.freeze({
   json: 'flag', 'allow-stale': 'flag', 'restart-obsidian': 'flag', print: 'flag', install: 'flag', remove: 'flag', help: 'flag', 'no-input': 'flag', 'allow-synced-location': 'flag', all: 'flag', default: 'flag', 'allow-empty': 'flag', yes: 'flag',
-  project: 'value', 'project-config': 'value', 'data-root': 'value', scope: 'value', 'consent-actor': 'value', actor: 'value', adapter: 'value', 'wait-ms': 'value', repo: 'value', tag: 'value',
+  project: 'value', 'project-config': 'value', 'personal-home': 'value', 'data-root': 'value', scope: 'value', 'consent-actor': 'value', actor: 'value', adapter: 'value', 'wait-ms': 'value', repo: 'value', tag: 'value',
   expand: 'value', folder: 'values',
 })
 
@@ -276,6 +281,7 @@ const NEXT = Object.freeze({
   'login-item-remove-failed': 'see `atelier obsidian status`; `atelier obsidian service unit --remove` tries again',
   'login-item-file-unsafe': 'the login item\'s file is a link or not a regular file and is left alone; remove it by hand, then try again',
   'invalid-login-item': 'the login item record in private state does not validate; inspect it, remove it, then install the login item again',
+  'selection-history-shortened': 'records of the selection history were removed after this process read them; put them back, or run the command in a process of its own, which reads the history as it now stands',
 })
 
 // The login item of `status`, in words.
@@ -372,10 +378,16 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
 
     const dataRoot = flags['data-root'] === undefined ? options.dataRoot : path.resolve(cwd, flags['data-root'])
     const configFlag = flags.project ?? flags['project-config']
-    const loadProject = options.loadProject ?? (() => resolveProjectConfig({ argv: configFlag === undefined ? [] : [`--project=${path.resolve(cwd, configFlag)}`], cwd, env, writeLocalState: false }))
+    // A personal home is followed instead of a project: the generation confirmed there is loaded (composed in this
+    // thread, as for a command run once), and the service's workspace is located from the home alone.
+    const personalHome = flags['personal-home'] === undefined ? null : path.resolve(cwd, flags['personal-home'])
+    if (personalHome !== null && configFlag !== undefined) refuse('usage', '--personal-home is given instead of --project, not with it')
+    const selection = personalHome === null ? null : await import('../runtime/obsidian/personal-selection.mjs')
+    const loadProject = options.loadProject ?? (selection !== null ? () => selection.loadSelectedProject({ personalHome }) : () => resolveProjectConfig({ argv: configFlag === undefined ? [] : [`--project=${path.resolve(cwd, configFlag)}`], cwd, env, writeLocalState: false }))
+    const locateProject = selection === null ? null : () => selection.locatePersonalHome({ personalHome })
     const registry = createObsidianRegistry({ reservedOperations: BUILT_IN_OPERATIONS, contributions: contributions ?? await loadContributions(contributionsDirectory === undefined ? {} : { directory: contributionsDirectory }) })
     const applyAvailable = registry.extensions.applyOperation() !== UNAVAILABLE_APPLY_OPERATION
-    const lifecycle = { loadProject, dataRoot, env, platform, ...(options.probeTimeoutMs === undefined ? {} : { probeTimeoutMs: options.probeTimeoutMs }) }
+    const lifecycle = { loadProject, ...(locateProject === null ? {} : { locateProject }), dataRoot, env, platform, ...(options.probeTimeoutMs === undefined ? {} : { probeTimeoutMs: options.probeTimeoutMs }) }
 
     // The adapter of this run: given now, or remembered by this workspace (read only when the real entry has no flag).
     const chooseAdapter = () => selectAdapter({ flag: flags.adapter, remembered: flags.adapter === undefined && production === true ? rememberedAdapter() : null, production, env })
@@ -617,7 +629,7 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
     const removeUnit = async () => {
       if (!STARTUP_PLATFORMS.includes(platform)) buildStartupAdapter({ platform })
       const manager = await managerSeam()
-      const removed = await removeLoginItem({ loadProject, dataRoot, env, platform, manager, clock })
+      const removed = await removeLoginItem({ loadProject: locateProject ?? loadProject, dataRoot, env, platform, manager, clock })
       const failed = removed.removed !== true && removed.reason !== undefined && removed.reason !== 'workspace-not-prepared'
       if (failed) return { exit: EXIT.notSuccess, document: { loginItem: removed }, human: [`login item not removed: ${removed.reason}${removed.message ? ` (${removed.message})` : ''}`, `Next: ${NEXT[removed.reason] ?? 'see `atelier obsidian status`'}`] }
       const remembered = removed.reason === 'workspace-not-prepared' ? false : rememberLoginItem('off')
@@ -720,7 +732,10 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
             const plugin = withPluginFilesPending(pluginView(running, workspace, scopeId), report.freshness)
             return enablement.state === 'disabled' ? { ...report, outcome: 'disabled', reason: enablement.reason, next: OPENING_OUTCOMES.disabled.next, plugin } : { ...report, plugin }
           })
+        // The confirmed selection a personal home's project was loaded under; reported, never confirmed here.
+        const pinned = selection === null ? null : selection.personalSelectionOf(project)
         const document = {
+          ...(pinned === null ? {} : { selection: { generationId: pinned.generationId, sequence: pinned.sequence } }),
           enablement: { state: enablement.state, reason: enablement.reason, defaultScopeId: enablement.defaultScopeId }, workspace: { workspaceId, prepared: workspace !== null },
           machine: shownMachine(machineOf(workspace), workspace), apply: applyShown,
           service: { state: service.state, reason: service.reason ?? null, address: service.address ?? null, runtimeId: service.record?.runtimeId ?? null, pid: service.record?.pid ?? null, lastTick: running?.lastTick ?? null, lastError: running?.lastError ?? null, app },
@@ -729,6 +744,7 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
         return {
           exit: EXIT.ok, document,
           human: [
+            ...(pinned === null ? [] : [`personal workspace: generation ${pinned.generationId}, confirmed as selection ${pinned.sequence}`]),
             `obsidian: ${enablement.state} (${enablement.reason}); mode ${document.machine.maintenanceMode}; audiences ${document.machine.audienceAllow.join(', ') || 'none'}`,
             `remembered: ${decisionSummary(document.machine.decisions)}`,
             `service: ${service.state} (${service.reason ?? 'no reason'})${app ? `; app ${app.outcome} (${app.reason})` : ''}`,
@@ -1073,13 +1089,13 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
       // Maintenance of this workspace ends here: the login item goes first, so its manager does not start the service
       // again, then the proven service stops. Everything a person made or may want back stays, and is named.
       async uninstall() {
-        const project = loadProject()
+        const project = (locateProject ?? loadProject)()
         let workspace = null
         try { const found = resolveServiceWorkspace({ project, dataRoot, env, platform }); workspace = found?.workspaceRoot ? found : null } catch (error) { if (!isTyped(error)) throw error }
         const record = workspace === null ? null : readLoginItemRecord(workspace)
         // What is kept is read before anything is stopped or removed, so nothing it finds can stop the answer after that.
         const kept = keptLocations(project, workspace)
-        const item = record === null ? { removed: false, reason: 'not-installed' } : await removeLoginItem({ loadProject, dataRoot, env, platform, manager: await managerSeam(), clock })
+        const item = record === null ? { removed: false, reason: 'not-installed' } : await removeLoginItem({ loadProject: locateProject ?? loadProject, dataRoot, env, platform, manager: await managerSeam(), clock })
         const service = workspace === null ? { state: 'stopped', stopped: false, refused: false, reason: 'workspace-not-prepared' } : await stopService(lifecycle, lifecycleRules)
         const itemGone = item.removed === true || item.reason === 'not-installed' || item.reason === 'workspace-not-prepared'
         const serviceGone = service.stopped === true || service.state === 'stopped'

package/src/graph/graph.mjs

@@ -5,9 +5,10 @@ import { VALID_AUDIENCES as PROJECTION_AUDIENCES } from '../projection/policy.mj
 import {
   REPO_ACCESS_SCHEMA,
   VALID_RELATION_TYPES,
-  buildKnowledgeGraph,
+  buildKnowledgeGraphSteps,
   createGraphFileCache,
   parseYamlSubset,
+  runGraphSteps,
 } from './knowledge-graph.mjs'
 
 export { createGraphFileCache }
@@ -116,11 +117,12 @@ function externalRepos(project) {
     .sort((a, b) => String(a.name).localeCompare(String(b.name)))
 }
 
-function canonicalBuild(project, overrides = {}) {
+function* canonicalBuildSteps(project, overrides = {}) {
   const input = canonicalInput(project)
-  const result = buildKnowledgeGraph({ ...input.options, ...overrides })
+  const result = yield* buildKnowledgeGraphSteps({ ...input.options, ...overrides })
   return { input, result }
 }
+const canonicalBuild = (project, overrides = {}) => runGraphSteps(canonicalBuildSteps(project, overrides))
 
 // The supported project-to-options seam: the exact buildKnowledgeGraph options
 // every graph consumer derives from a loaded project, plus the configured
@@ -144,8 +146,14 @@ const canonicalEdgeId = (edge) => JSON.stringify([edge.source, edge.type, edge.t
 // bytes did not change; the result is the same as without it. `observedDigest`
 // (see createGraphFileCache) lets a caller that observes sources by digest
 // spare the read of a source it knows unchanged.
-export function buildCanonicalGraph(project, { isLinkTargetEligible, isAssetEligible, fileCache = null, observedDigest = null } = {}) {
-  const { input, result } = canonicalBuild(project, {
+// buildCanonicalGraphSteps is the same build as steps (see buildKnowledgeGraphSteps), for a caller that waits between
+// them; buildCanonicalGraph runs them through.
+export function buildCanonicalGraph(project, options = {}) {
+  return runGraphSteps(buildCanonicalGraphSteps(project, options))
+}
+
+export function* buildCanonicalGraphSteps(project, { isLinkTargetEligible, isAssetEligible, fileCache = null, observedDigest = null } = {}) {
+  const { input, result } = yield* canonicalBuildSteps(project, {
     ...(isLinkTargetEligible ? { isLinkTargetEligible } : {}),
     ...(isAssetEligible ? { isAssetEligible } : {}),
     ...(fileCache ? { fileCache } : {}),

package/src/graph/knowledge-graph.mjs

@@ -1387,7 +1387,24 @@ function markdownCensus({ repoName, repoRoot, coverage, file, accessConfig, cach
   return { node: structuredClone(entry.node), scan: structuredClone(entry.scan), reused: entry === cached, read }
 }
 
-export function buildKnowledgeGraph({
+// Runs the steps of a graph build through, with no wait, and answers what the build answers.
+export function runGraphSteps(steps) {
+  for (;;) {
+    const step = steps.next()
+    if (step.done) return step.value
+  }
+}
+
+// The knowledge graph of a workspace, in one stretch. Every caller but the maintenance engine's tick builds it this way.
+export function buildKnowledgeGraph(options) {
+  return runGraphSteps(buildKnowledgeGraphSteps(options))
+}
+
+// The same build as steps: one after each Markdown source of the census (its read, hash and parse, or its reuse from
+// the file cache), named 'graph-census'. A caller that gives the event loop a turn between steps (the maintenance
+// engine) keeps a large census from holding it; walking the directories, resolving links and assembling the graph
+// are not split. The answer is the one buildKnowledgeGraph gives.
+export function* buildKnowledgeGraphSteps({
   workspaceRoot,
   repoAccessConfig,
   repoRoots = null,
@@ -1466,6 +1483,7 @@ export function buildKnowledgeGraph({
         scanned.set(node, entry.scan)
         reuse[entry.reused ? 'reused' : 'derived'] += 1
         if (entry.read) reuse.read += 1
+        yield 'graph-census'
       } else {
         node = nodeForFile(repoName, repoRoot, coverage, file, accessConfig)
       }

package/src/ingestion/optional/graphify/graphify_supplier.py

@@ -717,6 +717,11 @@ class GraphifySupplier:
                 settings = {"parallel": False, "max_workers": 1, **settings}
                 require(type(settings["parallel"]) is bool and type(settings["max_workers"]) is int
                         and 1 <= settings["max_workers"] <= 32, "BUDGET_UNBOUNDED", "Finite native structural worker bound required")
+                # Parallel extraction starts worker processes that import Graphify through the
+                # ordinary import system, outside the pinned source loader, so they may run a
+                # cached pyc this supplier never attested. Only in-process extraction is admitted.
+                require(settings["parallel"] is False, "NATIVE_WORKERS_UNATTESTED",
+                        "Parallel native extraction runs worker processes outside the attested loader")
             if op == "cache-check":
                 require(settings.get("prompt") is None or isinstance(settings["prompt"], str), "PROMPT_SCOPE", "Prompt must be explicit text")
                 if settings.get("prompt_file") is not None: