create-walle 0.10.1 → 0.10.3

package/template/coding-task-manager/lib/landing/sync.js

@@ -0,0 +1,456 @@
+'use strict';
+// WP-1 (docs/fleet-origin-main-sync-skill-2026-10-31.html §5 R-1..R-5/R-7/R-9, §6.1-§6.3, §8 WP-1,
+// §9 S-3/S-4/S-6/S-7): `land sync` — the ONE command that pulls origin, trains + gates when the box
+// has diverged, pushes, and (WP-2) schedules the idle restart.
+//
+// The state machine is exactly §6.3, with the local branch `landing/origin-main` as the train's
+// source (§5 R-1) so the queue needs no new source kind:
+//
+//   fetch(remote, branch) -> O                       (no-prompt env, below)
+//   O == main                       -> in_sync
+//   O is an ancestor of main        -> push main                                -> pushed
+//   main is an ancestor of O        -> CAS main := O, schedule restart          -> pulled
+//   diverged                        -> update-ref landing/origin-main O
+//                                      enqueue an ordinary queue job kind:"sync" (the existing train
+//                                      merges it into main, regenerates/refreshes, gates and
+//                                      CAS-moves main), then push the landed sha  -> published
+//
+// A rejected push is a CAS miss, not a failure (§5 R-4): non-fast-forward / fetch-first re-enters the
+// machine at step 1, bounded by `publish.maxRetrains` extra trains; anything else is `publish_failed`
+// with git's stderr verbatim and is never retried.
+//
+// HARD RULES (§5 R-3, §6.3, house rule "NO TEST/DEV RUN MAY START A GITHUB/CLAUDE LOGIN"): every git
+// child that talks to the remote runs the scrubbed landing env PLUS GIT_TERMINAL_PROMPT=0,
+// GCM_INTERACTIVE=never and GIT_SSH_COMMAND="ssh -o BatchMode=yes"; nothing here ever passes
+// --force, --force-with-lease, --no-verify or a rebase.
+//
+// The push for a `kind:"sync"` job is performed by the RUNNER (`finishSyncJob`), not by the CLI: the
+// job that lands is the job that publishes, so the CLI's `land sync` and the R-9 auto-publish after an
+// ordinary landing share one code path (`syncOnce` + `finishSyncJob`).
+
+const path = require('path');
+const fsp = require('fs/promises');
+const { landingError, childEnv, runGitRaw } = require('./git');
+const { readJsonSafe, writeJsonAtomic } = require('./state');
+
+const CONTRACT = 1;
+const SYNC_STATE_FILE = 'sync-state.json';
+// §6.3: the local branch origin/main is materialised as, so the train consumes a plain local branch.
+const ORIGIN_BRANCH = 'landing/origin-main';
+// §6.1 defaults. The publish block is only ever present when the repository asked for it.
+const DEFAULT_REMOTE = 'origin';
+const DEFAULT_BRANCH = 'main';
+const DEFAULT_MAX_RETRAINS = 3;
+
+// §6.3: the no-prompt env. Layered on top of the landing scrub by `childEnv`, so the GIT_* incident
+// list stays scrubbed and these three can never be forgotten at a call site.
+const NO_PROMPT_ENV = Object.freeze({
+  GIT_TERMINAL_PROMPT: '0',
+  GCM_INTERACTIVE: 'never',
+  GIT_SSH_COMMAND: 'ssh -o BatchMode=yes',
+});
+
+function noPromptEnv(extra) {
+  return childEnv({ ...NO_PROMPT_ENV, ...(extra || {}) });
+}
+
+// The one injected git runner: `(args, extraEnv) -> { status, stdout, stderr }`. Every remote child
+// goes through it, which is what makes the state machine testable without a network.
+function gitRunner(cwd) {
+  return (args, extraEnv) => runGitRaw(cwd, args, { env: noPromptEnv(extraEnv) });
+}
+
+function remoteRef(remote, branch) {
+  return `refs/remotes/${remote}/${branch}`;
+}
+
+function originBranchRef() {
+  return `refs/heads/${ORIGIN_BRANCH}`;
+}
+
+function targetRef(target) {
+  return `refs/heads/${target}`;
+}
+
+// --- sync state (§6.2 `land status` origin.lastSync, §6.3 atomic writes) -------------------------
+
+function syncStatePath(common) {
+  return path.join(common, 'landing', SYNC_STATE_FILE);
+}
+
+function readSyncState(common) {
+  const data = readJsonSafe(syncStatePath(common));
+  return data && typeof data === 'object' ? data : null;
+}
+
+// Atomic tmp+rename like every other landing state file (state.writeJsonAtomic stamps `contract: 1`).
+function writeSyncState(common, patch) {
+  const before = readSyncState(common) || {};
+  const next = { ...before, ...patch };
+  writeJsonAtomic(syncStatePath(common), next);
+  return next;
+}
+
+// §6.2: `lastSync` is the verdict a reader shows on the Machines card — the verdict, when it was
+// reached, and the attempt count when the push had to re-train.
+function recordSyncVerdict(common, verdict, extra = {}) {
+  const at = new Date().toISOString();
+  return writeSyncState(common, { lastSync: { verdict, at, ...extra } });
+}
+
+// --- git primitives over the injected runner ------------------------------------------------------
+
+function revParseVia(runGit, rev) {
+  const res = runGit(['rev-parse', '--verify', '--quiet', rev]);
+  return res.status === 0 ? (res.stdout.trim() || null) : null;
+}
+
+function isAncestorVia(runGit, ancestor, descendant) {
+  const res = runGit(['merge-base', '--is-ancestor', ancestor, descendant]);
+  if (res.status === 0) return true;
+  if (res.status === 1) return false;
+  throw landingError('git_failed', `git merge-base --is-ancestor ${ancestor} ${descendant} exited ${res.status}: ${String(res.stderr || '').trim()}`, {
+    ancestor, descendant,
+  });
+}
+
+// `git fetch <remote> <branch>`: no `--tags`, no `+` refspec — a failed fetch writes nothing locally.
+function fetchOrigin(runGit, { remote, branch }) {
+  const res = runGit(['fetch', '--prune', remote, branch]);
+  return { ok: res.status === 0, status: res.status, stderr: String(res.stderr || '').trim() };
+}
+
+// §5 R-3/R-4: a plain fast-forward push of exactly `sha`. Porcelain is used so the flag column says
+// WHY a ref was rejected. Every wording that means "the ref moved under us" is a CAS MISS — the same
+// condition as a non-fast-forward, and the trigger for one more train:
+//   `! [rejected] ... (non-fast-forward)` / `(fetch first)` / `(stale info)` — the smart-transport
+//   wordings, and `cannot lock ref ... is at X but expected Y`, which is what a filesystem/`file://`
+//   remote reports for the very same race.
+const CAS_MISS = /non-fast-forward|fetch first|stale info|\[rejected\]|cannot lock ref/i;
+
+function classifyPush(res) {
+  if (res.status === 0) {
+    // `=` is porcelain's "up to date" flag: nothing was transferred, origin already held the sha.
+    const text = String(res.stdout || '');
+    if (/^\s*=\s/m.test(text) && !/^\s*[+*!]\s/m.test(text)) return 'up_to_date';
+    return 'ok';
+  }
+  const text = `${res.stdout || ''}\n${res.stderr || ''}`;
+  if (CAS_MISS.test(text)) return 'rejected';
+  return 'failed';
+}
+
+function pushMain(runGit, { remote, branch, sha }) {
+  const res = runGit(['push', '--porcelain', remote, `${sha}:refs/heads/${branch}`]);
+  let outcome = classifyPush(res);
+  // git words a lost race differently across versions and transports (2.54 local: "cannot lock ref",
+  // 2.50 local: only "failed to push some refs"; smart HTTP/ssh: "[rejected] (fetch first)"), so the
+  // wording is a hint, never the decision. The decision is the fact: re-fetch, and if `sha` is no
+  // longer a fast-forward of the remote tip, origin moved under us — a CAS miss (§5 R-4). If it still
+  // IS a fast-forward, the push failed for another reason (auth, network, a hook) and stays failed.
+  if (outcome === 'failed') {
+    const refetched = fetchOrigin(runGit, { remote, branch });
+    const tip = refetched.ok ? revParseVia(runGit, remoteRef(remote, branch)) : null;
+    if (tip && tip !== sha && !isAncestorVia(runGit, tip, sha)) outcome = 'rejected';
+  }
+  return {
+    outcome,
+    status: res.status,
+    stdout: String(res.stdout || '').trim(),
+    stderr: String(res.stderr || '').trim(),
+  };
+}
+
+// §5 R-1/§6.3: origin/main is materialised as the local branch the train consumes. Only ever called
+// on the diverged path — the two ancestor cases are decided before this.
+function materializeOrigin(runGit, { remote, branch }) {
+  const tip = revParseVia(runGit, remoteRef(remote, branch));
+  if (!tip) {
+    throw landingError('origin_ref_missing', `cannot resolve ${remoteRef(remote, branch)} after fetching ${remote}/${branch}`, { remote, branch });
+  }
+  const res = runGit(['update-ref', originBranchRef(), tip]);
+  if (res.status !== 0) {
+    throw landingError('git_failed', `git update-ref ${originBranchRef()} ${tip} exited ${res.status}: ${String(res.stderr || '').trim()}`, { tip });
+  }
+  return tip;
+}
+
+// §5 R-2/R-5: a pull is a pure fast-forward of main and nothing else, through the SAME ref-move path
+// the runner uses for a landing (`train.landTrain`: `git merge --ff-only` when the target is checked
+// out, a CAS `update-ref` otherwise). LAND_ALLOW_MANUAL=1 is the ref guard's sanctioned fast-forward
+// path (§7 E-1 rule (b)) — it still refuses a rewind, so this can never move main backwards.
+function defaultMoveTarget(cwd, { target, to, from }) {
+  const train = require('./train');
+  const result = train.landTrain(cwd, target, to, from, { env: { LAND_ALLOW_MANUAL: '1' } });
+  return { sha: result.sha, via: result.via };
+}
+
+// --- WP-2 hook -----------------------------------------------------------------------------------
+
+// §5 R-7 / §8 WP-2b: every move of main whose new tip differs from the running build schedules
+// `bin/fleet-apply.js --local <to>` to wait for the restart guard's idle verdict, restart without
+// force and confirm readyz. The SCHEDULER (and every refusal guard) lives in lib/fleet-update.js,
+// which is the only place that knows how a box launches its own helper; this module only knows WHEN
+// a move happened.
+//
+// `syncedRepoRoot` is the MAIN worktree of the repository the sync ran in (the git common dir's
+// parent, resolved). fleet-update refuses to act unless it is the very repository that ships that
+// fleet-apply.js, so a sync in a scratch/test repository can never restart a real CTM.
+async function scheduleRestartAfterMove({ from, to, syncedRepoRoot = null }) {
+  if (!to || to === from) return { spawned: false, reason: 'no_move' };
+  const fleetUpdate = require('../fleet-update');
+  return fleetUpdate.scheduleLocalApply({ to, syncedRepoRoot });
+}
+
+// The main worktree of the repository whose common dir this is: `<top>/.git` for the main checkout,
+// and the main checkout's `.git` for every linked worktree. Unreadable ⇒ `null`, which fleet-update
+// reads as "not the repository I ship in" (never a spawn).
+async function syncedRepoRootOf(common) {
+  if (!common) return null;
+  try {
+    return path.dirname(await fsp.realpath(common));
+  } catch (error) {
+    /* expected: an unreadable common dir means "cannot prove this is my own repository" — the
+       scheduler then refuses (reason `foreign_repo`) instead of spawning against a guess */
+    return null;
+  }
+}
+
+// §8 WP-2b: the restart is best-effort by contract — `land sync` already did the work that matters
+// (main moved, or origin caught up), so a scheduler that throws is reported in the verdict, never
+// turned into a failed sync.
+async function scheduleRestartForTip({ from, to, common }) {
+  try {
+    return (await scheduleRestartAfterMove({ from, to, syncedRepoRoot: await syncedRepoRootOf(common) })) || null;
+  } catch (error) {
+    return { spawned: false, reason: `scheduler_error: ${error.message}` };
+  }
+}
+
+// --- the state machine (§6.3) --------------------------------------------------------------------
+
+function publishOf(config) {
+  const publish = config && config.publish;
+  if (!publish) return null;
+  return {
+    remote: publish.remote || DEFAULT_REMOTE,
+    branch: publish.branch || DEFAULT_BRANCH,
+    maxRetrains: Number.isInteger(publish.maxRetrains) ? publish.maxRetrains : DEFAULT_MAX_RETRAINS,
+  };
+}
+
+function result(verdict, extra = {}) {
+  return { contract: CONTRACT, verdict, ...extra };
+}
+
+// Exit codes (§6.2): 0 ok · 1 typed refusal/failure. `in_sync`, `pulled`, `pushed` and `published`
+// are the ok verdicts; everything else is a refusal the caller must read.
+function exitCodeForVerdict(verdict) {
+  return verdict === 'in_sync' || verdict === 'pulled' || verdict === 'pushed' || verdict === 'published' ? 0 : 1;
+}
+
+// The full §6.3 machine.
+//
+// deps:
+//   cwd, common                  repository paths (common = the git common dir)
+//   config                       the VALIDATED landing config (`config.publish` present)
+//   pullOnly                     §6.2 `land sync --pull-only`: never merges and never pushes
+//   runGit(args, env)            injected git runner (default: no-prompt git in `cwd`)
+//   moveTarget({to, from})       the CAS/ff ref move (default: train.landTrain with LAND_ALLOW_MANUAL)
+//   runTrain({tip, attempt})     enqueue the `kind:"sync"` train job; resolves to
+//                                { jobId, state, reason, sync, waited } — `waited: false` means the
+//                                caller only enqueued (the runner itself, which cannot block on its
+//                                own queue).
+async function syncOnce(deps) {
+  const publish = publishOf(deps.config);
+  if (!publish) {
+    throw landingError('sync_not_configured', `no landing.publish block in ${(deps.config && deps.config.configDir) || deps.cwd}/.ctm.json; land sync is off for this repository`, {
+      configDir: (deps.config && deps.config.configDir) || deps.cwd,
+    });
+  }
+  const runGit = deps.runGit || gitRunner(deps.cwd);
+  const moveTarget = deps.moveTarget || ((args) => defaultMoveTarget(deps.cwd, args));
+  const target = deps.config.target;
+  const { remote, branch, maxRetrains } = publish;
+  const pullOnly = Boolean(deps.pullOnly);
+  let retrains = 0;
+  const attempts = [];
+
+  for (;;) {
+    const fetched = fetchOrigin(runGit, { remote, branch });
+    writeSyncState(deps.common, { fetchedAt: new Date().toISOString() });
+    if (!fetched.ok) {
+      return result('publish_failed', {
+        remote, branch, attempts: retrains + 1,
+        error: { code: 'fetch_failed', message: fetched.stderr || `git fetch ${remote} ${branch} exited ${fetched.status}` },
+        stderr: fetched.stderr,
+      });
+    }
+    const originTip = revParseVia(runGit, remoteRef(remote, branch));
+    if (!originTip) {
+      return result('publish_failed', {
+        remote, branch, attempts: retrains + 1,
+        error: { code: 'origin_ref_missing', message: `cannot resolve ${remoteRef(remote, branch)} after fetching ${remote}/${branch}` },
+      });
+    }
+    const mainTip = revParseVia(runGit, targetRef(target));
+    if (!mainTip) {
+      return result('publish_failed', {
+        remote, branch, attempts: retrains + 1,
+        error: { code: 'target_missing', message: `${targetRef(target)} does not exist` },
+      });
+    }
+
+    // 2. already level with origin.
+    if (originTip === mainTip) return result('in_sync', { remote, branch, tip: mainTip, attempts: retrains + 1 });
+
+    // 4. local-only commits: publish them (a fast-forward push; nothing to pull and nothing to gate).
+    if (isAncestorVia(runGit, originTip, mainTip)) {
+      if (pullOnly) return result('ahead', { remote, branch, hint: 'land sync', attempts: retrains + 1 });
+      const push = pushMain(runGit, { remote, branch, sha: mainTip });
+      if (push.outcome === 'ok') return result('pushed', { remote, branch, tip: mainTip, attempts: retrains + 1 });
+      if (push.outcome === 'rejected') {
+        retrains += 1;
+        if (retrains > maxRetrains) return result('publish_contended', { remote, branch, attempts: retrains, stderr: push.stderr });
+        continue; // §5 R-4: origin moved between our fetch and our push — fetch again and redo step 1
+      }
+      return result('publish_failed', {
+        remote, branch, attempts: retrains + 1, stderr: push.stderr,
+        error: { code: 'push_failed', message: push.stderr || `git push ${remote} exited ${push.status}` },
+      });
+    }
+
+    // 3. behind-only: the origin tip is a commit some box's train gated, so it is a fast-forward —
+    // no train, no gate (§5 R-5 / D-4).
+    if (isAncestorVia(runGit, mainTip, originTip)) {
+      let moved;
+      try {
+        moved = moveTarget({ target, to: originTip, from: mainTip });
+      } catch (error) {
+        return result('publish_failed', {
+          remote, branch, attempts: retrains + 1, error: { code: error.code || 'git_failed', message: error.message },
+        });
+      }
+      // §8 WP-2b: main moved — this box converges onto the sha it just pulled.
+      const restart = await scheduleRestartForTip({ from: mainTip, to: moved.sha || originTip, common: deps.common });
+      return result('pulled', { remote, branch, tip: moved.sha || originTip, from: mainTip, restart, attempts: retrains + 1 });
+    }
+
+    // 5. diverged: only a true divergence builds a train.
+    if (pullOnly) return result('diverged', { remote, branch, hint: 'land sync', attempts: retrains + 1 });
+
+    let tip;
+    try {
+      tip = materializeOrigin(runGit, { remote, branch });
+    } catch (error) {
+      return result('publish_failed', {
+        remote, branch, attempts: retrains + 1, error: { code: error.code || 'git_failed', message: error.message },
+      });
+    }
+    let attempt = retrains + 1;
+    // The train job lands and then publishes itself (`finishSyncJob` writes `job.sync.verdict`). A
+    // rejected push makes that job write `retraining` + a `retryJobId`, which the CLI follows here —
+    // one train per attempt, bounded by `publish.maxRetrains` extra trains on the runner side.
+    let trained = await deps.runTrain({ tip, attempt });
+    for (;;) {
+      attempts.push({ attempt, jobId: trained.jobId, state: trained.state, verdict: trained.sync ? trained.sync.verdict : null });
+      if (trained.waited === false) {
+        // The runner enqueued its own train and cannot block on it: the push happens when that job
+        // lands (§5 R-9). One job per attempt, never a second one from here.
+        return result('publishing', { remote, branch, jobId: trained.jobId, attempts: attempt, attemptsDetail: attempts });
+      }
+      if (trained.state !== 'landed') {
+        const verdict = trained.state === 'blocked' || trained.reason === 'conflict' ? 'conflict' : 'gate_failed';
+        return result(verdict, { remote, branch, jobId: trained.jobId, reason: trained.reason, attempts: attempt, attemptsDetail: attempts });
+      }
+      const verdict = trained.sync ? trained.sync.verdict : null;
+      const stderr = (trained.sync && trained.sync.stderr) || '';
+      if (verdict === 'published' || verdict === 'pushed') {
+        // §8 WP-2b: the train that published also moved main — the runner recorded the restart
+        // outcome on the job (`finishSyncJob`), and the verdict carries it to the caller.
+        return result('published', {
+          remote, branch, jobId: trained.jobId, tip: (trained.sync && trained.sync.tip) || null,
+          restart: (trained.sync && trained.sync.restart) || null, attempts: attempt, attemptsDetail: attempts,
+        });
+      }
+      if (verdict === 'in_sync' || verdict === 'up_to_date') {
+        return result('in_sync', { remote, branch, jobId: trained.jobId, attempts: attempt, attemptsDetail: attempts });
+      }
+      if (verdict === 'publish_contended') {
+        return result('publish_contended', { remote, branch, jobId: trained.jobId, attempts: attempt, stderr, attemptsDetail: attempts });
+      }
+      if (verdict === 'publish_failed') {
+        return result('publish_failed', {
+          remote, branch, jobId: trained.jobId, attempts: attempt, stderr,
+          error: { code: 'push_failed', message: stderr || 'push failed' },
+          attemptsDetail: attempts,
+        });
+      }
+      if (verdict === 'retraining' && trained.sync.retryJobId) {
+        attempt += 1;
+        trained = await deps.followRetry(trained.sync.retryJobId);
+        continue;
+      }
+      // A landed sync job always carries a verdict; anything else means the runner died between the
+      // landing and the push — reported as a failure, never as a silent success.
+      return result('publish_failed', {
+        remote, branch, jobId: trained.jobId, attempts: attempt,
+        error: { code: 'sync_verdict_missing', message: 'the sync job landed but recorded no push verdict' },
+      });
+    }
+  }
+}
+
+// §6.2: `origin: { ahead, behind, fetchedAt, lastSync }` for `land status`. Read-only, and a
+// repository without the publish block (or without the tracking ref) reports nulls rather than
+// failing the status verb.
+function originStatus({ runGit, target, config, common }) {
+  const publish = publishOf(config);
+  const state = readSyncState(common) || {};
+  const base = { ahead: null, behind: null, fetchedAt: state.fetchedAt || null, lastSync: state.lastSync || null };
+  if (!publish) return base;
+  const ref = remoteRef(publish.remote, publish.branch);
+  const mainTip = revParseVia(runGit, targetRef(target));
+  const originTip = revParseVia(runGit, ref);
+  if (!mainTip || !originTip) return { ...base, ahead: null, behind: null };
+  const res = runGit(['rev-list', '--left-right', '--count', `${mainTip}...${originTip}`]);
+  if (res.status !== 0) return base;
+  const [ahead, behind] = String(res.stdout).trim().split(/\s+/).map((value) => Number(value));
+  return {
+    ...base,
+    ahead: Number.isFinite(ahead) ? ahead : null,
+    behind: Number.isFinite(behind) ? behind : null,
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  SYNC_STATE_FILE,
+  ORIGIN_BRANCH,
+  NO_PROMPT_ENV,
+  DEFAULT_REMOTE,
+  DEFAULT_BRANCH,
+  DEFAULT_MAX_RETRAINS,
+  noPromptEnv,
+  gitRunner,
+  remoteRef,
+  originBranchRef,
+  targetRef,
+  syncStatePath,
+  readSyncState,
+  writeSyncState,
+  recordSyncVerdict,
+  revParseVia,
+  isAncestorVia,
+  fetchOrigin,
+  classifyPush,
+  pushMain,
+  materializeOrigin,
+  defaultMoveTarget,
+  scheduleRestartAfterMove,
+  scheduleRestartForTip,
+  publishOf,
+  exitCodeForVerdict,
+  syncOnce,
+  originStatus,
+};