Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain sources writer git-durability <source> --enable|--disable [--pat-file <p>] [--dry-run]`
* (#5182, #5808): the trusted-local admin verb that records a managed worktree's
* Git-durability opt-in on this host's binding, re-wires the repo-scoped push
* credential, and catches up the Git effects skipped while durability was off.
*
* It is a `PERSISTENCE_ADMIN_OPERATIONS` verb (never a public operation) with
* the same `--admin-intent`/`--expected-state` handshake as `writer_activate`:
* the binding column is part of the admin-state hash, so a stale state is
* refused. The opt-in is a database column, the credential is Git metadata in
* `.git/config` plus a 0600 store under the gbrain home (the same keys
* `sources harden` uses, so `sources unharden` removes it), and the push probe
* is `git push --dry-run`. The one file under the canonical root this verb
* writes is the resolver file's durability block (#5808): `--enable` and
* `--pat-file` rewrite it idempotently to the managed variant, which never
* sends agents around the owner, and leave it for the operator to commit.
*/
import { chmodSync, existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
import { join, relative } from 'node:path';
import { execFileBounded } from '../bounded-child-exec.ts';
import { classifyGitCheckout } from '../git-checkout.ts';
import { durableSsrfFlags, GIT_ENV, GIT_ENV_AUTH, GIT_SSRF_SUBCOMMAND_FLAGS } from '../git-remote.ts';
import { gitChildEnv } from '../git-env.ts';
import { NON_FAST_FORWARD } from './effect-git.ts';
import { ensureGbrainHome, resolveGbrainHome } from '../gbrain-home.ts';
import { OperationError, opError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import type { Action } from '../agent-output.ts';
import type { BrainEngine } from '../engine.ts';
import { existingHostIdFor } from './identity.ts';
import { getWorktreeBinding, type GitDurabilitySetting, type WorktreeBinding } from './ownership.ts';
import { requireWriterAdminIntent, assertWriterAdminState, writerAdminState } from './admin-intent.ts';
import { gitDurabilityPolicy, planGitDurabilityCatchUp, requeueGitDurabilityCatchUp } from './git-durability-policy.ts';
import { refusalEnvelope, retryParkedEffects } from './effect-retry.ts';
import { GIT_PUSH_CODES } from './git-push-holds.ts';
import { patchManagedDurabilityBlock } from '../brain-repo-durability.ts';
import { findResolverFile } from '../resolver-filenames.ts';
export const GIT_DURABILITY_PARAMS = ['source_id', 'enable', 'disable', 'pat_file', 'dry_run', 'admin_intent', 'expected_state'] as const;
/** The same repo-local key `sources harden` writes, so `sources unharden` removes a credential this verb wired. */
const CRED_MANAGED_KEY = 'gbrain.durability.managedcredential';
const GIT_TIMEOUT_MS = 20_000;
const statusFix = (sourceId: string): Action => readFix(`Shows source ${sourceId}'s owner binding, its git_durability setting and the admin_state the verb needs, read-only.`,
{ argv: ['gbrain', 'sources', 'writer', 'status', sourceId, '--json'] });
const invalid = (message: string, suggestion: string, sourceId?: string) => opError('invalid_params', message, suggestion, sourceId ? { fix: statusFix(sourceId) } : {});
export interface GitDurabilityInput { sourceId: string; enable: boolean; disable: boolean; patFile?: string; dryRun: boolean }
export function parseGitDurabilityParams(params: Record<string, unknown>): GitDurabilityInput {
for (const key of ['enable', 'disable', 'dry_run'] as const) {
if (params[key] !== undefined && typeof params[key] !== 'boolean') throw invalid(`${key} must be a boolean.`, `Pass --${key.replace('_', '-')} as a bare flag; it takes no value.`);
}
if (params.enable === true && params.disable === true) throw invalid('Choose --enable or --disable, not both.',
'Run gbrain sources writer git-durability <source> --enable to publish through the persistence owner, or --disable to keep Git effects off.');
if (params.pat_file !== undefined && (typeof params.pat_file !== 'string' || !params.pat_file.trim() || params.pat_file.includes('\0'))) {
throw invalid('pat_file must be a path to a file holding the token.', 'Pass --pat-file <path>; the token is read from that 0600 file and never from the command line.');
}
if (params.disable === true && params.pat_file !== undefined) throw invalid('--pat-file cannot be combined with --disable.',
'Disable without a token, or re-wire the credential with --enable --pat-file <path> (or --pat-file alone to keep the current setting).');
if (params.enable !== true && params.disable !== true && params.pat_file === undefined) throw invalid('Name the change: --enable, --disable, or --pat-file <path>.',
'gbrain sources writer git-durability <source> --enable publishes page writes through the owner\'s Git effect; --disable turns that off; --pat-file <path> alone re-wires the push credential and retries parked pushes.');
return { sourceId: String(params.source_id), enable: params.enable === true, disable: params.disable === true,
patFile: typeof params.pat_file === 'string' ? params.pat_file : undefined, dryRun: params.dry_run === true };
}
async function git(root: string, args: string[], auth = false): Promise<{ code: number; stdout: string; stderr: string }> {
const { error, stdout, stderr } = await execFileBounded('git', ['-C', root, ...(auth ? durableSsrfFlags() : []), ...args],
{ timeout: GIT_TIMEOUT_MS, maxBuffer: 1024 * 1024, env: gitChildEnv({ ...GIT_ENV, ...(auth ? GIT_ENV_AUTH : {}), LC_ALL: 'C' }) });
if (error && (error.killed || typeof error.code !== 'number')) throw opError('git_unavailable', 'Git did not finish within its bounded attempt.',
`git ${args[0]} in ${root} did not finish within ${GIT_TIMEOUT_MS / 1000} seconds or could not start; nothing was changed. Check that git runs in that checkout on the brain host, then rerun.`);
return { code: error ? error.code as number : 0, stdout, stderr };
}
/**
* The checkout must be a Git checkout on a born branch before durability can
* be enabled: a detached HEAD would push the wrong ref, and an unborn branch
* (a fresh `init --git` root with no commit yet, #6332) has nothing to push
* and is named as such, not as a detached HEAD.
*/
export async function inspectDurabilityCheckout(root: string): Promise<{ branch: string; remote: string | null; merge: string | null }> {
const checkout = classifyGitCheckout(root);
if (checkout !== 'git') {
throw opError('git_checkout_required', `${root} is not inside a Git checkout, so its Git effects have nothing to commit to.`,
'Initialize the canonical root as a Git repository (git init, a first commit, and a remote) on the brain host, then rerun; a database-only source needs no Git durability.');
}
const symbolic = await git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
if (symbolic.code !== 0) {
throw opError('git_detached_head', `${root} is on a detached HEAD, so a push would target the wrong ref.`,
'Check out the branch the remote should track (git switch <branch>) on the brain host, then rerun.');
}
const branch = symbolic.stdout.trim();
const head = await git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']);
if (head.code !== 0) {
throw opError('git_branch_unborn', `Branch ${branch} in ${root} is unborn: it has no commit yet, so there is nothing for a Git effect to build on.`,
`Make the first commit on ${branch} (for example commit the existing page files with git add -A && git commit -m "Initial brain") on the brain host, then rerun.`);
}
const remote = await git(root, ['config', '--get', `branch.${branch}.remote`]);
const merge = await git(root, ['config', '--get', `branch.${branch}.merge`]);
const tracked = remote.code === 0 && merge.code === 0 && remote.stdout.trim() && remote.stdout.trim() !== '.';
return { branch, remote: tracked ? remote.stdout.trim() : null, merge: tracked ? merge.stdout.trim() : null };
}
export type PushProbe = { ok: true; skipped?: 'no_tracking_remote'; remote_moved?: true; detail?: string }
| { ok: false; reason: 'auth' | 'protected' | 'unreachable' | 'other'; detail: string };
/**
* `git push --dry-run` to the branch's tracking remote: proves push authority without a commit; the same refspec the Git effect pushes.
* GBRA-133: a rejection only because the remote moved (`fetch first`, `non-fast-forward`) comes after the remote accepted
* the push connection, and the Git effect publishes that case itself (it merges the remote commits in memory and pushes,
* #7010, `pushGitRoot`), so the probe passes it with `remote_moved`. Auth, protected-branch and unreachable refusals still fail.
*/
export async function probeDurabilityPush(root: string, checkout: { remote: string | null; merge: string | null }, redact: (s: string) => string): Promise<PushProbe> {
if (!checkout.remote || !checkout.merge) return { ok: true, skipped: 'no_tracking_remote' };
const push = await git(root, ['push', ...GIT_SSRF_SUBCOMMAND_FLAGS, '--dry-run', '--', checkout.remote, `HEAD:${checkout.merge}`], true);
if (push.code === 0) return { ok: true };
const detail = redact(`${push.stderr}\n${push.stdout}`).replace(/\s+/g, ' ').trim().slice(0, 200);
if (NON_FAST_FORWARD.test(push.stderr)) return { ok: true, remote_moved: true,
detail: 'the remote branch has commits this checkout lacks; the Git effect merges them in memory and pushes the merge (#7010) without pulling into the checkout, and holds a same-file conflict as integrate_conflict for the user to choose' };
const low = detail.toLowerCase();
const reason = low.includes('authentication') || low.includes('403') || low.includes('permission') || low.includes('could not read') ? 'auth'
: low.includes('protected') || low.includes('pre-receive') || low.includes('hook declined') ? 'protected'
: low.includes('could not resolve') || low.includes('unable to access') || low.includes('timed out') || low.includes('network') ? 'unreachable' : 'other';
return { ok: false, reason, detail };
}
/** Read the token from a private file: refuses a group/other-readable or empty file before anything is written. */
export function readPatFile(path: string): string {
if (!existsSync(path)) throw opError('pat_file_unreadable', `--pat-file ${path} does not exist.`, 'Write the token to a file only you can read (chmod 600), then pass its path with --pat-file.');
const mode = statSync(path).mode;
if (process.platform !== 'win32' && (mode & 0o077) !== 0) {
throw opError('pat_file_unreadable', `--pat-file ${path} is group- or other-readable (mode ${(mode & 0o777).toString(8)}), so it was not read.`,
`Run chmod 600 ${path} and rerun; a token file that other users can read is refused before any credential is written.`);
}
const token = readFileSync(path, 'utf8').trim();
if (!token || /\s/.test(token)) throw opError('pat_file_unreadable', `--pat-file ${path} is empty or holds more than one token.`,
'Put exactly one token on one line in the file, then rerun.');
return token;
}
async function remoteHost(root: string, remote: string | null): Promise<string> {
const url = remote ? await git(root, ['remote', 'get-url', remote]) : { code: 1, stdout: '' };
try { return new URL(url.stdout.trim()).hostname || 'github.com'; } catch { return 'github.com'; }
}
/**
* Wire a repo-scoped credential for the tracking remote's host: a repo-LOCAL
* `credential.helper store --file <gbrain-home>/git-credentials` (0600) marked
* with the key `sources harden` uses, so both verbs share one store and
* `sources unharden` removes either's wiring. A repo-local helper gbrain did not
* write is left alone. The token never appears in the result or a log line.
*/
export async function wireDurabilityCredential(root: string, remote: string | null, token: string, dryRun: boolean): Promise<{ status: 'ok' | 'fixed'; detail: string }> {
const existing = (await git(root, ['config', '--local', '--get', 'credential.helper'])).stdout.trim();
const ours = (await git(root, ['config', '--local', '--get', CRED_MANAGED_KEY])).stdout.trim() === 'true';
if (existing && !ours) return { status: 'ok', detail: 'reusing the repo-local credential.helper another tool configured (no store written)' };
const host = await remoteHost(root, remote);
const store = join(resolveGbrainHome(), 'git-credentials');
const line = `https://x-access-token:${token}@${host}`;
const lines = existsSync(store) ? readFileSync(store, 'utf8').split('\n') : [];
if (ours && existing && lines.includes(line)) return { status: 'ok', detail: `repo-scoped credential already wired for ${host}` };
if (dryRun) return { status: 'fixed', detail: `would wire a repo-scoped credential for ${host} (dry-run)` };
ensureGbrainHome();
const prefix = 'https://x-access-token:';
const kept = lines.filter(entry => entry && !(entry.startsWith(prefix) && entry.endsWith(`@${host}`)));
writeFileSync(store, `${[...kept, line].join('\n')}\n`, { mode: 0o600 });
try { chmodSync(store, 0o600); } catch { /* best effort on filesystems without modes */ }
const set = await git(root, ['config', '--local', 'credential.helper', `store --file ${store}`]);
const mark = await git(root, ['config', '--local', CRED_MANAGED_KEY, 'true']);
if (set.code !== 0 || mark.code !== 0) throw opError('git_unavailable', 'The repo-local credential helper could not be configured.',
`git config --local in ${root} failed, so the push credential was not wired; nothing else changed. Check that the checkout's .git/config is writable on the brain host, then rerun.`);
return { status: 'fixed', detail: `wired a repo-scoped credential for ${host} (store 0600; replaces an earlier token for that host)` };
}
/** A failed Git effect held on one of $2's codes: a parked target with it, or (#7378) a push that failed without parking. */
const HELD_ON_CODES = `e.error_code=ANY($2::text[]) OR e.error_code='targets_parked'
AND EXISTS (SELECT 1 FROM jsonb_array_elements(COALESCE(e.data->'parked','[]'::jsonb)) p WHERE p->>'error_code'=ANY($2::text[]))`;
/**
* #7378: unsettled Git effects of the source held on these codes but bound to another (former) worktree. A retry of the
* current worktree never reaches them (the binding guard refuses their stale binding), so an empty retry is not their
* resolution: they are named with the settle preview that can account for them.
*/
async function formerWorktreeHolds(engine: BrainEngine, sourceId: string, worktreeId: string, codes: readonly string[]) {
const [row] = await engine.executeRaw<{ effects: number; code: string | null; worktree_ids: string[]; requests: string[] }>(`SELECT count(*)::int AS effects,
min(CASE WHEN e.error_code=ANY($2::text[]) THEN e.error_code ELSE (SELECT min(p->>'error_code') FROM jsonb_array_elements(e.data->'parked') p
WHERE p->>'error_code'=ANY($2::text[])) END) AS code,
array_agg(DISTINCT e.worktree_id::text) AS worktree_ids, (array_agg(DISTINCT r.request_id::text))[1:5] AS requests
FROM persistence_effects e JOIN persistence_requests r ON r.id=e.request_id WHERE e.source_id=$1 AND e.worktree_id IS DISTINCT FROM $3::uuid AND e.kind='git' AND e.state='failed'
AND NOT (e.data ? 'settled') AND (${HELD_ON_CODES})`, [sourceId, [...codes], worktreeId]);
if (!row?.effects || !row.code) return {};
const command = ['gbrain', 'sources', 'writer', 'settle-effects', sourceId, '--parked-code', row.code, '--dry-run'];
return { former_worktree: { effects: Number(row.effects), command, worktree_ids: row.worktree_ids, requests: row.requests,
why: `${row.effects} held Git effect(s) of source ${sourceId} (requests ${row.requests.join(', ')}) belong to former canonical worktree ${row.worktree_ids.join(', ')}, not the current ${worktreeId}: retry cannot run them (their binding changed) and this preview does not resolve them, so its counts do not include them. Preview settling them on proof: ${command.join(' ')}` } };
}
export type ParkedPushRefusal = { source_id: string; request_id: string; code: string; message: string; suggestion?: string; fix?: Action };
export type ParkedPushRetry = { status: 'ok' | 'partial'; requests: number; queued: number; unchanged: number; refused: ParkedPushRefusal[] };
const REQUEST_REFUSALS = new Set(['permission_denied', 'source_changed', 'write_claim_lost', 'page_not_found']);
/**
* #7110: the stored remote authority can no longer see the request's page (it became private), so the retry's
* authority check refuses it as page_not_found. That is this request's refusal, not the run's; the trusted local
* operator gets the slug and the receipt to read instead of the remote writer's non-disclosing message.
*/
function hiddenTargetRefusal(row: { request_id: string; slug: string }): Omit<ParkedPushRefusal, 'source_id' | 'request_id'> {
return { code: 'page_not_found', message: `Page ${row.slug} is no longer visible to request ${row.request_id}'s original remote writer, so its parked Git effect was not retried under that writer.`,
suggestion: 'The other parked requests were still retried. This one stays parked: no retry runs it under another authority. Read its receipt, then decide with the brain owner whether the page should be visible to that writer again.',
fix: readFix(`Reads request ${row.request_id}'s receipt: its source, state and effect outcomes, read-only.`, { argv: ['gbrain', 'write-request', '--', row.request_id] }) };
}
/**
* #5808(a): after a credential change, one more attempt for every effect of this
* worktree that parked on a push code (`git_push_unavailable`; #7010 adds
* `push_unconfirmed` and `integrate_conflict`, see `retrySourceParkedPushes`). Other worktrees are untouched;
* each journal row goes through `retryParkedEffects`, so the original write's
* authority is re-checked and a claimed or settled effect is left alone.
* #6678: effects reference the internal journal id, so the public receipt id is
* joined for the report and the row is selected by its internal id. A request
* refused on its own (revoked writer, replaced source, live claim) is listed in
* `refused` with the same envelope in preview and apply, and the run is `partial`;
* a host or binding problem (`owner_unavailable`) still stops the whole run.
*/
export async function retryParkedPushes(engine: BrainEngine, worktreeId: string, dryRun: boolean, codes: readonly string[] = GIT_PUSH_CODES): Promise<ParkedPushRetry> {
const rows = await engine.executeRaw<{ source_id: string; id: string; request_id: string; slug: string }>(`
SELECT DISTINCT e.source_id,r.id::text AS id,r.request_id::text AS request_id,r.slug FROM persistence_effects e
JOIN persistence_requests r ON r.id=e.request_id
WHERE e.worktree_id=$1::uuid AND e.kind='git' AND e.state='failed' AND e.recovery IS NULL AND NOT (e.data ? 'settled') AND (${HELD_ON_CODES})
ORDER BY e.source_id,request_id,id`, [worktreeId, [...codes]]);
let queued = 0, unchanged = 0;
const refused: ParkedPushRefusal[] = [];
for (const row of rows) {
const target = { source_id: row.source_id, request_id: row.request_id };
let result: Record<string, unknown> | null;
try {
result = await retryParkedEffects(engine, row.source_id, row.request_id, dryRun, { internalId: row.id, parkedOnly: true, failedCodes: codes });
} catch (error) {
if (!(error instanceof OperationError) || !REQUEST_REFUSALS.has(error.code)) throw error;
refused.push({ ...target, ...(error.code === 'page_not_found' ? hiddenTargetRefusal(row) : refusalEnvelope(error)) });
continue;
}
if (result?.action === 'owner_revoked') { refused.push({ ...target, ...(result.refusal as ReturnType<typeof refusalEnvelope>) }); continue; }
const effects = (result?.effects ?? []) as Array<{ action: string }>;
if (effects.some(effect => effect.action === 'retry_queued' || effect.action === 'would_retry')) queued++; else unchanged++;
}
return { status: refused.length ? 'partial' : 'ok', requests: rows.length, queued, unchanged, refused };
}
/**
* #7010: `retry-effects <source> --parked-pushes`: one more attempt for every Git effect of the source's worktree
* parked on a push code, without a credential change. A push the remote rejected because it moved now publishes over
* the remote without moving the checkout, so the effects a moved remote parked before this release go through.
*/
export async function retrySourceParkedPushes(engine: BrainEngine, sourceId: string, dryRun: boolean): Promise<Record<string, unknown>> {
const binding = await ownedBinding(engine, sourceId);
return { action: 'writer_retry_parked_pushes', source_id: sourceId, worktree_id: binding.worktree_id, dry_run: dryRun,
...await retryParkedPushes(engine, binding.worktree_id, dryRun), ...await formerWorktreeHolds(engine, sourceId, binding.worktree_id, GIT_PUSH_CODES) };
}
/**
* GBRA-133: `retry-effects <source> --parked-code <code>`: one more attempt for every Git effect of the source's worktree
* with a target parked on `code` (for example `git_target_ignored` after its .gitignore rule changed), each through
* `retryParkedEffects` as `--parked-pushes` does.
*/
export async function retrySourceParkedCode(engine: BrainEngine, sourceId: string, code: string, dryRun: boolean): Promise<Record<string, unknown>> {
const binding = await ownedBinding(engine, sourceId);
return { action: 'writer_retry_parked_code', source_id: sourceId, worktree_id: binding.worktree_id, code, dry_run: dryRun,
...await retryParkedPushes(engine, binding.worktree_id, dryRun, [code]), ...await formerWorktreeHolds(engine, sourceId, binding.worktree_id, [code]) };
}
async function ownedBinding(engine: BrainEngine, sourceId: string): Promise<WorktreeBinding & { local_path: string }> {
const hostId = existingHostIdFor(engine);
const binding = await getWorktreeBinding(engine, sourceId, hostId);
if (!binding) {
throw opError('writer_registration_required', `Source ${sourceId} has no canonical owner on this brain.`,
`Claim its checkout first (gbrain sources writer claim ${sourceId} --path <directory>, with the admin-intent handshake), then enable Git durability; a database-only source needs neither.`,
{ fix: statusFix(sourceId) });
}
if (!hostId || binding.owner_host_id !== hostId || !binding.local_path) {
throw opError('permission_denied', `Only source ${sourceId}'s owner host can change its Git durability.`,
`This host is not the registered owner of source ${sourceId}'s checkout (or has no local binding for it), so nothing was changed. Run the verb on the owner host that writer status names.`,
{ fix: statusFix(sourceId) });
}
if (binding.state !== 'active') throw opError('recovery_required', `Source ${sourceId}'s worktree is ${binding.state}, not active.`,
'Finish the pending recovery or transfer that writer status shows before changing Git durability; the setting is recorded on the active binding.', { fix: statusFix(sourceId) });
return binding as WorktreeBinding & { local_path: string };
}
/** The verb. `params` are the raw admin params; the caller has already checked the key set. */
export async function runGitDurabilityAdministration(engine: BrainEngine, params: Record<string, unknown>): Promise<Record<string, unknown>> {
const input = parseGitDurabilityParams(params);
// #7634: approval and the reviewed state are checked before the token is read or the checkout, credential store or parked pushes change.
const expectedState = await requireWriterAdminIntent(engine, 'writer_git_durability', params);
const binding = await ownedBinding(engine, input.sourceId);
const root = binding.local_path;
const token = input.patFile === undefined ? undefined : readPatFile(input.patFile);
const redact = token ? (text: string) => text.split(token).join('[redacted]') : (text: string) => text;
const before: GitDurabilitySetting = binding.git_durability;
const target: GitDurabilitySetting = input.enable ? 'enabled' : input.disable ? 'disabled' : before;
const report: Record<string, unknown> = { source_id: input.sourceId, worktree_id: binding.worktree_id, path: root, dry_run: input.dryRun,
git_durability: { before, after: target }, action: 'writer_git_durability' };
// Policy under the current binding, so the operator sees what the hook probe says when nothing is recorded yet.
report.current_policy = await gitDurabilityPolicy(binding, root).then(policy => ({ ...policy }), error => ({ error: error instanceof Error ? error.message : String(error) }));
let checkout: Awaited<ReturnType<typeof inspectDurabilityCheckout>> | undefined;
if (target === 'enabled' || token) {
checkout = await inspectDurabilityCheckout(root);
report.branch = checkout.branch;
report.tracking_remote = checkout.remote;
}
if (token && checkout) {
report.credential = await wireDurabilityCredential(root, checkout.remote, token, input.dryRun);
// Only after the credential write succeeded: one more attempt per parked push of this worktree.
const parked = await retryParkedPushes(engine, binding.worktree_id, input.dryRun);
report.parked_pushes = parked;
report.status = parked.status;
}
if (target === 'enabled' && checkout) {
const probe = await probeDurabilityPush(root, checkout, redact);
report.push_probe = probe;
if (!probe.ok) {
throw opError('git_push_unavailable', `The read-only push probe for ${input.sourceId} failed (${probe.reason}), so Git durability was not enabled.`,
`git push --dry-run to ${checkout.remote} from ${root} failed: ${probe.detail || probe.reason}. Enabling now would park every Git effect on its push. ${probe.reason === 'auth' ? 'Pass a token file with --pat-file <path> (chmod 600) to wire a repo-scoped credential, or ' : ''}Fix the remote or its credentials on the brain host, check with git push --dry-run there, then rerun. Nothing was changed.`,
{ fix: statusFix(input.sourceId) });
}
}
const plan = target === 'enabled' ? await planGitDurabilityCatchUp(engine, binding) : [];
report.catch_up = { planned: plan.length, paths: plan.slice(0, 50).map(effect => effect.relative_path) };
// #5808: a block `sources harden` rendered before activation tells agents to pull --rebase and run the push helper;
// on this managed root it is replaced with the managed variant (a non-page file: the operator commits it).
if (checkout) {
const agents = patchManagedDurabilityBlock(root, input.sourceId, input.dryRun);
const file = relative(root, findResolverFile(root) ?? join(root, 'AGENTS.md'));
// GST-2767: the verb itself commits nothing (the apply never moves HEAD); whenever the file it owns is not committed,
// including an untracked copy an earlier run left while the block is already current, it names the exact door command.
const status = input.dryRun ? null : await execFileBounded('git', ['-C', root, 'status', '--porcelain', '--untracked-files=all', '--', file], { timeout: 10_000, env: gitChildEnv({ ...GIT_ENV }) });
const pending = !!status && (status.error !== null || status.stdout.trim() !== '');
report.agents = { ...agents, file, ...(pending ? {
commit: `The durability block is a non-page file: review it and commit it with gbrain git commit-push --path ${root} -m "<msg>" -- ${file}; it rides the owner's next push.`,
commit_argv: ['gbrain', 'git', 'commit-push', '--path', root, '-m', `gbrain: durability rules for source ${input.sourceId}`, '--', file] } : {}) };
}
if (input.dryRun) {
const state = await writerAdminState(engine);
if (before === target && !token) return { ...report, queued_catch_up: 0, why: 'The setting is already as requested; nothing to apply.' };
return { ...report, queued_catch_up: 0, why: 'Review this preview, then run the apply command; it records the setting on this host\'s binding and re-queues the listed effects.',
fix: { argv: ['gbrain', 'sources', 'writer', 'git-durability', input.sourceId, ...(input.enable ? ['--enable'] : input.disable ? ['--disable'] : []),
...(input.patFile ? ['--pat-file', input.patFile] : []), '--admin-intent', 'writer_git_durability', '--expected-state', state],
consent: token ? ['credentials'] : [], actor: 'agent', requires_exclusive: false, why: 'Applies the previewed Git durability change on the owner host.',
verify: { argv: ['gbrain', 'sources', 'writer', 'status', input.sourceId, '--json'] } } };
}
const queued = await engine.transaction(async tx => {
await tx.executeRaw("SELECT set_config('lock_timeout','2000ms',true),set_config('synchronous_commit','on',true)");
await assertWriterAdminState(tx, expectedState);
const [updated] = await tx.executeRaw<{ git_durability: GitDurabilitySetting }>(`UPDATE persistence_host_bindings SET git_durability=$3
WHERE worktree_id=$1::uuid AND host_id=$2::uuid RETURNING git_durability`, [binding.worktree_id, binding.owner_host_id, target]);
if (!updated) throw opError('source_changed', 'The host binding disappeared while the setting was being recorded.',
`Source ${input.sourceId}'s host binding was removed by another topology change, so nothing was recorded. Inspect writer status before trying again.`, { fix: statusFix(input.sourceId) });
return target === 'enabled' ? await requeueGitDurabilityCatchUp(tx, binding, plan.map(effect => effect.id)) : [];
});
return { ...report, applied: true, queued_catch_up: queued.length, fix: statusFix(input.sourceId),
why: target === 'enabled' ? `Page writes to ${input.sourceId} now commit (and push to ${checkout?.remote ?? 'no tracking remote: commits stay local'}) through the persistence owner's Git effect; ${queued.length} earlier skipped effect(s) were re-queued.`
: target === 'disabled' ? `Git effects for ${input.sourceId} now complete as skipped (durability_not_enabled) even where a legacy hook exists; database writes are unaffected. Re-enable with --enable; the skipped effects are caught up then.`
: `The push credential was re-wired; ${report.parked_pushes ? (report.parked_pushes as ParkedPushRetry).queued : 0} parked push(es) got one more attempt${
report.status === 'partial' ? `; ${(report.parked_pushes as ParkedPushRetry).refused.length} request(s) were refused on their own and are listed in parked_pushes.refused with their fix (exit 1)` : ''}.` };
}