Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
40.9 KB
Raw Blame
/** Trusted local administration, shared by direct CLI and its authenticated resident proxy. */
import { isAbsolute, join } from 'node:path';
import { claimedWorktreeRoot, inspectClaimedPhysicalRoot } from './topology-locks.ts';
import { movedPhysicalRootRefusal } from './physical-root.ts';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { UNSUPPORTED_MANAGED_BULK_WRITERS } from './maintenance.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { isValidSourceId } from '../source-id.ts';
import { assertValidSlugPrefixes } from '../grants/encoding.ts';
import { isWriteRequestId } from './types.ts';
import { writerDiagnostics } from './control.ts';
import { acceptWriterTransfer, claimWorktree, getWorktreeBinding, humanManifestProgress, prepareWriterTransfer, readManagedMode, storedManifestScope, worktreeManifest, type StoredWorktreeManifest } from './ownership.ts';
import { inspectPersistenceBrain } from './managed-mode.ts';
import { currentVerifiedLocalWriter, persistenceHome, readLocalWriter, registerLocalWriter, revokeLocalWriter, type LocalGrant, existingHostIdFor } from './identity.ts';
import type { PersistenceAdminOperation } from './admin-contract.ts';
import { operationScopesAllowed } from '../scope.ts';
import { assertWriterAdminState, requireWriterAdminIntent, writerAdminState, WRITER_INSPECTION_HINT } from './admin-intent.ts';
import { writerOnboardingPreflight } from './onboarding.ts';
import { assertWriterAdminUnlocked, readWriterAdminLock, setWriterAdminLock } from './admin-lock.ts';
import { listBlockingEffects } from './blocking-effects.ts';
import { listWriterVersions } from './writer-versions.ts';
import { readFix, trustedCliRequired } from '../ops/op-fix.ts';
import type { Action } from '../agent-output.ts';

async function writerStatusCheckouts(bindings: Array<{ source_id: string; local_path: string | null }>) {
  const { readCheckoutState } = await import('./checkout-state.ts');
  const roots = new Map<string, string[]>();
  for (const { source_id, local_path } of bindings) if (local_path) roots.set(local_path, [...roots.get(local_path) ?? [], source_id]);
  return [...roots].map(([root, source_ids]) => ({ source_ids, ...readCheckoutState(root) }));
}

export const invalid = (message: string, suggestion: string, fix?: Action) =>
  opError('invalid_params', message, suggestion, fix ? { fix } : {});
const sourcesListFix = (why: string) => readFix(why, { argv: ['gbrain', 'sources', 'list', '--json'] });
const writerListFix = readFix('Lists the local writer registrations and their ids, read-only.', { argv: ['gbrain', 'auth', 'local-writer', 'list', '--json'] });
const LIST_EXAMPLES: Record<string, string> = { source_ids: 'default,notes', scopes: 'read,write', allowed_operations: 'search,get_page', slug_prefixes: 'people/,companies/' };
const cliFlag = (key: string) => `--${key.replaceAll('_', '-')}`;
export function source(value: unknown): string {
  if (typeof value !== 'string' || !isValidSourceId(value)) throw invalid('An explicit active source ID is required.', 'Name the source explicitly with its id; gbrain sources list --json shows the active sources.',
    sourcesListFix('Lists the active source ids, read-only.'));
  return value;
}
export function path(value: unknown): string {
  if (typeof value !== 'string' || !isAbsolute(value) || value.includes('\0')) throw invalid('path must be an absolute directory path on this host.',
    'Pass --path with an absolute directory on this host, e.g. --path /srv/brain/notes; a relative path or one containing a NUL byte is refused.');
  return value;
}
function uuid(value: unknown, message: string, suggestion: string, fix?: Action): string {
  if (!isWriteRequestId(value)) throw invalid(message, suggestion, fix);
  return value;
}
function strings(value: unknown, key: string): string[] {
  if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || !item)) throw invalid(`${key} must be an array of non-empty strings.`,
    `Pass ${cliFlag(key)} as a comma-separated list with no empty entries, e.g. ${cliFlag(key)} ${LIST_EXAMPLES[key] ?? 'a,b'}.`);
  return [...new Set(value)];
}
export function bool(params: Record<string, unknown>, key: string): void {
  if (params[key] !== undefined && typeof params[key] !== 'boolean') throw invalid(`${key} must be a boolean.`,
    `Send ${key} as a JSON boolean (true or false); on the CLI it is the bare flag ${cliFlag(key)}, which takes no value.`);
}
export function keys(params: Record<string, unknown>, allowed: string[]) {
  const unknown = Object.keys(params).filter(key => !allowed.includes(key));
  if (unknown.length) throw invalid(`Unsupported administration parameters: ${unknown.join(', ')}.`,
    `Remove ${unknown.join(', ')}; this operation accepts ${allowed.length ? allowed.join(', ') : 'no parameters'}. A caller on another gbrain release sends the parameters of its own release: run one release on both sides.`);
  bool(params, 'dry_run');
}

async function registrationGrant(engine: BrainEngine, params: Record<string, unknown>): Promise<LocalGrant> {
  const sourceIds = params.source_ids === undefined ? ['*'] : strings(params.source_ids, 'source_ids');
  if (!sourceIds.length || sourceIds.includes('*') && sourceIds.length !== 1 || sourceIds.some(id => id !== '*' && !isValidSourceId(id))) throw invalid('source_ids must name active sources, or contain only "*".',
    'Pass --source-ids as a comma-separated list of active source ids, or omit it to grant every source; "*" cannot be combined with ids.',
    sourcesListFix('Lists the active source ids a grant can name, read-only.'));
  if (!sourceIds.includes('*')) {
    const rows = await engine.executeRaw<{ id: string }>('SELECT id FROM sources WHERE id=ANY($1::text[]) AND NOT archived', [sourceIds]);
    const missing = sourceIds.filter(id => !rows.some(row => row.id === id));
    if (missing.length) throw invalid('Every source_ids entry must name an active source.',
      `${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} not an active source on this brain: drop ${missing.length === 1 ? 'it' : 'them'} from --source-ids, or add or restore the source first.`,
      sourcesListFix('Lists the active source ids a grant can name, read-only.'));
  }
  const scopes = params.scopes === undefined ? ['read', 'write'] : strings(params.scopes, 'scopes');
  if (!scopes.length || scopes.some(scope => !['read', 'write', 'skill_editor', 'skills_member_self'].includes(scope))) throw invalid('Local writer scopes may contain read, write, skill_editor and skills_member_self only.',
    'Pass --scopes as a comma-separated subset of read, write, skill_editor and skills_member_self, e.g. --scopes read,write.');
  const operations = params.allowed_operations === undefined ? null : strings(params.allowed_operations, 'allowed_operations');
  if (scopes.some(scope => scope === 'skill_editor' || scope === 'skills_member_self') && !operations?.length) {
    throw invalid('Shared-skill capabilities require an explicit nonempty allowed_operations snapshot.',
      'Add --allowed-operations with the exact comma-separated operations this lane may call, or drop skill_editor and skills_member_self from --scopes.');
  }
  if (operations) {
    const { operations: registry } = await import('../operations.ts');
    const outside = operations.filter(name => !registry.some(op => op.name === name && !op.localOnly && operationScopesAllowed(scopes, op)));
    if (outside.length) {
      throw invalid('allowed_operations must name public operations within the requested read/write scope.',
        `Remove ${outside.join(', ')} from --allowed-operations, or widen --scopes (now ${scopes.join(',')}) to the scope each needs; local-only operations can never be granted.`);
    }
  }
  const slugPrefixes = params.slug_prefixes === undefined ? null : strings(params.slug_prefixes, 'slug_prefixes');
  if (slugPrefixes) assertValidSlugPrefixes(slugPrefixes);
  return { sourceIds, scopes, operations, slugPrefixes };
}

/** Shown by `writer claim` (and its dry run) while persistence is not activated. */
export const CLAIM_BEFORE_ACTIVATION_NOTICE = 'Persistence is not activated. After this claim, gbrain sync refuses this source with '
  + 'writer_coordinator_required until activation, and legacy file writers in its checkout (sources push, lint --fix and other '
  + 'file-writing maintenance) refuse while the checkout is managed. Stop older writers, review gbrain sources writer status, '
  + 'then activate deliberately.';

/** #6650: `sources writer failures` options, validated with the usage each one takes. */
function writerFailuresQuery(sourceId: string, params: Record<string, unknown>): import('./terminal-failures.ts').TerminalFailureQuery {
  const bad = (key: string, pattern: RegExp) => params[key] !== undefined && (typeof params[key] !== 'string' || !pattern.test(params[key] as string));
  if (bad('state', /^(all|unresolved)$/)) throw invalid('Invalid --state value.', 'Pass --state all to include resolved and historical receipts, or leave it out for the unresolved ones.');
  if (bad('group_by', /^category$/)) throw invalid('Invalid --group-by value.', 'Pass --group-by category (groups on code, origin and category, and a sync fault on its operation too), or leave it out to list receipts.');
  if (bad('since', /^[1-9]\d{0,3}d$/)) throw invalid('Invalid --since value.', 'Pass --since as whole days, e.g. --since 7d; the window is clamped to persistence.receipt_retention_days.');
  if (bad('before', /^\d{1,19}$/)) throw invalid('Invalid --before value.', 'Pass --before exactly as the previous page\'s next_cursor.');
  if (bad('code', /^[a-z][a-z0-9_]{0,63}$/)) throw invalid('Invalid --code value.', 'Pass --code as a snake_case code a group names, e.g. --code storage_error.');
  if (bad('origin', /^[a-z][a-z0-9_]{0,63}$/)) throw invalid('Invalid --origin value.', 'Pass --origin as an origin a group names, or none for receipts with no recorded origin.');
  if (bad('operation', /^[a-z][a-z0-9_]{0,63}$/)) throw invalid('Invalid --operation value.', 'Pass --operation as the operation a group names, e.g. --operation put_page or --operation canonical_reconcile.');
  if (bad('category', /^[a-z][a-z_]{0,63}$/)) throw invalid('Invalid --category value.', 'Pass --category as a category a group names, e.g. --category knock_on.');
  if (params.limit !== undefined && !(typeof params.limit === 'number' && Number.isInteger(params.limit) && params.limit >= 1 && params.limit <= 100)) {
    throw invalid('Invalid --limit value.', 'Pass --limit as a whole number from 1 to 100 (default 20).');
  }
  const p = params as { state?: 'all' | 'unresolved'; group_by?: string; since?: string; limit?: number; before?: string; code?: string; origin?: string; category?: string; operation?: string };
  return { sourceId, ...(p.state ? { state: p.state } : {}), ...(p.group_by ? { groupBy: 'category' as const } : {}), ...(p.since ? { sinceDays: Number(p.since.slice(0, -1)) } : {}),
    ...(p.limit !== undefined ? { limit: p.limit } : {}), ...(p.before ? { before: p.before } : {}), ...(p.code ? { code: p.code } : {}), ...(p.origin ? { origin: p.origin } : {}),
    ...(p.category ? { category: p.category } : {}), ...(p.operation ? { operation: p.operation } : {}) };
}

/** GBRA-130 A-59: writer status's movement, or a `not_read` with its code and a read-only fix; a failed read never reads as no movement. */
async function writerStatusMovement(engine: BrainEngine, sourceId: string | undefined) {
  return (await import('./sync-movement.ts')).readSourceMovement(engine, sourceId === undefined ? {} : { sourceIds: [sourceId] })
    .catch((error: unknown) => ({ status: 'not_read' as const, code: String((error as { code?: unknown } | null)?.code ?? 'storage_error'),
      fix: readFix('Reads source movement on its own, read-only.', { argv: ['gbrain', 'sources', 'writer', 'movement', ...(sourceId === undefined ? [] : [sourceId]), '--json'] }) }));
}

async function writerClaim(engine: BrainEngine, params: Record<string, unknown>): Promise<Record<string, unknown>> {
  keys(params, ['source_id', 'path', 'dry_run', 'admin_intent', 'expected_state']);
  const sourceId = source(params.source_id), root = path(params.path);
  // #5198: say at claim time what the claim retires, before and after the fact.
  const notice = await readManagedMode(engine) ? {} : { activation_required: CLAIM_BEFORE_ACTIVATION_NOTICE };
  // #8625: a moved checkout at the root the claim reserves is named with its exit.
  const worktree = claimedWorktreeRoot(root);
  if (params.dry_run) {
    if (worktree) await inspectClaimedPhysicalRoot(engine, sourceId, worktree, 'claim', existingHostIdFor(engine));
    return { dry_run: true, action: 'writer_claim', source_id: sourceId, path: root, current: await getWorktreeBinding(engine, sourceId, existingHostIdFor(engine)), ...notice };
  }
  const expectedState = await requireWriterAdminIntent(engine, 'writer_claim', params);
  try { return { claimed: true, binding: await claimWorktree(engine, sourceId, root, undefined, expectedState), ...notice }; }
  catch (error) {
    if (!(error instanceof OperationError) || error.detail !== 'physical_root_moved' || !worktree) throw error;
    throw await movedPhysicalRootRefusal(engine, worktree, { sourceId, operation: 'claim' }, existingHostIdFor(engine)) ?? error;
  }
}

export async function runPersistenceAdministration(engine: BrainEngine, operation: PersistenceAdminOperation,
  params: Record<string, unknown>, config?: GBrainConfig, embeddingRetryPolicy: 'owner' | 'mounted_database' = 'owner'): Promise<Record<string, unknown>> {
  if (operation === 'writer_reconcile_preview') return (await import('./reconcile.ts')).runReconcilePreview(engine, params);
  if (operation === 'writer_reconcile_apply') return (await import('./reconcile.ts')).runReconcileApply(engine, params);
  if (operation === 'writer_reconcile_audit') return (await import('./reconcile-audit.ts')).runReconcileAudit(engine, params);
  if (operation === 'writer_reconcile_backups') return (await import('./reconcile.ts')).runReconcileBackups(engine, params);
  if (operation === 'company_brain_preview' || operation === 'company_brain_connect' || operation === 'company_brain_resume') {
    const writer = currentVerifiedLocalWriter();
    if (!writer || writer.remote || writer.principal.kind !== 'local_cli') throw trustedCliRequired('Company source administration requires an authenticated local CLI registration.');
    keys(params, ['brain_id', 'source_id', 'path', 'plan', 'request_id']);
    if (typeof params.brain_id !== 'string' || !params.brain_id.trim()) throw invalid('An explicit brain_id is required.',
      'Name the destination brain with --brain on gbrain sources connect (host, or a mounted brain id); gbrain mounts list --json shows the mounted brains.');
    const destination = { brainId: params.brain_id, sourceId: source(params.source_id), remote: false };
    const runtime = await import('../company-brain/runtime.ts');
    if (operation === 'company_brain_resume') return { ...await runtime.resumeCompanyBrain(engine, destination) };
    const input = { ...destination, path: path(params.path), plan: params.plan as import('../company-brain/types.ts').CompanyBrainPlan,
      ...(params.request_id === undefined ? {} : { requestId: uuid(params.request_id, 'A valid connect request UUID is required.',
        'Pass --request-id with the UUID the earlier connect preview printed, or omit it to start a new connect request.') }) };
    if (operation === 'company_brain_preview') return { ...await runtime.previewCompanyBrain(engine, input) };
    return { ...await runtime.connectCompanyBrain(engine, input) };
  }
  if (operation === 'trust_read' || operation === 'trust_preview' || operation === 'trust_apply') return (await import('../trust/owner-ipc.ts')).runTrustAdministration(engine, operation, params, config);
  if (currentVerifiedLocalWriter()?.remote) throw trustedCliRequired('Writer administration requires a trusted local CLI caller.');
  if (operation === 'writer_lock' || operation === 'writer_unlock') {
    keys(params, []);
    return { ...await setWriterAdminLock(engine, operation === 'writer_lock') };
  }
  // Early refusal before any native lock or preview; the checks inside each transaction stay authoritative.
  if (['writer_claim', 'writer_activate', 'writer_transfer_prepare', 'writer_transfer_accept', 'writer_transfer_cancel'].includes(operation)) await assertWriterAdminUnlocked(engine);
  if (operation === 'writer_sync') return (await import('./sync-administration.ts')).runAuthenticatedSyncSlice(engine, params);
  if (operation === 'writer_refresh') {
    keys(params, ['source_id', 'dry_run', 'resume', 'abandon', 'wait_drain_ms', 'fetch_timeout_ms']);
    const writer = currentVerifiedLocalWriter();
    if (!writer || writer.remote || writer.principal.kind !== 'local_cli') throw trustedCliRequired('Worktree refresh requires a trusted CLI registration.');
    const ms = (value: unknown, name: string) => {
      if (value === undefined) return undefined;
      if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) throw invalid(`${name} must be a non-negative number of milliseconds.`, 'Pass `--wait-drain <seconds>` or `--fetch-timeout-ms <ms>` to `gbrain sources refresh <source-id>` with a non-negative number, or leave the flag out for its default.');
      return value;
    };
    const waitDrainMs = ms(params.wait_drain_ms, 'wait_drain_ms');
    const fetchTimeoutMs = ms(params.fetch_timeout_ms, 'fetch_timeout_ms');
    return { ...await (await import('./worktree-refresh.ts')).refreshWorktree(engine, source(params.source_id), {
      dryRun: params.dry_run === true, resume: params.resume === true, abandon: params.abandon === true,
      ...(waitDrainMs !== undefined ? { waitDrainMs } : {}), ...(fetchTimeoutMs !== undefined ? { fetchTimeoutMs } : {}) }) };
  }
  if (operation === 'writer_extract_stale') {
    keys(params, ['source_id', 'dry_run', 'catch_up', 'source_mode', 'retry_held']);
    const writer = currentVerifiedLocalWriter();
    if (!writer || writer.remote || writer.principal.kind !== 'local_cli') throw trustedCliRequired('Stale extraction requires a trusted CLI registration.');
    const { managedPersistenceEnabled } = await import('./ownership.ts');
    if (!await managedPersistenceEnabled(engine)) throw new OperationError('writer_coordinator_required', 'Owner-delegated stale extraction requires activated managed persistence.', WRITER_INSPECTION_HINT);
    const sourceId = params.source_id === undefined ? undefined : source(params.source_id);
    // #6803 (D2): the CLI validated --source before the hand-off; only the owner can see whether a source is named db.
    if (params.source_mode === 'db') await (await import('../../commands/extract-stale-options.ts')).assertStaleSourceModeUnambiguous(engine, ['--stale', '--source', 'db', ...(sourceId ? ['--source-id', sourceId] : [])]);
    return { ...await (await import('./links-maintenance.ts')).runManagedStaleExtraction(engine,
      { sourceId, dryRun: params.dry_run === true, catchUp: params.catch_up === true, retryHeld: params.retry_held === true }) };
  }
  if (operation === 'writer_reindex_code') return (await import('./reindex-administration.ts')).runAuthenticatedCodeReindex(engine, params);
  if (operation === 'writer_embed_facts') return (await import('./embed-facts-administration.ts')).runAuthenticatedFactEmbedding(engine, params, config);
  if (operation === 'writer_git_durability') {
    const { GIT_DURABILITY_PARAMS, runGitDurabilityAdministration } = await import('./git-durability-administration.ts');
    keys(params, [...GIT_DURABILITY_PARAMS]);
    source(params.source_id);
    return runGitDurabilityAdministration(engine, params);
  }
  if (operation === 'writer_retry_effects') {
    keys(params, ['source_id', 'request_id', 'dry_run', 'admin_intent', 'expected_state', 'parked_pushes', 'parked_code']);
    if (params.parked_code !== undefined) {
      if (typeof params.parked_code !== 'string' || !/^[a-z][a-z0-9_]*$/.test(params.parked_code) || params.parked_pushes !== undefined || params.request_id !== undefined
        || params.admin_intent !== undefined || params.expected_state !== undefined) throw invalid(
        '--parked-code retries every Git effect of the source parked on one error code; it takes no --request-id, --parked-pushes or admin intent.',
        'Run gbrain sources writer retry-effects <source> --parked-code <code> [--dry-run]; doctor parked_effects lists each parked code with its command.');
      return (await import('./git-durability-administration.ts')).retrySourceParkedCode(engine, source(params.source_id), params.parked_code, params.dry_run === true);
    }
    if (params.parked_pushes === true) {
      if (params.request_id !== undefined || params.admin_intent !== undefined || params.expected_state !== undefined) throw invalid(
        '--parked-pushes retries every parked push of the source; it takes no --request-id or admin intent.',
        'Run gbrain sources writer retry-effects <source> --parked-pushes [--dry-run], or name one request with --request-id instead.');
      return (await import('./git-durability-administration.ts')).retrySourceParkedPushes(engine, source(params.source_id), params.dry_run === true);
    }
    if (!isWriteRequestId(params.request_id)) throw invalid('A valid original write request UUID is required.',
      'Pass --request-id with the original write\'s request id (a UUID); gbrain sources writer status for that source lists blocked effects with their request ids.',
      typeof params.source_id === 'string' && isValidSourceId(params.source_id)
        ? readFix(`Lists source ${params.source_id}'s blocked effects with their request ids, read-only.`, { argv: ['gbrain', 'sources', 'writer', 'status', params.source_id, '--json'] })
        : undefined);
    // #6697 (D6): the admin-intent handshake is the owner's approval to retry a revoked writer's parked Git effect under owner authority.
    const ownerHost = params.admin_intent !== undefined || params.expected_state !== undefined;
    if (ownerHost) await requireWriterAdminIntent(engine, 'writer_retry_effects', params);
    return (await import('./effect-retry.ts')).retryRequestEffects(engine, source(params.source_id), params.request_id, params.dry_run === true, config, embeddingRetryPolicy, ownerHost);
  }
  if (operation === 'writer_settle_effects') {
    keys(params, ['source_id', 'request_id', 'parked_code', 'unsettle', 'retire', 'apply', 'expect', 'dry_run']);
    bool(params, 'unsettle'); bool(params, 'retire'); bool(params, 'apply');
    if (params.apply === true && params.dry_run === true) throw invalid('settle-effects takes --dry-run or --apply, not both.',
      'Preview with --dry-run, then run the apply_command it prints (--apply --expect <plan_hash>) after the user agrees.');
    if (params.parked_code !== undefined && (typeof params.parked_code !== 'string' || !/^[a-z][a-z0-9_]*$/.test(params.parked_code))) throw invalid('Invalid --parked-code value.',
      'Pass --parked-code as a snake_case code doctor parked_effects names, e.g. --parked-code git_target_unsafe.');
    if (params.expect !== undefined && (typeof params.expect !== 'string' || !/^ph_[0-9a-f]{24}$/.test(params.expect))) throw invalid('Invalid --expect value.',
      'Pass --expect exactly as the plan_hash the settle-effects preview printed (ph_ followed by 24 hex digits).');
    const sourceId = source(params.source_id);
    const requestId = params.request_id === undefined ? undefined : uuid(params.request_id, 'A valid original write request UUID is required.',
      'Pass --request-id with the request id doctor parked_effects or gbrain sources writer status lists for the effect.');
    return (await import('./effect-settle.ts')).settleEffects(engine, { sourceId, requestId, parkedCode: params.parked_code as string | undefined,
      unsettle: params.unsettle === true, retire: params.retire === true, apply: params.apply === true, expect: params.expect as string | undefined });
  }
  if (operation === 'source_add' || operation === 'source_lifecycle') {
    const { managedPersistenceEnabled } = await import('./ownership.ts');
    if (!await managedPersistenceEnabled(engine)) throw new OperationError('writer_coordinator_required',
      'Resident source administration requires activated managed persistence.',
      WRITER_INSPECTION_HINT);
  }
  if (operation === 'source_add') {
    keys(params, ['options', 'request_id', 'dry_run', 'legacy_hardening']);
    if (params.legacy_hardening !== undefined) throw new OperationError('writer_coordinator_required',
      'Source creation cannot install legacy Git hardening on a managed worktree.', 'Create the source without --pat-file.');
    if (!params.options || typeof params.options !== 'object' || Array.isArray(params.options)) throw invalid('Source add requires typed options.',
      'Add the source with gbrain sources add, which builds the typed options; a resident-proxy caller sends params.options as a JSON object.');
    const { managedSourceAddInput } = await import('./managed-sources.ts');
    const { runManagedSourceLifecycle } = await import('./source-lifecycle.ts');
    const options = await (await import('../source-default-search.ts')).withDefaultSearchChoice(engine, params.options as import('../sources-ops.ts').AddSourceOpts);
    if (options.requestId !== params.request_id || !isWriteRequestId(params.request_id)) throw invalid('Source add request identity must match its options.',
      'Send one UUID as both params.request_id and options.requestId; gbrain sources add sets both from one request id, so run the add through it.');
    return runManagedSourceLifecycle(engine, { ...managedSourceAddInput(options), dryRun: params.dry_run === true });
  }
  if(operation==='source_lifecycle') {
    keys(params,['action','source_id','request_id','expected_incarnation','path','name','config','refederate','confirm_destructive','dry_run','remote_url','create_directory','expired_only']);
    if (params.action === 'claim') throw new OperationError('writer_admin_intent_required', 'Claims require the dedicated state-bound writer administration surface.', WRITER_INSPECTION_HINT);
    const { runManagedSourceLifecycle }=await import('./source-lifecycle.ts');
    const result=await runManagedSourceLifecycle(engine,{operation:params.action as import('./source-lifecycle.ts').SourceLifecycleInput['operation'],sourceId:source(params.source_id),
      requestId:params.request_id as string|undefined,expectedIncarnation:params.expected_incarnation as string|undefined,
      path:params.path===undefined?undefined:path(params.path),name:params.name as string|undefined,config:params.config as Record<string,unknown>|undefined,
      refederate:params.refederate as boolean|undefined,confirmDestructive:params.confirm_destructive as boolean|undefined,dryRun:params.dry_run===true,
      remoteUrl:params.remote_url as string|undefined,createDirectory:params.create_directory as boolean|undefined,expiredOnly:params.expired_only as boolean|undefined});
    // #8982: a restore that re-federates names the remote-written pages without readers it makes no-grant readable.
    if (params.action !== 'restore' || params.dry_run === true || result.noop === true || params.source_id === 'default') return result;
    const [restored] = await engine.executeRaw<{ config: unknown }>('SELECT config FROM sources WHERE id=$1', [source(params.source_id)]);
    const exposed = await (await import('../access/federation-exposure.ts')).remotePagesFederationExposesOrWarn(engine, source(params.source_id),
      (await import('../sources-load.ts')).isSourceFederated(restored?.config));
    return exposed ? { ...result, pages_exposed: exposed } : result;
  }
  if (operation === 'writer_failures') {
    keys(params, ['source_id', 'state', 'group_by', 'since', 'limit', 'before', 'code', 'origin', 'category', 'operation']);
    const sourceId = source(params.source_id);
    const [known] = await engine.executeRaw<{ id: string }>('SELECT id FROM sources WHERE id=$1 AND archived IS NOT TRUE', [sourceId]);
    if (!known) throw invalid(`No active source ${sourceId}.`, 'Name an active source; archived sources are not inspected.', sourcesListFix('Lists the active source ids, read-only.'));
    const { readTerminalFailures } = await import('./terminal-failures.ts');
    return { ...await readTerminalFailures(engine, writerFailuresQuery(sourceId, params)) };
  }
  if (operation === 'writer_status') {
    keys(params, ['source_id', 'probe']);
    bool(params, 'probe');
    const adminState = await writerAdminState(engine);
    const diagnostics = await writerDiagnostics(engine);
    const bindings = await engine.executeRaw(`SELECT b.source_id,b.source_incarnation,b.worktree_id,b.relative_path,b.topology_generation::text AS topology_generation,
      w.owner_host_id,w.owner_epoch::text AS owner_epoch,w.state,w.manifest->>'digest' AS manifest_digest,w.manifest->>'prepared_at' AS prepared_at,h.local_path,h.git_durability,
      CASE h.git_durability WHEN 'enabled' THEN 'on' WHEN 'disabled' THEN 'off' ELSE 'unknown' END AS git_durability_state FROM persistence_source_bindings b
      JOIN persistence_worktrees w ON w.id=b.worktree_id
      LEFT JOIN persistence_host_bindings h ON h.worktree_id=b.worktree_id AND h.host_id=$1::uuid
      WHERE ($2::text IS NULL OR b.source_id=$2) ORDER BY b.source_id`, [existingHostIdFor(engine), params.source_id === undefined ? null : source(params.source_id)]);
    let native: unknown;
    if (params.probe === true) {
      const { nativeLockCapability, tryAcquireNativeLock } = await import('./native-lock.ts');
      const capability = await nativeLockCapability();
      const lock = await tryAcquireNativeLock(join(persistenceHome(), 'locks', 'admin-status-probe.lock'));
      if (!lock) {
        throw opError('writer_lock_unavailable', 'The native lock probe is busy.',
          'Another writer status probe or activation holds the native probe lock on this host. Run the status again without --probe, or probe again once the other command finishes; both are read-only.');
      }
      await lock.release();
      native = { ...capability, acquired: true, released: lock.released };
    }
    const onboarding = await writerOnboardingPreflight(engine, params.source_id as string | undefined);
    const [sharedSkills] = await engine.executeRaw<{ writer_protocol_floor: number; skill_bundles_enabled: boolean }>(
      'SELECT writer_protocol_floor,skill_bundles_enabled FROM persistence_brain WHERE singleton=1');
    const adminLock = await readWriterAdminLock(engine);
    const blockingEffects = await listBlockingEffects(engine, { sourceId: params.source_id as string | undefined, limit: 20 });
    const writerVersions = await listWriterVersions(engine);
    await assertWriterAdminState(engine, adminState, false);
    const { cleanupRetiredManagedMarkers } = await import('./deactivation.ts');
    // #6482: a malformed singleton reports `mode: 'unknown'` with its problem (this is the refusal's fix command), never refuses.
    const mode = await inspectPersistenceBrain(engine);
    return { ...diagnostics, mode: !mode.row ? 'unknown' : mode.row.enabled ? 'managed' : 'classic', mode_epoch: Number(mode.row?.mode_epoch ?? 1),
      ...(mode.problem ? { mode_problem: mode.problem } : {}),
      local_markers: await cleanupRetiredManagedMarkers(engine),
      host_id: existingHostIdFor(engine), local_host_id: existingHostIdFor(engine), bindings, admin_state: adminState,
      admin_lock: { locked: adminLock.locked, set_at: adminLock.set_at, host_id: adminLock.host_id }, blocking_effects: blockingEffects,
      // GBRA-133: effects that have waited on a busy canonical worktree for over 10 minutes.
      stalled_catchups: await (await import('./effect-catchup.ts')).readStalledCatchups(engine, params.source_id ? [params.source_id as string] : undefined),
      parked_groups: await (await import('./parked-groups.ts')).readParkedGroups(engine, params.source_id ? [params.source_id as string] : undefined),
      writer_versions: writerVersions, onboarding, shared_skills: sharedSkills, ...(native ? { native_lock: native } : {}),
      // #6317 (B3): every process holding a consumer on this host, from the heartbeat rows (kind, pid, nonce, mode, age, wedge report).
      host: { host_id: existingHostIdFor(engine), ...await (await import('./consumer-diagnostics.ts')).hostConsumersReport(engine, existingHostIdFor(engine)) },
      worktree_refreshes: await (await import('./worktree-refresh.ts')).activeWorktreeRefreshes(engine, params.source_id as string | undefined),
      // #8984: stopped remove/purge requests (retire admissions) and the ones a later lifecycle change superseded.
      topology_requests: await engine.executeRaw(`SELECT request_id::text AS request_id,operation,source_id,source_incarnation::text AS source_incarnation,state,outcome->>'error' AS error,created_at::text AS created_at
        FROM persistence_topology_changes WHERE ($1::text IS NULL OR source_id=$1) AND operation IN ('remove','purge') AND recovery IS NULL
        AND (state='recovering' OR state='failed' AND outcome->>'error'='source_retire_superseded') ORDER BY created_at DESC LIMIT 20`, [params.source_id === undefined ? null : source(params.source_id)]),
      // Q1: each canonical checkout on this host against its last fetched upstream: commits it holds that the upstream lacks, and its porcelain.
      checkouts: await writerStatusCheckouts(bindings as Array<{ source_id: string; local_path: string | null }>),
      // #6317 (B4): per managed source, whether sync data moves (shares the reader of sources status, doctor and writer movement).
      movement: await writerStatusMovement(engine, params.source_id === undefined ? undefined : source(params.source_id)) };
  }
  if (operation === 'writer_claim') return writerClaim(engine, params);
  if (operation === 'writer_activate') {
    keys(params, ['confirm_quiesced', 'dry_run', 'shared_skills', 'admin_intent', 'expected_state', 'cleanup_dead_local_locks']);
    bool(params, 'cleanup_dead_local_locks');
    if (params.confirm_quiesced !== true) throw invalid('Activation requires --confirm-quiesced after upgrading and stopping older writers on every host.',
      'Upgrade and stop older writers on every host, review gbrain sources writer status --json, then run gbrain sources writer activate --confirm-quiesced with --admin-intent writer_activate and --expected-state set to the admin_state that status printed.',
      readFix('Shows writer topology, blocking effects and the admin_state activation must name, read-only.', { argv: ['gbrain', 'sources', 'writer', 'status', '--json'] }));
    bool(params, 'shared_skills');
    const expectedState = await requireWriterAdminIntent(engine, operation, params);
    if (params.shared_skills === true) {
      const { activateSharedSkillPersistence } = await import('./skill-activation.ts');
      return { ...await activateSharedSkillPersistence(engine, { confirmQuiesced: true, dryRun: params.dry_run === true, expectedState }),
        ...(params.dry_run ? { dry_run: true, action: operation } : {}) };
    }
    const { activatePersistence } = await import('./activation.ts');
    return { ...await activatePersistence(engine, { confirmQuiesced: true, dryRun: params.dry_run === true, expectedState, cleanupDeadLocalLocks: params.cleanup_dead_local_locks === true }),
      unsupported_maintenance: [...UNSUPPORTED_MANAGED_BULK_WRITERS],
      ...(params.dry_run ? { dry_run: true, action: operation } : {}) };
  }
  if (operation === 'writer_deactivate') {
    if (params.source_id !== undefined) throw invalid('Deactivate is brain-wide: it converts every source of this brain back to classic mode. Omit the <source> argument.',
      'Run gbrain sources writer deactivate with no source; --dry-run first lists every source it converts and each blocker.',
      readFix('Previews the brain-wide deactivation and its blockers; changes nothing.', { argv: ['gbrain', 'sources', 'writer', 'deactivate', '--dry-run', '--json'] }));
    keys(params, ['dry_run', 'admin_intent', 'expected_state', 'request_id']);
    const { deactivatePersistence } = await import('./deactivation.ts');
    if (params.dry_run === true) {
      // DX-O13: a clean preview prints the state-bound command that applies exactly what it reviewed, so the
      // state is read before the preview and the command is printed only when nothing moved while it ran.
      const state = await writerAdminState(engine);
      const report = await deactivatePersistence(engine, { dryRun: true });
      const unchanged = state === await writerAdminState(engine);
      return { ...report, action: operation, ...((report.mode === 'managed' || report.pre_activation_claims?.length) && report.blockers.length === 0 && unchanged
        ? { apply_command: `gbrain sources writer deactivate --admin-intent writer_deactivate --expected-state ${state}` } : {}) };
    }
    let expectedState: string | undefined;
    try { expectedState = await requireWriterAdminIntent(engine, operation, params); }
    catch (error) {
      if (!(error instanceof OperationError) || error.code !== 'writer_admin_state_changed') throw error;
      error.suggestion = `The current admin_state is ${await writerAdminState(engine)}. Review gbrain sources writer status --json, then rerun with --expected-state <that admin_state>.`;
      throw error;
    }
    return { ...await deactivatePersistence(engine, { expectedState, requestId: params.request_id === undefined ? undefined
      : uuid(params.request_id, 'A valid deactivation request UUID is required.', 'Pass --request-id as a UUID, or omit it and gbrain generates one.') }) };
  }
  if (operation === 'writer_transfer_prepare' || operation === 'writer_transfer_accept' || operation === 'writer_transfer_cancel') return (await import('./transfer-administration.ts')).runWriterTransferAdministration(engine, operation, params);
  if (operation === 'local_writer_list') {
    keys(params, ['limit', 'before']);
    const limit = params.limit ?? 100;
    if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > 1000) throw invalid('limit must be an integer from 1 to 1000.',
      'Pass --limit as an integer from 1 to 1000, e.g. gbrain auth local-writer list --limit 100.');
    const before = params.before === undefined ? null : uuid(params.before, 'A valid local writer UUID is required.',
      'Pass --before with the next value the previous gbrain auth local-writer list page printed (a writer UUID).', writerListFix);
    const rows = await engine.executeRaw<{ id: string }>(`SELECT id,lane,grant_ceiling,revoked_at,created_at FROM persistence_local_writers
      WHERE ($1::uuid IS NULL OR id<$1::uuid) ORDER BY id DESC LIMIT $2`, [before, limit + 1]);
    return { writers: rows.slice(0, limit), next: rows.length > limit ? rows[limit - 1].id : null };
  }
  if (operation === 'local_writer_register') {
    keys(params, ['lane', 'source_ids', 'scopes', 'allowed_operations', 'slug_prefixes', 'replace', 'dry_run']);
    if (params.lane !== 'cli' && params.lane !== 'stdio') throw invalid('lane must be cli or stdio.',
      'Name the lane right after register: gbrain auth local-writer register cli (trusted administration) or gbrain auth local-writer register stdio (MCP over stdio).');
    bool(params, 'replace');
    const grant = await registrationGrant(engine, params);
    // Register is idempotent. Changing an existing ceiling is an explicit replacement.
    if (!params.replace) {
      let existing;
      try { existing = await readLocalWriter(engine, params.lane); }
      catch (error) { if (!(error instanceof OperationError && error.code === 'writer_registration_required')) throw error; }
      if (existing) {
        const [row] = await engine.executeRaw<{ grant_ceiling: LocalGrant }>('SELECT grant_ceiling FROM persistence_local_writers WHERE id=$1::uuid', [existing.id]);
        const sameSet = (a: string[] | null, b: string[] | null) => a === null || b === null ? a === b : JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
        if (!sameSet(row.grant_ceiling.sourceIds, grant.sourceIds) || !sameSet(row.grant_ceiling.scopes, grant.scopes)
          || !sameSet(row.grant_ceiling.operations, grant.operations) || !sameSet(row.grant_ceiling.slugPrefixes, grant.slugPrefixes)) {
          throw new OperationError('writer_regrant_required', 'This lane already has a different grant.', 'Use register --replace with the complete reviewed grant; the previous registration will be revoked.');
        }
      }
    }
    if (params.dry_run) return { dry_run: true, action: operation, lane: params.lane, grant, replace: params.replace === true };
    const local = await registerLocalWriter(engine, params.lane, grant, params.replace === true);
    // Credentials remain in the private local file, never in output or on the socket.
    return { registered: true, id: local.id, lane: local.lane, grant, replaced: params.replace === true };
  }
  if (operation !== 'local_writer_revoke') throw invalid('Unknown local administration operation.',
    `This brain host does not know ${operation}: upgrade the caller and the host to one release (gbrain --version on both).`);
  keys(params, ['id', 'dry_run']);
  const id = uuid(params.id, 'A valid local writer UUID is required.',
    'Pass the id of the writer to revoke exactly as gbrain auth local-writer list --json prints it (a UUID).', writerListFix);
  if (params.dry_run) return { dry_run: true, action: 'local_writer_revoke', id };
  return { id, revoked: await revokeLocalWriter(engine, id) };
}