gowalk-cicd 1.0.140 → 1.0.142

package/CLAUDE.md

@@ -27,7 +27,7 @@ gowalk-cicd/                     ← repo root IS the gowalk-cicd package
 │   └── scripts/*.py
 ├── bin/cli.mjs                  ← CLI entrypoint (parses flags, calls runInstall)
 ├── src/install.mjs              ← copy logic, gitignore-check, summary print
-├── templates/deploy.yml         ← dual-platform workflow copied verbatim
+├── templates/deploy.yml         ← managed dual-platform workflow template
 ├── templates/deploy-web.yml     ← Flutter web workflow copied conditionally
 ├── backend-action/              ← backend deploy action + remote host script
 ├── templates/deploy-backend.yml ← backend workflow copied when compose exists
@@ -81,8 +81,8 @@ mkdir /tmp/scratch && cd /tmp/scratch && git init
 node /path/to/gowalk-cicd/bin/cli.mjs --dry-run
 ```
 
-Or install into a real app repo (overwrites both action directories and
-`.github/workflows/deploy.yml`):
+Or install into a real app repo after `npm install` in this source checkout
+(updates action directories and renders workflows from `.gowalk-cicd.yml`):
 
 ```bash
 cd ~/path/to/app-project
@@ -91,8 +91,12 @@ node /path/to/gowalk-cicd/bin/cli.mjs
 
 ## Conventions
 
-- Use Node's built-in `fs`/`path`/`url` modules; no runtime deps except
-  `update-notifier` for the nag banner.
+- Prefer Node built-ins. `yaml` parses and edits app configuration/workflows during installation;
+  `update-notifier` supplies the optional update banner. Neither adds an app CI job.
+- `.gowalk-cicd.yml` owns app settings and workflow extensions. The generated workflow digests
+  and template baselines live in `.gowalk-cicd.lock.json`. Plan all migrations before any writes;
+  never overwrite a conflicting app customization. See `docs/CONFIGURATION.md`.
+  Refresh `templates/history.json.gz` with `node scripts/build-workflow-history.mjs` when templates change.
 - Never hardcode paths — use `fileURLToPath(import.meta.url)` and derive
   from `__dirname`.
 - Keep the CLI surface minimal: `--dry-run`, `-v`, `-h`. Resist adding flags.
@@ -103,6 +107,9 @@ node /path/to/gowalk-cicd/bin/cli.mjs
   `test/env-keys.test.mjs` scans the templates and actions. Set lower-case spellings
   or clear a lower-case bypass through `play_store_proxy.py -- <command>` (child
   process) or `play_store_proxy.py --github-env` (later steps), never through YAML.
+- Composite action steps cannot use workflow-only `timeout-minutes`. Native cache restores
+  retain their segment timeout and the caller's job deadline; workflow-level cache steps
+  can retain their two-minute step limits. `test/composite-timeouts.test.mjs` guards this schema boundary.
 - Store API calls belong in GitHub Actions. Local tests may build/sign but must
   never connect to App Store Connect or Google Play.
 - Every Apple/Google store API call, OAuth exchange and binary upload requires its

package/README.md

@@ -5,6 +5,10 @@ artifacts. It supports native Swift/SwiftUI iOS projects, native Kotlin/Gradle
 Android projects, and Flutter apps. Provision encrypted repository secrets, validate a
 task candidate, and promote its release intent. Store builds and uploads run only in GitHub Actions.
 
+App-specific workflow settings live in `.gowalk-cicd.yml`. The installer migrates supported
+existing settings once and regenerates managed workflows without replacing custom behavior.
+See [configuration and parallel organization upgrades](docs/CONFIGURATION.md).
+
 ## Install
 
 From the root of your app repo:

package/action/.daemux-version

@@ -1 +1 @@
-1.0.140
+1.0.142

package/action/action.yml

@@ -304,7 +304,6 @@ runs:
       if: ${{ steps.native_cache_scope.outputs.key != '' && inputs.candidate-binary == '' }}
       uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25
       continue-on-error: true
-      timeout-minutes: 2
       env:
         NODE_OPTIONS: --require "${{ steps.native_cache_scope.outputs.preloader }}"
         SEGMENT_DOWNLOAD_TIMEOUT_MINS: '1'
@@ -366,7 +365,6 @@ runs:
             && inputs.candidate-binary == '' }}
       uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25
       continue-on-error: true
-      timeout-minutes: 2
       env:
         NODE_OPTIONS: --require "${{ steps.native_cache_scope.outputs.preloader }}"
       with:

package/android-action/.daemux-version

@@ -1 +1 @@
-1.0.140
+1.0.142

package/backend-action/.daemux-version

@@ -1 +1 @@
-1.0.140
+1.0.142

package/bin/cli.mjs

@@ -54,6 +54,8 @@ workflow into the current app project. Flutter web apps also get a release
 artifact workflow. Re-run anytime to update them.
 
 What it writes:
+  .gowalk-cicd.yml            - app-owned settings and custom workflow extensions
+  .gowalk-cicd.lock.json      - generated workflow and template version state
   .github/actions/swift-app/   - vendored composite action (action.yml + scripts/)
   .github/actions/android-app/ - Flutter Android build/sign action
   .github/workflows/deploy.yml - dual-platform workflow
@@ -86,7 +88,14 @@ After install:
 }
 
 const { runInstall } = await import('../src/install.mjs');
-await runInstall({ dryRun });
+try {
+  await runInstall({ dryRun });
+} catch (error) {
+  console.error(JSON.stringify(error.result || {
+    schema: 'gowalk-cicd/migration-repair.v1', code: 'installer_unavailable',
+  }));
+  process.exit(1);
+}
 
 const notifier = await loadNotifier();
 notifier.notify();

package/docs/CONFIGURATION.md

@@ -0,0 +1,86 @@
+# Configuration-preserving upgrades
+
+Run `npx --yes gowalk-cicd@<version>` from the app repository. The first upgrade
+extracts supported settings from existing workflows into `.gowalk-cicd.yml` and
+renders the managed workflows in the same change. Later upgrades read that file.
+The installer does this locally; app CI gains no configuration job or preflight.
+
+```yaml
+schema: 1
+mobile:
+  platforms: ios
+  candidate-artifacts: true
+  ios:
+    project: Forms.xcodeproj
+    workspace: Forms.xcworkspace
+    scheme: Forms
+    configuration: Release
+    firebase-app-id: ${{ vars.FIREBASE_APP_ID }}
+backend:
+  host: ${{ vars.BACKEND_DEPLOY_HOST }}
+  runtime-env: ${{ secrets.BACKEND_RUNTIME_ENV }}
+workflows:
+  deploy.yml:
+    overrides: []
+```
+
+Omitted settings retain the template defaults. The installer initially extracts
+existing variable expressions, so current GitHub variables remain authoritative
+until the app explicitly replaces their references in this file. Keep passwords,
+signing material, tokens and private keys in GitHub Secrets. Reference their names;
+never put their values in this configuration.
+
+The supported managed files are `deploy.yml`, `mobile-candidate.yml`,
+`deploy-web.yml` and `deploy-backend.yml`. App-specific values outside the named
+mobile/backend inputs, and custom jobs or steps embedded in those workflows,
+are retained as sparse `workflows.<file>.overrides` entries. An override identifies
+a YAML path, with `value` or `remove: true`; step paths use stable IDs/names rather
+than numeric positions. These extensions are app-owned configuration, including
+their execution conditions, dependencies and secret references.
+
+Candidate artifacts are enabled automatically for recognized execution. Custom deployment
+commands that the installer cannot establish as candidate-safe retain the normal main
+release build, with `mobile.candidate-artifacts: false`; no candidate store mutation is
+inferred safe from a custom step name. Candidate misses never wait or reserve a machine.
+
+Separate custom workflows remain app-owned. Recognized native dependency jobs
+receive optional lock/toolchain-keyed cache restore/save inside their existing job.
+A validation workflow already cancelling superseded work may coalesce duplicate
+push/PR runs for the same app branch. Its triggers, job names, commands and custom
+checks remain. Separate platforms and repositories keep their existing parallelism.
+
+`.gowalk-cicd.lock.json` records the template and generated-file digests. Commit it
+with the configuration and rendered workflows. It is migration state, not a CI job.
+Edit configuration, then rerun the installer; editing a managed generated workflow
+directly yields `managed_workflow_modified_use_config` without overwriting the edit.
+
+The package carries released template history for versioned three-way migrations.
+An unknown layout or overlapping custom code edit returns a JSON
+`gowalk-cicd/migration-repair.v1` receipt with its code, file and YAML path. The
+receipt never includes the conflicting value. Resolve that specific customization
+in the same repository; unrelated repositories can continue upgrading.
+
+# Organization rollout
+
+Use the script from the exact released package being installed:
+
+```sh
+node /path/to/package/scripts/upgrade-org.mjs \
+  --org gowalk-public --state /durable/cicd-rollout/state.json \
+  --workers 8 --max-active 8
+```
+
+It paginates the organization, discovers actual installed actions, and uses one
+`task/gowalk-cicd-<version>` branch/PR per affected repository. Workers prepare
+independent repositories concurrently. Existing CI remains authoritative; each
+successful candidate merges independently, and any resulting push workflows are
+followed before branch/checkout cleanup. No factory task or Mac reservation is
+created. API throttling and queued CI limit new migration PR publication while
+other local preparation and completed candidates continue.
+
+The state file records repository heads, PR/run URLs, failures and cleanup.
+Restart with the same file and package to resume. `--retry-unresolved` retries
+recorded exceptions after their cause is repaired; `--dry-run` prepares local
+changes without pushing, opening PRs or merging. Use a separate state file for a
+new target version. The final status counts distinguish updated, already-current,
+not-installed and unresolved repositories; an unresolved result exits nonzero.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gowalk-cicd",
-  "version": "1.0.140",
+  "version": "1.0.142",
   "description": "Zero-config GitHub Actions delivery for iOS TestFlight and Android Google Play.",
   "type": "module",
   "bin": {
@@ -22,7 +22,10 @@
     "README.md",
     "CLAUDE.md",
     "docs/GRADLE_CACHE.md",
-    "docs/CANDIDATE_ARTIFACTS.md"
+    "docs/CANDIDATE_ARTIFACTS.md",
+    "scripts/upgrade-org.mjs",
+    "scripts/lib/",
+    "docs/CONFIGURATION.md"
   ],
   "keywords": [
     "ios",
@@ -57,6 +60,7 @@
     "test:ios": "python3 -m unittest discover -s action/scripts -p 'test_*.py'"
   },
   "dependencies": {
-    "update-notifier": "^7.3.1"
+    "update-notifier": "^7.3.1",
+    "yaml": "2.9.0"
   }
 }

package/scripts/lib/checks.mjs

@@ -0,0 +1,73 @@
+import { command, RolloutError } from './github.mjs';
+import { rmSync } from 'node:fs';
+
+export async function checkCandidate(github, repo, options) {
+  const pull = await github.api(`repos/${repo.name}/pulls/${repo.pr}`);
+  if (pull.merged) { repo.merge = pull.merge_commit_sha; repo.status = 'deploy'; return; }
+  if (pull.state !== 'open') throw new RolloutError('migration_pull_request_closed');
+  if (pull.head.sha !== repo.head) throw new RolloutError('migration_pull_request_head_changed');
+  if (pull.mergeable === false) { repo.status = 'update-base'; return; }
+  const runs = await github.pages(`repos/${repo.name}/actions/runs?head_sha=${repo.head}`, 'workflow_runs');
+  const latest = new Map();
+  for (const run of runs.filter(run => ['push', 'pull_request'].includes(run.event))) {
+    const key = run.workflow_id;
+    if (!latest.has(key) || latest.get(key).id < run.id) latest.set(key, run);
+  }
+  const current = [...latest.values()];
+  repo.queued = current.filter(run => ['queued', 'waiting', 'pending'].includes(run.status)).length;
+  repo.runs = current.map(run => ({ id: run.id, status: run.status, conclusion: run.conclusion, url: run.html_url }));
+  const enrolling = !current.length && Date.now() - repo.publishedAt < 60000;
+  if (enrolling || current.some(run => run.status !== 'completed') || pull.mergeable == null) {
+    if (Date.now() - repo.publishedAt > options.ciTimeout) throw new RolloutError('candidate_ci_timeout');
+    repo.nextAt = Date.now() + 30000;
+    return;
+  }
+  if (!current.length) throw new RolloutError('candidate_ci_missing');
+  if (current.some(run => !['success', 'skipped'].includes(run.conclusion))) {
+    throw new RolloutError('candidate_ci_failed');
+  }
+  // GitHub enforces existing required checks and reviews; no admin bypass or new gate is installed.
+  await (github.command || command)('gh', ['pr', 'merge', String(repo.pr), '--repo', repo.name, '--squash',
+    '--match-head-commit', repo.head]);
+  repo.status = 'deploy';
+}
+
+export async function checkDeploy(github, repo, options) {
+  const pull = await github.api(`repos/${repo.name}/pulls/${repo.pr}`);
+  if (!pull.merged || !pull.merge_commit_sha) throw new RolloutError('merge_readback_failed');
+  repo.merge = pull.merge_commit_sha;
+  repo.mergedAt ||= Date.parse(pull.merged_at);
+  const runs = await github.pages(`repos/${repo.name}/actions/runs?head_sha=${repo.merge}`, 'workflow_runs');
+  const current = runs.filter(run => run.event === 'push');
+  repo.deploys = current.map(run => ({
+    id: run.id, status: run.status, conclusion: run.conclusion, url: run.html_url,
+  }));
+  if (Date.now() - repo.mergedAt < 60000 || current.some(run => run.status !== 'completed')) {
+    if (Date.now() - repo.mergedAt > options.ciTimeout) throw new RolloutError('deployment_ci_timeout');
+    repo.nextAt = Date.now() + 30000;
+    return;
+  }
+  if (current.some(run => !['success', 'skipped'].includes(run.conclusion))) {
+    throw new RolloutError('deployment_ci_failed');
+  }
+  repo.status = 'cleanup';
+}
+
+export async function cleanup(github, repo) {
+  const reference = await github.api(`repos/${repo.name}/git/ref/heads/${repo.branch}`, { missing: true });
+  if (reference && reference.object.sha !== repo.head) throw new RolloutError('cleanup_branch_head_changed');
+  if (reference) await github.api(`repos/${repo.name}/git/refs/heads/${repo.branch}`, { method: 'DELETE' });
+  await command('git', ['switch', '--detach', repo.merge], { cwd: repo.directory }).catch(async () => {
+    await command('git', ['fetch', 'origin', repo.defaultBranch], { cwd: repo.directory });
+    await command('git', ['switch', '--detach', repo.merge], { cwd: repo.directory });
+  });
+  const local = await command('git', ['branch', '--list', repo.branch], { cwd: repo.directory });
+  if (local.trim()) await command('git', ['update-ref', '-d', `refs/heads/${repo.branch}`, repo.head], {
+    cwd: repo.directory,
+  });
+  const dirty = (await command('git', ['status', '--porcelain'], { cwd: repo.directory })).trim();
+  if (dirty) throw new RolloutError('cleanup_checkout_dirty');
+  rmSync(repo.directory, { recursive: true });
+  repo.status = 'updated';
+  repo.cleaned = true;
+}

package/scripts/lib/discovery.mjs

@@ -0,0 +1,27 @@
+import { RolloutError } from './github.mjs';
+const installs = /^\.github\/actions\/(swift-app|android-app|backend-app)\/(action\.yml|\.daemux-version)$/;
+
+export async function discover(github, state) {
+  const repositories = await github.pages(`orgs/${state.data.org}/repos?type=all`);
+  for (const repo of repositories) {
+    if (state.data.repositories[repo.full_name]) continue;
+    state.data.repositories[repo.full_name] = {
+      name: repo.full_name, defaultBranch: repo.default_branch, archived: repo.archived,
+      disabled: repo.disabled, writable: repo.permissions?.push === true,
+      status: repo.size ? 'inspect' : 'not-installed',
+    };
+  }
+  state.data.discovered = true;
+  state.save();
+}
+
+export async function inspect(github, repo) {
+  const tree = await github.api(`repos/${repo.name}/git/trees/${encodeURIComponent(repo.defaultBranch)}?recursive=1`);
+  if (tree.truncated) throw new RolloutError('repository_tree_truncated');
+  const installed = tree.tree.some(file => installs.test(file.path));
+  if (!installed) { repo.status = 'not-installed'; return; }
+  repo.installed = true;
+  repo.status = repo.archived || repo.disabled || !repo.writable ? 'unresolved' : 'prepare';
+  if (repo.status === 'unresolved') repo.reason = 'repository_not_writable';
+  repo.tree = tree.sha;
+}

package/scripts/lib/github.mjs

@@ -0,0 +1,85 @@
+// The installed gh credential remains inside gh. Results and failures never include raw CLI stderr.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execute = promisify(execFile);
+export const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+export class RolloutError extends Error {
+  constructor(code, retryAt = null) { super(code); this.code = code; this.retryAt = retryAt; }
+}
+
+export async function command(program, args, options = {}) {
+  try {
+    return (await execute(program, args, {
+      encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, timeout: 180000, ...options,
+    })).stdout;
+  } catch (error) {
+    const failure = new RolloutError(error.killed ? 'command_timeout' : `${program}_command_failed`);
+    const line = String(error.stderr || '').trim().split('\n').at(-1);
+    try {
+      const receipt = JSON.parse(line);
+      if (receipt.schema === 'gowalk-cicd/migration-repair.v1' && /^[a-z_]+$/.test(receipt.code)) {
+        failure.code = receipt.code;
+        failure.result = receipt;
+      }
+    } catch { /* Unknown output remains private. */ }
+    throw failure;
+  }
+}
+
+export class GitHub {
+  constructor() { this.blockedUntil = 0; this.nextRequest = 0; }
+
+  async api(endpoint, { method = 'GET', data, missing = false } = {}) {
+    const now = Date.now();
+    if (this.blockedUntil > now) throw new RolloutError('github_rate_limited', this.blockedUntil);
+    const start = Math.max(now, this.nextRequest);
+    this.nextRequest = start + 150;
+    await delay(start - now);
+    const args = ['api', '--include', '--method', method, endpoint];
+    if (data) args.push('--input', '-');
+    const result = await new Promise(resolve => {
+      const child = execFile('gh', args, { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, timeout: 60000 },
+        (error, stdout) => resolve({ error, stdout }));
+      child.stdin.end(data ? JSON.stringify(data) : undefined);
+    });
+    const response = decodeResponse(result.stdout);
+    if (response.status === 404 && missing) return null;
+    const retry = Number(response.headers['retry-after']);
+    const remaining = Number(response.headers['x-ratelimit-remaining'] ?? 5000);
+    if (response.status === 429 || (response.status === 403 && (retry || remaining === 0))) {
+      this.blockedUntil = retry ? Date.now() + retry * 1000
+        : Number(response.headers['x-ratelimit-reset']) * 1000 + 5000 || Date.now() + 60000;
+      throw new RolloutError('github_rate_limited', this.blockedUntil);
+    }
+    if (result.error || response.status >= 400) {
+      throw new RolloutError(`github_http_${response.status || 'unavailable'}`,
+        response.status >= 500 ? Date.now() + 30000 : null);
+    }
+    return response.body;
+  }
+
+  async pages(endpoint, key = null) {
+    const rows = [];
+    for (let page = 1; ; page++) {
+      const result = await this.api(`${endpoint}${endpoint.includes('?') ? '&' : '?'}per_page=100&page=${page}`);
+      const batch = key ? result[key] : result;
+      if (!Array.isArray(batch)) throw new RolloutError('github_pagination_shape_invalid');
+      rows.push(...batch);
+      if (batch.length < 100) return rows;
+    }
+  }
+}
+
+export function decodeResponse(text) {
+  const split = text.search(/\r?\n\r?\n/);
+  const head = split < 0 ? '' : text.slice(0, split);
+  const lines = head.split(/\r?\n/);
+  const status = Number(lines.shift()?.match(/HTTP\/\S+\s+(\d+)/)?.[1] || 0);
+  const headers = Object.fromEntries(lines.flatMap(line => {
+    const colon = line.indexOf(':');
+    return colon < 0 ? [] : [[line.slice(0, colon).toLowerCase(), line.slice(colon + 1).trim()]];
+  }));
+  let body;
+  try { body = JSON.parse(text.slice(split).trim()); } catch { body = null; }
+  return { status, headers, body };
+}

package/scripts/lib/repository.mjs

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { command, RolloutError } from './github.mjs';
+const git = (cwd, ...args) => command('git', args, { cwd });
+
+export async function checkout(repo, options) {
+  const directory = join(options.workDir, repo.name.split('/')[1]);
+  repo.directory = directory;
+  repo.branch ||= `task/gowalk-cicd-${options.version}`;
+  if (!existsSync(directory)) {
+    mkdirSync(options.workDir, { recursive: true });
+    await command('git', ['clone', '--filter=blob:none', '--no-checkout',
+      `https://github.com/${repo.name}.git`, directory]);
+  }
+  const origin = (await git(directory, 'remote', 'get-url', 'origin')).trim();
+  if (!origin.endsWith(`${repo.name}.git`)) throw new RolloutError('checkout_repository_mismatch');
+  await git(directory, 'fetch', '--prune', 'origin', repo.defaultBranch);
+  await git(directory, 'sparse-checkout', 'set', '--cone', '.github', 'backend', 'server', 'web');
+  const local = (await git(directory, 'branch', '--list', repo.branch)).trim();
+  const remote = (await git(directory, 'ls-remote', '--heads', 'origin', repo.branch)).trim();
+  if (local) await git(directory, 'switch', repo.branch);
+  else if (remote) {
+    await git(directory, 'fetch', 'origin', repo.branch);
+    await git(directory, 'switch', '-c', repo.branch, 'FETCH_HEAD');
+  } else await git(directory, 'switch', '-c', repo.branch, `origin/${repo.defaultBranch}`);
+  repo.base = (await git(directory, 'rev-parse', `origin/${repo.defaultBranch}`)).trim();
+  return directory;
+}
+
+export async function prepare(github, repo, options) {
+  const directory = await checkout(repo, options);
+  const before = (await git(directory, 'status', '--porcelain')).trim();
+  if (before && !repo.preparing) throw new RolloutError('checkout_has_unowned_changes');
+  repo.preparing = true;
+  options.save();
+  await command(process.execPath, [join(options.packageDir, 'bin/cli.mjs')], { cwd: directory });
+  const diff = (await git(directory, 'diff', '--name-only')).trim();
+  const untracked = (await git(directory, 'ls-files', '--others', '--exclude-standard')).trim();
+  const changed = [...new Set((diff + '\n' + untracked).split('\n').filter(Boolean))];
+  if (changed.some(file => !file.startsWith('.github/') && !/^\.gowalk-cicd\.(yml|lock\.json)$/.test(file))) {
+    throw new RolloutError('migration_changed_unowned_file');
+  }
+  if (changed.length) {
+    await git(directory, 'add', '--', ...changed);
+    await git(directory, 'diff', '--cached', '--check');
+    await git(directory, 'commit', '-m', `Upgrade gowalk-cicd to ${options.version}`,
+      '-m', 'Preserve app settings in configuration and adopt supported workflow migrations.');
+  }
+  repo.head = (await git(directory, 'rev-parse', 'HEAD')).trim();
+  repo.preparing = false;
+  const ahead = (await git(directory, 'rev-list', '--count', `origin/${repo.defaultBranch}..HEAD`)).trim();
+  repo.status = ahead === '0' ? 'already-current' : 'publish';
+  if (options.dryRun) repo.status = ahead === '0' ? 'already-current' : 'dry-run';
+  if (repo.status === 'already-current') {
+    rmSync(directory, { recursive: true });
+    repo.cleaned = true;
+  }
+}
+
+export async function publish(github, repo) {
+  await git(repo.directory, 'push', '--set-upstream', 'origin', repo.branch);
+  const pulls = await github.api(`repos/${repo.name}/pulls?state=all&head=${repo.name.split('/')[0]}:${repo.branch}`);
+  let pull = pulls.find(pr => pr.state === 'open');
+  if (!pull) pull = await github.api(`repos/${repo.name}/pulls`, { method: 'POST', data: {
+    title: 'Preserve app configuration during gowalk-cicd upgrades', head: repo.branch, base: repo.defaultBranch,
+    body: 'Upgrade the installed plugin and move app settings into `.gowalk-cicd.yml`. '
+      + 'Generated workflows retain custom checks and secret references; supported caches and candidate reuse '
+      + 'are adopted by the installer. Existing repository CI validates this exact candidate. '
+      + 'No factory tasks, scheduling changes, Mac reservations or additional approval stages are introduced.',
+  } });
+  repo.pr = pull.number;
+  repo.url = pull.html_url;
+  repo.publishedAt = Date.now();
+  repo.status = 'ci';
+}
+
+export async function incorporateBase(repo) {
+  await git(repo.directory, 'fetch', 'origin', repo.defaultBranch);
+  try { await git(repo.directory, 'merge', '--no-edit', `origin/${repo.defaultBranch}`); }
+  catch { throw new RolloutError('migration_branch_conflict'); }
+  repo.status = 'prepare';
+}

package/scripts/lib/state.mjs

@@ -0,0 +1,39 @@
+import {
+  existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, openSync, closeSync, unlinkSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+import { RolloutError } from './github.mjs';
+
+export function openState(path, org, version) {
+  mkdirSync(dirname(path), { recursive: true });
+  const lock = path + '.lock';
+  try { closeSync(openSync(lock, 'wx', 0o600)); }
+  catch {
+    let owner;
+    try { owner = JSON.parse(readFileSync(lock, 'utf8')); } catch { throw new RolloutError('rollout_lock_unreadable'); }
+    try { process.kill(owner.pid, 0); throw new RolloutError('rollout_already_running'); }
+    catch (error) { if (error.code !== 'ESRCH') throw error; }
+    unlinkSync(lock);
+    closeSync(openSync(lock, 'wx', 0o600));
+  }
+  writeFileSync(lock, JSON.stringify({ pid: process.pid }));
+  const data = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : {
+    schema: 1, org, version, repositories: {}, discovered: false,
+  };
+  if (data.schema !== 1 || data.org !== org || data.version !== version) {
+    unlinkSync(lock);
+    throw new RolloutError('rollout_state_target_mismatch');
+  }
+  const save = () => {
+    writeFileSync(path + '.tmp', JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+    renameSync(path + '.tmp', path);
+  };
+  return { data, save, close: () => unlinkSync(lock) };
+}
+
+export function summary(state) {
+  return Object.values(state.repositories).reduce((result, repo) => {
+    result[repo.status] = (result[repo.status] || 0) + 1;
+    return result;
+  }, {});
+}

package/scripts/upgrade-org.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Run from one exact published package. Local workers never claim or reserve factory Macs.
+import { readFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { GitHub, RolloutError, delay } from './lib/github.mjs';
+import { openState, summary } from './lib/state.mjs';
+import { discover, inspect } from './lib/discovery.mjs';
+import { prepare, publish, incorporateBase } from './lib/repository.mjs';
+import { checkCandidate, checkDeploy, cleanup } from './lib/checks.mjs';
+
+function options(args) {
+  const packageDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const version = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8')).version;
+  const result = { packageDir, version, org: 'gowalk-public', workers: 8, maxActive: 8, ciTimeout: 3600000 };
+  const names = { '--org': 'org', '--state': 'statePath', '--workers': 'workers', '--max-active': 'maxActive' };
+  for (let index = 0; index < args.length; index++) {
+    if (args[index] === '--dry-run') { result.dryRun = true; continue; }
+    if (args[index] === '--retry-unresolved') { result.retryUnresolved = true; continue; }
+    const name = names[args[index]];
+    if (!name || !args[index + 1]) throw new RolloutError('invalid_rollout_arguments');
+    result[name] = ['workers', 'maxActive'].includes(name) ? Number(args[++index]) : args[++index];
+  }
+  if (!result.statePath || !/^[\w-]+$/.test(result.org)
+      || ![result.workers, result.maxActive].every(value => Number.isInteger(value) && value > 0 && value <= 32)) {
+    throw new RolloutError('invalid_rollout_arguments');
+  }
+  result.statePath = resolve(result.statePath);
+  result.workDir = join(dirname(result.statePath), 'checkouts');
+  return result;
+}
+
+function eligible(repo, repositories, opts) {
+  if ((repo.nextAt || 0) > Date.now()) return false;
+  if (repo.status === 'publish') {
+    const active = repositories.filter(row => ['ci', 'deploy', 'cleanup'].includes(row.status));
+    return active.length + (opts.publishing || 0) < opts.maxActive && !active.some(row => row.queued > 0);
+  }
+  return ['inspect', 'prepare', 'ci', 'deploy', 'cleanup', 'update-base'].includes(repo.status);
+}
+
+async function advance(github, repo, opts) {
+  const handlers = { inspect, prepare, publish, ci: checkCandidate, deploy: checkDeploy, cleanup };
+  if (repo.status === 'update-base') return incorporateBase(repo);
+  return handlers[repo.status](github, repo, opts);
+}
+
+function launch(github, repo, opts, state, running, status) {
+  running.set(repo.name, advance(github, repo, opts).catch(error => {
+    repo.reason = error.code || 'rollout_operation_failed';
+    repo.repair = error.result;
+    if (error.retryAt) repo.nextAt = error.retryAt;
+    else { repo.resumeStatus = status; repo.status = 'unresolved'; }
+  }).finally(() => {
+    if (status === 'publish') opts.publishing--;
+    state.save();
+    running.delete(repo.name);
+  }));
+}
+
+async function run(opts, state) {
+  const github = new GitHub();
+  if (!state.data.discovered) await discover(github, state);
+  const recorded = Object.values(state.data.repositories);
+  if (opts.dryRun && recorded.some(repo => ['publish', 'ci', 'deploy', 'cleanup'].includes(repo.status))) {
+    throw new RolloutError('dry_run_requires_separate_state');
+  }
+  if (!opts.dryRun) for (const repo of recorded.filter(repo => repo.status === 'dry-run')) repo.status = 'publish';
+  if (opts.retryUnresolved) {
+    for (const repo of Object.values(state.data.repositories).filter(row => row.status === 'unresolved')) {
+      repo.status = repo.resumeStatus || (repo.installed ? 'prepare' : 'inspect');
+      delete repo.nextAt;
+    }
+  }
+  opts.save = state.save;
+  const running = new Map();
+  let lastReport = 0;
+  while (true) {
+    const repositories = Object.values(state.data.repositories);
+    const pending = repositories.filter(repo => eligible(repo, repositories, opts) && !running.has(repo.name));
+    pending.sort((a, b) => Number(['ci', 'deploy', 'cleanup'].includes(b.status))
+      - Number(['ci', 'deploy', 'cleanup'].includes(a.status)));
+    for (const repo of pending.slice(0, opts.workers - running.size)) {
+      if (!eligible(repo, repositories, opts)) continue;
+      const status = repo.status;
+      if (status === 'publish') opts.publishing = (opts.publishing || 0) + 1;
+      launch(github, repo, opts, state, running, status);
+    }
+    if (Date.now() - lastReport > 30000) {
+      console.log(JSON.stringify({ version: opts.version, ...summary(state.data) }));
+      lastReport = Date.now();
+    }
+    const active = repositories.some(repo => !['updated', 'already-current', 'not-installed', 'unresolved', 'dry-run']
+      .includes(repo.status));
+    if (!active && !running.size) return;
+    await Promise.race([...running.values(), delay(1000)]);
+  }
+}
+
+let state;
+try {
+  const opts = options(process.argv.slice(2));
+  state = openState(opts.statePath, opts.org, opts.version);
+  await run(opts, state);
+  state.save();
+  console.log(JSON.stringify({ complete: true, ...summary(state.data) }));
+  if (Object.values(state.data.repositories).some(repo => repo.status === 'unresolved')) process.exitCode = 1;
+} catch (error) {
+  console.error(JSON.stringify({ code: error.code || 'rollout_unavailable', retryAt: error.retryAt || null }));
+  process.exitCode = 1;
+} finally { state?.close(); }