@ghl-ai/aw 0.1.44-beta.1 → 0.1.44-beta.2

package/c4/preflight.mjs

@@ -0,0 +1,254 @@
+/**
+ * c4/preflight.mjs — preflight aggregator for `aw c4`.
+ *
+ * Composes harness, token resolution, REST-API auth verification, gh CLI
+ * presence, ECC bridge-status probe, and disk-free reporting into a single
+ * PreflightResult shape with per-failure recommendation strings. Pure
+ * orchestration over already-tested c4 primitives — no new I/O patterns.
+ *
+ * The orchestrator (commands/c4.mjs) consumes runPreflight() up front so:
+ *   (a) `aw c4 --dry-run` can short-circuit with the full report before any
+ *       harness write, and
+ *   (b) install-mode runs print recommendations[] alongside the summary
+ *       line so the user sees actionable guidance for every degraded
+ *       outcome (no token → set GITHUB_PAT, 401 → refresh PAT, etc.).
+ *
+ * Every external signal is dependency-injected via opts so this module is
+ * exhaustively testable without touching env, network, the real shell, or
+ * the real filesystem disk-stat surface.
+ *
+ * Contract: spec.md::§"c4/preflight.mjs", tasks.md::4.1.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { getGithubToken } from './secrets.mjs';
+import { verifyAuth } from './gitAuth.mjs';
+
+/**
+ * @typedef {'cursor-cloud' | 'codex-web' | 'claude-web' | 'unknown'} Harness
+ * @typedef {'GITHUB_PAT' | 'GITHUB_TOKEN' | null} TokenSource
+ * @typedef {'ok' | 'will-install' | 'failed'} BridgeStatus
+ *
+ * @typedef {object} PreflightResult
+ * @property {Harness}      harness
+ * @property {boolean}      hasToken
+ * @property {TokenSource}  tokenSource
+ * @property {boolean}      authOk
+ * @property {string}       [authError]   Short failure tag (e.g. 'http-401', 'network').
+ * @property {boolean}      ghCliPresent
+ * @property {BridgeStatus} bridgeStatus
+ * @property {number}       diskFreeMb
+ * @property {string[]}     recommendations  Actionable guidance strings.
+ */
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Constants — thresholds and message templates.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+const DISK_FREE_THRESHOLD_MB = 200;
+
+const REC = Object.freeze({
+  noToken:
+    'Set GITHUB_PAT in your harness secrets UI before running aw c4 ' +
+    '(GITHUB_TOKEN is also accepted as a fallback).',
+  authInvalid:
+    'PAT is invalid, expired, or SAML not authorized — refresh the token ' +
+    'and re-authorize the GoHighLevel org if your harness uses SSO.',
+  authForbidden:
+    'PAT lacks platform-docs repo access — grant the `repo` scope (or ' +
+    'add the user to GoHighLevel/platform-docs) and retry.',
+  authNetwork:
+    'Network connectivity to api.github.com is broken — verify the harness ' +
+    'has outbound HTTPS and DNS reachability before running aw c4.',
+  authOther: (status) =>
+    `Auth verification returned an unexpected response (${status ?? 'no-status'}); aw c4 will continue but ghl-ai MCP and registry sync may fail.`,
+  ghMissing:
+    'gh CLI is not installed — aw c4 will install via apt or fall back to ' +
+    'the insteadOf rewrite alone (degraded but still functional).',
+  lowDisk: (mb) =>
+    `Insufficient disk: ${mb}MB free (aw c4 needs at least ${DISK_FREE_THRESHOLD_MB}MB ` +
+    'for ECC clone + registry pull).',
+  bridgeWillInstall:
+    'ECC registry bridge will be installed during this run (Codex only — ' +
+    'Bug A workaround that symlinks ECC stage skills into ~/.aw/.aw_registry).',
+  bridgeFailed:
+    'ECC and/or AW registry not yet provisioned — aw init will create them ' +
+    'on the first c4 run; re-run preflight afterwards.',
+});
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Default adapters — overridden in tests.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+function defaultShell(cmd) {
+  const result = spawnSync(cmd, [], {
+    shell: true,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return {
+    ok: result.status === 0,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    exitCode: result.status ?? -1,
+  };
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Helpers — small pure functions per signal.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+function runShell(shell, cmd) {
+  try {
+    return shell(cmd) ?? { ok: false, stdout: '', stderr: '', exitCode: -1 };
+  } catch (err) {
+    return { ok: false, stdout: '', stderr: String(err?.message ?? err), exitCode: -1 };
+  }
+}
+
+function classifyAuthError(verifyResult) {
+  if (verifyResult.ok) return undefined;
+  if (typeof verifyResult.status === 'number') {
+    if (verifyResult.status === 401) return 'http-401';
+    if (verifyResult.status === 403) return 'http-403';
+    if (verifyResult.status === 404) return 'http-404';
+    return `http-${verifyResult.status}`;
+  }
+  if (verifyResult.error) return 'network';
+  return 'unknown';
+}
+
+function probeBridgeStatus(harness, awHome, eccHome) {
+  if (harness !== 'codex-web') return 'ok';
+
+  // Bridge installs ~/.aw/.aw_registry/platform/core/skills/<aw-*>/SKILL.md
+  // symlinks pointing at ~/.aw-ecc/skills/<aw-*>/SKILL.md. If aw-plan is
+  // already present in the registry path, the bridge is a no-op (ok).
+  const bridgedSkillPath = join(
+    awHome,
+    '.aw_registry/platform/core/skills/aw-plan/SKILL.md',
+  );
+  if (existsSync(bridgedSkillPath)) return 'ok';
+
+  // Bridge can install when both ECC home and the registry skeleton exist.
+  // (The aw-plan skill source must exist somewhere — the bridge follows
+  // applyEccRegistryBridge's contract; preflight only certifies feasibility.)
+  if (existsSync(eccHome) && existsSync(awHome)) return 'will-install';
+
+  return 'failed';
+}
+
+function buildRecommendations({
+  hasToken,
+  authOk,
+  authError,
+  authStatus,
+  ghCliPresent,
+  bridgeStatus,
+  diskFreeMb,
+}) {
+  const out = [];
+  if (!hasToken) out.push(REC.noToken);
+  if (hasToken && !authOk) {
+    if (authError === 'http-401') out.push(REC.authInvalid);
+    else if (authError === 'http-403' || authError === 'http-404') out.push(REC.authForbidden);
+    else if (authError === 'network') out.push(REC.authNetwork);
+    else out.push(REC.authOther(authStatus ?? authError));
+  }
+  if (!ghCliPresent) out.push(REC.ghMissing);
+  if (diskFreeMb < DISK_FREE_THRESHOLD_MB) out.push(REC.lowDisk(diskFreeMb));
+  if (bridgeStatus === 'will-install') out.push(REC.bridgeWillInstall);
+  else if (bridgeStatus === 'failed') out.push(REC.bridgeFailed);
+  return out;
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * runPreflight — public API.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Aggregate every preflight signal the orchestrator needs before deciding
+ * whether to skip, dry-run, or proceed with a full c4 install.
+ *
+ * @param {object} opts
+ * @param {Harness} opts.harness     Required — pre-detected by detect.mjs.
+ * @param {string}  opts.cwd         Required — repo working directory.
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {(cmd: string) => { ok: boolean, stdout: string, stderr: string, exitCode: number }} [opts.shell]
+ * @param {typeof globalThis.fetch} [opts.fetchImpl]
+ * @param {string}  [opts.home]      Defaults to env.HOME.
+ * @param {string}  [opts.awHome]    Defaults to <home>/.aw.
+ * @param {string}  [opts.eccHome]   Defaults to <home>/.aw-ecc.
+ * @param {number}  [opts.diskFreeMb]  Inject for tests; production defaults to a real statfs probe.
+ * @returns {Promise<PreflightResult>}
+ */
+export async function runPreflight(opts = {}) {
+  if (!opts.harness) throw new Error('runPreflight: harness is required');
+  if (!opts.cwd) throw new Error('runPreflight: cwd is required');
+
+  const {
+    harness,
+    env = process.env,
+    shell = defaultShell,
+    fetchImpl = globalThis.fetch,
+    diskFreeMb,
+  } = opts;
+  // home: prefer explicit opts.home, then env.HOME (already DI'd), only
+  // last-resort to '~'. Removed the redundant process.env.HOME fallback —
+  // when env is the injected `{}`, opts.home should have been passed instead.
+  const home = opts.home ?? env.HOME ?? '~';
+  const awHome = opts.awHome ?? join(home, '.aw');
+  const eccHome = opts.eccHome ?? join(home, '.aw-ecc');
+
+  // 1. Token resolution.
+  const { token, source: tokenSource } = getGithubToken(env);
+  const hasToken = token != null;
+
+  // 2. Auth verification — only when we have a token to verify.
+  let authOk = false;
+  let authError;
+  let authStatus;
+  if (hasToken) {
+    const verify = await verifyAuth('rest-api', token, { shell, fetchImpl });
+    authOk = verify.ok;
+    authStatus = verify.status;
+    if (!authOk) authError = classifyAuthError(verify);
+  }
+
+  // 3. gh CLI presence.
+  const ghCliPresent = runShell(shell, 'command -v gh').ok;
+
+  // 4. Bridge status (codex-web only; other harnesses always 'ok').
+  const bridgeStatus = probeBridgeStatus(harness, awHome, eccHome);
+
+  // 5. Disk free MB. For tests, callers inject the value directly; in
+  //    production the orchestrator passes a measured number. Defaulting to
+  //    Infinity here keeps the preflight from spuriously flagging low disk
+  //    when the orchestrator forgets to measure.
+  const diskFreeMbResolved = typeof diskFreeMb === 'number' ? diskFreeMb : Number.POSITIVE_INFINITY;
+
+  // 6. Compose recommendations.
+  const recommendations = buildRecommendations({
+    hasToken,
+    authOk,
+    authError,
+    authStatus,
+    ghCliPresent,
+    bridgeStatus,
+    diskFreeMb: diskFreeMbResolved,
+  });
+
+  return {
+    harness,
+    hasToken,
+    tokenSource,
+    authOk,
+    ...(authError ? { authError } : {}),
+    ghCliPresent,
+    bridgeStatus,
+    diskFreeMb: diskFreeMbResolved,
+    recommendations,
+  };
+}

package/c4/repoLocalClaudeSettings.mjs

@@ -0,0 +1,54 @@
+/**
+ * c4/repoLocalClaudeSettings.mjs — per-repo Claude settings.local.json with
+ * Skill permission scoped to the current repo.
+ *
+ * Why per-repo: home-level settings.json governs the entire user. A repo
+ * may want Skill dispatch enabled without inheriting that permission across
+ * every other workspace. Pilot script writes this file so the repo-scoped
+ * session can dispatch the Skill tool independently.
+ *
+ * Never overwrites: if the file exists (user-authored or AW-authored from a
+ * prior run), we return { alreadyPresent: true, written: false } and leave
+ * it untouched. Idempotency is achieved by NOT being a "merge" — it's a
+ * "create if absent" semantic.
+ *
+ * Contract: spec.md::§"c4/repoLocalClaudeSettings.mjs", tasks.md::3.4c.
+ */
+
+import {
+  existsSync,
+  writeFileSync,
+  chmodSync,
+  mkdirSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const FILE_MODE = 0o600;
+
+const CANONICAL_BODY = {
+  $schema: 'https://json.schemastore.org/claude-code-settings.json',
+  permissions: { allow: ['Skill'] },
+};
+
+/**
+ * Write `<cwd>/.claude/settings.local.json` if absent.
+ *
+ * @param {string} cwd  Repo root.
+ * @returns {{ written: boolean, alreadyPresent: boolean }}
+ */
+export function ensureRepoLocalClaudeSettings(cwd) {
+  if (!cwd || typeof cwd !== 'string') {
+    throw new Error('ensureRepoLocalClaudeSettings: cwd is required');
+  }
+
+  const filePath = join(cwd, '.claude/settings.local.json');
+  if (existsSync(filePath)) {
+    return { written: false, alreadyPresent: true };
+  }
+
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(CANONICAL_BODY, null, 2) + '\n', { mode: FILE_MODE });
+  try { chmodSync(filePath, FILE_MODE); } catch { /* best-effort */ }
+
+  return { written: true, alreadyPresent: false };
+}

package/c4/repoLocalIgnore.mjs

@@ -0,0 +1,157 @@
+/**
+ * c4/repoLocalIgnore.mjs — append entries to `<cwd>/.git/info/exclude` so
+ * AW C4 cloud bootstrap pollution doesn't show up in `git status`.
+ *
+ * Contract: spec.md::§"c4/repoLocalIgnore.mjs", tasks.md::3.6.
+ *
+ * Notes:
+ * - Repo-local only. Never touches `.gitignore` (committed file).
+ * - No-op if `<cwd>/.git` is absent.
+ * - Idempotent: lines are added only when `grep -qxF`-style identity match
+ *   is missing (whole-line, fixed-string).
+ * - MD entries (CLAUDE.md / AGENTS.md) are conditional: we only add them if
+ *   the file is NOT already tracked in git. This preserves user repos that
+ *   intentionally commit their own root-level instruction files.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const ALWAYS_ENTRIES = ['.aw_registry', '.aw/', '.aw-ecc/'];
+
+const PER_HARNESS_ENTRIES = {
+  'claude-web': ['.claude/hook-logs/', '.claude/settings.local.json'],
+  'cursor-cloud': [
+    '.cursor/hook-logs/',
+    '.cursor/settings.local.json',
+    '.cursor/mcp.json',
+  ],
+  'codex-web': ['.codex/hook-logs/', '.codex/config.local.toml'],
+};
+
+const CONDITIONAL_MD_BY_HARNESS = {
+  'claude-web': ['CLAUDE.md'],
+  'cursor-cloud': ['AGENTS.md'],
+  'codex-web': ['AGENTS.md'],
+};
+
+/**
+ * Default shell adapter — runs `git -C <cwd> ls-files --error-unmatch <path>`
+ * via `spawnSync` and reports a normalized result. Production callers can
+ * inject their own (e.g. tests) via `opts.shell`.
+ *
+ * @param {string} cmd
+ * @returns {{ ok: boolean, exitCode: number }}
+ */
+function defaultShell(cmd) {
+  const result = spawnSync('bash', ['-lc', cmd], { encoding: 'utf8' });
+  return {
+    ok: result.status === 0,
+    exitCode: typeof result.status === 'number' ? result.status : 1,
+  };
+}
+
+/**
+ * Whether a repo-relative path is currently tracked in git (committed or
+ * staged). Mirrors the pilot's `git ls-files --error-unmatch <file>` check.
+ *
+ * @param {string} cwd
+ * @param {string} relativePath
+ * @param {(cmd: string) => { ok: boolean, exitCode: number }} shell
+ * @returns {boolean}
+ */
+function isTrackedInGit(cwd, relativePath, shell) {
+  const cmd = `git -C ${shellQuote(cwd)} ls-files --error-unmatch ${shellQuote(relativePath)}`;
+  const { ok } = shell(cmd);
+  return ok === true;
+}
+
+function shellQuote(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+function readExclude(filePath) {
+  if (!existsSync(filePath)) return '';
+  return readFileSync(filePath, 'utf8');
+}
+
+/**
+ * Whether `entry` already appears as a whole line in the file body.
+ * Mirrors `grep -qxF` semantics (fixed string, full-line match).
+ */
+function hasExactLine(body, entry) {
+  if (body === '') return false;
+  const lines = body.split('\n');
+  return lines.includes(entry);
+}
+
+/**
+ * Append the given entries to the file body and return the new body.
+ * Ensures a single trailing newline. Skips entries already present.
+ */
+function appendMissing(body, entries) {
+  let next = body;
+  if (next.length > 0 && !next.endsWith('\n')) next += '\n';
+  for (const entry of entries) {
+    if (hasExactLine(next, entry)) continue;
+    next += `${entry}\n`;
+  }
+  return next;
+}
+
+/**
+ * Append AW C4 entries to `<cwd>/.git/info/exclude`.
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd Repo root.
+ * @param {'claude-web'|'cursor-cloud'|'codex-web'} opts.harness
+ * @param {(cmd: string) => { ok: boolean, exitCode: number }} [opts.shell]
+ *   Optional shell adapter (defaults to spawnSync-backed). Tests inject this
+ *   to simulate `git ls-files --error-unmatch` outcomes.
+ * @returns {{ added: string[] }}
+ */
+export function ensureRepoLocalIgnore(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new Error('ensureRepoLocalIgnore: opts object is required');
+  }
+  const { cwd, harness } = opts;
+  const shell = typeof opts.shell === 'function' ? opts.shell : defaultShell;
+
+  if (!cwd || typeof cwd !== 'string') {
+    throw new Error('ensureRepoLocalIgnore: opts.cwd is required');
+  }
+  if (!PER_HARNESS_ENTRIES[harness]) {
+    throw new Error(`ensureRepoLocalIgnore: unsupported harness "${harness}"`);
+  }
+
+  // No-op if the repo isn't a git repo at all.
+  if (!existsSync(join(cwd, '.git'))) {
+    return { added: [] };
+  }
+
+  const excludePath = join(cwd, '.git/info/exclude');
+  const currentBody = readExclude(excludePath);
+
+  // Compose desired entries.
+  const desired = [...ALWAYS_ENTRIES, ...PER_HARNESS_ENTRIES[harness]];
+  for (const md of CONDITIONAL_MD_BY_HARNESS[harness]) {
+    if (!isTrackedInGit(cwd, md, shell)) desired.push(md);
+  }
+
+  // Compute which entries are actually new (so we can report `added`).
+  const added = desired.filter((e) => !hasExactLine(currentBody, e));
+  if (added.length === 0) return { added: [] };
+
+  // Ensure parent dir, then atomically rewrite with new content.
+  mkdirSync(dirname(excludePath), { recursive: true });
+  const nextBody = appendMissing(currentBody, desired);
+  writeFileSync(excludePath, nextBody);
+
+  return { added };
+}

package/c4/repoRootInstructions.mjs

@@ -0,0 +1,166 @@
+/**
+ * c4/repoRootInstructions.mjs — copy ECC's persistent context file
+ * (CLAUDE.md / AGENTS.md) into the repo root, with codex-source precedence
+ * (L2) and user-authored file preservation.
+ *
+ * Per harness:
+ *   - claude-web    → ~/.aw-ecc/CLAUDE.md → <cwd>/CLAUDE.md
+ *   - cursor-cloud  → ~/.aw-ecc/AGENTS.md → <cwd>/AGENTS.md
+ *   - codex-web     → ~/.codex/AGENTS.md (preferred) OR ~/.aw-ecc/AGENTS.md (fallback)
+ *
+ * (L2) Codex source precedence: ~/.codex/AGENTS.md is what `aw init`'s
+ * codex provider personalized for this user (rules-bridge + harness
+ * tweaks). Always prefer it over the raw ECC fallback when present, even
+ * if it lacks the managed-block marker — the user customization wins.
+ *
+ * Behavior matrix:
+ *   - target absent + source present       → copy verbatim, source: 'aw-ecc-home' or 'codex-home'.
+ *   - target absent + source absent        → no-op, source: 'none'.
+ *   - target user-authored + source present → preserve user content, replace
+ *                                               managed block in place,
+ *                                               source: 'preserved-user-file'.
+ *   - target managed-only (rare)           → managed block updated in place.
+ *
+ * Managed-block markers (this module):
+ *   <!-- aw-managed:start repo-root-instructions -->
+ *   ...content...
+ *   <!-- aw-managed:end repo-root-instructions -->
+ *
+ * Contract: spec.md::§"c4/repoRootInstructions.mjs", tasks.md::3.5.
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const MANAGED_START = '<!-- aw-managed:start repo-root-instructions -->';
+const MANAGED_END = '<!-- aw-managed:end repo-root-instructions -->';
+
+const HARNESS_TARGETS = {
+  'claude-web': 'CLAUDE.md',
+  'cursor-cloud': 'AGENTS.md',
+  'codex-web': 'AGENTS.md',
+};
+
+/**
+ * Replace any existing managed block with `bodyToInject`. Appends a fresh
+ * managed block if none exists. Preserves user content outside the block.
+ */
+function upsertManagedBlock(existing, bodyToInject) {
+  const startIdx = existing.indexOf(MANAGED_START);
+  const endIdx =
+    startIdx === -1
+      ? -1
+      : existing.indexOf(MANAGED_END, startIdx + MANAGED_START.length);
+
+  const block = `${MANAGED_START}\n${bodyToInject.trimEnd()}\n${MANAGED_END}\n`;
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Replace existing block in place.
+    return (
+      existing.slice(0, startIdx) +
+      block +
+      existing.slice(endIdx + MANAGED_END.length).replace(/^\n+/, '')
+    );
+  }
+
+  // Append a managed block (with a separating blank line).
+  const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+  return existing + sep + block;
+}
+
+/**
+ * Pick the source file for a harness, applying codex-source precedence.
+ *
+ * Codex-web precedence (per execution.md::Phase 0 item 8 L2):
+ *   1. <cwd>/.codex/AGENTS.md   — repo-author intent (highest priority)
+ *   2. ~/.codex/AGENTS.md       — aw-init's harness-personalized output
+ *   3. ~/.aw-ecc/AGENTS.md      — raw ECC fallback
+ *
+ * Both repo-local and home-level codex variants resolve to type
+ * `'codex-home'` because the orchestrator does not need to distinguish
+ * which one won — only that we used the codex-personalized form rather
+ * than the raw ECC fallback.
+ */
+function resolveSource({ harness, cwd, eccHome, home }) {
+  if (harness === 'claude-web') {
+    const eccPath = join(eccHome, 'CLAUDE.md');
+    if (existsSync(eccPath)) return { type: 'aw-ecc-home', path: eccPath };
+    return { type: 'none', path: null };
+  }
+  if (harness === 'cursor-cloud') {
+    const eccPath = join(eccHome, 'AGENTS.md');
+    if (existsSync(eccPath)) return { type: 'aw-ecc-home', path: eccPath };
+    return { type: 'none', path: null };
+  }
+  if (harness === 'codex-web') {
+    const cwdCodexPath = join(cwd, '.codex/AGENTS.md');
+    if (existsSync(cwdCodexPath)) return { type: 'codex-home', path: cwdCodexPath };
+    const homeCodexPath = join(home, '.codex/AGENTS.md');
+    if (existsSync(homeCodexPath)) return { type: 'codex-home', path: homeCodexPath };
+    const eccPath = join(eccHome, 'AGENTS.md');
+    if (existsSync(eccPath)) return { type: 'aw-ecc-home', path: eccPath };
+    return { type: 'none', path: null };
+  }
+  throw new Error(`copyRepoRootInstructions: unsupported harness "${harness}"`);
+}
+
+/**
+ * Copy a repo-root persistent-context file into the repo, preserving any
+ * user-authored content via managed-block semantics.
+ *
+ * @param {'claude-web'|'cursor-cloud'|'codex-web'} harness
+ * @param {string} cwd                Repo root.
+ * @param {string} eccHome            ~/.aw-ecc.
+ * @param {{ home?: string }} [opts]  User home (default os.homedir()).
+ * @returns {{ copied: string[], sources: Record<string, 'codex-home'|'aw-ecc-home'|'preserved-user-file'|'none'> }}
+ */
+export function copyRepoRootInstructions(harness, cwd, eccHome, opts = {}) {
+  const fileName = HARNESS_TARGETS[harness];
+  if (!fileName) {
+    throw new Error(`copyRepoRootInstructions: unsupported harness "${harness}"`);
+  }
+  if (!cwd || typeof cwd !== 'string') {
+    throw new Error('copyRepoRootInstructions: cwd is required');
+  }
+  if (!eccHome || typeof eccHome !== 'string') {
+    throw new Error('copyRepoRootInstructions: eccHome is required');
+  }
+
+  const home = opts.home ?? homedir();
+  const targetPath = join(cwd, fileName);
+  const sources = {};
+  const copied = [];
+
+  const userFileExists = existsSync(targetPath);
+  const source = resolveSource({ harness, cwd, eccHome, home });
+
+  if (source.type === 'none') {
+    sources[fileName] = userFileExists ? 'preserved-user-file' : 'none';
+    return { copied, sources };
+  }
+
+  const sourceBody = readFileSync(source.path, 'utf8');
+
+  if (!userFileExists) {
+    // Fresh copy — write source verbatim.
+    writeFileSync(targetPath, sourceBody);
+    sources[fileName] = source.type;
+    copied.push(fileName);
+    return { copied, sources };
+  }
+
+  // User file exists — never replace it; only update managed block.
+  const userContent = readFileSync(targetPath, 'utf8');
+  const next = upsertManagedBlock(userContent, sourceBody);
+  if (next !== userContent) {
+    writeFileSync(targetPath, next);
+    copied.push(fileName);
+  }
+  sources[fileName] = 'preserved-user-file';
+  return { copied, sources };
+}

package/c4/secrets.mjs

@@ -0,0 +1,55 @@
+/**
+ * c4/secrets.mjs — GitHub token resolution and masking helpers.
+ *
+ * The same token is reused for two purposes (user-confirmed):
+ *   1. Git authentication (insteadOf rewrite + credential.helper store + gh login)
+ *   2. ghl-ai MCP Bearer auth (Authorization header on JSON-RPC requests)
+ *
+ * Resolution rules:
+ *   - Prefer GITHUB_PAT (canonical name in pilot bootstraps).
+ *   - Fall back to GITHUB_TOKEN (some harness UIs only expose this name).
+ *   - Treat empty/whitespace-only values as absent (defensive — env UIs
+ *     sometimes echo trailing newlines or leave the field literally blank).
+ *   - Both empty ⇒ { token: null, source: null }; orchestrator emits a
+ *     one-line skip and lets the agent continue (exit 0).
+ *
+ * @typedef {'GITHUB_PAT' | 'GITHUB_TOKEN' | null} TokenSource
+ */
+
+const ELLIPSIS = '\u2026';
+const MASK_PREFIX_LEN = 8;
+
+function readEnvVar(env, name) {
+  const raw = env?.[name];
+  if (typeof raw !== 'string') return '';
+  return raw.trim();
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ token: string | null, source: TokenSource }}
+ */
+export function getGithubToken(env = process.env) {
+  const pat = readEnvVar(env, 'GITHUB_PAT');
+  if (pat) return { token: pat, source: 'GITHUB_PAT' };
+
+  const token = readEnvVar(env, 'GITHUB_TOKEN');
+  if (token) return { token, source: 'GITHUB_TOKEN' };
+
+  return { token: null, source: null };
+}
+
+/**
+ * Mask a token for log/diagnostic display. Reveals the first 8 chars (enough
+ * to identify the prefix family — `ghp_`, `ghs_`, `gho_`, etc.) followed by
+ * a single Unicode ellipsis. Never returns the full token, even for short
+ * inputs (we still append `…` so the value is visibly redacted).
+ *
+ * @param {unknown} token
+ * @returns {string}
+ */
+export function maskToken(token) {
+  if (typeof token !== 'string' || token.length === 0) return '';
+  if (token.length <= MASK_PREFIX_LEN) return token + ELLIPSIS;
+  return token.slice(0, MASK_PREFIX_LEN) + ELLIPSIS;
+}