@ghl-ai/aw 0.1.52 → 0.1.54-beta.0

package/c4/eccRegistryBridge.mjs

@@ -13,8 +13,9 @@
  * On Codex Web, neither Claude's plugin marketplace nor Cursor's direct
  * `~/.cursor/skills/...` resolution applies. The only way Codex can see
  * ECC skills is if the registry path is populated. We bridge by symlinking
- * each ECC skill's SKILL.md into the registry layout, idempotently, without
- * clobbering any user-authored content already present at the target.
+ * each ECC skill's SKILL.md into the registry layout. The default mode keeps
+ * the original non-clobbering behavior. `preferEccSkills` only retargets
+ * existing symlinks; regular files are treated as user-owned and preserved.
  *
  * Also installs a fallback symlink at `<homeOf(awHome)>/.aw_registry` →
  * `<awHome>/.aw_registry` because some legacy hooks read from that path.
@@ -46,6 +47,26 @@ function isBrokenSymlink(path) {
   }
 }
 
+/** True iff `path` is a symlink that already points at `target`. */
+function isSymlinkTo(path, target) {
+  try {
+    const st = lstatSync(path);
+    if (!st.isSymbolicLink()) return false;
+    return readlinkSync(path) === target;
+  } catch {
+    return false;
+  }
+}
+
+/** True iff `path` is any symlink, regardless of where it points. */
+function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Install the fallback symlink `~/.aw_registry → ~/.aw/.aw_registry` if not
  * present and not blocked by an existing real directory. Best-effort.
@@ -82,7 +103,8 @@ function installRegistryFallbackLink(awHome) {
  *
  * Result shape:
  *   - linked   — skill names freshly bridged this call
- *   - skipped  — skill names whose registry target already existed (file or healthy symlink)
+ *   - skipped  — skill names whose registry target already existed and was preserved
+ *   - replaced — skill names whose registry target was replaced with the ECC symlink
  *   - broken   — skill directories that exist in eccHome/skills/ but have no SKILL.md
  *                (broken ECC layout — distinct from already-bridged so the orchestrator
  *                can surface a real diagnostic rather than treating it as success)
@@ -94,14 +116,18 @@ function installRegistryFallbackLink(awHome) {
  * @param {object} opts
  * @param {string} opts.awHome    Path of the AW home (e.g. ~/.aw).
  * @param {string} opts.eccHome   Path of the ECC home (e.g. ~/.aw-ecc).
+ * @param {boolean} [opts.preferEccSkills=false]
+ *   Retarget existing registry SKILL.md symlinks to ECC. Regular files are
+ *   never replaced because they may be user-owned overrides.
  * @returns {{
  *   linked: string[],
  *   skipped: string[],
+ *   replaced: string[],
  *   broken: string[],
  *   reason?: 'already-bridged' | 'ecc-missing'
  * }}
  */
-export function applyEccRegistryBridge({ awHome, eccHome } = {}) {
+export function applyEccRegistryBridge({ awHome, eccHome, preferEccSkills = false } = {}) {
   if (!awHome || !eccHome) {
     throw new Error('applyEccRegistryBridge: awHome and eccHome are required');
   }
@@ -113,6 +139,7 @@ export function applyEccRegistryBridge({ awHome, eccHome } = {}) {
 
   const linked = [];
   const skipped = [];
+  const replaced = [];
   const broken = [];
 
   let entries;
@@ -138,7 +165,9 @@ export function applyEccRegistryBridge({ awHome, eccHome } = {}) {
     const targetDir = join(awHome, '.aw_registry/platform/core/skills', name);
     const target = join(targetDir, 'SKILL.md');
 
-    // If target already exists and is a healthy file/symlink, leave it alone.
+    // If target already exists and is healthy, preserve regular files. The
+    // optional preference mode may only retarget generated symlinks; it must
+    // not delete user-owned registry files.
     let targetExists = false;
     try {
       lstatSync(target);
@@ -148,7 +177,29 @@ export function applyEccRegistryBridge({ awHome, eccHome } = {}) {
     }
 
     if (targetExists && !isBrokenSymlink(target)) {
-      skipped.push(name);
+      if (isSymlinkTo(target, source)) {
+        skipped.push(name);
+        continue;
+      }
+
+      if (!preferEccSkills || !isSymlink(target)) {
+        skipped.push(name);
+        continue;
+      }
+
+      try {
+        unlinkSync(target);
+      } catch {
+        broken.push(name);
+        continue;
+      }
+
+      try {
+        symlinkSync(source, target);
+        replaced.push(name);
+      } catch {
+        broken.push(name);
+      }
       continue;
     }
 
@@ -169,12 +220,13 @@ export function applyEccRegistryBridge({ awHome, eccHome } = {}) {
 
   installRegistryFallbackLink(awHome);
 
-  const result = { linked, skipped, broken };
+  const result = { linked, skipped, replaced, broken };
   // Only flag 'already-bridged' when every well-formed skill was already linked
   // AND no broken skills exist — i.e. this run was a true no-op.
   if (
     skillDirCount > 0 &&
     linked.length === 0 &&
+    replaced.length === 0 &&
     broken.length === 0 &&
     skipped.length === skillDirCount
   ) {

package/commands/c4.mjs

@@ -10,6 +10,9 @@
  *   --dry-run   stops before step 6 (no npm install, no aw init, no harness writes).
  *   --diagnose  runs only steps 1, 16, 17, 18 — and ALWAYS exits 0
  *               (G7: report mode, not gate mode).
+ *   --skip-self-install or AW_C4_SKIP_SELF_INSTALL=1 skips only the
+ *               `npm install -g @ghl-ai/aw@latest` self-update step and uses
+ *               the aw binary already provided by the runtime image.
  *
  * Every barrel symbol used here is dependency-injected via the second
  * argument so the test in tests/c4/c4.command.test.mjs can exercise the
@@ -45,7 +48,14 @@ function normalizeArgs(input) {
     const out = { _positional: [] };
     for (let i = 0; i < input.length; i++) {
       const a = input[i];
-      if (a === '--dry-run' || a === '-v' || a === '--verbose' || a === '--diagnose' || a === '--skip-pull') {
+      if (
+        a === '--dry-run' ||
+        a === '-v' ||
+        a === '--verbose' ||
+        a === '--diagnose' ||
+        a === '--skip-pull' ||
+        a === '--skip-self-install'
+      ) {
         out[a] = true;
       } else if (a === '--harness') {
         out['--harness'] = input[i + 1];
@@ -109,6 +119,12 @@ function setupGitAuth({ token, c4, home, cwd }) {
   c4.ensureOriginRemote({ cwd });
 }
 
+function resolveCodexRouterSkillPath({ awHome, eccHome, existsSync = fsExistsSync }) {
+  const eccRouterSkillPath = join(eccHome, 'skills/using-aw-skills/SKILL.md');
+  if (existsSync(eccRouterSkillPath)) return eccRouterSkillPath;
+  return join(awHome, '.aw_registry/platform/core/skills/using-aw-skills/SKILL.md');
+}
+
 /* ─────────────────────────────────────────────────────────────────────────
  * Per-harness branch (step 10).
  *
@@ -117,7 +133,7 @@ function setupGitAuth({ token, c4, home, cwd }) {
  * marketplace / slim card) bubble up as thrown Errors.
  * ───────────────────────────────────────────────────────────────────────── */
 
-function runHarnessBranch({ harness, c4, home, eccHome, cwd, writer }) {
+function runHarnessBranch({ harness, c4, home, eccHome, cwd, writer, existsSync = fsExistsSync }) {
   if (harness === 'claude-web') {
     // Marketplace registration is non-fatal — the slim card is the routing
     // mechanism (state.json::resolved_decisions exit-code item 3 lists slim
@@ -138,7 +154,7 @@ function runHarnessBranch({ harness, c4, home, eccHome, cwd, writer }) {
     const awHome = join(home, '.aw');
     c4.applyEccRegistryBridge({ awHome, eccHome });
     c4.ensureCodexHooksFlag(home);
-    const routerSkillPath = join(awHome, '.aw_registry/platform/core/skills/using-aw-skills/SKILL.md');
+    const routerSkillPath = resolveCodexRouterSkillPath({ awHome, eccHome, existsSync });
     // Pass hookPath explicitly: defaultHookPath() reads os.homedir() at module
     // load time, which ignores the orchestrator's `home` (env.HOME). Without
     // this, installs land in the real ~/.codex even when HOME is overridden
@@ -350,10 +366,15 @@ export async function c4Command(rawArgs, overrides = {}) {
     return exit(0);
   }
 
-  // Step 6 — npm install -g @ghl-ai/aw@latest.
-  const npmRes = spawnSync('npm', ['install', '-g', '@ghl-ai/aw@latest'], { stdio: 'pipe' });
-  if (npmRes && npmRes.status !== 0) {
-    writer.stderr('[aw-c4] npm install -g @ghl-ai/aw@latest failed (non-fatal); using existing aw if present\n');
+  // Step 6 — npm install -g @ghl-ai/aw@latest unless the image owns AW.
+  const skipSelfInstall = args['--skip-self-install'] === true || env.AW_C4_SKIP_SELF_INSTALL === '1';
+  if (skipSelfInstall) {
+    writer.stdout('[aw-c4] self-install skipped; using runtime aw\n');
+  } else {
+    const npmRes = spawnSync('npm', ['install', '-g', '@ghl-ai/aw@latest'], { stdio: 'pipe' });
+    if (npmRes && npmRes.status !== 0) {
+      writer.stderr('[aw-c4] npm install -g @ghl-ai/aw@latest failed (non-fatal); using existing aw if present\n');
+    }
   }
 
   // Step 7 — aw init --silent.
@@ -374,7 +395,7 @@ export async function c4Command(rawArgs, overrides = {}) {
   // Step 10 — per-harness branch.
   let branch;
   try {
-    branch = runHarnessBranch({ harness, c4, home, eccHome, cwd, writer });
+    branch = runHarnessBranch({ harness, c4, home, eccHome, cwd, writer, existsSync: fs.existsSync });
   } catch (err) {
     writer.stderr(`[aw-c4] FATAL: harness branch (${harness}) failed: ${err?.message ?? err}\n`);
     return exit(1);

package/git.mjs

@@ -388,8 +388,17 @@ export async function fetchAndMerge(awHome, { silent = true } = {}) {
   // We avoid `merge --ff-only` and `merge --no-edit` entirely: both trigger a
   // git 2.46+ bug on blob:none + no-cone sparse-checkout repos that silently
   // drops bare-name patterns (e.g. "content", "CODEOWNERS") when HEAD advances.
-  try {
-    await exec(`git -C "${awHome}" rebase origin/${REGISTRY_BASE_BRANCH}`);
+  //
+  // --autostash: AW writes into the registry working tree from external
+  // sources (ensureAwRuntimeHook copies ~/.aw-ecc/.../session-start.sh into a
+  // tracked path; transformCursorAwRefs rewrites /aw: → /aw- through Cursor
+  // skill directory symlinks that resolve into .aw_registry/). When those
+  // versions drift, the working tree is dirty at rebase time and rebase
+  // refuses to run, silently aborting the entire pull. Autostash stashes the
+  // dirty bytes, rebases cleanly, and reapplies them — so the registry stays
+  // in sync even when external sources have leaked into the tracked tree.
+  try {
+    await exec(`git -C "${awHome}" rebase --autostash origin/${REGISTRY_BASE_BRANCH}`);
     updated = true;
     // Push branch rebase rewrites commit SHAs — force-push so origin/upload/...
     // stays in sync with the rebased local branch.  Without this, VS Code and
@@ -683,7 +692,10 @@ export function checkoutMain(awHome) {
  */
 export async function rebaseOntoOriginMain(awHome) {
   try {
-    await exec(`git -C "${awHome}" rebase origin/${REGISTRY_BASE_BRANCH}`);
+    // --autostash: see fetchAndMerge() above. Project-local worktrees see the
+    // same external-write patterns (runtime hook copy + Cursor symlink writes)
+    // and need the same dirty-tree tolerance here.
+    await exec(`git -C "${awHome}" rebase --autostash origin/${REGISTRY_BASE_BRANCH}`);
   } catch (e) {
     // Surface stderr so callers can show a meaningful message
     const stderr = e.stderr?.toString().trim() || e.stdout?.toString().trim() || e.message;

package/package.json

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