Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Serve-delegated sync — the CLI half (decision ladders + poll loop).
*
* On a PGLite brain a live `gbrain serve` holds the single-writer lock for
* its lifetime, so `gbrain sync` cannot open the brain (LiveServeLockError
* since #2348 — a live holder is never displaced). Instead of failing, the
* pre-connect hook in cli.ts calls maybeDelegateSyncToServe: when the holder
* is a live serve, the sync runs INSIDE the serve over the resolve-IPC socket
* (sync_start / sync_status / sync_abort; wire shapes in
* core/context/sync-ipc.ts, execution in core/serve-sync-runner.ts) and this
* module polls progress and prints the result.
*
* PGLite decision ladder (returns false = fall through to the normal connect path):
* 0. --no-delegate / GBRAIN_SYNC_NO_DELEGATE=1 → false (opt-out).
* 1. Non-host brain (mounts) → false — delegation targets the host data dir.
* 2. No live holder, or a live NON-serve holder → false (existing behavior:
* dead-PID reap / bounded wait in acquireLock).
* 3. Live serve + any argv token outside the explicit allowlist →
* DEFAULT-DENY refusal naming the flag (a silently-dropped --exclude
* would perform the WRONG sync; refusing is the only safe default).
* 4. Live serve + socket answers → delegate: banner, 1s status polls,
* Ctrl-C → sync_abort (second Ctrl-C hard-exits), printSyncResult.
* 5. Live serve + no socket / stale serve / unauthorized → polite typed
* refusal with remediation, exit verdict 1 — never a raw stack.
*
* Every refusal names three ways out: drop the flag (when flag-caused), stop
* the serve, or --no-delegate.
*
* #6317 (D1 a′), Postgres managed brains: maybeDelegateManagedSyncToServe is
* the same family one rung later. Postgres has no lock to lose, so the CLI
* connects as usual and `runSingleSourceSync` asks this ladder right before
* `performSync`: when a live full `serve` consumer owns this host (the B3
* heartbeat row in `persistence_consumers`, read through the database, never
* a socket), the managed drain runs inside that serve as THIS CLI's verified
* `cli` writer (the registration rides in sync_start) and the CLI prints the
* drain's own lines from sync_status. The result comes back as a SyncResult,
* so the caller's printing, JSON envelope and exit verdict are the in-process
* ones. Every rung that cannot delegate falls back to today's own consumer
* with ONE actionable line, never a refusal: an unsupported flag, a missing
* socket, GBRAIN_SERVE_SYNC_IPC=0, an older serve (`unknown_kind` /
* `stale_serve` / `unsupported_kind`), a serve bound to another source, or a
* serve that dies mid-drain (the durable cursor resumes in-process). Only an
* authorization refusal of the hand-off is terminal, thrown as the same
* OperationError the in-process path would raise.
*/
import { randomUUID } from 'node:crypto';
import { existsSync } from 'node:fs';
import { serr } from '../core/console-prefix.ts';
import { probeLivePgliteHolder } from '../core/bootstrap/uninstall.ts';
import {
IPC_UNAVAILABLE,
hookResolveSocketForConfig,
readIpcSecret,
readIpcSecretForConfig,
requestSyncAbort,
requestSyncNudge,
requestSyncStart,
requestSyncStatus,
resolveSocketPath,
type IpcPathConfig,
type SyncStartIpcResult,
} from '../core/context/resolve-ipc.ts';
import {
DELEGATED_SYNC_LANES_MAX,
SYNC_NUDGE_VERSION,
type DelegatedSyncOptions,
type SyncNudgeResponse,
type SyncStartRegistration,
type SyncStatusResponse,
type WireSyncResult,
} from '../core/context/sync-ipc.ts';
import { OperationError } from '../core/ops/contract.ts';
import { SYNC_FLAGS, syncFlagsRouted, type SyncFlagSpec } from '../core/sync-flags.ts';
import type { BrainEngine } from '../core/engine.ts';
import type { ConsumerRow } from '../core/persistence/consumer-heartbeat.ts';
import type { SyncOpts, SyncResult } from './sync.ts';
import { VERSION } from '../version.ts';
/** Poll cadence for sync_status while a delegated job runs. */
const POLL_MS = 1000;
/**
* Consecutive failed polls tolerated before declaring the socket dead. A
* delegated import can block the serve's event loop for stretches (long
* synchronous WASM statements), so transient timeouts are EXPECTED; the PID
* probe below distinguishes "busy" from "gone" every PID_PROBE_EVERY misses.
*/
const MAX_POLL_FAILURES = 60;
const PID_PROBE_EVERY = 5;
/**
* The serve hand-off's view of the one sync flag table (`src/core/sync-flags.ts`). Everything the table does not
* route through the serve refuses: default-deny is what keeps a future flag from being silently dropped.
*/
const SERVE_FLAGS = SYNC_FLAGS as Record<string, SyncFlagSpec>;
/** Boolean flags forwarded over the wire (flag → DelegatedSyncOptions field). */
export const WIRE_BOOL_FLAGS: Record<string, keyof DelegatedSyncOptions> = Object.fromEntries(syncFlagsRouted('serve', 'forward')
.filter(flag => SERVE_FLAGS[flag].arity === 'boolean' && SERVE_FLAGS[flag].sets === undefined).map(flag => [flag, SERVE_FLAGS[flag].field as keyof DelegatedSyncOptions]));
/** Value-taking flags the ladder consumes itself (`--lanes` is validated and forwarded; the deadlines are derived). */
export const VALUE_FLAGS = new Set<string>([...syncFlagsRouted('serve', 'client'), ...syncFlagsRouted('serve', 'forward')].filter(flag => SERVE_FLAGS[flag].arity === 'value'));
/** Flags that are meaningful only outside delegation, handled pre-ladder, or rendered by this client (`--json`). */
export const IGNORED_FLAGS = new Set<string>(syncFlagsRouted('serve', 'client').filter(flag => SERVE_FLAGS[flag].arity === 'boolean'));
export type ParsedDelegatedArgs =
| { ok: true; options: Omit<DelegatedSyncOptions, 'timeoutSeconds'>; explicitSource: string | null }
| { ok: false; refused: string };
/**
* Pure argv classifier (exported for the drift-pin test). timeoutSeconds is
* derived separately (resolveSyncHardDeadline needs env/TTY context).
*/
export function parseDelegatedSyncArgs(args: string[]): ParsedDelegatedArgs {
const options: Record<string, unknown> = {};
let explicitSource: string | null = null;
for (let i = 0; i < args.length; i++) {
const tok = args[i];
if (WIRE_BOOL_FLAGS[tok]) {
options[WIRE_BOOL_FLAGS[tok]] = true;
continue;
}
const fixed = SERVE_FLAGS[tok];
if (fixed?.serve === 'forward' && fixed.sets !== undefined && fixed.field) {
options[fixed.field] = fixed.sets;
continue;
}
if (IGNORED_FLAGS.has(tok)) continue;
if (VALUE_FLAGS.has(tok)) {
const v = args[i + 1];
if (v === undefined || v.startsWith('--')) return { ok: false, refused: `${tok} (missing value)` };
if (tok === '--source') explicitSource = v;
if (tok === '--lanes') {
const lanes = Number(v);
if (!Number.isInteger(lanes) || lanes < 1 || lanes > DELEGATED_SYNC_LANES_MAX) return { ok: false, refused: `${tok} (invalid value)` };
options.lanes = lanes;
}
i++; // --timeout / --hard-deadline are consumed by the deadline derivation
continue;
}
// Default-deny: subcommands (`trigger`), unsupported flags (--repo,
// --all, --watch, --exclude, --workers, …) and anything future.
return { ok: false, refused: tok };
}
return { ok: true, options: options as Omit<DelegatedSyncOptions, 'timeoutSeconds'>, explicitSource };
}
/**
* The client's hard deadline for the delegated job, in seconds. 0 = the user
* explicitly waived the bound (--no-hard-deadline) — the ONLY unbounded
* encoding; an interactive TTY default (null from resolveSyncHardDeadline)
* maps to the same 3600s the non-TTY default uses, so a job whose client
* dies is always bounded. A single-source --timeout bounds the job itself,
* not the watchdog's later backstop.
*/
export async function deriveDelegatedTimeoutSeconds(
args: string[],
opts: { isTty?: boolean; env?: Record<string, string | undefined> } = {},
): Promise<number> {
if (args.includes('--no-hard-deadline')) return 0;
const { resolveSyncHardDeadline, HARD_DEADLINE_GRACE_SEC } = await import('../core/sync-reconcile.ts');
const res = resolveSyncHardDeadline(args, {
isTty: opts.isTty ?? Boolean(process.stdout.isTTY),
env: opts.env ?? process.env,
});
if (!res) return 3600;
const hard = Math.max(1, Math.round(res.deadlineMs / 1000));
return res.reason === 'flag:--timeout' ? hard - HARD_DEADLINE_GRACE_SEC : hard;
}
async function setVerdict(code: number): Promise<void> {
const { setCliExitVerdict } = await import('../core/cli-force-exit.ts');
setCliExitVerdict(code);
}
function remediation(pid: number, extra?: string): string {
return (
(extra ? `${extra} ` : '') +
`Ways out: ${extra ? '' : 'drop the unsupported flag, '}stop the serve (PID ${pid}) and re-run, ` +
`or pass --no-delegate to skip delegation.`
);
}
/**
* Pre-connect delegation ladder. Returns true when the sync was HANDLED here
* (delegated to a live serve, or politely refused with the exit verdict set);
* false falls through to the normal connectEngine path unchanged.
*/
export async function maybeDelegateSyncToServe(dataDir: string, args: string[]): Promise<boolean> {
// 0. Explicit opt-outs.
if (args.includes('--no-delegate') || process.env.GBRAIN_SYNC_NO_DELEGATE === '1') return false;
// 1. Mounts never delegate — the socket/secret/lock all belong to the HOST
// brain's data dir; a mounted brain's sync must take the normal path.
try {
const { resolveBrainId } = await import('../core/brain-resolver.ts');
const { getCliOptions } = await import('../core/cli-options.ts');
if (resolveBrainId(getCliOptions().brain) !== 'host') return false;
} catch { /* resolver trouble → normal path (fail open to old behavior) */ }
// 2. Holder probe (read-only; never reaps).
const holder = probeLivePgliteHolder(dataDir);
if (!holder || !holder.serve) return false;
// 3. Argv gate (default-deny).
const parsed = parseDelegatedSyncArgs(args);
if (!parsed.ok) {
serr(
`[sync] a live \`gbrain serve\` (PID ${holder.pid}) holds this PGLite brain, and ` +
`\`${parsed.refused}\` isn't supported through serve-delegated sync. ` +
remediation(holder.pid),
);
await setVerdict(1);
return true;
}
// Engine-free source tiers (env var, .gbrain-source dotfile) — the client
// has no engine to run the DB tiers; absent → the serve's bound/default.
let sourceId: string | undefined;
try {
const { resolveSourceIdEngineFree } = await import('../core/source-resolver.ts');
const resolved = resolveSourceIdEngineFree(parsed.explicitSource);
if (resolved === '__all__') {
serr(
`[sync] --source __all__ isn't supported through serve-delegated sync (the client has ` +
`no engine to enumerate sources). ${remediation(holder.pid, 'Sync one source at a time (--source <id>).')}`,
);
await setVerdict(1);
return true;
}
sourceId = resolved ?? undefined;
} catch (e) {
serr(`[sync] ${e instanceof Error ? e.message : String(e)}`);
await setVerdict(1);
return true;
}
// 4. Socket + secret.
const sock = resolveSocketPath(dataDir);
const secret = readIpcSecret(dataDir);
if (!existsSync(sock) || !secret) {
serr(
`[sync] a live \`gbrain serve\` (PID ${holder.pid}) holds this PGLite brain's ` +
`single-writer lock but exposes no sync IPC (older gbrain, \`serve --http\`, or ` +
`GBRAIN_SERVE_SYNC_IPC=0). ` + remediation(holder.pid, 'If that serve runs an older gbrain, restart it on this version.'),
);
await setVerdict(1);
return true;
}
const options: DelegatedSyncOptions = {
...parsed.options,
...(sourceId ? { sourceId } : {}),
timeoutSeconds: await deriveDelegatedTimeoutSeconds(args),
};
const clientToken = randomUUID();
let start = await requestSyncStart(sock, { secret, clientToken, options });
if (start === IPC_UNAVAILABLE) {
// Race: the serve may have died between probe and connect — or it started
// the job and the ack was lost. Re-probe; alive → ONE retry with the SAME
// token (busy/attach semantics make it safe), dead → normal path.
const still = probeLivePgliteHolder(dataDir);
if (!still || !still.serve) return false;
start = await requestSyncStart(sock, { secret, clientToken, options });
if (start === IPC_UNAVAILABLE) {
serr(
`[sync] the live \`gbrain serve\` (PID ${holder.pid}) is not answering its IPC socket. ` +
remediation(holder.pid, 'It may be wedged.'),
);
await setVerdict(1);
return true;
}
}
if ('degraded' in (start as object)) {
serr(
`[sync] the running \`gbrain serve\` (PID ${holder.pid}) predates serve-delegated sync. ` +
remediation(holder.pid, 'Restart it on this gbrain version.'),
);
await setVerdict(1);
return true;
}
const startResp = start as Exclude<SyncStartIpcResult, typeof IPC_UNAVAILABLE | { degraded: string }>;
// GBRA-133 PR 2a: a serve already syncing records this request as a wanted marker (never for --dry-run, which stays
// read-only); its notifier runs it once the running sync ends, so the request is not dropped.
if (!startResp.ok && startResp.error === 'busy' && !options.dryRun) {
const nudged = await requestSyncNudge(sock, { secret, version: SYNC_NUDGE_VERSION, sourceId: sourceId ?? 'default', requestedBy: 'delegated_sync',
...(options.full ? { intent: 'full' as const } : options.noPull ? { intent: 'freshness' as const } : {}) });
const ack = nudged === IPC_UNAVAILABLE || 'degraded' in (nudged as object) ? null : nudged as SyncNudgeResponse;
if (ack?.ok && ack.marker) {
const m = ack.marker;
serr(`[sync] the serve (PID ${holder.pid}) is already syncing (job ${startResp.jobId ?? '?'}); recorded this request as wanted (${m.intent}`
+ `${m.wanted_head ? ` ${m.wanted_head.slice(0, 8)}` : ''}, generation ${m.generation}); ${ack.notifier ? 'its notifier runs it when that sync ends' : 'the next resident with a notifier runs it'}.`);
if (args.includes('--json')) await (await import('../core/cli-force-exit.ts')).writeStdoutFinal(JSON.stringify({ action: 'nudged', source_id: m.source_id, intent: m.intent, wanted_head: m.wanted_head, marker_generation: m.generation, running_job_id: startResp.jobId ?? null }) + '\n');
await setVerdict(0);
return true;
}
}
if (!startResp.ok) {
serr(`[sync] ${startRefusalText(startResp)} ${remediation(holder.pid, '')}`);
await setVerdict(1);
return true;
}
const jobId = startResp.jobId!;
if (startResp.completed) {
serr(`[sync] attached to an already-completed delegated sync (job ${jobId}).`);
} else {
serr(
`[sync] live \`gbrain serve\` (PID ${holder.pid}) holds the PGLite lock — delegating ` +
`the sync through it (job ${jobId}; Ctrl-C aborts, progress is checkpointed).`,
);
}
const polled = await pollDelegatedJob({
sock, secret, jobId, pid: holder.pid,
alive: () => { const still = probeLivePgliteHolder(dataDir); return !!still && still.serve; },
});
if (polled.kind === 'lost') { await setVerdict(1); return true; }
if (polled.kind === 'failed') {
if (polled.error instanceof OperationError) {
const { reportPersistenceCliError } = await import('./persistence-delegate.ts');
if (await reportPersistenceCliError(polled.error, args.includes('--json'))) return true;
}
serr(`[sync] delegated sync failed inside the serve: ${polled.error.message}`);
await setVerdict(1);
return true;
}
await printDelegatedResult(polled.result, options, { args, sourceId: polled.status.sourceId ?? sourceId ?? 'default', json: args.includes('--json') });
return true;
}
function startRefusalText(resp: { error?: string; jobId?: string }): string {
const messages: Record<string, string> = {
busy: `another delegated sync (job ${resp.jobId ?? '?'}) is already running inside the serve — wait for it to finish and re-run.`,
unauthorized: `the serve rejected the IPC secret — restart the serve (it re-provisions \`.gbrain-ipc-secret\`) and re-run.`,
shutting_down: `the serve is shutting down — re-run in a moment (or after it exits, sync runs directly).`,
source_mismatch: `the serve is bound to a different source than this sync targets — run \`gbrain sync --source <the serve's source>\`, or stop the serve to sync this source directly.`,
unsupported_kind: `the serve has sync delegation disabled (GBRAIN_SERVE_SYNC_IPC=0 or a startup failure).`,
};
return messages[resp.error ?? ''] ?? `the serve refused the delegated sync (${resp.error}).`;
}
/** The serve's `refusal` / `jobErrorEnvelope` (an OperationError.toJSON()) back into the error the in-process path throws. */
export function operationErrorFromEnvelope(envelope: Record<string, unknown>): OperationError {
const code = typeof envelope.error === 'string' ? envelope.error : typeof envelope.code === 'string' ? envelope.code : 'unavailable';
const error = new OperationError(code as OperationError['code'], typeof envelope.message === 'string' ? envelope.message : 'The serve refused the delegated sync.',
typeof envelope.suggestion === 'string' ? envelope.suggestion : undefined, typeof envelope.docs === 'string' ? envelope.docs : undefined);
if (typeof envelope.code === 'string' && envelope.code !== code) error.canonical = envelope.code as OperationError['canonical'];
if (typeof envelope.detail === 'string') error.detail = envelope.detail;
if (typeof envelope.reason === 'string') error.reason = envelope.reason;
if (typeof envelope.why === 'string') error.why = envelope.why;
if (envelope.fix && typeof envelope.fix === 'object') error.fix = envelope.fix as OperationError['fix'];
if (envelope.contract_version === 1) error.contractVersion = 1;
return error;
}
type PolledJob =
| { kind: 'done'; result: WireSyncResult; status: SyncStatusResponse }
| { kind: 'failed'; error: Error }
/** The serve died, restarted or stopped answering; the failure was printed. */
| { kind: 'lost' };
/**
* Shared poll loop. Prints the job's human lines (a managed drain's own
* progress, stall and lanes lines) or, for a legacy job, phase changes and
* banked counts. `signal` (the caller's deadline or interrupt) and Ctrl-C both
* send sync_abort once and keep polling until the serve settles the typed
* partial; a second Ctrl-C exits without waiting. `alive` tells a busy serve
* (transient poll timeouts) from a dead one.
*/
async function pollDelegatedJob(ctx: {
sock: string;
secret: string;
jobId: string;
pid: number;
alive: () => boolean | Promise<boolean>;
signal?: AbortSignal;
}): Promise<PolledJob> {
const { sock, secret, jobId, pid } = ctx;
let failures = 0;
let lastPhase: string | undefined;
let lastBanked: number | undefined;
let afterLine = 0;
let abortRequested = false;
const abort = (why: string): void => {
if (abortRequested) return;
abortRequested = true;
serr(`[sync] ${why} — aborting the delegated sync (progress is checkpointed; re-run to resume).`);
void requestSyncAbort(sock, { secret, jobId });
};
const onSigint = () => {
if (abortRequested) process.exit(130);
abort('Ctrl-C');
serr('[sync] Ctrl-C again to exit without waiting.');
process.once('SIGINT', onSigint);
};
process.once('SIGINT', onSigint);
const onAbort = () => abort('deadline reached');
ctx.signal?.addEventListener('abort', onAbort, { once: true });
const crashHint = () =>
serr(
`[sync] progress is checkpointed — re-run \`gbrain sync\` to resume. Note: the dead ` +
`serve's sync lock row may take up to 60s to become reclaimable; if the re-run reports ` +
`a dead-PID lock, \`gbrain sync --break-lock\` clears it.`,
);
try {
for (;;) {
await new Promise((r) => setTimeout(r, POLL_MS));
const s = await requestSyncStatus(sock, { secret, jobId, afterLine });
if (s === IPC_UNAVAILABLE || 'degraded' in (s as object)) {
failures++;
if (failures % PID_PROBE_EVERY === 0 && !(await ctx.alive())) {
serr(`[sync] the serve (PID ${pid}) died mid-sync.`);
crashHint();
return { kind: 'lost' };
}
if (failures >= MAX_POLL_FAILURES) {
serr(`[sync] the serve (PID ${pid}) stopped answering its IPC socket mid-sync.`);
crashHint();
return { kind: 'lost' };
}
continue;
}
failures = 0;
const status = s as SyncStatusResponse;
if (!status.ok) {
if (status.error === 'unknown_job') {
serr(`[sync] the serve restarted mid-sync (job ${jobId} is gone).`);
crashHint();
return { kind: 'lost' };
}
return { kind: 'failed', error: new Error(`delegated sync failed: ${status.error}`) };
}
if (status.managed) {
for (const line of status.lines ?? []) {
process.stderr.write(line.text + '\n');
afterLine = Math.max(afterLine, line.seq);
}
} else {
if (status.phase && status.phase !== lastPhase) {
lastPhase = status.phase;
serr(`[sync] serve: ${status.phase}`);
}
if (status.bankedFiles !== undefined && status.bankedFiles !== lastBanked) {
lastBanked = status.bankedFiles;
serr(`[sync] serve: banked ${status.bankedFiles} file(s)`);
}
}
if (status.state === 'error') {
return { kind: 'failed', error: status.jobErrorEnvelope ? operationErrorFromEnvelope(status.jobErrorEnvelope) : new Error(status.jobError ?? 'unknown error') };
}
if (status.state === 'done' && status.result) return { kind: 'done', result: status.result, status };
// running / aborting → keep polling.
}
} finally {
process.off('SIGINT', onSigint);
ctx.signal?.removeEventListener('abort', onAbort);
}
}
/** The wire result as the SyncResult the in-process printers take (the page list is capped on the wire). */
export function syncResultFromWire(wire: WireSyncResult): { result: SyncResult; pagesAffectedTotal: number } {
const { pagesAffectedTotal, ...rest } = wire;
return { result: { ...rest, pagesAffected: wire.pagesAffected }, pagesAffectedTotal };
}
async function printDelegatedResult(wire: WireSyncResult, options: DelegatedSyncOptions, ctx: { args: string[]; sourceId: string; json: boolean }): Promise<void> {
const { printSyncResult } = await import('./sync.ts');
const { result, pagesAffectedTotal } = syncResultFromWire(wire);
const human = ctx.json ? process.stderr : process.stdout;
printSyncResult(result, human);
if (pagesAffectedTotal > wire.pagesAffected.length) {
serr(`[sync] (+${pagesAffectedTotal - wire.pagesAffected.length} more pages affected — list truncated for the IPC wire)`);
}
if (!options.dryRun && !options.noEmbed && result.added + result.modified > 0) {
serr('[sync] embeds deferred — the serve drains them in background sweeps (its environment/keys apply).');
}
const { drainJsonFields, formatDrainSummary, syncOutcome } = await import('../core/persistence/sync-drain.ts');
const { syncResumeCommand } = await import('../core/sync-reconcile.ts');
const { getCliOptions } = await import('../core/cli-options.ts');
const resume = syncResumeCommand(ctx.args.filter(a => a !== '--json'), getCliOptions().brain);
for (const line of formatDrainSummary(result, resume, ctx.sourceId)) human.write(line + '\n');
if (ctx.json) {
// The single-source envelope the in-process `--json` path emits (#4888: stdout carries that one document).
const { buildSingleSyncJsonEnvelope } = await import('../core/sync-embed-backfill.ts');
const { writeStdoutFinal } = await import('../core/cli-force-exit.ts');
await writeStdoutFinal(JSON.stringify({ ...buildSingleSyncJsonEnvelope(ctx.sourceId, result),
...(result.managedWrite ? { managed_write: result.managedWrite } : {}), ...drainJsonFields(result, resume, ctx.sourceId) }) + '\n');
}
// Mirror runSync's verdict rule (#3068): a pull_failed partial will not
// self-heal — exit non-zero so cron sees the wedge. #5984: a blocked drain too.
if ((result.status === 'partial' && result.reason === 'pull_failed') || syncOutcome(result) === 'blocked') {
await setVerdict(1);
}
}
// ── #6317: Postgres managed brains ─────────────────────────────────────────
/** Test seams for the Postgres ladder: the brain config, the heartbeat probe and the socket/secret discovery. */
export interface ManagedDelegationDeps {
config?: IpcPathConfig | null;
probe?: (engine: BrainEngine) => Promise<ConsumerRow | null>;
socket?: (sourceId: string) => Promise<{ sock: string | null; secret: string | null }>;
env?: Record<string, string | undefined>;
}
export type ManagedDelegationOutcome =
| { kind: 'delegated'; result: SyncResult; pid: number }
/** Not delegated; `reason` names the rung, `line` is the one line printed (null when nothing was printed). */
| { kind: 'own_consumer'; reason: 'opted_out' | 'not_host' | 'not_postgres' | 'not_managed' | 'no_owner' | 'owner_not_serve' | 'probe_failed'
| 'kill_switch' | 'unsupported_flag' | 'no_socket' | 'older_serve' | 'serve_refused' | 'serve_lost'; line: string | null };
/**
* #6543: only a forced rung (the serve cannot take the run) really runs a consumer beside the serve; on the others this
* process admits its writes and, with persistence.single_consumer on, the serve's consumer publishes them.
*/
const ownConsumerLine = (pid: number, cause: string, forced: boolean, fix = 'Restart that serve on this gbrain version to run the catch-up inside it.'): string => forced
? `[sync] ${cause}; this run uses its own consumer beside the serve (PID ${pid}). ${fix}`
: `[sync] ${cause}; this run does not delegate to the serve (PID ${pid}): it admits its own writes, and with persistence.single_consumer on the serve's consumer publishes them. ${fix}`;
/**
* The Postgres rung of the delegation ladder (#6317). Called with the connected
* engine and the sync's resolved options right before `performSync`; returns
* the drain's SyncResult when the resident serve ran it, else the rung that
* kept today's own consumer. Throws the hand-off's authorization refusal
* (denied, revoked or stdio registration) as the OperationError the in-process
* `managedSyncAuthority` would have thrown.
*/
export async function maybeDelegateManagedSyncToServe(engine: BrainEngine, args: string[], opts: SyncOpts, deps: ManagedDelegationDeps = {}): Promise<ManagedDelegationOutcome> {
const env = deps.env ?? process.env;
// #6543: `force` makes "this run uses its own consumer" true where the serve cannot take the run (the opt-out, a serve
// not answering its socket, an older serve): with persistence.single_consumer on, this process would otherwise run
// waiter-only behind the serve it bypassed. A healthy serve beside a kill switch or an unsupported flag keeps consuming.
const own = async (reason: Extract<ManagedDelegationOutcome, { kind: 'own_consumer' }>['reason'], line: string | null = null, force = false): Promise<ManagedDelegationOutcome> => {
if (line) serr(line);
// #7167: a dry run writes nothing, so it starts no consumer of its own.
if (force && !opts.dryRun) (await import('../core/persistence/consumer-election.ts')).forceOwnConsumer(reason);
return { kind: 'own_consumer', reason, line };
};
// #7167: a dry run that is not delegated previews in this process and writes nothing; it neither admits writes nor runs a consumer.
const fallbackLine = (pid: number, cause: string, forced: boolean, fix?: string): string => opts.dryRun
? `[sync] ${cause}; this dry run previews in this process instead of the serve (PID ${pid}) and writes nothing.` : ownConsumerLine(pid, cause, forced, fix);
// 0. Opt-outs bypass the ladder before anything is probed or classified.
if (args.includes('--no-delegate') || env.GBRAIN_SYNC_NO_DELEGATE === '1') return own('opted_out', null, true);
const { resolveBrainId } = await import('../core/brain-resolver.ts');
const { getCliOptions } = await import('../core/cli-options.ts');
if (resolveBrainId(getCliOptions().brain) !== 'host') return own('not_host');
// The host brain's config decides the engine (the PGLite ladder ran pre-connect; a PGLite mount never reaches here).
const cfg = deps.config !== undefined ? deps.config : (await import('../core/config.ts')).loadConfig();
if (cfg?.engine !== 'postgres' || !cfg.database_url) return own('not_postgres');
const sourceId = opts.sourceId ?? 'default';
// 1. Only a managed source has the two-consumer problem; classic sync keeps its own path.
const { readManagedMode } = await import('../core/persistence/managed-mode.ts');
const dispatch = await import('../core/sync-dispatch-read.ts');
const routing = await dispatch.syncDispatchRow(engine, sourceId);
if (!(routing ? dispatch.dispatchManagedMode(routing) : await readManagedMode(engine))) return own('not_managed');
// #6696 C2: a flag the managed source refuses never reaches the serve; the refusal names it before any probe or socket call.
const { managedForbiddenFlag, managedSyncFlagRefusal } = await import('../core/persistence/managed-sync-flags.ts');
const forbidden = managedForbiddenFlag(opts);
if (forbidden) throw managedSyncFlagRefusal(forbidden, sourceId, args);
// 2. The owner probe: the B3 heartbeat row, through the database (the persistence socket does not exist on Postgres).
let owner: ConsumerRow | null;
try {
owner = deps.probe ? await deps.probe(engine) : await (async () => {
const { probeLiveFullConsumer, consumerIdentity } = await import('../core/persistence/consumer-heartbeat.ts');
const { localHostId } = await import('../core/persistence/identity.ts');
return probeLiveFullConsumer(engine, localHostId(), consumerIdentity());
})();
} catch (e) {
return own('probe_failed', `[sync] could not read this host's consumer heartbeat (${e instanceof Error ? e.message : String(e)}); this run uses its own consumer.`);
}
if (!owner) return own('no_owner');
const pid = owner.pid;
const sameBuild = owner.version === VERSION;
if (owner.kind !== 'serve') {
return own('owner_not_serve', `[sync] the live write owner on this host is a ${owner.kind} process (PID ${pid}), which cannot host a delegated sync; this run uses its own consumer beside it.`);
}
if (env.GBRAIN_SERVE_SYNC_IPC === '0') {
return own('kill_switch', fallbackLine(pid, 'GBRAIN_SERVE_SYNC_IPC=0 turns serve-delegated sync off', false, 'Unset it to run the catch-up inside the serve.'));
}
// 3. Argv gate (default-deny). On Postgres an unsupported flag keeps today's own consumer instead of refusing.
const parsed = parseDelegatedSyncArgs(args);
if (!parsed.ok) {
return own('unsupported_flag', fallbackLine(pid, `\`${parsed.refused}\` isn't supported through serve-delegated sync`, false, 'Drop the flag to run the catch-up inside the serve.'));
}
// 4. Socket + secret: the serve bound to this source, else the legacy URL-keyed socket.
const { sock, secret } = deps.socket ? await deps.socket(sourceId)
: { sock: await hookResolveSocketForConfig(cfg, sourceId, { delegation: true }), secret: readIpcSecretForConfig(cfg) };
if (!sock || !existsSync(sock) || !secret) {
return own('no_socket', fallbackLine(pid, 'the running gbrain serve exposes no sync IPC socket (older gbrain, or GBRAIN_SERVE_SYNC_IPC=0 on the serve)', false,
sameBuild ? `That serve already runs this gbrain version (v${VERSION}), so restarting it changes nothing here: unset GBRAIN_SERVE_SYNC_IPC=0 on the serve, or read its log for why its sync IPC did not start.` : undefined));
}
// 5. The hand-off: this CLI's durable writer registration (the one its own consumer would run under).
dispatch.endSyncDispatchRead();
const { registerLocalWriter } = await import('../core/persistence/identity.ts');
const local = await registerLocalWriter(engine, 'cli');
const registration: SyncStartRegistration = { id: local.id, credential: local.credential, lane: 'cli' };
const { parseDurationSeconds } = await import('../core/sync-concurrency.ts');
const soft = parseDurationSeconds(args.find((_, i) => args[i - 1] === '--timeout'), '--timeout');
const hard = await deriveDelegatedTimeoutSeconds(args, { env });
const timeoutSeconds = soft && soft > 0 ? (hard > 0 ? Math.min(soft, hard) : soft) : hard;
const options: DelegatedSyncOptions = {
// #6696 (A5): an operator's sync keeps the capacity background producers leave free.
sourceId, timeoutSeconds, origin: 'interactive',
// The table's forwarded booleans only: a field a newer gbrain retired (src/core/wire-skew.ts) is never in it, so it is never sent.
...pick(opts as unknown as Record<string, boolean | undefined>, Object.values(WIRE_BOOL_FLAGS)) as Partial<DelegatedSyncOptions>,
...(opts.lanes !== undefined ? { lanes: opts.lanes } : {}),
// Sent only when set, so a serve that predates the field keeps accepting every run without a deferral.
...(opts.embedDeferred ? { embedDeferred: true } : {}),
};
const clientToken = randomUUID();
const { probeLiveFullConsumer, consumerIdentity } = await import('../core/persistence/consumer-heartbeat.ts');
const { localHostId } = await import('../core/persistence/identity.ts');
const ownerAlive = async (): Promise<boolean> => {
try {
const row = deps.probe ? await deps.probe(engine) : await probeLiveFullConsumer(engine, localHostId(), consumerIdentity());
return !!row && row.pid === pid && row.nonce === owner!.nonce;
} catch { return true; }
};
let start = await requestSyncStart(sock, { secret, clientToken, options, registration });
if (start === IPC_UNAVAILABLE && await ownerAlive()) start = await requestSyncStart(sock, { secret, clientToken, options, registration });
if (start === IPC_UNAVAILABLE) {
return own('no_socket', fallbackLine(pid, 'the running gbrain serve is not answering its IPC socket', true,
sameBuild ? `That serve already runs this gbrain version (v${VERSION}); it may be wedged.` : undefined), true);
}
if ('degraded' in (start as object)) {
return own('older_serve', fallbackLine(pid, 'the running gbrain serve predates serve-delegated managed sync', true), true);
}
const startResp = start as Exclude<SyncStartIpcResult, typeof IPC_UNAVAILABLE | { degraded: string }>;
if (!startResp.ok) {
if (startResp.refusal) throw operationErrorFromEnvelope(startResp.refusal);
if (startResp.error === 'unsupported_kind') {
// #6543: a current serve that echoes the protocol with unsupported_kind is healthy with delegation off on its side: it keeps consuming.
return own('older_serve', fallbackLine(pid, 'the running gbrain serve runs with serve-delegated managed sync off (GBRAIN_SERVE_SYNC_IPC=0 on the serve)', false, 'Unset it on the serve to run the catch-up inside it.'));
}
if (startResp.error === 'permission_denied') throw operationErrorFromEnvelope({ error: 'permission_denied', message: 'The serve refused this CLI\'s writer registration.' });
return own('serve_refused', fallbackLine(pid, startRefusalText(startResp).replace(/\.$/, ''), false, 'Fix that, or let this run finish without the serve.'));
}
const jobId = startResp.jobId!;
serr(startResp.completed
? `[sync] attached to an already-completed delegated sync inside the serve (job ${jobId}).`
: `[sync] a live gbrain serve (PID ${pid}) owns this host's writes — running the managed catch-up inside it as this CLI's writer (job ${jobId}; Ctrl-C aborts, the cursor is durable).`);
const polled = await pollDelegatedJob({ sock, secret, jobId, pid, alive: ownerAlive, signal: opts.signal });
if (polled.kind === 'lost') return own('serve_lost', '[sync] continuing the catch-up with this process\'s own consumer; the durable cursor resumes where the serve left it.');
if (polled.kind === 'failed') throw polled.error;
const { result, pagesAffectedTotal } = syncResultFromWire(polled.result);
if (pagesAffectedTotal > polled.result.pagesAffected.length) {
serr(`[sync] (+${pagesAffectedTotal - polled.result.pagesAffected.length} more pages affected — list truncated for the IPC wire)`);
}
return { kind: 'delegated', result, pid };
}
function pick<T extends object, K extends keyof T>(source: T, keys: readonly K[]): Partial<Pick<T, K>> {
const out: Partial<Pick<T, K>> = {};
for (const key of keys) if (source[key] !== undefined) out[key] = source[key];
return out;
}
/**
* GBRA-133 PR 2a: `gbrain sync trigger` while a live serve holds the PGLite brain. The request is recorded as a wanted
* marker through the serve (sync_nudge, acknowledged) and its notifier starts the sync: action nudged, exit 0. A serve
* running without a notifier (GBRAIN_NOTIFIER=0) records it too; the outcome then carries resident: null and the
* no_resident notice with the fix. Returns false off PGLite or when no serve holds the brain (the engine path records
* the marker and queues the job).
* The owner-delegated sync paths in cli/main.ts skip `sync trigger`, which they would refuse as an unknown sync option.
*/
export async function maybeTriggerThroughServe(config: { engine?: string; database_path?: string; database_url?: string } | null, args: string[]): Promise<boolean> {
if (config?.engine !== 'pglite' || !config.database_path || config.database_url || args.includes('--help') || args.includes('-h')) return false;
const dataDir = config.database_path;
const sourceId = args.find((a, i) => args[i - 1] === '--source');
if (!sourceId) return false;
const holder = probeLivePgliteHolder(dataDir);
if (!holder || !holder.serve) return false;
const json = args.includes('--json');
const sock = resolveSocketPath(dataDir);
const secret = readIpcSecret(dataDir);
const refuse = async (why: string) => { serr(`[sync trigger] a live gbrain serve (PID ${holder.pid}) holds this PGLite brain and ${why} ` + remediation(holder.pid, '')); await setVerdict(1); return true; };
if (!existsSync(sock) || !secret) return refuse('exposes no sync IPC (older gbrain, serve --http, or GBRAIN_SERVE_SYNC_IPC=0).');
const r = await requestSyncNudge(sock, { secret, version: SYNC_NUDGE_VERSION, sourceId, requestedBy: 'sync_trigger' });
if (r === IPC_UNAVAILABLE) return refuse('is not answering its IPC socket.');
if ('degraded' in (r as object)) return refuse('predates sync_nudge; restart it on this gbrain version.');
const resp = r as SyncNudgeResponse;
if (!resp.ok || !resp.marker) {
if (resp.error === 'unknown_source') { serr(`Source "${sourceId}" not found. List with: gbrain sources list`); await setVerdict(1); return true; }
return refuse(`refused the request (${resp.error ?? 'unknown error'}).`);
}
const { printTriggerOutcome } = await import('./sync/trigger.ts');
const m = resp.marker;
printTriggerOutcome({ action: 'nudged', source_id: m.source_id, intent: m.intent, wanted_head: m.wanted_head, marker_generation: m.generation,
resident: resp.notifier ? { kind: resp.resident ?? 'serve', pid: holder.pid } : null }, json);
await setVerdict(0);
return true;
}