@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/executor/worker-finalization.js

@@ -69,6 +69,14 @@
  * Both keep the `clean_exit` classification the process earned. No-expected-branch
  * and absent-on-origin are still one cause, and may be refined later.
  *
+ * BAPI-1426: a managed ticket may stop on purpose with pushed work and no pull
+ * request, because the server holds its delivery (blocked work, a failed
+ * required check, missing or stale evidence). When the caller passes a fresh,
+ * server-confirmed outcome whose preserved head equals both the worker HEAD and
+ * the origin tip, that exit is reported as an intentional hold under a
+ * completion-cause error kind — still a failure, never a success, and never a
+ * missing pull request. Without that confirmation every check below is unchanged.
+ *
  * This check is deliberately fail-CLOSED, unlike the BAPI-586 base check it now
  * shares a lookup with. "The PR could not be verified" and "there is no PR" are
  * the same thing from the contract's point of view: neither is evidence that the
@@ -78,6 +86,7 @@
  */
 import { ReconcileOverlapPushUnfinalized, WorkerFinalizationMissingRemoteBranchAndPr, WorkerFinalizationOriginUnverifiable, WorkerFinalizationPrBaseMismatch, WorkerFinalizationPrNotAttached, WorkerFinalizationPublicationUnverified, WorkerFinalizationSavedButUnfinalized, } from "./job-errors.js";
 import { isImplementationStyleJobType } from "./job-types.js";
+import { COMPLETION_CAUSE_ERROR_KINDS } from "./completion-supervision.js";
 /** A full, lower-case 40-hex commit SHA. */
 const FULL_SHA_RE = /^[0-9a-f]{40}$/;
 /** The `runCommand` options for one bounded read; `{ cwd }` alone when unbounded. */
@@ -492,6 +501,82 @@ function reconcilePushUnfinalizedFailure(job, branch, originSha, pushedSha) {
         last_commit_sha: originSha,
     };
 }
+/**
+ * BAPI-1426: server outcomes that hold a bound attempt whatever the pull-request
+ * state. `awaiting_post_pr` is handled separately: it holds only while no pull
+ * request is attached, because its remaining work needs one.
+ */
+const DELIVERY_HOLD_OUTCOMES = new Set([
+    "blocked",
+    "verification_failed",
+    "evidence_missing_or_stale",
+]);
+const MAX_HOLD_BLOCKERS_IN_MESSAGE = 8;
+/**
+ * BAPI-1426: the hold the server confirmed for THIS head, or null. Every
+ * condition must hold: a bound, available outcome; a full preserved head; a full
+ * worker HEAD equal to it; and an origin tip equal to both. Anything less is not
+ * server confirmation, and the caller falls through to its existing checks.
+ */
+function confirmedDeliveryHold(delivery, workerHeadSha, originSha) {
+    if (!delivery || delivery.bound !== true || delivery.unavailable === true)
+        return null;
+    if (typeof delivery.attemptId !== "string" || !delivery.attemptId)
+        return null;
+    if (typeof delivery.outcome !== "string")
+        return null;
+    const preserved = typeof delivery.preservedHeadSha === "string" ? delivery.preservedHeadSha.trim().toLowerCase() : "";
+    if (!FULL_SHA_RE.test(preserved) || !FULL_SHA_RE.test(workerHeadSha))
+        return null;
+    if (preserved !== workerHeadSha || originSha !== workerHeadSha)
+        return null;
+    return {
+        attempt_id: delivery.attemptId,
+        outcome: delivery.outcome,
+        preserved_head_sha: preserved,
+        blockers: (delivery.blockers ?? []).map((b) => typeof b.step_id === "number" ? { kind: b.kind, step_id: b.step_id } : { kind: b.kind }),
+    };
+}
+/**
+ * BAPI-1426: the intentional checkpoint a managed ticket ends with when the
+ * server holds its delivery. This is a `/fail`, never a success, and it never
+ * claims a pull request is missing. A failed required check is
+ * `RequiredCheckFailed`; every other hold is `RequiredWorkIncomplete`. A lookup
+ * or provider outage never reaches here, so it is never named a failed check.
+ *
+ * The message carries only public identifiers, the closed outcome token, a
+ * truncated head, and blocker kinds with step ids — never evidence text.
+ */
+function deliveryHoldFailure(job, branch, hold) {
+    const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
+    const shown = hold.blockers.slice(0, MAX_HOLD_BLOCKERS_IN_MESSAGE);
+    const blockerText = shown.length
+        ? shown.map((b) => (typeof b.step_id === "number" ? `${b.kind}(step ${b.step_id})` : b.kind)).join(", ") +
+            (hold.blockers.length > shown.length ? `, +${hold.blockers.length - shown.length} more` : "")
+        : "none reported";
+    const telemetry = { delivery_hold: hold };
+    return {
+        error_kind: hold.outcome === "verification_failed"
+            ? COMPLETION_CAUSE_ERROR_KINDS.required_check_failed
+            : COMPLETION_CAUSE_ERROR_KINDS.required_work_incomplete,
+        error_message: `${label}: delivery attempt ${hold.attempt_id} is held by the server at outcome ` +
+            `'${hold.outcome}'. Head ${hold.preserved_head_sha.slice(0, 12)} is durable on origin branch ` +
+            `'${branch}' and matches the head the server preserved. Remaining blockers: ${blockerText}. ` +
+            `This is an intentional checkpoint: the ticket is not delivered and no pull request was ` +
+            `required. Recovery: resolve the blockers and resume from the preserved head.`,
+        classification: "clean_exit",
+        last_commit_sha: hold.preserved_head_sha,
+        telemetry,
+    };
+}
+/**
+ * BAPI-1426: the delivery hold a finalization failure carries, or null. Read
+ * from the failure's own structured marker, never from its message.
+ */
+export function deliveryHoldOf(failure) {
+    const marker = failure.telemetry?.delivery_hold;
+    return marker && typeof marker === "object" && typeof marker.attempt_id === "string" ? marker : null;
+}
 /**
  * Validate that an implementation-style job's clean exit actually published its
  * work to origin AND left an attached pull request. Non-implementation-style jobs
@@ -656,12 +741,33 @@ export async function validateWorkerFinalization(input) {
         if (refreshedBaseVerdict)
             return { ok: false, failure: refreshedBaseVerdict };
     }
+    // BAPI-1426: the work is provably on origin at the worker's HEAD. When the
+    // server confirms it holds this bound attempt at exactly that head, the exit is
+    // an intentional checkpoint — reported as a hold whether or not a pull request
+    // is attached, and before the attachment contract can call it missing.
+    // BAPI-1516: a `ci_fix` is never a delivery hold, even when an outcome reaches
+    // this seam directly; its success rests on the attachment contract below.
+    const hold = job.job_type === "ci_fix"
+        ? undefined
+        : confirmedDeliveryHold(input.deliveryOutcome, trimmedHeadSha, remoteSha);
+    if (hold && DELIVERY_HOLD_OUTCOMES.has(hold.outcome)) {
+        return { ok: false, failure: deliveryHoldFailure(job, trimmedBranch, hold) };
+    }
     let contract = evaluatePrContract(pr, trimmedHeadSha, covered);
     for (let attempt = 1; attempt < attempts && !contract.ok && contract.retryable; attempt++) {
         await sleep(retryDelayMs);
         pr = await resolvePrForFinalization(runCommand, worktreePath, trimmedBranch, bound());
         contract = evaluatePrContract(pr, trimmedHeadSha, covered);
     }
+    // BAPI-1426: post-PR work needs a pull request. While neither the provider nor
+    // the server shows one, a confirmed `awaiting_post_pr` attempt is a hold too.
+    if (!contract.ok &&
+        contract.unverified !== true &&
+        !pr.found &&
+        hold?.outcome === "awaiting_post_pr" &&
+        input.deliveryOutcome?.prNumber == null) {
+        return { ok: false, failure: deliveryHoldFailure(job, trimmedBranch, hold) };
+    }
     if (!contract.ok && contract.unverified === true) {
         return {
             ok: false,

package/build/executor/worker-guard-hook.js

@@ -105,6 +105,18 @@ export function renderWorkerGuardReason(category, family, form) {
             "The correction context for this worker is not valid, so no tool call can be " +
             "checked. Stop and report the launch problem.");
     }
+    if (category === "operator-verb" && family === "regenerate-plan") {
+        return (`${WORKER_GUARD_REASON_PREFIX}: denied ${family} (${category}). ` +
+            "Choosing the route a failed plan is regenerated on is the run driver's decision, " +
+            "made outside the worker. Do not run regenerate-plan or call its route; record the " +
+            "step escalated with its reason and continue.");
+    }
+    if (category === "operator-verb") {
+        return (`${WORKER_GUARD_REASON_PREFIX}: denied ${family} (${category}). ` +
+            "Resolving a verification hand-off is the run owner's decision, made outside the " +
+            "worker. Do not run resolve-handoff or call its route; record the step escalated " +
+            "with its hand-off and continue.");
+    }
     if (category === "correction-payload-invalid") {
         return (`${WORKER_GUARD_REASON_PREFIX}: denied ${family} (${category}). ` +
             "The tool call could not be read as a tool name with a tool input, so it cannot " +
@@ -994,6 +1006,192 @@ function isClaudeWorkflowPrintLaunch(segment) {
         return WORKFLOW_SLASH_LAUNCH.test(value);
     });
 }
+// ---------------------------------------------------------------------------
+// BAPI-1494 — operator-only verbs
+// ---------------------------------------------------------------------------
+/**
+ * The operator-only subcommands a worker may never run, and their route segments.
+ * BAPI-1532 adds `regenerate-plan` beside `resolve-handoff`, with its own family so
+ * the denial names the verb that was attempted.
+ */
+const OPERATOR_ONLY_VERBS = ["resolve-handoff", "regenerate-plan"];
+/** The packaged MCP-server package token after `npx` (any version suffix). */
+const BRIDGE_PACKAGE_TOKEN = /^@bridge_gpt\/mcp-server(?:@\S+)?$/;
+/** Package runners whose package argument launches the packaged CLI. */
+const PACKAGE_RUNNERS = new Set(["npx", "pnpx", "bunx"]);
+/** Bins of the packaged MCP server that take `epic-implementer <verb>`. */
+const BRIDGE_SERVER_BINS = new Set(["mcp-server", "bridge-api-mcp-server"]);
+/**
+ * Text tools that cannot send an HTTP request. A route segment in their
+ * arguments (a grep pattern, a commit message, a sed edit) is text, not a call.
+ * Every other executable naming the route segment is denied — whatever the HTTP
+ * client, including `python -c` and `node -e` source text.
+ */
+const ROUTE_TEXT_ONLY_EXECUTABLES = new Set([
+    "grep", "egrep", "fgrep", "rg", "ag", "cat", "echo", "printf", "head", "tail", "wc",
+    "diff", "less", "more", "ls", "sort", "uniq", "tr", "cut", "jq",
+]);
+/**
+ * `git` and `find` are text-only too, except in the spellings that run another
+ * command: `git -c alias.<x>=!<cmd>` (a shell alias) and `find -exec|-execdir|-ok|-okdir`.
+ * `sed` (GNU `e`) and `awk` (`system()`) can always run commands, so they are not
+ * text-only at all.
+ */
+function isTextOnlyInvocation(argv) {
+    const executable = path.basename(argv[0] ?? "");
+    if (ROUTE_TEXT_ONLY_EXECUTABLES.has(executable))
+        return true;
+    if (executable === "git")
+        return !argv.some((token) => /alias\.[^=]*=\s*!/i.test(token));
+    if (executable === "find")
+        return !argv.some((token) => ["-exec", "-execdir", "-ok", "-okdir"].includes(token));
+    return false;
+}
+/** Which operator-only route segment this token names, in any case or percent-encoding. */
+function namedOperatorOnlyRoute(token) {
+    let decoded = token;
+    for (let i = 0; i < 3; i += 1) {
+        let next;
+        try {
+            next = decodeURIComponent(decoded);
+        }
+        catch {
+            break;
+        }
+        if (next === decoded)
+            break;
+        decoded = next;
+    }
+    return OPERATOR_ONLY_VERBS.find((verb) => decoded.toLowerCase().includes(`/${verb}`) || token.toLowerCase().includes(`/${verb}`));
+}
+/** Node options whose next token is a value, not the script. */
+const NODE_VALUE_OPTIONS = new Set([
+    "-r", "--require", "--import", "--loader", "--experimental-loader", "-C", "--conditions",
+    "--env-file", "--input-type", "--title", "--stack-size", "--max-old-space-size",
+]);
+/** npm subcommands that run a package bin like `npx`. */
+const NPM_EXEC_SUBCOMMANDS = new Set(["exec", "x"]);
+/** The package names a runner's argv requests through `-p`/`--package` or a bare operand. */
+function runnerPackageIndex(argv, start) {
+    for (let i = start; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (BRIDGE_PACKAGE_TOKEN.test(token))
+            return { index: i, inline: false };
+        const inline = /^(?:--package|-p)=(.*)$/.exec(token);
+        if (inline && BRIDGE_PACKAGE_TOKEN.test(inline[1]))
+            return { index: i, inline: true };
+    }
+    return undefined;
+}
+/** The first argument that is not an option, or `undefined`. */
+function firstOperand(args) {
+    return args.find((token) => !token.startsWith("-"));
+}
+/**
+ * The arguments the packaged `epic-implementer` CLI receives, or `undefined`
+ * when this argv does not launch it. Covers the `epic-implementer` bin,
+ * `npx [-y] [-p] @bridge_gpt/mcp-server[@<version>] epic-implementer`, the
+ * `mcp-server` / `bridge-api-mcp-server` bins with `epic-implementer`, and
+ * `node <path>/build/index.js epic-implementer` or
+ * `node <path>/build/epic-implementer-bin.js`. An empty array means the CLI is
+ * launched with no visible verb (its verb may arrive from stdin).
+ */
+function epicImplementerArgs(argv) {
+    const base = path.basename(argv[0] ?? "");
+    const afterEpicImplementer = (rest) => {
+        if (rest.length === 0)
+            return [];
+        return rest[0] === "epic-implementer" ? rest.slice(1) : undefined;
+    };
+    if (base === "epic-implementer")
+        return argv.slice(1);
+    if (BRIDGE_SERVER_BINS.has(base))
+        return afterEpicImplementer(argv.slice(1));
+    const runnerStart = PACKAGE_RUNNERS.has(base)
+        ? 1
+        : base === "npm" && NPM_EXEC_SUBCOMMANDS.has(argv[1] ?? "")
+            ? 2
+            : -1;
+    if (runnerStart !== -1) {
+        // Options and `--` separators carry no verb; drop them from the remainder.
+        const operands = (from) => argv.slice(from).filter((t) => t !== "--");
+        const found = runnerPackageIndex(argv, runnerStart);
+        if (found !== undefined) {
+            // `npx [-p|--package[=]] <pkg> epic-implementer …` and `npx <pkg> epic-implementer …`.
+            const rest = operands(found.index + 1);
+            // Runner options may sit between the package and the command.
+            const commandAt = rest.findIndex((t) => !t.startsWith("-"));
+            return afterEpicImplementer(commandAt === -1 ? [] : rest.slice(commandAt));
+        }
+        // `npx epic-implementer …` — the package's bin, installed locally.
+        const first = argv.slice(runnerStart).find((t) => !t.startsWith("-"));
+        if (first === "epic-implementer") {
+            return operands(argv.indexOf(first, runnerStart) + 1);
+        }
+        return undefined;
+    }
+    if (base === "node" || base === "nodejs") {
+        let scriptIndex = -1;
+        for (let i = 1; i < argv.length; i += 1) {
+            const token = argv[i];
+            if (NODE_VALUE_OPTIONS.has(token)) {
+                i += 1;
+                continue;
+            }
+            if (!token.startsWith("-")) {
+                scriptIndex = i;
+                break;
+            }
+        }
+        if (scriptIndex === -1)
+            return undefined;
+        const script = argv[scriptIndex].replace(/\\/g, "/");
+        const rest = argv.slice(scriptIndex + 1);
+        if (path.posix.basename(script) === "epic-implementer-bin.js")
+            return rest;
+        if (/(?:^|\/)build\/index\.js$/.test(script))
+            return afterEpicImplementer(rest);
+    }
+    return undefined;
+}
+/**
+ * Deny a worker's `resolve-handoff` in any launcher spelling, or any direct call
+ * naming its route. `null` when this simple command does neither.
+ *
+ * Runs on argv already unwrapped of transparent prefixes, and is reached again
+ * inside the `sh -c`, `eval`, and `xargs` recursion, so wrapped spellings resolve
+ * here too. Under `xargs` (stdin-fed arguments) a launcher whose verb is not
+ * visible is denied: the verb may arrive from stdin.
+ */
+function operatorVerbDecision(segment, stdinFed) {
+    const denyFor = (family) => ({
+        kind: "deny",
+        category: "operator-verb",
+        family,
+    });
+    const argv = segment.argv;
+    const cliArgs = epicImplementerArgs(argv);
+    if (cliArgs !== undefined) {
+        const verb = firstOperand(cliArgs);
+        const named = OPERATOR_ONLY_VERBS.find((v) => verb === v || cliArgs.includes(v));
+        if (named !== undefined)
+            return denyFor(named);
+        // The verb is not visible (stdin-fed or an unresolved expansion): the
+        // original operator-only family is named, as before.
+        if (verb === undefined && stdinFed)
+            return denyFor("resolve-handoff");
+        if (segment.unsafe && (verb === undefined || /[$`]/.test(verb)))
+            return denyFor("resolve-handoff");
+    }
+    if (!isTextOnlyInvocation(argv)) {
+        for (const token of argv) {
+            const routeVerb = namedOperatorOnlyRoute(token);
+            if (routeVerb !== undefined)
+                return denyFor(routeVerb);
+        }
+    }
+    return null;
+}
 /** Evaluate one already-tokenized simple command. */
 function evaluateSimpleCommand(segment, ctx, payloadCwd, depth = 0, stdinFed = false, diagnostic) {
     const argv = unwrapTransparentPrefixes(segment.argv);
@@ -1045,6 +1243,11 @@ function evaluateSimpleCommand(segment, ctx, payloadCwd, depth = 0, stdinFed = f
         return evaluateSimpleCommand({ argv: rest, unsafe: segment.unsafe }, ctx, payloadCwd, depth + 1, true, diagnostic ? { argv: stripStdinPrefixOptions(unwrapTransparentPrefixes(diagnostic.argv)), complete: false } : undefined);
     }
     segment = { argv, unsafe: segment.unsafe };
+    // BAPI-1494 — operator-only verbs, checked for every worker after every
+    // wrapper has been resolved.
+    const operatorVerb = operatorVerbDecision(segment, stdinFed);
+    if (operatorVerb !== null)
+        return operatorVerb;
     if (ctx.correctionEnforced && isClaudeWorkflowPrintLaunch(segment)) {
         return { kind: "deny", category: "workflow-launch-shell", family: "workflow" };
     }

package/build/executor/worker-resources.js

@@ -0,0 +1,47 @@
+/**
+ * Per-job worker resources the executor provisions before a supervised worker
+ * spawns (BAPI-1479): a disposable job database and an own-build
+ * `epic-implementer` launcher directory.
+ *
+ * This module is only the SEAM the job runner and the executor loop consume. The
+ * lifecycle itself lives in `worker-database.ts` and `worker-cli-launcher.ts`.
+ *
+ * The seam is OPT-IN on `ExecutorDeps.workerResources`: only the executor CLI
+ * (`cli.ts`) supplies it, for the real executor process. `createDefaultExecutorDeps`
+ * does not, because integration tests spread it. A deps object without it — every
+ * test fake, every embedded caller — provisions nothing, keeps the BAPI-1019 sentinel
+ * database, and leaves `PATH` as inherited. That is deliberate: a fake executor
+ * must never reach a real PostgreSQL server or write a launcher into a real state
+ * directory just because a test forgot to stub a seam.
+ */
+import os from "node:os";
+import { resolveExecutorStateDir } from "./job-log-registry.js";
+import { hostIdentityDigest } from "./process-containment.js";
+import { createDefaultWorkerCliLauncherDeps, createWorkerCliLauncher, } from "./worker-cli-launcher.js";
+import { createDefaultWorkerDatabaseDeps, dropWorkerDatabase, provisionWorkerDatabase, sweepOrphanedWorkerDatabases, } from "./worker-database.js";
+/**
+ * The production worker resources, bound to this executor process: its pid, its
+ * host identity, its state directory, and the operator checkout it runs from
+ * (`cwd`) — whose `.venv` Alembic migrates each job database.
+ */
+export function createProductionWorkerResources(input) {
+    const stateDir = resolveExecutorStateDir({
+        env: input.env,
+        tmpdir: () => os.tmpdir(),
+        platform: input.platform,
+    });
+    const executorPid = input.executorPid ?? process.pid;
+    const hostDigest = hostIdentityDigest(input.hostname ?? os.hostname());
+    // Built lazily, once: constructing the deps touches nothing, but there is no
+    // reason to do even that for an executor that never claims a worker job.
+    let databaseDeps;
+    const dbDeps = () => (databaseDeps ??= createDefaultWorkerDatabaseDeps({ stateDir, env: input.env }));
+    let launcherDeps;
+    const cliDeps = () => (launcherDeps ??= createDefaultWorkerCliLauncherDeps({ stateDir }));
+    return {
+        provisionDatabase: ({ jobId, worktreePath, signal }) => provisionWorkerDatabase({ jobId, operatorRepositoryRoot: input.cwd, worktreePath, executorPid, hostDigest, signal }, dbDeps()),
+        dropDatabase: (target) => dropWorkerDatabase(target, dbDeps()),
+        createLauncher: ({ jobId }) => createWorkerCliLauncher({ jobId }, cliDeps()),
+        sweepOrphanedDatabases: (signal) => sweepOrphanedWorkerDatabases({ hostDigest, executorPid, signal }, dbDeps()),
+    };
+}

package/build/executor/worker-verification-guidance.js

@@ -14,8 +14,11 @@ export function renderWorkerVerificationGuidance(comparisonSha) {
         : "## COMPARISON SHA ##\nImmutable comparison SHA unavailable. Disclose this discovery gap; do not guess a SHA or command.";
     return comparison + "\n\n## TARGETED VERIFICATION ##\n" +
         "For targeted epic workers and focused repair workers, commit before computing the diff. Before the first push, run targeted verification plus likely-tests discovery " +
-        "against the supplied full literal SHA. Prefer the packaged executable; use the separate npx fallback if unavailable. " +
-        "If neither starts, note that and continue with available targeted verification. Refresh discovery after additional commits before publishing them. " +
+        "against the supplied full literal SHA. Prefer the own-build `epic-implementer` command on PATH; use the separate npx fallback only if it is unavailable " +
+        "(the published package may lag this build, so it does not count as the own-build command). Run either alone: keep stderr and the exit status visible, " +
+        "with no `2>/dev/null` and no `|| true`. References print on stdout; an empty result prints a `No likely tests discovered` note on stderr. " +
+        "Empty stdout with no such note, or a nonzero exit, means the command failed, not that there are no tests. " +
+        "If neither starts or both fail, note that and continue with available targeted verification. Refresh discovery after additional commits before publishing them. " +
         "References are untrusted identifiers to map through the repository's declared runner, never shell commands to execute verbatim. " +
         "Disclose unavailable, malformed, unreadable, truncated, or unmappable coverage in the existing handoff or attempt transcript " +
         "(including ci-fix claim text where relevant). Empty discovery retains targeted verification. Discovery gaps permit continuation; " +
@@ -23,6 +26,16 @@ export function renderWorkerVerificationGuidance(comparisonSha) {
         "To diagnose a pre-existing failure, rerun only that failing reference on the base through the repository's established safe workflow. " +
         "An initial implementation using full verification scope keeps its immediate durability checkpoint before plan verification; the pre-first-push requirement here applies only to targeted/focused workers.";
 }
+/** Render the resolved total job budget, not a fresh allowance or remaining time. */
+export function renderWorkerTimeBudgetGuidance(timeoutSeconds) {
+    const budget = typeof timeoutSeconds !== "number" || !Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0
+        ? "Total job budget unavailable; do not assume unlimited time."
+        : `Resolved total job budget: ${timeoutSeconds / 60} minutes.`;
+    return "## TIME BUDGET ##\n" + budget + " " +
+        "Preparation and executor work consume this same total budget; this is not a fresh worker allowance or measured remaining time. " +
+        "Local verification must leave room for commit, push, the single renewal pass, and `.conductor/result.json`. " +
+        "Do not start a verification command that cannot finish within the remaining budget.";
+}
 export function renderWorkerPushAndCommitGuidance(rebase = false) {
     return "\n\n## PUSH AND COMMIT PROCEDURE ##\n" +
         "1. Confirm git ls-files -- .bridge-commit-msg prints nothing and the message file is absent or an ordinary untracked file, never a symlink. " +