@ghl-ai/aw 0.1.44-beta.8 → 0.1.44

package/c4/index.mjs

@@ -64,3 +64,11 @@ export {
   diagnoseSkillResolution,
   dumpPostInitState,
 } from './diagnostics.mjs';
+export {
+  DEFAULT_TEMPLATES_DIR,
+  loadManifest,
+  expectedContent,
+  planActions,
+  applyActions,
+  initRepo,
+} from './initRepo.mjs';

package/c4/initRepo.mjs

@@ -0,0 +1,567 @@
+/**
+ * c4/initRepo.mjs — engine for `aw init-repo`.
+ *
+ * Scaffolds the 4 cloud-bootstrap files into a target git repo from
+ * bundled literal templates (under ./templates/). Idempotent:
+ * SHA-256 byte compare per file decides create / skip-equal /
+ * blocked-edited / overwrite. `--dry-run` and `--diff` are read-only.
+ *
+ * Public surface (composed in this order):
+ *   loadManifest(templatesDir)        — read & parse templates/manifest.json
+ *   planActions(opts, manifest)       — pure: decide per-file action
+ *   applyActions(opts, actions)       — FS effects (gated by dryRun)
+ *   initRepo(opts)                    — orchestrator + exitCode summary
+ *
+ * Contract: spec.md::"New: libs/aw/c4/initRepo.mjs (engine)"
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  chmodSync,
+  statSync,
+} from 'node:fs';
+import { join, dirname, basename, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Default `git check-ignore` runner. Returns true when `relpath` is ignored
+ * by the user's gitignore rules, false otherwise (or when git is unavailable).
+ *
+ * Exit codes per `git check-ignore --quiet`:
+ *   0 — file IS ignored
+ *   1 — file is NOT ignored
+ *   128 — error (no git repo, etc.) — treat as not-ignored to avoid noisy
+ *         false-positive warnings on broken installs
+ */
+const DEFAULT_CHECK_IGNORE = (repoRoot, relpath) => {
+  try {
+    const result = spawnSync(
+      'git',
+      ['-C', repoRoot, 'check-ignore', '--quiet', relpath],
+      { stdio: 'pipe' },
+    );
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Variable substitution table for `kind: "interpolated"` templates.
+ *
+ * Each value is computed lazily from `opts` (the engine call site provides
+ * `repoRoot`). Adding a new variable here means it becomes referenceable as
+ * `{{NAME}}` inside any interpolated template.
+ *
+ * REPO_BASENAME is the leaf directory name of `repoRoot` after `path.resolve`
+ * — exactly what Codex Cloud uses as the project key (`/workspace/<basename>`).
+ */
+const SUBSTITUTIONS = {
+  REPO_BASENAME: (opts) => basename(resolve(opts.repoRoot)),
+};
+
+/**
+ * Render `{{VAR}}` placeholders in `content` using the SUBSTITUTIONS table.
+ *
+ * Throws on any `{{...}}` reference whose key isn't in the table — fail loud
+ * over silently shipping `{{REPO_BASENAME}}` in a config file.
+ *
+ * @param {string} content
+ * @param {{repoRoot: string}} opts
+ * @returns {string} content with all known placeholders substituted
+ */
+function renderInterpolated(content, opts) {
+  return content.replace(/\{\{(\w+)\}\}/g, (_, name) => {
+    if (!Object.prototype.hasOwnProperty.call(SUBSTITUTIONS, name)) {
+      throw new Error(
+        `init-repo: unknown variable {{${name}}} in interpolated template. ` +
+        `Known: ${Object.keys(SUBSTITUTIONS).join(', ')}.`,
+      );
+    }
+    return SUBSTITUTIONS[name](opts);
+  });
+}
+
+/**
+ * Render the full expected file content for a `kind: "managed-block"` template.
+ *
+ * Reads the bundled block source (just the inner lines), strips any existing
+ * managed block bearing the same `marker` from the dest file (so re-runs
+ * cleanly replace stale content), and appends a fresh marker-wrapped block.
+ *
+ * Format on disk (matches existing AW convention from integrate.mjs and
+ * repoRootInstructions.mjs — colon-no-space, marker name on both ends):
+ *   <pre-existing user content (managed block stripped)>
+ *
+ *   # aw-managed:start <marker> (DO NOT EDIT — managed by `aw init-repo`)
+ *   <block source content>
+ *   # aw-managed:end <marker>
+ *
+ * The single blank line separator between user content and our block is only
+ * emitted when prior content exists. The file always ends with one trailing
+ * newline.
+ *
+ * @param {{src: string, marker: string}} template
+ * @param {{templatesDir: string, repoRoot: string}} opts
+ * @returns {string} full expected file content
+ */
+function renderManagedBlock(template, opts) {
+  const blockSrcPath = join(opts.templatesDir, template.src);
+  const blockBody = readFileSync(blockSrcPath, 'utf8').replace(/\n+$/, '');
+
+  const destPath = join(opts.repoRoot, template.dest);
+  const existing = existsSync(destPath) ? readFileSync(destPath, 'utf8') : '';
+  const preserved = stripManagedBlock(existing, template.marker).replace(/\n+$/, '');
+
+  const wrapped =
+    `# aw-managed:start ${template.marker} (DO NOT EDIT — managed by \`aw init-repo\`)\n` +
+    blockBody +
+    '\n' +
+    `# aw-managed:end ${template.marker}\n`;
+
+  return preserved.length > 0 ? `${preserved}\n\n${wrapped}` : wrapped;
+}
+
+/**
+ * Remove every `# aw-managed:start <marker> ... # aw-managed:end <marker>`
+ * block from `content`. Idempotent on content with no such block.
+ *
+ * Defensive against multiple stale blocks with the same marker (all collapse
+ * to none — fresh block is appended afterward by the caller).
+ */
+function stripManagedBlock(content, marker) {
+  const safeMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(
+    `(?:^|\\n)# aw-managed:start ${safeMarker}(?:[^\\n]*)\\n` +
+    `[\\s\\S]*?` +
+    `# aw-managed:end ${safeMarker}[ \\t]*\\n?`,
+    'g',
+  );
+  return content.replace(re, '\n');
+}
+
+/** Default fs surface — node:fs. Tests inject mocks for failure paths. */
+const DEFAULT_FS = {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  chmodSync,
+  statSync,
+};
+
+/** Default writer — process.stdout / process.stderr. */
+const DEFAULT_WRITER = {
+  stdout: (s) => process.stdout.write(s),
+  stderr: (s) => process.stderr.write(s),
+};
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Default location of bundled templates inside the npm package. */
+export const DEFAULT_TEMPLATES_DIR = join(__dirname, 'templates');
+
+/**
+ * Read & parse the templates manifest from the given directory.
+ *
+ * Throws a structured Error with a `code: 'TEMPLATES_NOT_FOUND'` marker
+ * when manifest.json is missing or unreadable — consumers (the
+ * orchestrator) translate this to user-facing exit-2 output.
+ *
+ * @param {string} templatesDir absolute path to the bundled templates dir
+ * @returns {{ version: 1, templates: Array<{kind:'literal',src:string,dest:string,mode:string}> }}
+ */
+export function loadManifest(templatesDir) {
+  const manifestPath = join(templatesDir, 'manifest.json');
+  let raw;
+  try {
+    raw = readFileSync(manifestPath, 'utf8');
+  } catch (err) {
+    const e = new Error(
+      `init-repo: bundled templates not found at ${manifestPath}. Reinstall @ghl-ai/aw.`,
+    );
+    e.code = 'TEMPLATES_NOT_FOUND';
+    e.cause = err;
+    throw e;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const e = new Error(
+      `init-repo: bundled templates manifest.json is malformed at ${manifestPath}: ${err.message}`,
+    );
+    e.code = 'TEMPLATES_MALFORMED';
+    e.cause = err;
+    throw e;
+  }
+
+  return parsed;
+}
+
+/**
+ * Render the expected file content for a single manifest entry.
+ *
+ * Dispatch by `template.kind`:
+ *   - 'literal'        → readFileSync of the bundled src verbatim
+ *   - 'interpolated'   → readFileSync + {{VAR}} substitution via SUBSTITUTIONS
+ *   - 'managed-block'  → strip stale managed block from dest, append fresh
+ *                        marker-wrapped block built from src body. Returns the
+ *                        FULL rendered dest content (preserves user content
+ *                        outside the markers).
+ *
+ * Pure read — no FS writes. Tests can exercise this directly. The action
+ * object carries both expected and current content so applyActions and the
+ * diff renderer don't have to re-read.
+ *
+ * @param {{kind?: string, src: string, dest?: string, marker?: string}} template
+ * @param {{templatesDir: string, repoRoot?: string}} opts
+ * @returns {string} rendered template content (UTF-8)
+ */
+export function expectedContent(template, opts) {
+  const kind = template.kind ?? 'literal';
+
+  if (kind === 'literal') {
+    return readFileSync(join(opts.templatesDir, template.src), 'utf8');
+  }
+  if (kind === 'interpolated') {
+    const raw = readFileSync(join(opts.templatesDir, template.src), 'utf8');
+    return renderInterpolated(raw, opts);
+  }
+  if (kind === 'managed-block') {
+    return renderManagedBlock(template, opts);
+  }
+  throw new Error(
+    `init-repo: unknown template kind "${kind}" for ${template.src ?? '?'}.`,
+  );
+}
+
+/**
+ * sha256(content) hex — byte-exact, no normalization.
+ *
+ * Note: this is sensitive to line endings and BOM. On Windows with
+ * core.autocrlf=true a CRLF-rewritten clone will hash-mismatch and surface
+ * as `blocked-edited` even on a clean checkout. spec.md::"Cross-platform
+ * line endings" recommends a repo-local .gitattributes with `* eol=lf`.
+ */
+function sha256(content) {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+/**
+ * Decide per-file action for every template — pure, no FS writes.
+ *
+ * Decision matrix:
+ *   file missing                 → 'create'
+ *   file exists, hash matches    → 'skip-equal'
+ *   file exists, hash differs:
+ *     opts.diff                  → 'diff'         (read-only inspection)
+ *     opts.force                 → 'overwrite'    (clobber edits)
+ *     else                       → 'blocked-edited' (exit 1, no write)
+ *
+ * @param {{repoRoot: string, templatesDir: string, force?: boolean, diff?: boolean}} opts
+ * @param {{templates: Array}} manifest
+ * @returns {Array<{template: object, dest: string, action: string, expectedContent: string, currentContent: string|null}>}
+ */
+export function planActions(opts, manifest) {
+  return manifest.templates.map((template) => {
+    const dest = join(opts.repoRoot, template.dest);
+    const expected = expectedContent(template, opts);
+
+    if (!existsSync(dest)) {
+      return {
+        template,
+        dest,
+        action: 'create',
+        expectedContent: expected,
+        currentContent: null,
+      };
+    }
+
+    const current = readFileSync(dest, 'utf8');
+    const isEqual = sha256(current) === sha256(expected);
+
+    if (isEqual) {
+      return {
+        template,
+        dest,
+        action: 'skip-equal',
+        expectedContent: expected,
+        currentContent: current,
+      };
+    }
+
+    let action;
+    if (template.kind === 'managed-block') {
+      // We own the marker-bracketed area; user edits OUTSIDE the markers are
+      // preserved by renderManagedBlock. Mismatch always means "our block is
+      // stale or missing" → safe to overwrite.
+      action = 'overwrite';
+    } else if (opts.diff) {
+      action = 'diff';
+    } else if (opts.force) {
+      action = 'overwrite';
+    } else {
+      action = 'blocked-edited';
+    }
+
+    return {
+      template,
+      dest,
+      action,
+      expectedContent: expected,
+      currentContent: current,
+    };
+  });
+}
+
+/**
+ * Apply planned actions to the filesystem.
+ *
+ * - 'create' / 'overwrite' → mkdirSync (recursive) + writeFileSync + chmodSync
+ * - 'skip-equal' / 'blocked-edited' / 'diff' → no-op (no FS write)
+ *
+ * No-op entirely when opts.dryRun is true. Non-atomic — partial-write
+ * failures self-heal on the next run (see spec.md "Atomicity note").
+ *
+ * chmod is best-effort: wrapped in try/catch for EPERM/ENOTSUP/ENOSYS.
+ * On chmod failure we emit a warn line via opts.writer.stderr and
+ * continue with exit 0 — the file write is the primary outcome and the
+ * x-bit is recoverable manually with `chmod +x <path>`.
+ *
+ * @param {{repoRoot:string, templatesDir:string, dryRun?:boolean, fs?:object, writer?:object}} opts
+ * @param {Array} actions output of planActions
+ */
+export function applyActions(opts, actions) {
+  if (opts.dryRun) return;
+
+  const fs = opts.fs ?? DEFAULT_FS;
+  const writer = opts.writer ?? DEFAULT_WRITER;
+
+  for (const action of actions) {
+    if (action.action !== 'create' && action.action !== 'overwrite') continue;
+
+    fs.mkdirSync(dirname(action.dest), { recursive: true });
+    fs.writeFileSync(action.dest, action.expectedContent);
+
+    if (action.template.mode) {
+      try {
+        fs.chmodSync(action.dest, parseInt(action.template.mode, 8));
+      } catch (err) {
+        writer.stderr(
+          `init-repo: WARN: failed to chmod ${action.dest}: ${err.code ?? err.message}. ` +
+          `File written but executable bit may be missing — set manually with chmod +x ${action.dest}.\n`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Run `git check-ignore` against every scaffolded file and return the list
+ * of paths still ignored after applyActions wrote the managed `.gitignore`
+ * block. Surfaces pathological gitignore patterns we can't override (most
+ * notably dir-only rules like `.codex/` — git refuses to look inside an
+ * excluded directory regardless of subsequent `!` rules).
+ *
+ * Skips:
+ *   - managed-block kind (`.gitignore` itself isn't normally tracked)
+ *   - blocked-edited / diff actions (file content is user's, not ours)
+ *
+ * @param {{repoRoot: string, checkIgnore?: (root: string, p: string) => boolean}} opts
+ * @param {Array} actions
+ * @returns {string[]} list of dest paths still ignored
+ */
+function verifyIgnoreStatus(opts, actions) {
+  const checkIgnore = opts.checkIgnore ?? DEFAULT_CHECK_IGNORE;
+  const stillIgnored = [];
+
+  for (const action of actions) {
+    if (action.template.kind === 'managed-block') continue;
+    if (action.action === 'blocked-edited' || action.action === 'diff') continue;
+
+    if (checkIgnore(opts.repoRoot, action.template.dest)) {
+      stillIgnored.push(action.template.dest);
+    }
+  }
+  return stillIgnored;
+}
+
+/**
+ * Build a stderr WARNING block for paths still ignored after applyActions.
+ *
+ * Most common cause: dir-only patterns (`.codex/`, `.claude/`) — git docs
+ * explicitly forbid re-include of files under an excluded directory. The
+ * fix is user-side, so we surface the exact paths and the change they need.
+ */
+function buildIgnoreWarning(paths) {
+  return [
+    '',
+    `init-repo: WARN: ${paths.length} scaffolded file${paths.length === 1 ? '' : 's'} still git-ignored:`,
+    ...paths.map((p) => `   - ${p}`),
+    '',
+    'Your .gitignore has rules that block our managed re-include — most likely',
+    'dir-only patterns (e.g. `.codex/`, `.claude/`, `.cursor/`). Per gitignore',
+    'docs, files cannot be re-included once a parent directory is excluded.',
+    '',
+    'Fix: change those rules to use a trailing `*` so they ignore CONTENTS rather',
+    'than the directory itself, then re-run `aw init-repo`. Examples:',
+    '   .codex/    →   .codex/*',
+    '   .claude/   →   .claude/*',
+    '   .cursor/   →   .cursor/*',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Format a single action line for the summary block.
+ *
+ * The 18-char tag width keeps `[blocked-edited]` aligned with shorter tags.
+ */
+function formatActionLine(action) {
+  const tag = `[${action.action}]`.padEnd(18, ' ');
+  return `  ${tag} ${action.template.dest}`;
+}
+
+/**
+ * Build the multi-line summary printed to stdout.
+ *
+ * Distinguishes dry-run vs apply, reports counts per action kind, and
+ * surfaces blocked-edited remediation hints inline so users don't have
+ * to dig through docs.
+ */
+function buildSummary({ repoRoot, dryRun, actions, blockedCount, exitCode }) {
+  const head = dryRun
+    ? `dry-run — would scaffold ${actions.length} files into ${repoRoot}`
+    : `Scaffolding ${actions.length} files into ${repoRoot}`;
+
+  const lines = [`init-repo: ${head}`, ...actions.map(formatActionLine), ''];
+
+  if (blockedCount > 0 && exitCode === 1) {
+    lines.push(
+      `${blockedCount} file${blockedCount === 1 ? '' : 's'} blocked ` +
+        `(locally edited; pass --force to overwrite or --diff to inspect).`,
+    );
+  }
+
+  if (dryRun) {
+    lines.push(`Run without --dry-run to write. exit ${exitCode}.`);
+  } else if (exitCode === 0) {
+    lines.push(`Done. exit 0.`);
+  } else {
+    lines.push(`exit ${exitCode}.`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Public orchestrator. Returns a {exitCode, summary, actions} record;
+ * the command-handler translates exitCode !== 0 to a CancelError.
+ *
+ * Validates inputs (git repo guard, --namespace rejection), composes
+ * loadManifest → planActions → applyActions, prints the summary via
+ * opts.writer, and never throws on user errors — every failure is
+ * encoded in exitCode + summary.
+ *
+ * @param {{
+ *   repoRoot: string,
+ *   templatesDir?: string,
+ *   namespace?: string,
+ *   force?: boolean,
+ *   diff?: boolean,
+ *   dryRun?: boolean,
+ *   noGitignore?: boolean,
+ *   checkIgnore?: (root: string, p: string) => boolean,
+ *   fs?: object,
+ *   writer?: object,
+ * }} opts
+ * @returns {{ exitCode: number, summary: string, actions: Array }}
+ */
+export function initRepo(opts) {
+  const writer = opts.writer ?? DEFAULT_WRITER;
+  const fs = opts.fs ?? DEFAULT_FS;
+  const templatesDir = opts.templatesDir ?? DEFAULT_TEMPLATES_DIR;
+  const repoRoot = opts.repoRoot;
+
+  // Guard: --namespace not supported in v1.
+  if (opts.namespace) {
+    const summary =
+      `init-repo: --namespace is not supported in v1. ` +
+      `init-repo only scaffolds the 4 cloud-bootstrap files. ` +
+      `Use 'aw init --namespace <team>' for namespace pulls.`;
+    writer.stderr(summary + '\n');
+    return { exitCode: 2, summary, actions: [] };
+  }
+
+  // Guard: repoRoot must be a git repo (.git can be a directory or a file
+  // — git worktrees use a file at .git that points to the worktree dir).
+  if (!fs.existsSync(join(repoRoot, '.git'))) {
+    const summary =
+      `init-repo: ${repoRoot} is not a git repository (no .git found). ` +
+      `Run 'git init' first or pass a path to an existing repo.`;
+    writer.stderr(summary + '\n');
+    return { exitCode: 2, summary, actions: [] };
+  }
+
+  // Load + plan + apply.
+  let manifest;
+  try {
+    manifest = loadManifest(templatesDir);
+  } catch (err) {
+    writer.stderr(err.message + '\n');
+    return { exitCode: 2, summary: err.message, actions: [] };
+  }
+
+  // --no-gitignore opt-out: drop every managed-block template before planning.
+  // Users who manage their .gitignore by hand can pass this flag to keep
+  // init-repo from injecting the cloud-bootstrap re-include block.
+  const filteredManifest = opts.noGitignore
+    ? { ...manifest, templates: manifest.templates.filter(t => t.kind !== 'managed-block') }
+    : manifest;
+
+  const actions = planActions(
+    { repoRoot, templatesDir, force: opts.force, diff: opts.diff, fs },
+    filteredManifest,
+  );
+
+  applyActions(
+    { repoRoot, templatesDir, dryRun: opts.dryRun, fs, writer },
+    actions,
+  );
+
+  const blockedCount = actions.filter(a => a.action === 'blocked-edited').length;
+  const exitCode = blockedCount > 0 ? 1 : 0;
+
+  const summary = buildSummary({
+    repoRoot,
+    dryRun: !!opts.dryRun,
+    actions,
+    blockedCount,
+    exitCode,
+  });
+
+  writer.stdout(summary + '\n');
+
+  // Post-apply: verify that scaffolded paths are actually trackable by git.
+  // Emitted AFTER the summary so the action list always renders first
+  // regardless of stdout/stderr buffering. Skip on dryRun — nothing was
+  // written, so check-ignore would probe stale state and emit noise.
+  if (!opts.dryRun) {
+    const stillIgnored = verifyIgnoreStatus(
+      { repoRoot, checkIgnore: opts.checkIgnore },
+      actions,
+    );
+    if (stillIgnored.length > 0) {
+      writer.stderr(buildIgnoreWarning(stillIgnored) + '\n');
+    }
+  }
+
+  return { exitCode, summary, actions };
+}

package/c4/templates/claude/scripts/claude-web-bootstrap.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# .claude/scripts/claude-web-bootstrap.sh — Claude Code Web entry shim.
+#
+# Claude Code Web's external Startup Command is configured to run this file.
+# Path is preserved so existing CCW UI configs keep working; logic is
+# delegated to scripts/aw-c4-bootstrap.sh.
+set -Eeuo pipefail
+exec bash "$(dirname "$0")/../../scripts/aw-c4-bootstrap.sh" --harness claude-web "$@"

package/c4/templates/codex/config.toml

@@ -0,0 +1,5 @@
+[features]
+codex_hooks = true
+
+[projects."/workspace/{{REPO_BASENAME}}"]
+trust_level = "trusted"

package/c4/templates/codex/scripts/codex-web-bootstrap.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# .codex/scripts/codex-web-bootstrap.sh — Codex Web entry shim.
+#
+# Codex Web's external setup script is configured to run this file. Path is
+# preserved so existing Codex UI configs keep working; logic is delegated to
+# scripts/aw-c4-bootstrap.sh.
+set -Eeuo pipefail
+exec bash "$(dirname "$0")/../../scripts/aw-c4-bootstrap.sh" --harness codex-web "$@"

package/c4/templates/cursor/environment.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://cursor.com/schemas/environment.json",
+  "install": "bash scripts/aw-c4-bootstrap.sh --harness cursor-cloud",
+  "terminals": []
+}

package/c4/templates/gitignore-block.txt

@@ -0,0 +1,14 @@
+# Cloud bootstrap files — re-include for tracking even when parent dirs are
+# ignored (e.g. .codex/*, .claude/*, .cursor/*). Order matters: a file under
+# an excluded directory cannot be un-ignored without first un-ignoring the
+# directory. We only un-ignore parent paths and whitelist AW-managed files —
+# we do NOT re-ignore other content inside these dirs, so users' own scripts
+# stay trackable. Hook-logs and other ephemeral state are managed elsewhere
+# (see `aw init`'s repoLocalIgnore manager).
+!scripts/aw-c4-bootstrap.sh
+!.codex/config.toml
+!.cursor/environment.json
+!.codex/scripts/
+!.codex/scripts/codex-web-bootstrap.sh
+!.claude/scripts/
+!.claude/scripts/claude-web-bootstrap.sh

package/c4/templates/manifest.json

@@ -0,0 +1,41 @@
+{
+  "version": 1,
+  "templates": [
+    {
+      "kind": "literal",
+      "src": "scripts/aw-c4-bootstrap.sh",
+      "dest": "scripts/aw-c4-bootstrap.sh",
+      "mode": "0755"
+    },
+    {
+      "kind": "literal",
+      "src": "codex/scripts/codex-web-bootstrap.sh",
+      "dest": ".codex/scripts/codex-web-bootstrap.sh",
+      "mode": "0755"
+    },
+    {
+      "kind": "literal",
+      "src": "claude/scripts/claude-web-bootstrap.sh",
+      "dest": ".claude/scripts/claude-web-bootstrap.sh",
+      "mode": "0755"
+    },
+    {
+      "kind": "literal",
+      "src": "cursor/environment.json",
+      "dest": ".cursor/environment.json",
+      "mode": "0644"
+    },
+    {
+      "kind": "interpolated",
+      "src": "codex/config.toml",
+      "dest": ".codex/config.toml",
+      "mode": "0644"
+    },
+    {
+      "kind": "managed-block",
+      "src": "gitignore-block.txt",
+      "dest": ".gitignore",
+      "marker": "cloud-bootstrap"
+    }
+  ]
+}

package/c4/templates/scripts/aw-c4-bootstrap.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# scripts/aw-c4-bootstrap.sh — single-entry cloud bootstrap for AW.
+#
+# Installs @ghl-ai/aw and runs `aw c4`, which handles ALL harness-specific
+# wiring (slim router card, hooks, MCP server, repo-root context, ECC bridge,
+# Codex prompt-injector, GitHub auth). Forward any extra args to `aw c4` so
+# `--dry-run` and `--diagnose` flow through untouched.
+#
+# Invoked from:
+#   - .cursor/environment.json::install        (passes --harness cursor-cloud)
+#   - .claude/scripts/claude-web-bootstrap.sh  (passes --harness claude-web)
+#   - .codex/scripts/codex-web-bootstrap.sh    (passes --harness codex-web)
+#
+# Override knobs (env):
+#   AW_PACKAGE   npm spec to install. Defaults to @ghl-ai/aw@latest. Override
+#                with @ghl-ai/aw@beta to opt into pre-release builds, or pin to
+#                @ghl-ai/aw@0.1.x for reproducible CI runs.
+set -Eeuo pipefail
+
+: "${GITHUB_PAT:?ERROR: Set GITHUB_PAT in your harness secrets UI before running aw c4}"
+
+# Ensure npm is on PATH. Cursor Cloud's install shell is non-interactive — nvm
+# is not auto-sourced, and Node may not be pre-installed at all. Walk common
+# locations first, then fall back to a NodeSource apt install (Ubuntu base).
+#
+# Hardening (vs the original):
+#   - Search nvm in multiple home dirs (current user, root, ubuntu).
+#   - Probe pre-installed Node binaries off the default PATH before falling
+#     through to apt — much faster when the agent snapshot ships Node in
+#     /usr/local/ or /opt/.
+#   - DEBIAN_FRONTEND=noninteractive prevents debconf prompts from hanging
+#     the apt configure step on a non-TTY shell.
+#   - Drop the >/dev/null on apt + NodeSource setup so progress is visible.
+#     The previous "silent + interactive" combination produced the canonical
+#     "looks frozen" symptom in pilot use after Cursor Cloud stopped shipping
+#     Node in their base image.
+#   - timeout 180 is the hard ceiling — fail fast with a clear error instead
+#     of hanging the whole agent boot.
+ensure_npm() {
+  command -v npm >/dev/null 2>&1 && return 0
+
+  for nvm_dir in "${NVM_DIR:-}" "$HOME/.nvm" /root/.nvm /home/ubuntu/.nvm; do
+    [ -z "$nvm_dir" ] && continue
+    if [ -s "$nvm_dir/nvm.sh" ]; then
+      export NVM_DIR="$nvm_dir"
+      # shellcheck source=/dev/null
+      . "$NVM_DIR/nvm.sh"
+      nvm use --lts >/dev/null 2>&1 || nvm install --lts >/dev/null 2>&1 || true
+      command -v npm >/dev/null 2>&1 && return 0
+    fi
+  done
+
+  for node_bin in /usr/local/bin/node /opt/node/bin/node; do
+    if [ -x "$node_bin" ]; then
+      export PATH="$(dirname "$node_bin"):$PATH"
+      command -v npm >/dev/null 2>&1 && return 0
+    fi
+  done
+
+  if command -v sudo >/dev/null 2>&1 && command -v apt-get >/dev/null 2>&1; then
+    echo "[aw-c4-bootstrap] npm not found; installing Node 20 via NodeSource (1-2 min over corporate proxy)"
+    export DEBIAN_FRONTEND=noninteractive
+    if ! timeout 180 bash -c 'curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -'; then
+      echo "[aw-c4-bootstrap] FATAL: NodeSource setup script timed out or failed after 180s" >&2
+      echo "[aw-c4-bootstrap]        Preinstall Node 20+ in the agent snapshot, or check proxy reachability." >&2
+      exit 1
+    fi
+    if ! timeout 180 sudo -E apt-get install -y nodejs; then
+      echo "[aw-c4-bootstrap] FATAL: apt-get install nodejs timed out or failed after 180s" >&2
+      exit 1
+    fi
+  fi
+
+  command -v npm >/dev/null 2>&1 || {
+    echo "[aw-c4-bootstrap] FATAL: npm not available; preinstall Node 20+ in the harness snapshot" >&2
+    exit 1
+  }
+}
+
+ensure_npm
+
+# Codex Cloud (and other corporate-MITM cloud agents) intercept HTTPS via an
+# Envoy-style proxy with a private CA at /usr/local/share/ca-certificates/.
+# curl/git/npm read the system CA bundle and Just Work, but Node uses its
+# own bundle. Bridging requires NODE_EXTRA_CA_CERTS pointed at the MITM CA;
+# without it, `aw c4`'s preflight `fetch()` calls fail with TLS errors even
+# when curl + git ls-remote succeed against the same hosts.
+ENVOY_CA="/usr/local/share/ca-certificates/envoy-mitmproxy-ca-cert.crt"
+if [ -f "$ENVOY_CA" ] && [ -z "${NODE_EXTRA_CA_CERTS:-}" ]; then
+  export NODE_EXTRA_CA_CERTS="$ENVOY_CA"
+  echo "[aw-c4-bootstrap] enabled NODE_EXTRA_CA_CERTS=$ENVOY_CA"
+fi
+
+AW_PACKAGE="${AW_PACKAGE:-@ghl-ai/aw@latest}"
+
+echo "[aw-c4-bootstrap] installing ${AW_PACKAGE}"
+npm install -g "${AW_PACKAGE}"
+
+echo "[aw-c4-bootstrap] running: aw c4 $*"
+exec aw c4 "$@"

package/cli.mjs

@@ -28,6 +28,7 @@ const COMMANDS = {
   telemetry: () => import('./commands/telemetry.mjs').then(m => m.telemetryCommand),
   'slack-sim': () => import('./commands/slack-sim.mjs').then(m => m.slackSimCommand),
   c4:      () => import('./commands/c4.mjs').then(m => m.c4Command),
+  'init-repo': () => import('./commands/init-repo.mjs').then(m => m.initRepoCommand),
 };
 
 function parseArgs(argv) {
@@ -85,6 +86,7 @@ function printHelp() {
     cmd('aw init --namespace <team/sub-team>', 'Add a team namespace (optional)'),
     `  ${chalk.dim('Teams: platform, revex, mobile, commerce, leadgen, crm, marketplace, ai')}`,
     `  ${chalk.dim('Example: aw init --namespace revex/courses')}`,
+    cmd('aw init-repo', 'Scaffold cloud-bootstrap files (idempotent, --dry-run/--force/--diff)'),
 
     sec('Download'),
     cmd('aw pull', 'Re-pull all synced paths (like git pull)'),

package/commands/init-repo.mjs

@@ -0,0 +1,94 @@
+/**
+ * commands/init-repo.mjs — thin command-handler for `aw init-repo`.
+ *
+ * Translates the cli.mjs-parsed args object into engine options, calls
+ * c4/initRepo.mjs::initRepo(), and converts non-zero exit codes into
+ * CancelError throws so cli.mjs::run() preserves the telemetry-end and
+ * update-notify lifecycle (see G36 in spec.md::"Failure modes").
+ *
+ * Contract: spec.md::"libs/aw/commands/init-repo.mjs (command handler)"
+ */
+
+import { initRepo as defaultInitRepo } from '../c4/initRepo.mjs';
+import { CancelError } from '../fmt.mjs';
+
+const HELP = `
+aw init-repo — scaffold cloud-bootstrap files into the current repo
+
+Usage:
+  aw init-repo                  Scaffold 6 files (idempotent: skip-equal on byte match)
+  aw init-repo --dry-run        Preview actions without writing
+  aw init-repo --diff           Show diffs for locally-edited files (no write)
+  aw init-repo --force          Overwrite locally-edited files
+  aw init-repo --no-gitignore   Skip the .gitignore managed block (manage it by hand)
+
+Files written:
+  scripts/aw-c4-bootstrap.sh                  (unified bootstrap, executable)
+  .codex/scripts/codex-web-bootstrap.sh       (executable)
+  .codex/config.toml                          (codex hooks + per-repo trust)
+  .claude/scripts/claude-web-bootstrap.sh     (executable)
+  .cursor/environment.json                    (cursor cloud config)
+  .gitignore                                  (managed block — re-include of the 5 above)
+
+Exit codes:
+  0  All files created or already in sync
+  1  At least one file was locally edited (no write — pass --force or --diff)
+  2  Bad input (not a git repo, --namespace passed, missing templates)
+
+Notes:
+  - Idempotent. SHA-256 byte-compare per file. Re-running on a clean repo is a no-op.
+  - --namespace is NOT supported (use 'aw init --namespace <team>' for namespace pulls).
+  - .cursor/environment.json is a literal template; manually-added terminals or
+    run-on-build entries will be overwritten by --force. Use --diff first.
+  - .codex/config.toml has {{REPO_BASENAME}} substituted at scaffold time so the
+    [projects."/workspace/<repo>"] trust block matches Codex Cloud's checkout path.
+  - .gitignore: a marker-bracketed block re-includes the 5 cloud-bootstrap files
+    even when parent dirs are ignored. User content outside the markers is preserved.
+    A WARN with paste-ready fix is printed if pathological dir-only rules
+    (e.g. \`.codex/\`, \`.claude/\`) prevent re-include — change those to
+    \`.codex/*\` / \`.claude/*\` and re-run.
+`.trim();
+
+function printHelp() {
+  console.log(HELP);
+}
+
+/**
+ * Command-handler entry. Resolves on success, throws CancelError on
+ * non-zero engine exit. Never calls process.exit — that is cli.mjs's job.
+ *
+ * @param {object} args parsed flags from cli.mjs::parseArgs
+ * @param {{ initRepo?: Function, cwd?: () => string }} [deps] testability injection
+ */
+export async function initRepoCommand(args, deps = {}) {
+  const _initRepo = deps.initRepo ?? defaultInitRepo;
+  const _cwd = deps.cwd ?? (() => process.cwd());
+
+  if (args['--help']) {
+    printHelp();
+    return;
+  }
+
+  // v1: --namespace is not part of init-repo. Reject early so users don't
+  // assume init-repo will fan out a registry pull on top of scaffolding.
+  if (args['--namespace']) {
+    throw new CancelError(
+      `aw init-repo: --namespace is not supported. ` +
+        `init-repo only scaffolds the 4 cloud-bootstrap files. ` +
+        `Use 'aw init --namespace <team>' for namespace pulls.`,
+      { exitCode: 2 },
+    );
+  }
+
+  const result = _initRepo({
+    repoRoot: _cwd(),
+    dryRun: !!args['--dry-run'],
+    force: !!args['--force'],
+    diff: !!args['--diff'],
+    noGitignore: !!args['--no-gitignore'],
+  });
+
+  if (result.exitCode !== 0) {
+    throw new CancelError(result.summary, { exitCode: result.exitCode });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.44-beta.8",
+  "version": "0.1.44",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {