@mnstry/atelier 0.2.0-alpha.5 → 0.2.0-alpha.8

package/src/cli/project-options.mjs

@@ -0,0 +1,58 @@
+// Shared project-location syntax. Command-specific arguments remain owned by
+// their command; this parser does not make unknown options globally valid.
+export const PROJECT_OPTION_SPEC = Object.freeze({
+  project: 'value',
+  'project-config': 'value',
+  'repo-path': 'value',
+})
+
+function invalid(message) {
+  const error = new Error(message)
+  error.code = 'project-option-invalid'
+  error.exitCode = 2
+  throw error
+}
+
+export function projectOptionAt(argv, index, configArgPrefix = '--project-config=') {
+  const arg = argv[index]
+  if (typeof arg !== 'string' || !arg.startsWith('--')) return null
+  const name = arg.slice(2).split('=')[0]
+  const custom = configArgPrefix !== '--project-config=' && arg.startsWith(configArgPrefix)
+  if (!custom && !Object.hasOwn(PROJECT_OPTION_SPEC, name)) return null
+  const inline = custom || arg.includes('=')
+  const value = custom ? arg.slice(configArgPrefix.length) : inline ? arg.slice(arg.indexOf('=') + 1) : argv[index + 1]
+  if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+    invalid(`--${custom ? 'project-config' : name} requires a non-empty value`)
+  }
+  const option = custom ? 'project-config' : name
+  if (option === 'repo-path') {
+    const separator = value.indexOf('=')
+    if (separator < 1 || !value.slice(0, separator).trim() || !value.slice(separator + 1).trim()) {
+      invalid('--repo-path requires NAME=PATH')
+    }
+  }
+  return { name: option, value, nextIndex: index + (inline ? 1 : 2) }
+}
+
+export function parseProjectOptions(argv = [], configArgPrefix = '--project-config=') {
+  let project = null
+  const repoPaths = new Map()
+  const remaining = []
+  for (let index = 0; index < argv.length;) {
+    const option = projectOptionAt(argv, index, configArgPrefix)
+    if (!option) {
+      remaining.push(argv[index++])
+      continue
+    }
+    if (option.name === 'repo-path') {
+      const separator = option.value.indexOf('=')
+      repoPaths.set(option.value.slice(0, separator).trim(), option.value.slice(separator + 1))
+    } else if (project === null) {
+      // Preserve the resolver's first project selection and last named repo
+      // override behavior, including aliases in the same invocation.
+      project = option.value.trim()
+    }
+    index = option.nextIndex
+  }
+  return { project, repoPaths, remaining }
+}

package/src/cli/run.mjs

@@ -58,6 +58,11 @@ export const commandMap = new Map([
   ['feedback:check', ['src/commands/feedback.mjs', 'check']],
   ['announcements', ['src/commands/announcements.mjs']],
   ['announcements:list', ['src/commands/announcements.mjs', 'list']],
+  ['sync', ['src/commands/sync.mjs']],
+  ['review', ['src/commands/review.mjs']],
+  ['coauthor', ['src/commands/coauthor.mjs']],
+  ['skills', ['src/commands/skills.mjs']],
+  ['obsidian', ['src/commands/obsidian.mjs']],
 ])
 
 function isDefaultBrand(brand) {
@@ -115,14 +120,30 @@ Core commands:
   support bundle --dry-run        Preview a no-send support bundle.
   feedback --message TEXT         Write a local, never-sent feedback report.
   announcements list              List and verify MNSTRY announcements.
+  sync enroll                     Explicitly enroll one repository for supervision.
+  sync status                     Fully observe the enrolled repository.
+  sync reconcile                  Fetch and perform only proven fast-forwards.
+  sync plan                       Prepare one bounded, reviewable commit plan.
+  sync commit                     Execute an exactly confirmed commit plan.
+  sync run --once                 Run one full-state supervisor cycle.
+  obsidian status|open|apply      Maintain and open Obsidian views of the corpus; apply edits made in them.
   egress check                    Check extracted Atelier paths for forbidden egress.
   boundary check                  Enforce private/shared repo placement rules.
   boundary audit                  Report content-rule matches tree-wide without blocking.
   boundary install-hooks          Install staged/private-domain Git guards.
   promote                         Record a git.promote disclosure event.
-  upgrade --dry-run               Plan a safe package/template upgrade.
+  upgrade plan --save             Save an exact local candidate plan.
+  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 --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.
+  lock provenance                Inspect actual installed package identity.
+  review run|history|handoff       Evidence-bound local human review.
+  review export|inspect|packs      Preview inspection bundles and pack lifecycle.
+  coauthor start|read|event|recover Save and resume private authoring drafts.
+  skills audit|observe|candidates|sync Audit and manage local skill projections.
   config check                    Validate project config.
   extension-pack validate         Validate declared extension packs.
   extension-pack list             List declared extension packs.
@@ -138,6 +159,9 @@ Attestation commands:
 Commands whose usage names --project accept --project=PATH or --project PATH.
 The project resolver also accepts --project-config=PATH and
 MNSTRY_ATELIER_PROJECT_CONFIG=PATH; each command's own help is authoritative.
+Project-aware commands accept repeated --repo-path NAME=PATH or
+--repo-path=NAME=PATH. Overrides change location, never declared read authority.
+Run config check --explain for path-free resolution sources.
 Machine-local repo paths belong in
 .atelier-local/, atelier.local.json, or atelier.workspace.local.json.`
 }
@@ -145,7 +169,14 @@ Machine-local repo paths belong in
 export function buildCommandHelpText(command, brand = DEFAULT_BRAND) {
   const c = brand.command
   const help = {
-    init: `Usage: ${c} init [--template private-domain|shared-project|sample-workspace|distribution] [--target DIR] [--actor ID]
+    skills: `Usage: ${c} skills audit|observe|candidates|sync
+Audit bundled skills or --root DIR [--peer DIR].
+Sync previews by default; applying requires --apply --confirm PLAN_DIGEST.
+Observations are local metadata, never automatic telemetry.`,
+    coauthor: `Usage: ${c} coauthor start|read|event|recover
+
+Read one JSON request from stdin (maximum 1 MiB). Start takes {"config":{"id":"SESSION","fields":[{"id":"FIELD","source":{"ref":"packet.md","digest":"SHA256"}}]}}. Read/recover take {"sessionId":"SESSION"}. Event takes {"sessionId":"SESSION","event":{"id":"UNIQUE","expectedRevision":0,"type":"answer","text":"ANSWER"}}. Run from the intended Git workspace with ignored .atelier-local/. Saves are private drafts, never canonical source edits.`,
+    init: `Usage: ${c} init [--template private-domain|shared-project|sample-workspace|distribution|external-project] [--target DIR] [--actor ID]
 
 Creates tracked starter files and an Atelier lockfile. It does not install hooks unless asked separately. An unrecognized --template exits 1 and writes nothing; omit --template for the blank scaffold.`,
     adopt: `Usage: ${c} adopt [--profile single-repo|private-domain|shared-project|multi-repo|monorepo|control-workspace] [--target DIR] [--yes]
@@ -176,7 +207,7 @@ Runs the bundled MNSTRY readiness pack claim-first. Protocol state and packet dr
   ${c} extension-pack validate [--json] [--project ./atelier.project.json]
   ${c} extension-pack list [--json] [--project ./atelier.project.json]
 
-Loads every extension pack declared under ext["mnstry.atelier"].extensionPacks in the tracked project config and reports one line per pack. Packs load additively alongside the bundled MNSTRY protocols and can never replace them. list is the default subcommand.`,
+Loads every extension pack declared under ext["mnstry.atelier"].extensionPacks in the tracked project config and reports one line per pack. Packs load additively alongside the bundled MNSTRY protocols and can never replace them. list is the default subcommand. Shared --project-config and repeated --repo-path NAME=PATH options are supported in both space and equals forms.`,
     distribution: `Usage: ${c} distribution check [--target DIR] [--pack DIR]
 
 Checks a distribution package for the required MNSTRY attribution markers. Blocking: the distribution README.md byte check, and a CLI probe that EXECUTES the target's declared bin with --version (spawned with the current Node, cwd set to the target — only run this against distributions you trust) and requires the attribution in its output; a target that looks like a distribution but declares no probe-able bin, or ships a malformed package.json, is also blocking. The extension-pack manifest attribution key is advisory and reported only. The normative wording lives in TRADEMARKS.md under "Required attribution"; see also docs/attestation.md and docs/distributions.md.`,
@@ -198,6 +229,33 @@ 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|scope|audience|mode|policy|service|open|apply|conflicts|apply-policy|selection|proposals [--project atelier.project.json] [--data-root DIR] [--json]
+
+  ${c} obsidian status
+  ${c} obsidian scope list | scope show ID
+  ${c} obsidian audience show | set A,B | clear
+  ${c} obsidian mode show | set manual|automatic
+  ${c} obsidian policy show | install FILE | revoke
+  ${c} obsidian service start [--consent-actor ID] --adapter=obsidian-cli | status | stop | unit --print --adapter=obsidian-cli
+  ${c} obsidian open [--scope ID] [--consent-actor ID] [--allow-stale] --adapter=obsidian-cli
+  ${c} obsidian apply list | show EDIT | run EDIT [--actor ID] | recover
+  ${c} obsidian conflicts [ID]
+  ${c} obsidian apply-policy create FILE | show | revoke
+  ${c} obsidian selection resolve ID | persist ID [allow-empty] | show ID | list
+  ${c} obsidian proposals list | show OPERATION
+
+Noninteractive. With --json exactly one JSON document is printed, for a refusal too. status, scope, audience show, mode show, policy 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. Audiences, mode and the apply policy 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.`,
+    sync: `Usage:
+  ${c} sync enroll --repo DIR [--project atelier.project.json] [--git ABSOLUTE_PATH]
+  ${c} sync status --repo DIR
+  ${c} sync reconcile --repo DIR [--retries 3]
+  ${c} sync run --repo DIR [--once] [--interval 30]
+  ${c} sync plan --repo DIR --path FILE [--path FILE] --message TEXT [--publish]
+  ${c} sync commit --repo DIR --operation ID --confirm ID
+  ${c} sync pause|freeze|resume --repo DIR
+  ${c} sync trace --repo DIR
+
+Enrolls exactly one repository and keeps Git plus readable files authoritative. Reconciliation observes the complete repository every cycle and performs only fast-forward updates. Commit creation is a two-phase user-confirmed operation: plan shows one bounded change set, and commit refuses unless the repository is unchanged and --confirm exactly repeats the operation id. No semantic conflict resolution, force operation, browser apply endpoint, telemetry, or desktop shell is present.`,
   }
   return help[command] || `Usage: ${c} ${command} [args]\n\nRun ${c} --help for the command list.`
 }

package/src/coauthor/session.mjs

@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import { canonicalize } from '../attestation/jcs.mjs';
+
+// Experimental adapter seam. This reducer performs no storage or authorization.
+export const COAUTHOR_SESSION_VERSION = 'atelier-coauthor-session/experimental-v1';
+export function contentDigest(text) {
+  if (typeof text !== 'string') throw new TypeError('text required');
+  if (Buffer.from(text, 'utf8').toString('utf8') !== text) throw new TypeError('text must be lossless UTF-8');
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+const digestPattern = /^[a-f0-9]{64}$/;
+function requireText(value, label) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 100000) {
+    throw new TypeError(`${label} required and bounded`);
+  }
+}
+function sourceCheck(source) {
+  if (!source || typeof source !== 'object') throw new TypeError('source required');
+  requireText(source.ref, 'source ref');
+  if (!digestPattern.test(source.digest)) throw new TypeError('source digest required');
+}
+export function createSession({ id, fields }) {
+  requireText(id, 'session id');
+  if (!Array.isArray(fields) || fields.length === 0 || fields.length > 1000) throw new TypeError('fields required');
+  const ids = new Set();
+  const targets = fields.map(({ id: fieldId, source }) => {
+    requireText(fieldId, 'field id');
+    if (ids.has(fieldId)) throw new Error('duplicate field');
+    ids.add(fieldId);
+    sourceCheck(source);
+    return { id: fieldId, source: { ref: source.ref, digest: source.digest } };
+  });
+  return { version: COAUTHOR_SESSION_VERSION, id, revision: 0, phase: 'input', index: 0,
+    fields: targets, answers: [], proposal: null, saved: [], pending: null, events: [] };
+}
+function checkEvent(event) {
+  if (!event || typeof event !== 'object' || Array.isArray(event)) throw new TypeError('event required');
+  requireText(event.id, 'event id');
+  if (!Number.isSafeInteger(event.expectedRevision) || event.expectedRevision < 0) throw new TypeError('revision required');
+  const keys = {
+    answer: ['text', 'continueAfterSave'], propose: ['text'], confirm: [], reject: [],
+    save: [], receipt: ['receipt'], failed: [], retry: [], advance: [], pause: [], resume: [],
+  }[event.type];
+  if (!keys || Object.keys(event).some(key => !['id', 'type', 'expectedRevision', ...keys].includes(key))) {
+    throw new TypeError('unknown event or field');
+  }
+  if (['answer', 'propose'].includes(event.type)) requireText(event.text, 'answer text');
+  if (event.continueAfterSave !== undefined && typeof event.continueAfterSave !== 'boolean') throw new TypeError('continue must be boolean');
+  if (event.type === 'receipt') {
+    const r = event.receipt;
+    if (!r || Object.keys(r).sort().join(',') !== 'fieldId,requestId,sessionId,sourceDigest,sourceRef,valueDigest') throw new TypeError('invalid receipt shape');
+    for (const key of ['requestId', 'sessionId', 'fieldId', 'sourceRef']) requireText(r[key], key);
+    for (const key of ['sourceDigest', 'valueDigest']) if (!digestPattern.test(r[key])) throw new TypeError('invalid receipt digest');
+  }
+}
+function need(state, phases) {
+  if (!phases.includes(state.phase)) throw new Error(`event refused in ${state.phase}`);
+}
+function writeEffect(state) {
+  const field = state.fields[state.index];
+  return { type: 'write-field', requestId: state.pending.requestId, sessionId: state.id,
+    fieldId: field.id, sourceRef: field.source.ref, sourceDigest: field.source.digest,
+    text: state.proposal.text, valueDigest: contentDigest(state.proposal.text) };
+}
+function advance(state) {
+  state.index += 1;
+  state.phase = state.index === state.fields.length ? 'complete' : 'input';
+  state.proposal = null;
+  state.pending = null;
+}
+export function transition(session, event) {
+  // State is trusted adapter-owned memory. Rehydrate by replaying validated events,
+  // not by accepting an arbitrary caller-supplied session snapshot.
+  if (session?.version !== COAUTHOR_SESSION_VERSION) throw new Error('unsupported session');
+  checkEvent(event);
+  const fingerprint = contentDigest(canonicalize(event));
+  const prior = session.events.find(item => item.id === event.id);
+  if (prior) {
+    if (prior.fingerprint !== fingerprint) throw new Error('event id conflict');
+    return { session: structuredClone(session), effects: [], duplicate: true };
+  }
+  if (event.expectedRevision !== session.revision) throw new Error('stale revision');
+  const state = structuredClone(session);
+  const effects = [];
+  switch (event.type) {
+    case 'answer':
+      need(state, ['input', 'draft']);
+      state.answers.push({ eventId: event.id, fieldId: state.fields[state.index].id, text: event.text });
+      state.proposal = { text: event.text, originalEventId: event.id, confirmed: true,
+        continueAfterSave: event.continueAfterSave ?? false };
+      state.phase = 'draft';
+      break;
+    case 'propose':
+      need(state, ['draft']);
+      // Every machine revision requires confirmation; no heuristic decides meaning.
+      state.proposal.text = event.text;
+      state.proposal.confirmed = false;
+      state.phase = 'confirmation';
+      break;
+    case 'confirm':
+      need(state, ['confirmation']);
+      state.proposal.confirmed = true;
+      state.phase = 'draft';
+      break;
+    case 'reject':
+      need(state, ['confirmation']);
+      state.proposal.text = state.answers.find(answer => answer.eventId === state.proposal.originalEventId).text;
+      state.proposal.confirmed = true;
+      state.phase = 'draft';
+      break;
+    case 'save':
+      need(state, ['draft']);
+      state.pending = { requestId: event.id, retries: 0 };
+      state.phase = 'saving';
+      effects.push(writeEffect(state));
+      break;
+    case 'failed':
+      need(state, ['saving']);
+      state.phase = 'recovery';
+      break;
+    case 'retry':
+      need(state, ['recovery']);
+      if (state.pending.retries >= 1) throw new Error('retry budget exhausted; adapter reconciliation required');
+      state.pending.retries += 1;
+      state.phase = 'saving';
+      effects.push(writeEffect(state));
+      break;
+    case 'receipt': {
+      need(state, ['saving', 'recovery']);
+      const expected = writeEffect(state);
+      for (const key of ['requestId', 'sessionId', 'fieldId', 'sourceRef', 'sourceDigest', 'valueDigest']) {
+        if (event.receipt[key] !== expected[key]) throw new Error(`receipt mismatch: ${key}`);
+      }
+      state.saved.push({ fieldId: expected.fieldId, text: state.proposal.text, receipt: structuredClone(event.receipt) });
+      state.phase = 'saved';
+      state.pending = null;
+      if (state.proposal.continueAfterSave) advance(state);
+      break;
+    }
+    case 'advance':
+      need(state, ['saved']);
+      advance(state);
+      break;
+    case 'pause':
+      need(state, ['input', 'draft', 'confirmation', 'saved', 'recovery']);
+      state.resumePhase = state.phase;
+      state.phase = 'paused';
+      break;
+    case 'resume':
+      need(state, ['paused']);
+      state.phase = state.resumePhase;
+      delete state.resumePhase;
+      break;
+  }
+  state.revision += 1;
+  state.events.push({ id: event.id, fingerprint, event: structuredClone(event) });
+  return { session: state, effects, duplicate: false };
+}
+export function replaySession(config, events) {
+  return events.reduce((session, event) => transition(session, event).session, createSession(config));
+}

package/src/coauthor/store.mjs

@@ -0,0 +1,173 @@
+import { withPrivateLock, publishPrivateFile } from '../project/durable-state.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { canonicalize } from '../attestation/jcs.mjs';
+import { createCollaborationEventLedger } from '../collaboration/event-ledger.mjs';
+import { ensureContainedPrivateDirectory, openRegularFileNoFollow } from '../project/private-state.mjs';
+import { createSession, transition, contentDigest } from './session.mjs';
+import { validateJsonSchema } from '../export/atelier-export-contract.mjs';
+
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-coauthor.v1.schema.json', import.meta.url), 'utf8'));
+function validate(value, kind) {
+  const errors = validateJsonSchema({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${kind}` }, value);
+  if (errors.length) throw new Error(`invalid coauthor ${kind}`);
+}
+
+const MAX_SOURCE_BYTES = 1024 * 1024;
+function readText(file) {
+  const fd = openRegularFileNoFollow(file);
+  try {
+    if (fs.fstatSync(fd).size > MAX_SOURCE_BYTES) throw new Error('coauthor file exceeds byte limit');
+    return new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(fd));
+  } finally { fs.closeSync(fd); }
+}
+function sourcePath(root, ref) {
+  if (typeof ref !== 'string' || !ref || ref.includes('\\') || path.isAbsolute(ref) || ref.split('/').some(s => !s || s === '.' || s === '..' || s.startsWith('.'))) {
+    throw new Error('source must be a visible workspace-relative file');
+  }
+  let current = root;
+  for (const part of ref.split('/')) {
+    current = path.join(current, part);
+    if (fs.lstatSync(current).isSymbolicLink()) throw new Error('redirected source refused');
+  }
+  return current;
+}
+
+// Local CLI boundary, not an authenticated multi-user service. Responses remain
+// private drafts; this store never modifies a canonical source file.
+export function createCoauthorStore({ workspaceRoot = process.cwd() } = {}) {
+  const root = fs.realpathSync(workspaceRoot);
+  function privatePlacement() {
+    const gitEnv = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')));
+    try {
+      const tracked = execFileSync('git', ['-C', root, 'ls-files', '-z', '--', '.atelier-local'], { env: gitEnv, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+      if (tracked) throw new Error('tracked private state');
+      execFileSync('git', ['-C', root, 'check-ignore', '--quiet', '.atelier-local/'], { env: gitEnv, stdio: 'ignore' });
+    } catch { throw new Error('coauthor requires a Git workspace with untracked, ignored .atelier-local/ state'); }
+  }
+  privatePlacement();
+  const directory = () => ensureContainedPrivateDirectory({ workspaceRoot: root,
+    directory: path.join(root, '.atelier-local', 'coauthor'), label: 'coauthor state' });
+  const ledger = () => createCollaborationEventLedger({ workspaceRoot: root,
+    ledgerPath: path.join(directory(), 'events.ndjson') });
+  const aggregate = id => `coauthor-${contentDigest(id)}`;
+  function locked(operation) {
+    privatePlacement();
+    const lockPath = path.join(directory(), 'operation.lock');
+    return withPrivateLock(lockPath, operation);
+  }
+  function load(id) {
+    const result = ledger().eventsFor(aggregate(id));
+    if (!result.ok) throw new Error(result.error);
+    if (!result.events.length) throw new Error('coauthor session not found');
+    let state;
+    let previous = null;
+    let version = 0;
+    let config;
+    for (const record of result.events) {
+      if (record.version !== ++version || record.payload.previousEventId !== previous) throw new Error('coauthor event chain is incomplete');
+      if (version === 1) {
+        if (record.type !== 'coauthor.started') throw new Error('coauthor start missing');
+        config = record.payload.config;
+        validate(config, 'config');
+        if (config.id !== id) throw new Error('coauthor identity mismatch');
+        state = createSession(config);
+      } else {
+        if (record.type !== 'coauthor.transition') throw new Error('unknown coauthor record');
+        const next = transition(state, record.payload.event);
+        if (next.duplicate) throw new Error('duplicate persisted transition');
+        state = next.session;
+      }
+      previous = record.id;
+    }
+    return { state, config, version, previous };
+  }
+  function verifySources(config) {
+    for (const field of config.fields) {
+      if (contentDigest(readText(sourcePath(root, field.source.ref))) !== field.source.digest) throw new Error('source changed; preserve history and start a newly bound session');
+    }
+  }
+  function append(id, current, event) {
+    const next = transition(current.state, event);
+    if (next.duplicate) return current;
+    const result = ledger().append({ aggregateId: aggregate(id), expectedVersion: current.version,
+      type: 'coauthor.transition', actor: 'local-harness', payload: { previousEventId: current.previous, event } });
+    if (!result.ok) throw new Error(result.error);
+    return { ...current, state: next.session, version: result.event.version, previous: result.event.id };
+  }
+  function reconcile(id, current) {
+    if (!['saving', 'recovery'].includes(current.state.phase)) return current;
+    verifySources(current.config);
+    const state = current.state;
+    const field = state.fields[state.index];
+    const requestId = state.pending.requestId;
+    const values = ensureContainedPrivateDirectory({ workspaceRoot: root,
+      directory: path.join(directory(), 'values', contentDigest(id)), label: 'coauthor values' });
+    const target = path.join(values, `${contentDigest(requestId)}.json`);
+    const receipt = { sessionId: id, requestId, fieldId: field.id, sourceRef: field.source.ref,
+      sourceDigest: field.source.digest, valueDigest: contentDigest(state.proposal.text) };
+    const saved = { schema: 'atelier-coauthor-draft@v1', status: 'draft', text: state.proposal.text, receipt };
+    validate(saved, 'draft');
+    const bytes = canonicalize(saved);
+    try {
+      // Existing values are immutable. A retry only verifies identical bytes.
+      try {
+        fs.lstatSync(target);
+        if (readText(target) !== bytes) throw new Error('saved draft differs from pending value');
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+        publishPrivateFile(target, bytes);
+      }
+      if (readText(target) !== bytes) throw new Error('saved draft readback mismatch');
+      verifySources(current.config);
+    } catch (error) {
+      if (state.phase === 'saving') append(id, current, {
+        id: `failure-${contentDigest(requestId)}-${state.revision}`, expectedRevision: state.revision, type: 'failed',
+      });
+      throw error;
+    }
+    return append(id, current, { id: `receipt-${contentDigest(requestId)}`,
+      expectedRevision: state.revision, type: 'receipt', receipt });
+  }
+  return {
+    start(config) {
+      return locked(() => {
+        validate(config, 'config');
+        const clean = createSession(config);
+        const canonicalConfig = { id: clean.id, fields: clean.fields };
+        verifySources(canonicalConfig);
+        const current = ledger().eventsFor(aggregate(clean.id));
+        if (!current.ok) throw new Error(current.error);
+        if (current.events.length) {
+          const existing = load(clean.id);
+          if (canonicalize(existing.config) !== canonicalize(canonicalConfig)) throw new Error('session id already bound to another configuration');
+          return existing.state;
+        }
+        const result = ledger().append({ aggregateId: aggregate(clean.id), expectedVersion: 0,
+          type: 'coauthor.started', actor: 'local-harness', payload: { previousEventId: null, config: canonicalConfig } });
+        if (!result.ok) throw new Error(result.error);
+        return load(clean.id).state;
+      });
+    },
+    read(id) { return load(id).state; },
+    dispatch(id, event) {
+      return locked(() => {
+        if (['receipt', 'failed'].includes(event?.type)) throw new Error('receipt and failure events are store-owned');
+        const current = load(id);
+        verifySources(current.config);
+        const next = append(id, current, event);
+        // Duplicate historical events never cause repeated effects.
+        if (next === current) return next.state;
+        return ['save', 'retry'].includes(event.type) ? reconcile(id, next).state : next.state;
+      });
+    },
+    recover(id) { return locked(() => {
+      const current = load(id);
+      // Paused and exhausted sessions require an explicit resume or operator
+      // reconciliation. Never turn a read into another automatic write attempt.
+      if (current.state.phase !== 'saving') return current.state;
+      return reconcile(id, current).state;
+    }); },
+  };
+}

package/src/collaboration/event-ledger.mjs

@@ -1,6 +1,7 @@
 import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
+import { withPrivateLock } from '../project/durable-state.mjs'
 import { canonicalize } from '../attestation/jcs.mjs'
 import {
   atomicReplacePrivateText,
@@ -26,18 +27,13 @@ function validTimestamp(value) {
 }
 
 function secureAppendLine(file, line) {
-  const descriptor = openRegularFileNoFollow(
-    file,
-    fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT,
-    0o600,
-  )
+  let previous = '';
   try {
-    fs.writeFileSync(descriptor, line)
-    fs.fsyncSync(descriptor)
-    fs.fchmodSync(descriptor, 0o600)
-  } finally {
-    fs.closeSync(descriptor)
-  }
+    const fd = openRegularFileNoFollow(file);
+    try { previous = fs.readFileSync(fd, 'utf8'); } finally { fs.closeSync(fd); }
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  // The ledger is bounded. Replace its complete validated prefix atomically.
+  atomicReplacePrivateText(file, previous + line);
 }
 
 function eventId(event) {
@@ -215,30 +211,12 @@ export function createCollaborationEventLedger({
   }
 
   function withWriteLock(operation) {
-    let descriptor
-    try {
-      descriptor = fs.openSync(lockPath, 'wx', 0o600)
-      fs.writeFileSync(descriptor, `${process.pid}\n`)
-      fs.fsyncSync(descriptor)
-    } catch (error) {
-      if (descriptor != null) fs.closeSync(descriptor)
-      if (error?.code === 'EEXIST') return { ok: false, status: 423, error: 'collaboration ledger is locked; retry after the active writer finishes' }
-      return { ok: false, status: 500, error: `collaboration ledger lock failed: ${error.message}` }
-    }
-    try {
-      return operation()
-    } finally {
-      fs.closeSync(descriptor)
-      try {
-        fs.unlinkSync(lockPath)
-      } catch {
-        // The completed write remains authoritative; cleanup can be diagnosed
-        // by the next writer's explicit locked result.
-      }
-    }
+    try { return withPrivateLock(lockPath, operation); }
+    catch (error) { return { ok: false, status: error.code === 'EEXIST' ? 423 : 500,
+      error: `collaboration ledger lock/write failed: ${error.message}` }; }
   }
 
-  function append({ aggregateId, expectedVersion = 0, type, actor, at = clock(), payload = {} }) {
+  function append({ aggregateId, expectedVersion = 0, type, actor, at = clock(), payload = {}, precondition = null }) {
     return withWriteLock(() => {
       const current = eventsFor(aggregateId)
       if (!current.ok) return current
@@ -249,6 +227,11 @@ export function createCollaborationEventLedger({
           error: `stale collaboration event refused: expected ${expectedVersion}, current ${current.currentVersion}`,
         }
       }
+      if (precondition !== null) {
+        if (typeof precondition !== 'function') return { ok: false, status: 400, error: 'append precondition must be a function' }
+        const permitted = precondition()
+        if (!permitted?.ok) return { ok: false, status: permitted?.status ?? 409, error: permitted?.error ?? 'append precondition refused' }
+      }
       if (current.stats.eventCount >= limits.maxEvents) {
         return { ok: false, status: 413, error: `collaboration ledger reached ${limits.maxEvents} event hard ceiling; compact it explicitly before appending` }
       }