Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/** 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) };
}