Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #6340: `gbrain sync status` and `gbrain sync unblock`, the operator contract
* for a managed catch-up (core in `src/core/persistence/sync-status.ts`,
* decision table in `sync-fault-class.ts`, prose in
* `docs/guides/sync-unblock-runbook.md`). Both speak the agent operator
* protocol: `--json` prints one envelope with `next` rendered as a fix. Since
* #6377 `unblock --apply` also runs the content-repair lane on the holds it
* clears (`--no-llm`, `--no-repair`), and each repaired path prints its
* location-only receipt.
*/
import type { BrainEngine } from '../../core/engine.ts';
import { cliRenderContext, renderAction } from '../../core/agent-output.ts';
import { writeJsonDocument } from '../../core/cli-force-exit.ts';
import { opError } from '../../core/ops/contract.ts';
import { readSyncStatus, unblockSync, type SyncStatus, type SyncStatusHold } from '../../core/persistence/sync-status.ts';
import { pageSortedRows, topCounts } from '../../core/bounded-listing.ts';
import { nextListingCommand, parseListingFlags } from '../../core/bounded-listing-cli.ts';
import { HOLD_ATTEMPTS_NEEDS_HUMAN, HOLD_ESCALATE_MS } from '../../core/persistence/sync-fault-class.ts';
import { CONTENT_REPAIR_HOLD_KINDS } from '../../core/repair/content-lane.ts';
import { resolveSourceIdEngineFree } from '../../core/source-resolver.ts';
/** The hold codes the content-repair lane clears today, for the help text. */
const CONTENT_HOLD_CODES = Object.entries(CONTENT_REPAIR_HOLD_KINDS).filter(([, kind]) => kind).map(([code]) => code).join(', ');
/** #7243: how the text status names what superseded a last error. */
const SUPERSEDED_TEXT: Record<NonNullable<NonNullable<SyncStatus['last_error']>['superseded']>['by'] & string, string> = {
commit: 'the sync committed a page', admission: 'a later sync admitted a page', level_read: 'a later pass read the source', pin: 'a later pass started',
};
export function printSyncStatusHelp(): void {
console.log(`Usage: gbrain sync status --source <id> [--detail] [--json]
[--limit <n>] [--cursor <next_cursor>] [--all] [--hold-state <state>]
[--slug <slug>] [--code <code>]
Where a managed catch-up stands and what to do next, for an operator agent:
the newest sync pass (convergence: outcome, round, candidates, settled,
remaining, classes) or, for a company-brain source, the cursor (index/total,
pinned target, last advance), pages committed in the last 10 minutes, every
held file and the last recorded failure, each with
class page | connection | systemic
safe_actions retry | retry_when_clean | repair | reconcile | upgrade | none
needs_human whether a person has to decide or act (human_reason says why)
and one \`next\` action, plus the source's state (synced | resumable |
blocked) and its reason, the oldest unfinished request and any recovery
record (bounded probes that need no cursor; a probe that times out makes the
state resumable/status_unknown, never synced).
The terminal-failure summary, the checkpoint blocker list and the live cursor
list are heavy reads: a plain status skips them (the fields keep their types,
empty or unknown) and says so in terminal_failures_read, checkpoint_blockers_read
and cursors_read (status not_read, with the --detail command as fix); --detail
runs them. Never read a skipped field as "none".
The loop: run this every few minutes; when committed_last_10m is 0 and
needs_human is false, run \`gbrain sync unblock --source <id> --apply\`, then
the sync it prints; when needs_human is true, page a person with the slug it
names; when a *_read field is not_read and you need it, run its fix.
convergence.classes counts the newest round's paths by class, each with an
action (who finishes it):
none matched, adopt, kept, untracked, gone, deleted_same, legacy_same, db_ahead
owner sync finishes it: in_flight, import, reparse, delete, keep_db,
keep_db_pending, legacy_unverified, paused_keep_db
repair a person decides: held, drift, delete_drift, deleted_edited, dirty,
spelling, deletes_withheld
Committed mode reads a file's working-copy dirtiness only for candidates, so
dirty counts only paths sync would otherwise admit.
Every status names last_commit (the commit sync applied through) and live (the
process holding the drain lease, a serve pass included, with its heartbeat and
progress; null when nothing holds it).
Holds are bounded: holds_summary counts every hold by code, by state
(needs_human | actionable | held) and by fault_code (the failure a
page_write_failed hold recorded), then holds lists the first ${PLAIN_STATUS_HOLDS}
(needs_human first). With --detail the list pages (100 per page): holds_page
carries returned, limit, complete, next_cursor and next_command; --limit <n>
sets the page size, --cursor <next_cursor> prints the next page, --all prints
every hold, and --hold-state <state> lists only that state. --slug <slug>
lists the hold on one slug (or path) and --code <code> the holds with that
code or fault_code, so one hold is found without paging.
Decision table: docs/guides/sync-unblock-runbook.md
`);
}
export function printSyncUnblockHelp(): void {
console.log(`Usage: gbrain sync unblock --source <id> [--apply] [--no-llm] [--no-repair] [--json]
Performs the safe action for every held file of a managed source and refuses
the rest by name. Without --apply it previews. Idempotent; it writes only
hash-bound repairs (each with its receipt), never drops content and never
clears a hold except by repairing its file: refusing is the only way it
leaves a file out, and each refusal names the file, why, and its fix.
worktree_dirty re-screened when its working-tree bytes are committed
at HEAD now (still dirty: refused still_dirty)
preparation_stalled re-screened (the writer, not the file, stalled)
concurrent_write refused: a person reconciles the two versions
file_drift refused: a person picks the database or the file
(gbrain repair file-drift --prefer database|file)
${CONTENT_HOLD_CODES.padEnd(22)}repaired by the content-repair lane (gbrain repair content,
each file bound to the bytes its plan read, under the
fences.repair caps), then re-screened; per
path: repaired | held | needs_human | skipped with the reason,
the receipt and the next step. A hold whose stored state waits
on a person, the user's spend decision or the owner host is
listed, not retried.
other repair holds refused with the repair preview to run
${HOLD_ATTEMPTS_NEEDS_HUMAN} failed attempts refused once also held ${HOLD_ESCALATE_MS / 3_600_000} h: the page keeps moving; needs a
person (never a file still being edited, never an image)
--no-llm repairs keep to their free tiers (model-tier files stay held)
--no-repair refuse every repair-class hold instead (the pre-#6377 behaviour)
Then run the sync \`next\` names (the cursor's own options).
Runbook: docs/guides/sync-unblock-runbook.md
`);
}
/**
* #6803: the operator verb a `gbrain sync` argument vector asks for, shared by
* the CLI's pre-connect preflight (no watchdog, no owner delegation) and
* `runSyncInner`. `gbrain sync --status` is the status read, the same as
* `gbrain sync status` (it used to run a full sync, because nothing read the
* flag). `--preview` and `--check` are read by no sync path, so a sync that
* would silently run past them is refused.
*/
export function syncOperatorVerb(args: readonly string[]): 'status' | 'unblock' | null {
if (args[0] === 'status' || args[0] === 'unblock') return args[0];
if (args[0] === 'trigger') return null;
const unread = args.find(a => a === '--preview' || a === '--check' || a.startsWith('--preview=') || a.startsWith('--check='));
if (unread) {
const flag = unread.split('=')[0];
throw opError('invalid_params', `gbrain sync does not read ${flag}; it would have run a full sync.`,
'Preview a sync with --dry-run, or read where the source stands with gbrain sync status.',
{ fix: { argv: ['gbrain', 'sync', ...args.filter(a => a !== unread && a !== '--dry-run'), '--dry-run'], consent: [], actor: 'agent', requires_exclusive: false,
why: 'The same sync with --dry-run reports what it would import and writes nothing.' } });
}
return args.includes('--status') ? 'status' : null;
}
/** `runSyncInner`'s operator route: `sync --status` prints one hint, then runs exactly `sync status`. */
export async function runSyncOperator(engine: BrainEngine, verb: 'status' | 'unblock', args: string[]): Promise<void> {
if (args[0] === verb) return verb === 'status' ? runSyncStatus(engine, args.slice(1)) : runSyncUnblock(engine, args.slice(1));
process.stderr.write('[gbrain] sync --status is the status read, the same as gbrain sync status (it never syncs).\n');
return runSyncStatus(engine, args.filter(a => a !== '--status'));
}
function sourceOf(args: string[]): string {
const explicit = args.find((a, i) => args[i - 1] === '--source') ?? null;
const source = resolveSourceIdEngineFree(explicit, process.cwd());
if (!source || source === '__all__') throw opError('invalid_params', 'sync status and sync unblock need one source.', 'Name one source with --source; the fix lists the ids.',
{ fix: { argv: ['gbrain', 'sources', 'list', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Lists the source ids, read-only; then rerun with --source and one of them.' } });
return source;
}
/** #7243: the holds a plain status lists (the rest are counted in `holds_summary`; `--detail` pages through them). */
export const PLAIN_STATUS_HOLDS = 20;
const HOLD_STATES = ['needs_human', 'actionable', 'held'] as const;
type HoldState = typeof HOLD_STATES[number];
/** A hold's state: a person decides, `sync unblock` has a safe action for it, or it stays held (by design or until its file changes). */
const holdState = (hold: SyncStatusHold): HoldState => hold.needs_human ? 'needs_human' : hold.safe_actions[0] !== 'none' ? 'actionable' : 'held';
/**
* #7243: the holds of one status read as a bounded listing: counts by code and state over every hold, then one page,
* needs-human first (a plain status lists the first `PLAIN_STATUS_HOLDS`; `--detail`, `--limit`, `--cursor` and `--all` page).
* A first page that holds every hold keeps the earlier shape (`holds` only, beside the summary).
*/
function holdsListing(holds: readonly SyncStatusHold[], args: string[], sourceId: string) {
const { request, rest } = parseListingFlags(args, 'gbrain sync status');
const value = (flag: string, example: string) => {
const at = rest.indexOf(flag);
if (at < 0) return undefined;
const given = rest[at + 1];
if (given === undefined || given === '' || given.startsWith('--')) throw opError('invalid_params', `${flag} needs a value.`, `Example: gbrain sync status --source ${sourceId} ${flag} ${example} --json`);
return given;
};
const state = value('--hold-state', 'needs_human');
if (state !== undefined && !HOLD_STATES.includes(state as HoldState)) {
throw opError('invalid_params', `--hold-state must be one of ${HOLD_STATES.join(', ')} (got "${state}").`, `Example: gbrain sync status --source ${sourceId} --detail --hold-state needs_human --json`);
}
const slug = value('--slug', '<slug>');
const code = value('--code', 'page_write_failed');
const filter = { ...(slug ? { slug } : {}), ...(code ? { code } : {}) };
const listed = holds.filter(hold => (!state || holdState(hold) === state) && (!slug || hold.slug === slug || hold.path === slug)
&& (!code || hold.code === code || hold.fault_code === code));
const sized = args.some(a => a === '--all' || a === '--limit' || a.startsWith('--limit='));
const page = pageSortedRows(listed, hold => [String(HOLD_STATES.indexOf(holdState(hold))), hold.path],
args.includes('--detail') || sized ? request : { ...request, limit: PLAIN_STATUS_HOLDS }, `sync_status_holds:${sourceId}:${state ?? 'all'}:${JSON.stringify(filter)}`);
const faulted = holds.filter(hold => hold.fault_code);
const summary = { total: holds.length, by_code: topCounts(holds, hold => hold.code, 20), by_state: topCounts(holds, holdState, 20),
by_fault_code: topCounts(faulted, hold => hold.fault_code!, 20) };
const paging = page.complete && request.cursor === undefined ? null
: { returned: page.returned, limit: page.limit, complete: page.complete, next_cursor: page.next_cursor, next_command: nextListingCommand(['gbrain', 'sync', 'status', ...rest], page) };
return { summary, filter: Object.keys(filter).length ? filter : null, matched: listed.length, paging, rows: page.rows };
}
export async function runSyncStatus(engine: BrainEngine, args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) return printSyncStatusHelp();
const sourceId = sourceOf(args);
const status = await readSyncStatus(engine, sourceId, { detail: args.includes('--detail') });
const listing = holdsListing(status.holds, args, sourceId);
const ctx = cliRenderContext();
// #6696 (A4): the capacity picture rides every status read (unthrottled), from the 60 s snapshot.
// #6803 C4: one bounded wait per status read, shared with its notices; a slow snapshot reads unknown for this call only.
const { capacitySnapshotWithin, capacityNotices, CAPACITY_READ_WAIT_MS } = await import('../../core/persistence/capacity-snapshot.ts');
const { renderNotice } = await import('../../core/agent-output.ts');
const snapshot = await capacitySnapshotWithin(engine, Date.now() + CAPACITY_READ_WAIT_MS);
const notices = (await capacityNotices(engine, { throttle: false, snapshot })).map(notice => renderNotice(notice, ctx));
// #6858 ask 6: commit→searchable / commit→embedded latency over 24 h (null for a source with no managed binding).
const { readSyncFreshness, formatSyncFreshness } = await import('../../core/persistence/sync-freshness.ts');
const [freshness = null] = await readSyncFreshness(engine, { sourceIds: [sourceId] }).catch(() => []);
const { readNotifierBlock, formatNotifierBlock } = await import('../../core/notifier/status.ts');
const notifierBlock = await readNotifierBlock(engine, sourceId).catch(() => null);
const notifier = notifierBlock && { ...notifierBlock, fix: notifierBlock.fix ? renderAction(notifierBlock.fix, ctx) : null };
const read = (r: typeof status.cursors_read) => r.status === 'read' ? r : { ...r, fix: renderAction(r.fix, ctx) };
const { holds: _holds, ...shown } = status;
const rendered = { ...shown,
git_push_holds: status.git_push_holds.map(hold => ({ ...hold, fix: renderAction(hold.fix, ctx) })),
fence_holds: status.fence_holds.map(hold => ({ ...hold, fix: renderAction(hold.fix, ctx) })), next: status.next ? renderAction(status.next, ctx) : null,
checkpoint_blockers_read: read(status.checkpoint_blockers_read), cursors_read: read(status.cursors_read), terminal_failures_read: read(status.terminal_failures_read),
landing_read: read(status.landing_read), landing: status.landing?.status === 'ok' ? { ...status.landing, pages: status.landing.pages.map(page => ({ ...page, fix: page.fix ? renderAction(page.fix, ctx) : null })) } : status.landing,
capacity: { status: snapshot.status, pause_pct: snapshot.pause_pct, low: snapshot.low, paused: snapshot.paused }, freshness, notifier, ...(notices.length ? { notices } : {}),
// #7243: the holds come last, summary first, so a reader can stop before the rows.
...(listing.filter ? { holds_filter: listing.filter } : {}), holds_summary: listing.summary, ...(listing.paging ? { holds_page: listing.paging } : {}), holds: listing.rows.map(hold => ({ ...hold, fix: renderAction(hold.fix, ctx) })) };
if (args.includes('--json')) return writeJsonDocument(JSON.stringify(rendered, null, 2));
const c = status.cursor;
console.log(syncStatusHeadline(status));
console.log(` ${c ? c.done ? `last run finished at ${c.index}/${c.total} (pinned ${c.pinned_target?.slice(0, 8) ?? '?'})` : `cursor ${c.index}/${c.total} at pinned target ${c.pinned_target?.slice(0, 8) ?? '?'}`
+ `${c.last_advance_at ? `, last advance ${c.last_advance_at}` : ''}` : 'no managed cursor'}`);
console.log(` committed in the last 10 minutes: ${status.committed_last_10m}${status.rate_pages_per_min !== null ? `, ${status.rate_pages_per_min} pages/min` : ''}`);
// #7243: the applied-through commit, the job doing the work, and what the newest pass pinned against what a stamp backs.
console.log(` last synced commit: ${status.last_commit?.slice(0, 8) ?? 'none yet'}`);
console.log(` last converged: ${status.last_sync_at ?? 'never'}; last committed write: ${status.last_committed_at ?? 'none yet'}${status.last_committed_at && (!status.last_sync_at || status.last_committed_at > status.last_sync_at) ? ' (still importing since it last converged)' : ''}`);
const live = status.live;
console.log(` live: ${live ? `${live.kind}${live.job_id !== null ? ` job #${live.job_id}` : live.id ? ` ${live.id}` : ''}${live.pid ? ` (PID ${live.pid})` : ''} holds the drain lease since ${live.started_at ?? '?'}`
+ `${live.progress ? `, ${live.progress.committed} page(s) committed since` : ''}${live.stalled ? ', STALLED (no commit or save for the stall window)' : ''}` : 'nothing holds the drain lease'}`);
const cut = status.interrupted;
if (cut) console.log(` INTERRUPTED: pass ${cut.pass_id.slice(0, 8)} stopped before it ended (last write ${cut.since})${cut.holder ? `; its holder ${cut.holder.kind}${cut.holder.pid ? ` (PID ${cut.holder.pid})` : ''} stopped renewing the lease at ${cut.holder.last_heartbeat_at ?? '?'}${cut.holder.progress ? ` after committing ${cut.holder.progress.committed} page(s)` : ''}` : ''}`);
const pass = status.convergence?.dry_run === false ? status.convergence : null;
if (pass) console.log(` newest pass: ${pass.outcome}${pass.stop_reason ? ` (${pass.stop_reason})` : ''}, round ${pass.round}, pinned ${pass.target.slice(0, 8)}; `
+ `${pass.converged_target ? `last converged at ${pass.converged_target.slice(0, 8)} (${pass.converged_at})` : 'no converged stamp stored'}`);
if (freshness) console.log(` freshness: ${formatSyncFreshness(freshness)}`);
if (notifierBlock) console.log(` ${formatNotifierBlock(sourceId, notifierBlock)}`);
console.log(` holds: ${status.holds.length}${status.holds.length ? ` (${status.holds.filter(h => h.needs_human).length} need a person)` : ''}; last error: ${status.last_error ? `${status.last_error.code} [${status.last_error.class}]` : 'none'}`);
for (const hold of listing.rows) console.log(` ${hold.path}${hold.slug ? ` (${hold.slug})` : ''}: ${hold.code}${hold.fault_code ? ` (${hold.fault_code})` : ''} [${hold.class}] safe: ${hold.safe_actions.join(',')}${hold.needs_human ? ` NEEDS HUMAN: ${hold.human_reason}` : ''}${hold.attempts > 1 ? ` (held ${hold.attempts} times)` : ''}`);
if (listing.paging && !listing.paging.complete) {
const codes = Object.entries(listing.summary.by_code.counts).map(([code, n]) => `${code} ${n}`).join(', ');
console.log(` ... ${listing.matched - listing.rows.length} more not listed here (${codes}${listing.summary.by_code.other ? `, other ${listing.summary.by_code.other}` : ''}); `
+ `${listing.paging?.next_command ? listing.paging.next_command.join(' ') : `gbrain sync status --source ${sourceId} --detail --json`} lists them`);
}
const superseded = status.last_error?.superseded;
if (status.last_error) console.log(` ${status.last_error.path ?? ''}: ${status.last_error.code}${superseded ? ` (superseded: ${SUPERSEDED_TEXT[superseded.by ?? 'commit']} at ${superseded.at}, after this error${superseded.age_seconds !== undefined ? `, recorded ${Math.round(superseded.age_seconds / 60)} min ago` : ''})` : ` safe: ${status.last_error.safe_actions.join(',')}${status.last_error.needs_human ? ` NEEDS HUMAN: ${status.last_error.human_reason}` : ''}`}`);
const ob = status.oldest_blocker;
console.log(` oldest unfinished request: ${ob.status === 'unknown' ? `unknown (${ob.reason})` : ob.request ? `${ob.request.request_id} (${ob.request.state}${ob.request.step ? `, step ${ob.request.step}` : ''}${ob.request.blocked_by ? `, blocked by ${ob.request.blocked_by.predicate}` : ''})` : 'none'}`
+ `; recovery records: ${status.recovery.status === 'unknown' ? `unknown (${status.recovery.reason})` : status.recovery.count}`);
const t = status.terminal_failures;
if (status.terminal_failures_read.status === 'not_read') console.log(' terminal write failures, checkpoint blockers and cursors: not read (run with --detail)');
else if (t.status === 'unknown') console.log(` terminal write failures: unknown (${t.reason})`);
else {
const oldest = t.unresolved.oldest_age_seconds === null ? '' : `, oldest ${Math.round(t.unresolved.oldest_age_seconds / 3600)} h`;
console.log(` terminal write failures (last ${t.window_days} d): ${t.active_blockers.length} active blocker(s), ${t.unresolved.rows} unresolved (${t.unresolved.distinct_slugs} page(s), `
+ `${t.unresolved.distinct_intents} intent(s)${oldest}), ${t.historical_rows} historical, ${t.new_last_24h} in the last 24 h${t.defects ? `, ${t.defects} gbrain-defect row(s)` : ''}`);
for (const b of t.active_blockers) console.log(` BLOCKING ${b.kind}: request ${b.request_id}${b.slug ? ` (${b.slug})` : ''} [${b.category}]`);
if (t.active_blockers.length || t.unresolved.rows) console.log(` drill down: ${t.drill_down.join(' ')}`);
}
const landing = status.landing;
if (landing?.status === 'ok') {
console.log(` synced but not searchable after ${landing.after_seconds} s (last ${landing.window_hours} h, ${landing.checked} page(s)${landing.complete ? '' : ', newest receipts only'}): ${landing.gaps}`
+ `${landing.gaps ? ` (${Object.entries(landing.by_state).map(([state, n]) => `${state} ${n}`).join(', ')})` : ''}`);
for (const page of landing.pages) console.log(` ${page.slug}: ${page.state}, synced ${page.age_seconds} s ago${page.fix?.argv ? `; fix: ${page.fix.argv.join(' ')}` : ''}`);
} else if (landing) console.log(` synced but not searchable: ${landing.status} (${landing.reason})`);
for (const hold of status.fence_holds) console.log(` ${hold.kind} held (${hold.reason}) on ${hold.slug}: ${hold.rows} row(s) kept live; ASK THE USER: ${hold.fix.user_message ?? hold.fix.why}`);
for (const hold of status.git_push_holds) console.log(` git backups not pushed: ${hold.retrying} retrying, ${hold.parked} parked (${hold.codes.join(', ')}) since ${hold.oldest_at}${hold.conflict ? `; CONFLICT in ${hold.conflict.paths.join(', ')} needs a person` : ''}`);
const connector = status.connector_last_error;
if (connector) console.log(` connector: ${connector.stopped ? 'STOPPED, ' : ''}the last ${connector.consecutive} run(s) ended on ${connector.code}${connector.slug ? ` at ${connector.slug}` : ''}: ${connector.message}`);
for (const notice of notices) console.log(` [gbrain notice ${notice.code}] ${notice.why}`);
if (rendered.next) console.log(` Next: ${rendered.next.command ?? rendered.next.argv?.join(' ')}\n Why: ${rendered.next.why}`);
else console.log(' Next: nothing; the source is synced and holds nothing.');
}
/** #6712 PR 2 (L5): the one headline per state; the reason names why. */
export function syncStatusHeadline(status: Pick<SyncStatus, 'source_id' | 'state' | 'reason' | 'cursor' | 'run_id' | 'holds' | 'live_job_id'> & Partial<Pick<SyncStatus, 'carried'>>): string {
const c = status.cursor;
switch (status.reason) {
case 'nothing_pending': return `Source ${status.source_id} is synced${c?.done ? ` (last run ${status.run_id?.slice(0, 8) ?? '?'} finished at ${c.index}/${c.total})` : ''}.`;
case 'held_by_design': return `Source ${status.source_id} is synced; ${status.holds.length} file(s) stay held by design${(status.carried ?? []).map(carried => `; ${carried.count} ${carried.class} (${carried.class === 'mirror_keep_deleted' ? 'deleted pages the user kept deleted although this read-only mirror\'s upstream edited their files' : 'database-only pages this read-only mirror keeps'}, e.g. ${carried.sample[0]}; list: ${carried.list.join(' ')})`).join('')}.`;
case 'held_needs_human': return `Source ${status.source_id} is synced except ${status.holds.length} held file(s), some waiting on a person (see NEEDS HUMAN below); the rest keeps syncing.`;
case 'live_job': return `Source ${status.source_id} is resumable: sync job #${status.live_job_id} is draining it.`;
case 'cursor_unfinished': return `Source ${status.source_id} is resumable: run ${status.run_id?.slice(0, 8) ?? '?'} stands at ${c?.index ?? '?'}/${c?.total ?? '?'}; the next sync resumes it.`;
case 'last_error': return `Source ${status.source_id} is resumable: the last run recorded a failure that a rerun holds or retries.`;
case 'holds_actionable': return `Source ${status.source_id} is resumable: held files have a safe action (sync unblock).`;
case 'recovery_pending': return `Source ${status.source_id} is resumable: a write's recovery record waits for an owner pass.`;
case 'request_pending': return `Source ${status.source_id} is resumable: a write request is still unfinished; the next sync drains it.`;
case 'status_unknown': return `Source ${status.source_id}: state unknown (a probe did not answer); not reported synced.`;
case 'needs_human': return `Source ${status.source_id} is blocked: a person has to decide (see NEEDS HUMAN below).`;
case 'head_blocked': return `Source ${status.source_id} is blocked: its oldest write waits on something only an operator clears.`;
case 'recovery_blocked': return `Source ${status.source_id} is blocked: a write's recovery record found changed bytes on disk.`;
case 'pass_unfinished': return `Source ${status.source_id} is resumable: the newest sync pass did not finish; the next sync continues it.`;
case 'pass_interrupted': return `Source ${status.source_id} is resumable: the newest sync pass stopped before it ended and no process owns it (killed, crashed or stopped by an unrecorded error); the next sync continues it.`;
case 'pass_terminated': return `Source ${status.source_id} is resumable: a termination signal (SIGTERM or SIGHUP) stopped the newest sync pass, which recorded its stop; the next sync continues it.`;
case 'pass_abandoned': return `Source ${status.source_id} is blocked: its sync passes keep stopping before they end (killed, stopped by a signal or by a recurring transient stop); another plain sync will not change that (report what doctor shows).`;
case 'not_converged': return `Source ${status.source_id} is resumable: the newest sync pass ran out of rounds before every path settled.`;
case 'settle_mismatch': return `Source ${status.source_id} is resumable: a path keeps settling without reading settled; three passes in a row hold it.`;
case 'deletes_withheld': return `Source ${status.source_id} is blocked: sync withheld a mass delete; the rest of the source is synced.`;
case 'selection_scoped': return `Source ${status.source_id} is synced at a narrower selection; the plain sync runs the configured one.`;
case 'admission_paused': return `Source ${status.source_id} is resumable: sync.admission pauses what sync admits.`;
case 'commits_waiting': return `Source ${status.source_id} is resumable: its checkout has commits past the last synced commit; the next sync imports them.`;
case 'writeback_failed': return `Source ${status.source_id} is blocked: the Git effect of a file sync rewrote failed and is parked; the checkout lags the brain.`;
}
}
export async function runSyncUnblock(engine: BrainEngine, args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) return printSyncUnblockHelp();
const sourceId = sourceOf(args);
const outcome = await unblockSync(engine, sourceId, { apply: args.includes('--apply'), noLlm: args.includes('--no-llm'), noRepair: args.includes('--no-repair') });
// #6712 PR 2: a soak intervention (soak-counters.ts).
if (outcome.apply) await (await import('../../core/persistence/soak-counters.ts')).recordSoakEvent(engine, 'unblock_apply');
const ctx = cliRenderContext();
const rendered = { ...outcome,
applied: outcome.applied.map(entry => entry.action === 'repair' ? { ...entry, repair: { ...entry.repair, next: renderAction(entry.repair.next, ctx) } } : entry),
refused: outcome.refused.map(entry => ({ ...entry, fix: renderAction(entry.fix, ctx) })), next: outcome.next ? renderAction(outcome.next, ctx) : null };
if (args.includes('--json')) return writeJsonDocument(JSON.stringify(rendered, null, 2));
const repaired = outcome.applied.filter(entry => entry.action === 'repair').length;
console.log(`Source ${sourceId}: ${outcome.applied.length} held file(s) ${outcome.apply ? `${repaired ? 'repaired or ' : ''}scheduled for a re-screen` : `would be ${repaired ? 'repaired or ' : ''}scheduled for a re-screen (preview; add --apply)`}, ${outcome.refused.length} refused.`);
for (const entry of outcome.applied) {
console.log(` ${entry.path}: ${entry.code} → ${entry.action}: ${entry.detail}`);
if (entry.action === 'repair' && entry.repair.receipt) console.log(` receipt: ${Object.entries(entry.repair.receipt).map(([k, v]) => `${k}=${v}`).join(', ')}`);
}
for (const entry of outcome.refused) console.log(` ${entry.path}: ${entry.code} refused (${entry.reason})${entry.needs_human ? ' NEEDS HUMAN' : ''}`);
if (rendered.next) console.log(` Next: ${rendered.next.command ?? rendered.next.argv?.join(' ')}\n Why: ${rendered.next.why}`);
else console.log(' Next: nothing held.');
}