@remogram/core 0.1.0-beta.6 → 0.1.0-beta.9

package/forge-changes-cursor.js

@@ -0,0 +1,88 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { parseSinceObservedAt } from './forge-changes.js';
+
+export const FORGE_CHANGES_CURSOR_VERSION = 1;
+export const DEFAULT_FORGE_CHANGES_PAGE_SIZE = 64;
+
+/**
+ * @param {{ since: string, offset: number }} state
+ * @returns {string}
+ */
+export function encodeForgeChangesCursor(state) {
+  const since = parseSinceObservedAt(state.since);
+  const offset = Number(state.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw Object.assign(new Error('Invalid forge changes cursor offset'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, 'cursor offset must be a non-negative integer'),
+    });
+  }
+  const payload = JSON.stringify({ v: FORGE_CHANGES_CURSOR_VERSION, since, offset });
+  return Buffer.from(payload, 'utf8').toString('base64url');
+}
+
+/**
+ * @param {unknown} raw
+ * @param {{ since?: string }} [opts]
+ * @returns {{ since: string, offset: number }}
+ */
+export function decodeForgeChangesCursor(raw, opts = {}) {
+  if (raw == null || raw === '') {
+    throw Object.assign(new Error('Missing forge changes cursor'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor must not be empty when provided'),
+    });
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(Buffer.from(String(raw), 'base64url').toString('utf8'));
+  } catch {
+    throw Object.assign(new Error('Invalid forge changes cursor'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor is malformed or not base64url JSON'),
+    });
+  }
+  if (decoded?.v !== FORGE_CHANGES_CURSOR_VERSION) {
+    throw Object.assign(new Error('Invalid forge changes cursor version'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor version is unsupported'),
+    });
+  }
+  const since = parseSinceObservedAt(decoded.since);
+  const offset = Number(decoded.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw Object.assign(new Error('Invalid forge changes cursor offset'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor offset must be a non-negative integer'),
+    });
+  }
+  if (opts.since != null && opts.since !== '') {
+    const requestedSince = parseSinceObservedAt(opts.since);
+    if (requestedSince !== since) {
+      throw Object.assign(new Error('Forge changes cursor since mismatch'), {
+        forgeError: forgeError(
+          ERROR_CODES.INVALID_ARGS,
+          '--since must match the cursor since when both are provided',
+        ),
+      });
+    }
+  }
+  return { since, offset };
+}
+
+/**
+ * @param {object} body
+ * @param {{ offset?: number, limit?: number }} [opts]
+ */
+export function paginateForgeChangesBody(body, opts = {}) {
+  const offset = opts.offset ?? 0;
+  const limit = opts.limit ?? DEFAULT_FORGE_CHANGES_PAGE_SIZE;
+  const allEvents = Array.isArray(body.events) ? body.events : [];
+  const pageEvents = allEvents.slice(offset, offset + limit);
+  const observedEnd = offset + pageEvents.length;
+  const hasMore = observedEnd < allEvents.length || body.events_truncated === true;
+  return {
+    ...body,
+    events: pageEvents,
+    has_more: hasMore,
+    complete: !hasMore,
+    ...(hasMore
+      ? { next_cursor: encodeForgeChangesCursor({ since: body.since, offset: observedEnd }) }
+      : {}),
+  };
+}

package/forge-changes.js

@@ -72,7 +72,7 @@ export function buildChecksConclusionObservedEvent(prNumber, checksBody) {
   return {
     kind: FORGE_CHANGE_EVENT_KINDS.CHECKS_CONCLUSION_OBSERVED,
     pr_number: Math.floor(Number(prNumber)),
-    head_sha: sanitizeField(checksBody?.head_sha ?? '') || null,
+    forge_source_sha: sanitizeField(checksBody?.forge_source_sha ?? '') || null,
     check_conclusion: sanitizeField(checksBody?.check_conclusion ?? '') || 'unknown',
     checks_truncated: Boolean(checksBody?.checks_truncated ?? false),
   };
@@ -171,7 +171,7 @@ export function buildForgeChangesFromGiteaPulls(sinceIso, pullsArray, opts = {})
           kind: FORGE_CHANGE_EVENT_KINDS.HEAD_SHA_MOVED,
           ...base,
           state: 'open',
-          head_sha: sanitizeField(pull.head?.sha ?? '') || null,
+          forge_source_sha: sanitizeField(pull.head?.sha ?? '') || null,
           updated_at: normalizeIsoTimestamp(updatedAt),
         });
       }

package/forge-identity.js

@@ -0,0 +1,42 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/**
+ * Canonical forge origin (scheme + host + port) from configured baseUrl.
+ * Config-derived trusted identity — not forge-sourced.
+ *
+ * @param {{ baseUrl?: string }} config
+ * @returns {string | null}
+ */
+export function normalizedForgeOrigin(config) {
+  if (!config?.baseUrl) return null;
+  let url;
+  try {
+    url = new URL(config.baseUrl);
+  } catch {
+    throw Object.assign(new Error('Invalid baseUrl'), {
+      forgeError: forgeError(ERROR_CODES.CONFIG_INVALID, 'Invalid baseUrl in .remogram.json'),
+    });
+  }
+  if (url.username || url.password) {
+    throw Object.assign(new Error('baseUrl must not contain userinfo'), {
+      forgeError: forgeError(ERROR_CODES.CONFIG_INVALID, 'baseUrl must not contain userinfo'),
+    });
+  }
+  if (url.pathname && url.pathname !== '/') {
+    throw Object.assign(new Error('baseUrl must be a forge origin'), {
+      forgeError: forgeError(
+        ERROR_CODES.CONFIG_INVALID,
+        'baseUrl must be a forge origin without a path',
+      ),
+    });
+  }
+  if (url.search || url.hash) {
+    throw Object.assign(new Error('baseUrl must be a forge origin'), {
+      forgeError: forgeError(
+        ERROR_CODES.CONFIG_INVALID,
+        'baseUrl must be a forge origin without query or fragment',
+      ),
+    });
+  }
+  return url.origin;
+}

package/idempotency.js

@@ -0,0 +1,69 @@
+import { createHash } from 'node:crypto';
+import { sanitizeField } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+/** @type {Map<string, string>} */
+const scopeBindings = new Map();
+
+export function resetIdempotencyScopeBindings() {
+  scopeBindings.clear();
+}
+
+export function normalizeIdempotencyKey(value) {
+  if (value == null || value === '') return null;
+  const key = sanitizeField(String(value).trim());
+  if (!key || !KEY_PATTERN.test(key)) {
+    throw Object.assign(new Error('Invalid idempotency key'), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        'idempotency key must be 1-128 characters from [A-Za-z0-9._:-]',
+      ),
+    });
+  }
+  return key;
+}
+
+export function idempotencyFingerprint(key, scopeParts = []) {
+  const normalizedKey = normalizeIdempotencyKey(key);
+  if (!normalizedKey) return null;
+  const scope = scopeParts.map((part) => sanitizeField(String(part ?? ''))).join('\0');
+  return createHash('sha256').update(`${normalizedKey}\0${scope}`).digest('hex').slice(0, 16);
+}
+
+export function idempotencyScopeKey(repoId, key) {
+  const normalizedKey = normalizeIdempotencyKey(key);
+  if (!normalizedKey) return null;
+  return `${sanitizeField(repoId)}:${normalizedKey}`;
+}
+
+export function bindIdempotencyScope(repoId, key, scopeParts) {
+  const normalizedKey = normalizeIdempotencyKey(key);
+  if (!normalizedKey) return null;
+  const bindingKey = idempotencyScopeKey(repoId, normalizedKey);
+  const serialized = JSON.stringify(scopeParts.map((part) => sanitizeField(String(part ?? ''))));
+  const prior = scopeBindings.get(bindingKey);
+  if (prior && prior !== serialized) {
+    throw Object.assign(new Error('Idempotency key scope conflict'), {
+      forgeError: forgeError(
+        ERROR_CODES.IDEMPOTENCY_CONFLICT,
+        'idempotency key was already used with a different write scope',
+      ),
+    });
+  }
+  scopeBindings.set(bindingKey, serialized);
+  return idempotencyFingerprint(normalizedKey, scopeParts);
+}
+
+export function idempotencyPacketFields(fingerprint, { reusedExisting = false, ambiguousAfterWrite = false } = {}) {
+  const fields = {};
+  if (fingerprint) fields.idempotency_fingerprint = fingerprint;
+  if (reusedExisting) {
+    fields.reused_existing = true;
+  } else {
+    fields.created = true;
+  }
+  if (ambiguousAfterWrite) fields.ambiguous_after_write = true;
+  return fields;
+}

package/index.js

@@ -52,6 +52,11 @@ export { assertGitRef, assertGitRemote } from './git-args.js';
 export { gitRevParse, gitCurrentBranch, gitAheadBehind, gitRepoRoot, gitDiffNameOnly } from './git-local.js';
 export { buildRefInventoryBody, refsInventory } from './ref-inventory.js';
 export { buildCrInventoryEntry, buildHeadReconcile, crInventory, DEFAULT_CR_INVENTORY_LIMIT, DEFAULT_CR_INVENTORY_SAFE_LIMIT, normalizeCrInventoryLimit } from './cr-inventory.js';
+export {
+  CR_INVENTORY_CURSOR_VERSION,
+  decodeCrInventoryCursor,
+  encodeCrInventoryCursor,
+} from './cr-inventory-cursor.js';
 export {
   CR_INVENTORY_SLICE_SORTS,
   DEFAULT_CR_INVENTORY_SLICE_SORT,
@@ -75,6 +80,18 @@ export {
   appendSortQuery,
 } from './open-pull-list.js';
 export { buildChangeRequestOpenedBody } from './cr-open.js';
+export { buildIssueOpenedBody, parseIssueOpenArgs } from './issue-open.js';
+export {
+  assertExpectedSha,
+  mergeExecuteViewFacts,
+  mergeExecuteChecksFacts,
+  buildMergeExecuteBeforeFacts,
+  collectMergeExecuteBlockers,
+  buildCrMergeBlockedBody,
+  buildCrMergedBody,
+  buildMergeExecuteAfterFacts,
+  buildMergeExecuteMergeFacts,
+} from './change-request-merge-execute.js';
 export {
   STATUS_SET_STATES,
   assertCommitSha,
@@ -104,6 +121,11 @@ export {
   MAX_BRANCH_PROTECTION_STATUS_CONTEXTS,
   MAX_BRANCH_PROTECTION_RULES,
 } from './branch-protection.js';
+export {
+  enrichCheckStatus,
+  buildCheckDiagnostics,
+  buildPrChecksBody,
+} from './check-diagnostics.js';
 export {
   buildCrFilesBody,
   buildCrFilesFromGiteaFiles,
@@ -126,6 +148,13 @@ export {
   MAX_FORGE_CHANGES_EVENTS,
   FORGE_CHANGE_EVENT_KINDS,
 } from './forge-changes.js';
+export {
+  encodeForgeChangesCursor,
+  decodeForgeChangesCursor,
+  paginateForgeChangesBody,
+  FORGE_CHANGES_CURSOR_VERSION,
+  DEFAULT_FORGE_CHANGES_PAGE_SIZE,
+} from './forge-changes-cursor.js';
 export {
   WRITE_COMMAND_IDS,
   CONFIGURED_WRITE_COMMANDS,
@@ -134,6 +163,29 @@ export {
   writeNotConfiguredMessage,
   isWriteCommandConfigured,
 } from './write-config.js';
+export {
+  buildWriteReadiness,
+  writeReadinessHasWarnings,
+} from './write-readiness.js';
+export {
+  buildApiReachabilityCheck,
+  classifyReachabilityFailure,
+  LIVE_REACHABILITY_TIMEOUT_MS,
+} from './provider-health.js';
+export {
+  bindIdempotencyScope,
+  idempotencyFingerprint,
+  idempotencyPacketFields,
+  normalizeIdempotencyKey,
+  resetIdempotencyScopeBindings,
+} from './idempotency.js';
+export {
+  resolveMergePolicy,
+  parseTruthyEnv,
+  mergePolicyAuditFacts,
+  ALLOW_MISSING_CHECKS_ENV,
+  ALLOW_PENDING_CHECKS_ENV,
+} from './merge-policy.js';
 export { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';
 export {
   applyForgePathScopeForMergePlan,
@@ -166,6 +218,7 @@ export {
   throwIfStaleHeadByNumber,
 } from './pr-head-reconcile.js';
 export { parseConfigFile, configSchema } from './config-schema.js';
+export { normalizedForgeOrigin } from './forge-identity.js';
 export {
   findConfigPath,
   loadConfig,

package/issue-open.js

@@ -0,0 +1,50 @@
+import { sanitizeField, sanitizeUrl } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/** Normalize Gitea issue create response into issue_opened body fields. */
+export function buildIssueOpenedBody(
+  issue,
+  { title },
+  { reusedExisting = false, idempotencyFields = null } = {},
+) {
+  const issueNumber = Number(issue?.number);
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+    throw Object.assign(new Error('Provider returned invalid issue number'), {
+      forgeError: forgeError(
+        ERROR_CODES.UNPARSEABLE_PROVIDER_OUTPUT,
+        'Provider returned invalid issue number',
+      ),
+    });
+  }
+  const resolvedTitle = reusedExisting
+    ? sanitizeField(issue?.title ?? title)
+    : sanitizeField(title ?? issue?.title);
+  const body = {
+    issue_number: issueNumber,
+    url: sanitizeUrl(issue.html_url ?? issue.url),
+    state: sanitizeField(String(issue?.state ?? 'open').toLowerCase()),
+    title: resolvedTitle,
+  };
+  if (reusedExisting) {
+    body.reused_existing = true;
+  } else {
+    body.created = true;
+  }
+  if (idempotencyFields && typeof idempotencyFields === 'object') {
+    Object.assign(body, idempotencyFields);
+  }
+  return body;
+}
+
+export function parseIssueOpenArgs({ title, body: issueBody }) {
+  if (title == null || String(title).trim() === '') {
+    throw Object.assign(new Error('--title required'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--title required for issue open'),
+    });
+  }
+  const parsed = { title: sanitizeField(String(title)) };
+  if (issueBody != null && String(issueBody).trim() !== '') {
+    parsed.body = sanitizeField(String(issueBody));
+  }
+  return parsed;
+}

package/merge-blockers.js

@@ -1,5 +1,25 @@
 import { allPathsAllowed, normalizeChangedPathList } from './path-allowlist.js';
 
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+
+function diagnosticBlockers(checks) {
+  const blockers = [];
+  const missing = checks.missing_required_contexts;
+  if (Array.isArray(missing) && missing.length > 0) blockers.push('required_checks_missing');
+  const stale = checks.stale_contexts;
+  if (Array.isArray(stale) && stale.length > 0) blockers.push('stale_status_context');
+  const required = new Set(
+    Array.isArray(checks.required_contexts) ? checks.required_contexts.filter(Boolean) : [],
+  );
+  if (required.size > 0 && Array.isArray(checks.pending_contexts)) {
+    const pendingRequired = checks.pending_contexts.filter((context) => required.has(context));
+    if (pendingRequired.length > 0) blockers.push('required_checks_pending');
+  }
+  return uniqueSorted(blockers);
+}
+
 /**
  * Derive merge blockers from already-fetched PR view and checks facts.
  * Shared by merge plan and cr inventory aggregation.
@@ -13,14 +33,19 @@ export function isOpenPrState(state) {
  * @param {object} checks
  * @param {{ allowed_paths?: string[], changed_paths?: string[] | null }} [pathScope]
  */
-export function mergeBlockersFromFacts(view, checks, pathScope = {}) {
+export function mergeBlockersFromFacts(view, checks, pathScope = {}, policy = {}) {
   const blockers = [];
   if (view.mergeability === 'conflicted') blockers.push('merge_conflict');
   if (!isOpenPrState(view.state)) blockers.push('pr_not_open');
   if (checks.checks_truncated === true) blockers.push('checks_incomplete');
   if (checks.check_conclusion === 'failure') blockers.push('checks_failed');
-  if (checks.check_conclusion === 'missing') blockers.push('checks_missing');
-  if (checks.check_conclusion === 'pending') blockers.push('checks_pending');
+  if (checks.check_conclusion === 'missing' && !policy.allow_missing_checks) {
+    blockers.push('checks_missing');
+  }
+  if (checks.check_conclusion === 'pending' && !policy.allow_pending_checks) {
+    blockers.push('checks_pending');
+  }
+  blockers.push(...diagnosticBlockers(checks));
 
   const allowedPaths = pathScope.allowed_paths;
   if (Array.isArray(allowedPaths) && allowedPaths.length > 0) {

package/merge-plan-forge.js

@@ -58,5 +58,6 @@ export async function buildMergePlanFromProviderFacts(ctx, opts, deps) {
   const mergeOpts = await resolveMergePlanOptsWithForgePaths(opts, () =>
     deps.crFiles(ctx, { number: view.pr_number }),
   );
-  return buildMergePlanBodyFromFacts(view, checks, mergeOpts);
+  const mergePolicy = opts.merge_policy ?? ctx.mergePolicy ?? {};
+  return buildMergePlanBodyFromFacts(view, checks, { ...mergeOpts, merge_policy: mergePolicy });
 }

package/merge-plan.js

@@ -61,16 +61,22 @@ export function resolveMergePlanPathScope(opts = {}) {
   return { allowed_paths: allowedPaths, changed_paths: null };
 }
 
-export function buildMergePlanBody(view, checks, pathScope = {}) {
+export function buildMergePlanBody(view, checks, pathScope = {}, policy = {}) {
   return {
     pr_number: view.pr_number,
     mergeability: view.mergeability,
     checks_conclusion: checks.check_conclusion,
-    blockers: mergeBlockersFromFacts(view, checks, pathScope),
+    required_contexts: checks.required_contexts ?? [],
+    missing_required_contexts: checks.missing_required_contexts ?? [],
+    failed_contexts: checks.failed_contexts ?? [],
+    pending_contexts: checks.pending_contexts ?? [],
+    stale_contexts: checks.stale_contexts ?? [],
+    blockers: mergeBlockersFromFacts(view, checks, pathScope, policy),
   };
 }
 
 export function buildMergePlanBodyFromFacts(view, checks, opts = {}) {
   const pathScope = resolveMergePlanPathScope(opts);
-  return buildMergePlanBody(view, checks, pathScope);
+  const policy = opts.merge_policy ?? {};
+  return buildMergePlanBody(view, checks, pathScope, policy);
 }

package/merge-policy.js

@@ -0,0 +1,55 @@
+export const ALLOW_MISSING_CHECKS_ENV = 'REMOGRAM_ALLOW_MISSING_CHECKS';
+export const ALLOW_PENDING_CHECKS_ENV = 'REMOGRAM_ALLOW_PENDING_CHECKS';
+
+/** @returns {boolean | null} true/false when recognized; null when unset/invalid */
+export function parseTruthyEnv(value) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+  return null;
+}
+
+function resolvePolicyFlag(configValue, envName) {
+  const envRaw = process.env[envName];
+  if (envRaw != null && envRaw !== '') {
+    const parsed = parseTruthyEnv(envRaw);
+    if (parsed === true) {
+      return { value: true, source: 'env' };
+    }
+  }
+  if (configValue === true) {
+    return { value: true, source: 'config' };
+  }
+  return { value: false, source: 'default' };
+}
+
+/**
+ * Resolved merge policy for blocker derivation (forge-facts layer only).
+ * @param {object | null | undefined} config consumer .remogram.json
+ */
+export function resolveMergePolicy(config) {
+  const filePolicy = config?.merge_policy ?? {};
+  const missing = resolvePolicyFlag(filePolicy.allow_missing_checks, ALLOW_MISSING_CHECKS_ENV);
+  const pending = resolvePolicyFlag(filePolicy.allow_pending_checks, ALLOW_PENDING_CHECKS_ENV);
+  return {
+    allow_missing_checks: missing.value,
+    allow_pending_checks: pending.value,
+    source: {
+      allow_missing_checks: missing.source,
+      allow_pending_checks: pending.source,
+    },
+  };
+}
+
+/** Observational snapshot for merge execute before facts. */
+export function mergePolicyAuditFacts(mergePolicy) {
+  if (!mergePolicy) return null;
+  return {
+    allow_missing_checks: mergePolicy.allow_missing_checks === true,
+    allow_pending_checks: mergePolicy.allow_pending_checks === true,
+    source: mergePolicy.source ?? {
+      allow_missing_checks: 'default',
+      allow_pending_checks: 'default',
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remogram/core",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.9",
   "description": "Remogram forge envelope, config, caps, and HTTP utilities",
   "type": "module",
   "license": "MIT",

package/pr-head-reconcile.js

@@ -3,7 +3,7 @@ import { ERROR_CODES, forgeError } from './contracts/errors.js';
 import { gitRevParse } from './git-local.js';
 
 export const STALE_HEAD_MESSAGE =
-  'Forge PR head SHA diverges from locally resolved git; fetch or refresh before trusting head_sha';
+  'Forge PR head SHA diverges from locally resolved git; fetch or refresh before trusting forge_source_sha';
 
 export function localHeadShaForPr(cwd, remoteName, headRef) {
   if (!headRef) return null;
@@ -18,8 +18,8 @@ export function staleHeadDetails(cwd, remoteName, headRef, forgeHeadSha) {
   if (!localHeadSha) return null;
   if (localHeadSha.toLowerCase() === String(forgeHeadSha).toLowerCase()) return null;
   return {
-    head_ref: headRef,
-    head_sha: forgeHeadSha,
+    forge_source_branch_ref: headRef,
+    forge_source_sha: forgeHeadSha,
     local_head_sha: localHeadSha,
   };
 }

package/provider-health.js

@@ -0,0 +1,93 @@
+import { ERROR_CODES } from './contracts/errors.js';
+import { sanitizeField } from './caps.js';
+
+const LIVE_REACHABILITY_TIMEOUT_MS = 5000;
+
+export { LIVE_REACHABILITY_TIMEOUT_MS };
+
+export function classifyReachabilityFailure(err) {
+  const code = err?.forgeError?.code;
+  const status = err?.status ?? err?.forgeError?.status ?? null;
+  let causeCode = null;
+  for (let current = err; current; current = current.cause) {
+    if (current.code) {
+      causeCode = current.code;
+      break;
+    }
+  }
+  const message = String(err?.forgeError?.message ?? err?.message ?? '');
+
+  if (code === ERROR_CODES.UNAUTHENTICATED_PROVIDER) return 'auth_missing';
+  if (code === ERROR_CODES.OVERSIZED_RAW_OUTPUT) return 'oversized_raw_output';
+  if (status === 401 || /401/.test(message)) return 'http_401';
+  if (status === 404 || /not found/i.test(message)) return 'repo_not_found';
+  if (status >= 300 && status < 400) return 'redirect_rejected';
+  if (/redirect rejected/i.test(message)) return 'redirect_rejected';
+  if (causeCode === 'ECONNREFUSED') return 'connection_refused';
+  if (causeCode === 'ENOTFOUND' || causeCode === 'EAI_AGAIN') return 'network_unreachable';
+  if (causeCode === 'ECONNRESET' || causeCode === 'ENETUNREACH') return 'network_unreachable';
+  if (err?.name === 'TimeoutError' || causeCode === 'ETIMEDOUT' || /timed out/i.test(message)) {
+    return 'timeout';
+  }
+  return 'network_unreachable';
+}
+
+export function doctorReachabilityCheck(name, status, message, details = null) {
+  return {
+    name,
+    status,
+    message: sanitizeField(message),
+    ...(details ? { details } : {}),
+  };
+}
+
+/**
+ * @param {object} ctx
+ * @param {object | undefined} provider
+ * @param {{ live?: boolean, prerequisitesPass?: boolean }} [opts]
+ */
+export async function buildApiReachabilityCheck(ctx, provider, opts = {}) {
+  const { live = false, prerequisitesPass = false } = opts;
+  if (!live) {
+    return doctorReachabilityCheck(
+      'api_reachability',
+      'skipped',
+      'Live API reachability is not checked by default',
+    );
+  }
+  if (!prerequisitesPass) {
+    return doctorReachabilityCheck(
+      'api_reachability',
+      'fail',
+      'Live reachability requires valid config and trusted host binding',
+      { failure_kind: 'prerequisites_failed' },
+    );
+  }
+  if (typeof provider?.apiReachability !== 'function') {
+    return doctorReachabilityCheck(
+      'api_reachability',
+      'warn',
+      'Provider does not implement live API reachability',
+      { failure_kind: 'not_implemented' },
+    );
+  }
+  try {
+    const facts = await provider.apiReachability(ctx);
+    return doctorReachabilityCheck(
+      'api_reachability',
+      'pass',
+      'Forge API is reachable',
+      { repo_accessible: true, ...(facts && typeof facts === 'object' ? facts : {}) },
+    );
+  } catch (err) {
+    return doctorReachabilityCheck(
+      'api_reachability',
+      'fail',
+      err.forgeError?.message || err.message || 'Forge API reachability check failed',
+      {
+        failure_kind: classifyReachabilityFailure(err),
+        ...(err.status != null ? { http_status: err.status } : {}),
+      },
+    );
+  }
+}

package/ref-inventory.js

@@ -53,8 +53,8 @@ function buildAncestryHints(cwd, defaultRef, refs) {
 
   return [
     {
-      base_ref: sanitizeField(defaultRef),
-      head_ref: sanitizeField(headBranch),
+      compare_base_ref: sanitizeField(defaultRef),
+      compare_head_ref: sanitizeField(headBranch),
       ahead_by: counts.ahead_by,
       behind_by: counts.behind_by,
     },

package/resolve.js

@@ -3,6 +3,8 @@ import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { parseConfigFile } from './config-schema.js';
 import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { normalizedForgeOrigin } from './forge-identity.js';
+import { resolveMergePolicy } from './merge-policy.js';
 import { assertGitRemote } from './git-args.js';
 import { gitRepoRoot } from './git-local.js';
 
@@ -145,8 +147,10 @@ export function forgeContext(loaded) {
     providerId: config.provider,
     remoteName: config.remote,
     repoId: `${parsed.owner}/${parsed.repo}`,
+    baseUrl: normalizedForgeOrigin(config),
     config,
     cwd: loaded.cwd,
     parsed,
+    mergePolicy: resolveMergePolicy(config),
   };
 }

package/status-set.js

@@ -64,7 +64,7 @@ export function parseStatusSetArgs({ sha, context, state, target_url, descriptio
 export function buildCommitStatusSetBody(
   response,
   args,
-  { reusedExisting = false } = {},
+  { reusedExisting = false, idempotencyFields = null } = {},
 ) {
   const state = normalizeStatusSetState(response?.status ?? response?.state ?? args.state);
   const body = {
@@ -82,6 +82,11 @@ export function buildCommitStatusSetBody(
   }
   if (reusedExisting) {
     body.reused_existing = true;
+  } else {
+    body.created = true;
+  }
+  if (idempotencyFields && typeof idempotencyFields === 'object') {
+    Object.assign(body, idempotencyFields);
   }
   return body;
 }