@smartmemory/compose 0.2.32-beta → 0.2.34-beta

package/bin/compose.js

@@ -16,6 +16,7 @@ import { spawn, spawnSync } from 'child_process'
 import { fileURLToPath } from 'url'
 import { findProjectRoot } from '../server/find-root.js'
 import { resolveWorkspace, getWorkspaceFlag } from '../lib/resolve-workspace.js'
+import { resolvePort } from '../lib/resolve-port.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const PACKAGE_ROOT = resolve(__dirname, '..')
@@ -1167,15 +1168,15 @@ if (cmd === 'roadmap') {
     if (res.pushed.length === 0) {
       console.log(`No external trackers to push (${res.scanned} push-opted link(s) checked, ${res.unchanged} already in sync).`)
     } else {
-      console.log(`${apply ? 'Pushed' : 'Would push'} ${res.pushed.length} external tracker(s):`)
-      for (const s of res.pushed) console.log(`  ${s.code}  github ${s.target}: ${s.from} → ${s.to} (${verb})`)
+      console.log(`${apply ? 'Pushed' : 'Would push'} ${res.pushed.length} external target(s):`)
+      for (const s of res.pushed) console.log(`  ${s.code}  ${s.provider} ${s.target}: ${s.summary} (${verb})`)
     }
     if (res.skipped.length > 0) {
       console.log(`\nSkipped ${res.skipped.length} link(s):`)
-      for (const s of res.skipped) console.log(`  ${s.code}  github ${s.target}: ${s.reason}`)
+      for (const s of res.skipped) console.log(`  ${s.code}  ${s.provider} ${s.target}: ${s.reason}`)
     }
     if (!apply && res.pushed.length > 0) {
-      console.log(`\nDry-run — pass --apply to write these changes to GitHub.`)
+      console.log(`\nDry-run — pass --apply to write these changes.`)
     }
     process.exit(0)
   }
@@ -2772,8 +2773,10 @@ if (cmd === 'build') {
     process.exit(1)
   }
 
-  // Resolve compose server URL (default http://localhost:3000)
-  const baseUrl = process.env.COMPOSE_URL || 'http://localhost:3000'
+  // Resolve compose server URL. Default must match the API server port
+  // (resolvePort: COMPOSE_PORT > PORT > 4001) — a stale :3000 here made every
+  // `compose loops` call fail with ECONNREFUSED in a default install.
+  const baseUrl = process.env.COMPOSE_URL || `http://127.0.0.1:${resolvePort()}`
 
   // COMP-WORKSPACE-HTTP T7: resolve workspace tolerantly so we can attach
   // X-Compose-Workspace-Id to the HTTP calls below. Loops CLI did not previously

package/contracts/feature-json.schema.json

@@ -95,7 +95,8 @@
                     "required": ["repo", "issue"],
                     "properties": {
                       "repo": { "pattern": "^[^\\s/#]+/[^\\s/#]+$" },
-                      "expect": { "enum": ["open", "closed"] }
+                      "expect": { "enum": ["open", "closed"] },
+                      "expect_labels": { "type": "array", "items": { "type": "string", "minLength": 1 } }
                     }
                   }
                 },
@@ -104,6 +105,7 @@
                   "then": {
                     "required": ["repo", "to_code"],
                     "properties": {
+                      "expect_labels": false,
                       "repo": {
                         "pattern": "^[A-Za-z0-9._-]+$",
                         "not": { "enum": [".", ".."] }
@@ -117,7 +119,8 @@
                   "then": {
                     "required": ["url"],
                     "properties": {
-                      "url": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9+\\-.]*://" }
+                      "url": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9+\\-.]*://" },
+                      "expect_labels": false
                     }
                   }
                 }

package/lib/feature-writer.js

@@ -844,7 +844,15 @@ function validateExternalArgs(args) {
     if (args.push != null && typeof args.push !== 'boolean') {
       throw new Error(`feature-writer: external github push must be boolean, got "${args.push}"`);
     }
+    if (args.expect_labels != null
+        && (!Array.isArray(args.expect_labels)
+            || !args.expect_labels.every((l) => typeof l === 'string' && l.length > 0))) {
+      throw new Error('feature-writer: external github expect_labels must be an array of non-empty strings');
+    }
   } else if (p === 'local') {
+    if (args.expect_labels != null) {
+      throw new Error('feature-writer: expect_labels is github-only (no labels on a local ref)');
+    }
     if (!args.repo || !args.to_code) {
       throw new Error('feature-writer: external local link requires repo + to_code');
     }
@@ -865,6 +873,9 @@ function validateExternalArgs(args) {
       );
     }
   } else if (XREF_URL_CLASS.has(p)) {
+    if (args.expect_labels != null) {
+      throw new Error('feature-writer: expect_labels is github-only (no labels on a url-class ref)');
+    }
     if (!args.url) {
       throw new Error(`feature-writer: external ${p} link (url-class) requires url`);
     }
@@ -923,6 +934,7 @@ async function linkFeatureExternal(cwd, args) {
     if (args.url != null) entry.url = args.url;
     if (args.expect != null) entry.expect = args.expect;
     if (args.push != null) entry.push = args.push;
+    if (args.expect_labels != null) entry.expect_labels = args.expect_labels;
     if (args.note) entry.note = args.note;
 
     if (matchIdx !== -1) links[matchIdx] = entry;

package/lib/resolve-port.js

@@ -1,7 +1,13 @@
 /**
  * Canonical port resolution for the Compose server.
- * Single source of truth: COMPOSE_PORT > PORT > 3001.
+ * Single source of truth: COMPOSE_PORT > PORT > 4001.
+ *
+ * The default MUST match server/index.js (`PORT || 4001`) and the supervisor,
+ * which start the API server on 4001. A stale 3001 default here silently sent
+ * every CLI probe / MCP lifecycle call / agent-hook to a dead port while the
+ * real server was alive on 4001 — gates fell back to readline, completions and
+ * loops failed with ECONNREFUSED.
  */
 export function resolvePort() {
-  return Number(process.env.COMPOSE_PORT) || Number(process.env.PORT) || 3001;
+  return Number(process.env.COMPOSE_PORT) || Number(process.env.PORT) || 4001;
 }

package/lib/xref-local.js

@@ -0,0 +1,42 @@
+/**
+ * xref-local.js — shared containment guard for `local`-provider external refs.
+ *
+ * A `local` external link names a sibling repo by a bare directory token
+ * (`repo`). Both the Pull resolver (xref-sync) and the Push writer (xref-push)
+ * must vet that token resolves to a DIRECT sibling of cwd before touching it —
+ * lexically first (no path separators, not `.`/`..`, parent must be cwd's
+ * parent), then by realpath to defeat a valid-named sibling symlinked outside
+ * the workspace parent. This is the security boundary for cross-repo operations.
+ *
+ * Scope: this helper covers ONLY the repo-token → siblingRoot containment. The
+ * caller still owns `to_code` presence checks and reading the sibling's own
+ * feature.json (the sibling may declare its own paths.features).
+ */
+
+import { resolve, dirname } from 'path';
+import { realpathSync } from 'fs';
+
+/**
+ * @param {string} cwd
+ * @param {string} repo  bare sibling directory token from the link
+ * @returns {{root: string} | {skipped: true, reason: string}}
+ */
+export function resolveSiblingRoot(cwd, repo) {
+  if (!repo) return { skipped: true, reason: 'incomplete local ref' };
+  const parentDir = resolve(cwd, '..');
+  const citedRoot = resolve(parentDir, String(repo));
+  // Lexical guard: a path separator, `.`/`..`, or a token whose parent isn't
+  // the workspace parent is not a direct sibling.
+  if (/[\\/]/.test(repo) || repo === '.' || repo === '..' || dirname(citedRoot) !== parentDir) {
+    return { skipped: true, reason: `local repo token "${repo}" is not a valid sibling` };
+  }
+  // Realpath guard: defeat a valid-named sibling symlinked outside the parent.
+  try {
+    if (dirname(realpathSync(citedRoot)) !== realpathSync(parentDir)) {
+      return { skipped: true, reason: `local repo "${repo}" escapes the workspace parent` };
+    }
+  } catch {
+    return { skipped: true, reason: `local target ${repo} not found` };
+  }
+  return { root: citedRoot };
+}

package/lib/xref-push.js

@@ -18,6 +18,7 @@
 import { readdirSync, existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { loadFeaturesDir } from './project-paths.js';
+import { resolveSiblingRoot } from './xref-local.js';
 
 const GITHUB_STATES = new Set(['open', 'closed']);
 
@@ -78,23 +79,28 @@ export async function defaultResolve(link, opts = {}) {
     }
     const state = r.body && r.body.state;
     if (!isGithubState(state)) return { skipped: true, reason: 'no parseable issue state' };
-    return { state };
+    // Normalize labels to a string[] of names — GitHub returns label OBJECTS
+    // ({name}); a labels-only link needs the names to compute the additive union.
+    const labels = (r.body && r.body.labels ? r.body.labels : []).map((l) => (l && l.name != null ? l.name : l));
+    return { state, labels };
   } catch (e) {
     return { skipped: true, reason: e && e.rateLimit ? 'rate limit' : (e && e.message) || 'resolution error' };
   }
 }
 
 /**
- * Write a github link's issue to `toState`. Uses updateIssueResult (status-
- * returning) so a non-2xx response degrades to a skip rather than a false
- * success. Returns { ok: true } or { skipped, reason }.
+ * Apply a `patch` (`{state?, labels?}`) to a github issue. Uses updateIssueResult
+ * (status-returning) so a non-2xx response degrades to a skip rather than a false
+ * success. A github PATCH replaces the whole label set, so `patch.labels` MUST be
+ * the full intended set (the additive union), never just the missing subset.
+ * Returns { ok: true } or { skipped, reason }.
  */
-export async function defaultWrite(link, toState, opts = {}) {
+export async function defaultWrite(link, patch, opts = {}) {
   if (!link.repo || link.issue == null) return { skipped: true, reason: 'incomplete github ref' };
   const c = await makeClient(link, opts);
   if (c.skipped) return c;
   try {
-    const r = await c.gh.updateIssueResult(link.issue, { state: toState });
+    const r = await c.gh.updateIssueResult(link.issue, patch);
     if (r.status < 200 || r.status >= 300) return { skipped: true, reason: `write HTTP ${r.status}` };
     return { ok: true };
   } catch (e) {
@@ -102,6 +108,49 @@ export async function defaultWrite(link, toState, opts = {}) {
   }
 }
 
+/**
+ * Pure additive label plan: which of `expectLabels` are missing from
+ * `currentNames`, and the full union to PATCH. Case-sensitive (GitHub label
+ * names are case-sensitive); never removes a label not in `expectLabels`.
+ *
+ * @param {string[]} currentNames
+ * @param {string[]} expectLabels
+ * @returns {{action: 'none'} | {action: 'add', add: string[], to: string[]}}
+ */
+export function planLabels(currentNames, expectLabels) {
+  if (!Array.isArray(expectLabels) || expectLabels.length === 0) return { action: 'none' };
+  const have = new Set(currentNames);
+  const missing = [...new Set(expectLabels)].filter((l) => !have.has(l));
+  if (missing.length === 0) return { action: 'none' };
+  return { action: 'add', add: missing, to: [...new Set([...currentNames, ...expectLabels])] };
+}
+
+/**
+ * Default local-status writer: delegate to the SIBLING repo's own
+ * setFeatureStatus so its transition policy + ROADMAP roundtrip apply. Never
+ * force/derived (the sibling's TRANSITIONS table governs). Throws on rejection;
+ * the caller degrade-skips.
+ */
+async function defaultSetStatus(siblingRoot, code, status) {
+  const { setFeatureStatus } = await import('./feature-writer.js');
+  return setFeatureStatus(siblingRoot, { code, status });
+}
+
+/**
+ * Resolve a local link's sibling current status, via the shared containment
+ * guard. Returns { state, root } or { skipped, reason }.
+ */
+function localResolve(link, cwd) {
+  if (!link.to_code) return { skipped: true, reason: 'incomplete local ref (no to_code)' };
+  const sib = resolveSiblingRoot(cwd, link.repo);
+  if (sib.skipped) return sib;
+  try {
+    const fjPath = join(sib.root, loadFeaturesDir(sib.root), link.to_code, 'feature.json');
+    if (!existsSync(fjPath)) return { skipped: true, reason: `local target ${link.repo}/${link.to_code} not found` };
+    return { state: JSON.parse(readFileSync(fjPath, 'utf8')).status || null, root: sib.root };
+  } catch (e) { return { skipped: true, reason: `unreadable local target: ${e.message}` }; }
+}
+
 /**
  * Push-write every eligible feature.json external link's target to match its
  * declared `expect`. Eligibility: github provider, `push === true`, and a valid
@@ -111,17 +160,22 @@ export async function defaultWrite(link, toState, opts = {}) {
  * @param {object} [opts]
  * @param {boolean} [opts.apply]       perform writes (default false = dry-run)
  * @param {string}  [opts.featuresDir]
- * @param {(link: object) => Promise<{state?: string, skipped?: boolean, reason?: string}>} [opts.resolve]
- * @param {(link: object, toState: string) => Promise<{ok?: boolean, skipped?: boolean, reason?: string}>} [opts.write]
- * @param {object} [opts.githubTransport]  injectable transport for the default resolve/write (tests)
- * @param {object} [opts.githubAuth]       injectable auth for the default resolve/write (tests)
+ * @param {(link: object) => Promise<{state?: string, labels?: string[], skipped?: boolean, reason?: string}>} [opts.resolve]
+ *   github resolve override (tests)
+ * @param {(link: object, patch: object) => Promise<{ok?: boolean, skipped?: boolean, reason?: string}>} [opts.write]
+ *   github write override (tests); patch is `{state?, labels?}`
+ * @param {object} [opts.githubTransport]  injectable transport for the default github resolve/write (tests)
+ * @param {object} [opts.githubAuth]       injectable auth for the default github resolve/write (tests)
+ * @param {(siblingRoot: string, code: string, status: string) => Promise<any>} [opts.setStatus]
+ *   local-status writer override (tests); default delegates to the sibling's setFeatureStatus
  * @returns {Promise<{pushed: Array, skipped: Array, unchanged: number, scanned: number}>}
  */
 export async function pushExternalRefs(cwd, opts = {}) {
   const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
   const clientOpts = { transport: opts.githubTransport ?? null, auth: opts.githubAuth };
-  const resolve = opts.resolve ?? ((link) => defaultResolve(link, clientOpts));
-  const write = opts.write ?? ((link, toState) => defaultWrite(link, toState, clientOpts));
+  const ghResolve = opts.resolve ?? ((link) => defaultResolve(link, clientOpts));
+  const ghWrite = opts.write ?? ((link, patch) => defaultWrite(link, patch, clientOpts));
+  const setStatus = opts.setStatus ?? defaultSetStatus;
   const apply = opts.apply === true;
   const dir = join(cwd, featuresDir);
 
@@ -129,6 +183,7 @@ export async function pushExternalRefs(cwd, opts = {}) {
   const skipped = [];
   let unchanged = 0;
   let scanned = 0;
+  const skip = (fj, link, reason) => skipped.push({ code: fj.code, provider: link.provider, target: targetLabel(link), reason });
 
   if (!existsSync(dir)) return { pushed, skipped, unchanged, scanned };
 
@@ -141,39 +196,80 @@ export async function pushExternalRefs(cwd, opts = {}) {
     if (!Array.isArray(fj.links)) continue;
 
     for (const link of fj.links) {
-      if (!link || link.kind !== 'external') continue;
-      // v1: github only, opt-in only, valid target state only.
-      if (link.provider !== 'github' || link.push !== true) continue;
-      scanned++;
-      if (!isGithubState(link.expect)) {
-        skipped.push({ code: fj.code, target: targetLabel(link), reason: `malformed expect "${link.expect}" (want open|closed)` });
-        continue;
-      }
+      if (!link || link.kind !== 'external' || link.push !== true) continue;
+      if (link.provider === 'github') {
+        // Eligible if it declares ANY intent (state and/or labels).
+        if (link.expect == null && link.expect_labels == null) continue;
+        scanned++;
+        // Malformed-state skip fires ONLY when a state intent is present —
+        // a labels-only link is still eligible.
+        if (link.expect != null && !isGithubState(link.expect)) {
+          skip(fj, link, `malformed expect "${link.expect}" (want open|closed)`);
+          continue;
+        }
+        const r = await ghResolve(link);
+        if (r.skipped) { skip(fj, link, r.reason); continue; }
 
-      const r = await resolve(link);
-      if (r.skipped) {
-        skipped.push({ code: fj.code, target: targetLabel(link), reason: r.reason });
-        continue;
-      }
-      const verdict = planPush(link, r.state ?? null);
-      if (verdict.action !== 'write') { unchanged++; continue; }
+        const statePlan = link.expect != null ? planPush(link, r.state ?? null) : { action: 'none' };
+        const labelsPlan = link.expect_labels != null ? planLabels(r.labels ?? [], link.expect_labels) : { action: 'none' };
+        if (statePlan.action !== 'write' && labelsPlan.action !== 'add') { unchanged++; continue; }
 
-      if (!apply) {
-        pushed.push({ code: fj.code, target: targetLabel(link), from: verdict.from, to: verdict.to });
-        continue;
-      }
-      const w = await write(link, verdict.to);
-      if (w.skipped) {
-        skipped.push({ code: fj.code, target: targetLabel(link), reason: w.reason });
-        continue;
+        const patch = {};
+        if (statePlan.action === 'write') patch.state = statePlan.to;
+        if (labelsPlan.action === 'add') patch.labels = labelsPlan.to; // FULL union, not the subset
+
+        if (apply) {
+          const w = await ghWrite(link, patch);
+          if (w.skipped) { skip(fj, link, w.reason); continue; }
+        }
+        pushed.push(githubRow(fj, link, statePlan, labelsPlan));
+      } else if (link.provider === 'local') {
+        if (link.expect == null) continue; // local has only the state aspect
+        scanned++;
+        const r = localResolve(link, cwd);
+        if (r.skipped) { skip(fj, link, r.reason); continue; }
+
+        const verdict = planPush(link, r.state ?? null);
+        if (verdict.action !== 'write') { unchanged++; continue; }
+
+        if (apply) {
+          try { await setStatus(r.root, link.to_code, link.expect); }
+          catch (e) { skip(fj, link, (e && e.message) || 'sibling write rejected'); continue; }
+        }
+        pushed.push({
+          code: fj.code, provider: 'local', target: targetLabel(link),
+          from: verdict.from, to: verdict.to,
+          state: { from: verdict.from, to: verdict.to },
+          summary: `status ${verdict.from} → ${verdict.to}`,
+        });
       }
-      pushed.push({ code: fj.code, target: targetLabel(link), from: verdict.from, to: verdict.to });
+      // other providers (url/reserved): not pushable, silently ignored.
     }
   }
 
   return { pushed, skipped, unchanged, scanned };
 }
 
+// Build a github result row. Keeps flat from/to (back-compat with -PUSH) for a
+// state change, plus structured state/labels aspects and a display summary.
+function githubRow(fj, link, statePlan, labelsPlan) {
+  const row = { code: fj.code, provider: 'github', target: targetLabel(link) };
+  const parts = [];
+  if (statePlan.action === 'write') {
+    row.from = statePlan.from;
+    row.to = statePlan.to;
+    row.state = { from: statePlan.from, to: statePlan.to };
+    parts.push(`state ${statePlan.from} → ${statePlan.to}`);
+  }
+  if (labelsPlan.action === 'add') {
+    row.labels = { added: labelsPlan.add };
+    parts.push(`labels +${labelsPlan.add.join(',')}`);
+  }
+  row.summary = parts.join('; ');
+  return row;
+}
+
 function targetLabel(link) {
+  if (link.provider === 'local') return `${link.repo}/${link.to_code}`;
   return `${link.repo}#${link.issue}`;
 }

package/lib/xref-sync.js

@@ -13,10 +13,11 @@
  * ROADMAP roundtrip fixed point. Resolution is injectable for testability.
  */
 
-import { readdirSync, existsSync, readFileSync, realpathSync } from 'fs';
-import { join, resolve as resolvePath, dirname } from 'path';
+import { readdirSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
 import { writeFeature } from './feature-json.js';
 import { loadFeaturesDir } from './project-paths.js';
+import { resolveSiblingRoot } from './xref-local.js';
 
 const RESOLVABLE = new Set(['github', 'local']);
 
@@ -71,20 +72,12 @@ async function defaultResolve(link, cwd, featuresDir) {
   if (link.provider === 'local') {
     // The target feature lives in a sibling repo; its status is the live state.
     if (!link.repo || !link.to_code) return { skipped: true, reason: 'incomplete local ref' };
-    // Containment guard (parity with feature-validator resolveLocalRef): the
-    // repo token must resolve to a DIRECT sibling of cwd — lexical check first,
-    // then realpath to defeat a valid-named sibling symlinked outside the parent.
-    const parentDir = resolvePath(cwd, '..');
-    const citedRoot = resolvePath(parentDir, String(link.repo));
-    if (/[\\/]/.test(link.repo) || link.repo === '.' || link.repo === '..'
-        || dirname(citedRoot) !== parentDir) {
-      return { skipped: true, reason: `local repo token "${link.repo}" is not a valid sibling` };
-    }
-    try {
-      if (dirname(realpathSync(citedRoot)) !== realpathSync(parentDir)) {
-        return { skipped: true, reason: `local repo "${link.repo}" escapes the workspace parent` };
-      }
-    } catch { return { skipped: true, reason: `local target ${link.repo} not found` }; }
+    // Containment guard (shared with xref-push): repo token must resolve to a
+    // DIRECT sibling of cwd. resolveSiblingRoot covers the repo-token guard ONLY;
+    // the to_code presence check above and the feature read below stay here.
+    const sib = resolveSiblingRoot(cwd, link.repo);
+    if (sib.skipped) return sib;
+    const citedRoot = sib.root;
     // Resolve the SIBLING's own features dir (it may have its own paths.features).
     try {
       const fjPath = join(citedRoot, loadFeaturesDir(citedRoot), link.to_code, 'feature.json');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.2.32-beta",
+  "version": "0.2.34-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",

package/server/agent-hooks.js

@@ -2,14 +2,16 @@
  * SDK hook callbacks for the Agent Server.
  *
  * These are in-process JavaScript functions passed to query() — not shell
- * scripts. They POST structured events to the api-server (port 3001), which
+ * scripts. They POST structured events to the api-server (port 4001), which
  * feeds SessionManager and VisionServer, preserving all Phase 3 monitoring.
  *
  * Single source of truth for TOOL_CATEGORIES (previously duplicated in
  * Terminal.jsx and vision-server.js).
  */
 
-const API_SERVER = `http://127.0.0.1:${process.env.PORT || 3001}`;
+import { resolvePort } from '../lib/resolve-port.js';
+
+const API_SERVER = `http://127.0.0.1:${resolvePort()}`;
 
 /** Semantic category for each Claude Code tool */
 export const TOOL_CATEGORIES = {

package/server/agent-server.js

@@ -6,7 +6,7 @@
  * User input arrives via POST — SSE is the right transport for a unidirectional
  * async iterator.
  *
- * Process isolation: this server only talks to api-server (3001) via SDK hooks.
+ * Process isolation: this server only talks to api-server (4001) via SDK hooks.
  * SessionManager and VisionServer require zero changes.
  */
 

package/server/compose-mcp-tools.js

@@ -114,6 +114,7 @@ export function assertTerminalStatusAuthorized(args, toolName, capsOverride) {
 }
 import { resolveWorkspace } from '../lib/resolve-workspace.js';
 import { discoverWorkspaces } from '../lib/discover-workspaces.js';
+import { resolvePort } from '../lib/resolve-port.js';
 
 export function getVisionFile() { return path.join(getDataDir(), 'vision-state.json'); }
 export function getSessionsFile() { return path.join(getDataDir(), 'sessions.json'); }
@@ -483,6 +484,16 @@ export async function toolRoadmapGraph({ project, out } = {}) {
   }
 }
 
+// COMP-ROADMAP-XREF-PUSH-2: programmatic push surface. Dry-run by default;
+// only links with push:true are eligible. Returns the small summary, never a
+// large body. apply:true performs the writes (github issue state/labels, local
+// sibling status via the sibling's own setFeatureStatus).
+export async function toolRoadmapXrefPush({ project, apply } = {}) {
+  const { pushExternalRefs } = await import('../lib/xref-push.js');
+  const cwd = project || getTargetRoot();
+  return pushExternalRefs(cwd, { apply: apply === true });
+}
+
 export async function toolRoadmapGraphCheck({ project, out } = {}) {
   const { checkRoadmapGraph } = await import('../lib/roadmap-graph/index.js');
   const cwd = project || getTargetRoot();
@@ -539,7 +550,7 @@ export async function toolBindSession({ featureCode, profile } = {}) {
 // ---------------------------------------------------------------------------
 
 function _getComposeApi() {
-  return `http://127.0.0.1:${process.env.COMPOSE_PORT || process.env.PORT || 3001}`;
+  return `http://127.0.0.1:${resolvePort()}`;
 }
 
 async function _postLifecycle(itemId, action, body) {
@@ -582,7 +593,7 @@ async function _postGate(gateId, action, body) {
  * COMP-WORKSPACE-HTTP T5.
  */
 async function _httpRequest(method, urlPath, body = null) {
-  const port = process.env.COMPOSE_PORT || process.env.PORT || 3001;
+  const port = resolvePort();
   const headers = { 'Content-Type': 'application/json' };
   if (_binding?.id) headers['X-Compose-Workspace-Id'] = _binding.id;
   let payload = null;

package/server/compose-mcp.js

@@ -61,6 +61,7 @@ import {
   toolValidateProject,
   toolRoadmapGraph,
   toolRoadmapGraphCheck,
+  toolRoadmapXrefPush,
   toolSetWorkspace,
   toolGetWorkspace,
   toolWriteCheckpoint,
@@ -407,6 +408,17 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'roadmap_xref_push',
+    description: 'COMP-ROADMAP-XREF-PUSH: write external trackers to match feature.json `expect=`/`expect_labels` declared intent (the write-side counterpart to roadmap xref-sync Pull). DRY-RUN by default — returns {pushed, skipped, unchanged, scanned} describing what WOULD change. Only links with `push: true` are eligible. apply:true performs the writes: github issue open/closed + additive labels (never removes; PR-backed refs skipped), and local refs via the sibling repo\'s own setFeatureStatus. Degrades (skips, never guesses) on offline/no-token/404/non-2xx/disallowed-transition. Returns a small summary, never a large body.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Project root path. Default: current workspace.' },
+        apply: { type: 'boolean', description: 'Perform the writes. Default false (dry-run — report only).' },
+      },
+    },
+  },
   {
     name: 'propose_followup',
     description: 'File a follow-up feature against a parent. Auto-numbers the next code in the parent\'s namespace (parent_code-N), adds the ROADMAP row, links surfaced_by from new → parent, and scaffolds design.md with a "## Why" rationale block. Idempotent on (parent_code, idempotency_key); resumes across partial failures via an inflight ledger.',
@@ -735,6 +747,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'validate_project':         result = await toolValidateProject(args); break;
       case 'roadmap_graph':            result = await toolRoadmapGraph(args); break;
       case 'roadmap_graph_check':      result = await toolRoadmapGraphCheck(args); break;
+      case 'roadmap_xref_push':        result = await toolRoadmapXrefPush(args); break;
       case 'propose_followup':         result = await toolProposeFollowup(args); break;
       case 'write_checkpoint':         result = await toolWriteCheckpoint(args); break;
       case 'compose_resume':           result = await toolComposeResume(args); break;

package/server/supervisor.js

@@ -1,9 +1,9 @@
 /**
  * Process supervisor for Compose.
  * Manages three independent processes:
- *   1. API server (port 3001) — Express + file-watcher + vision
- *   2. Agent server (port 3002) — SDK streaming, structured messages (Tier 1, immortal)
- *   3. Vite dev server (port 5173) — Frontend HMR
+ *   1. API server (port 4001) — Express + file-watcher + vision
+ *   2. Agent server (port 4002) — SDK streaming, structured messages (Tier 1, immortal)
+ *   3. Vite dev server (port 5195) — Frontend HMR
  *
  * Each process gets independent restart with exponential backoff.
  * If a process keeps crashing for > 1 minute, the supervisor gives up on it.