@lumenflow/core 1.3.6 → 1.4.0

package/README.md

@@ -68,6 +68,29 @@ const exists = await worktrees.exists('/path/to/worktree');
 await worktrees.remove('worktrees/operations-wu-123');
 ```
 
+### Agent Branch Patterns
+
+Check if a branch is an agent branch that can bypass worktree requirements. Patterns are fetched from a central registry with 7-day caching.
+
+```typescript
+import { isAgentBranch, getAgentPatterns } from '@lumenflow/core';
+
+// Check if branch can bypass worktree requirements (async, uses registry)
+if (await isAgentBranch('claude/session-12345')) {
+  console.log('Agent branch - bypass allowed');
+}
+
+// Get the current list of agent patterns
+const patterns = await getAgentPatterns();
+// ['agent/*', 'claude/*', 'codex/*', 'copilot/*', 'cursor/*', ...]
+
+// Synchronous version (uses local config only, no registry fetch)
+import { isAgentBranchSync } from '@lumenflow/core';
+const result = isAgentBranchSync('agent/task-123');
+```
+
+Protected branches (main, master, lane/\*) are **never** bypassed, regardless of patterns.
+
 ## API Reference
 
 ### GitAdapter

package/dist/agent-patterns-registry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Agent Patterns Registry
+ *
+ * Central registry for AI agent branch patterns (claude/*, codex/*, copilot/*, cursor/*, etc.)
+ * that bypass worktree requirements. Static JSON served from lumenflow.dev,
+ * cached locally for 7 days with fallback to defaults.
+ *
+ * @module agent-patterns-registry
+ */
+/** Default agent branch patterns (narrow: just agent/*) */
+export declare const DEFAULT_AGENT_PATTERNS: string[];
+/** Remote registry URL */
+export declare const REGISTRY_URL = "https://lumenflow.dev/registry/agent-patterns.json";
+/** Cache TTL: 7 days in milliseconds */
+export declare const CACHE_TTL_MS: number;
+/**
+ * Options for getAgentPatterns
+ */
+interface GetAgentPatternsOptions {
+    /** Override cache directory (default: ~/.lumenflow/cache) */
+    cacheDir?: string;
+    /** Fetch timeout in milliseconds (default: 5000) */
+    timeoutMs?: number;
+}
+/**
+ * Get the default cache directory
+ *
+ * @returns Path to cache directory (~/.lumenflow/cache or LUMENFLOW_HOME/cache)
+ */
+export declare function getCacheDir(): string;
+/**
+ * Get agent branch patterns from registry with caching
+ *
+ * Fetches patterns from remote registry, caches locally for 7 days,
+ * and falls back to defaults on failure.
+ *
+ * @param options - Options
+ * @returns Array of agent branch patterns (glob format)
+ *
+ * @example
+ * ```typescript
+ * const patterns = await getAgentPatterns();
+ * // ['claude/*', 'codex/*', 'copilot/*', 'cursor/*', 'agent/*']
+ * ```
+ */
+export declare function getAgentPatterns(options?: GetAgentPatternsOptions): Promise<string[]>;
+/**
+ * Clear the in-memory cache
+ *
+ * Used primarily for testing.
+ */
+export declare function clearCache(): void;
+export {};

package/dist/agent-patterns-registry.js

@@ -0,0 +1,190 @@
+/**
+ * Agent Patterns Registry
+ *
+ * Central registry for AI agent branch patterns (claude/*, codex/*, copilot/*, cursor/*, etc.)
+ * that bypass worktree requirements. Static JSON served from lumenflow.dev,
+ * cached locally for 7 days with fallback to defaults.
+ *
+ * @module agent-patterns-registry
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+/** Default agent branch patterns (narrow: just agent/*) */
+export const DEFAULT_AGENT_PATTERNS = ['agent/*'];
+/** Remote registry URL */
+export const REGISTRY_URL = 'https://lumenflow.dev/registry/agent-patterns.json';
+/** Cache TTL: 7 days in milliseconds */
+export const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** Cache file name */
+const CACHE_FILE_NAME = 'agent-patterns-cache.json';
+/** Default fetch timeout in milliseconds */
+const DEFAULT_TIMEOUT_MS = 5000;
+/** In-memory cache for patterns */
+let memoryCache = null;
+/** In-memory cache timestamp */
+let memoryCacheTime = 0;
+/**
+ * Get the default cache directory
+ *
+ * @returns Path to cache directory (~/.lumenflow/cache or LUMENFLOW_HOME/cache)
+ */
+export function getCacheDir() {
+    const lumenflowHome = process.env.LUMENFLOW_HOME;
+    if (lumenflowHome) {
+        return path.join(lumenflowHome, 'cache');
+    }
+    return path.join(os.homedir(), '.lumenflow', 'cache');
+}
+/**
+ * Validate registry response
+ *
+ * @param data - Data to validate
+ * @returns True if valid registry response
+ */
+function isValidRegistryResponse(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const obj = data;
+    if (!Array.isArray(obj.patterns))
+        return false;
+    if (!obj.patterns.every((p) => typeof p === 'string'))
+        return false;
+    return true;
+}
+/**
+ * Read cache from disk
+ *
+ * @param cacheDir - Cache directory
+ * @returns Cache data or null if not found/invalid
+ */
+function readCache(cacheDir) {
+    try {
+        const cacheFile = path.join(cacheDir, CACHE_FILE_NAME);
+        if (!fs.existsSync(cacheFile))
+            return null;
+        const content = fs.readFileSync(cacheFile, 'utf8');
+        const data = JSON.parse(content);
+        // Validate cache structure
+        if (!Array.isArray(data.patterns))
+            return null;
+        if (typeof data.fetchedAt !== 'number')
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write cache to disk
+ *
+ * @param cacheDir - Cache directory
+ * @param data - Data to cache
+ */
+function writeCache(cacheDir, data) {
+    try {
+        // Ensure cache directory exists
+        if (!fs.existsSync(cacheDir)) {
+            fs.mkdirSync(cacheDir, { recursive: true });
+        }
+        const cacheFile = path.join(cacheDir, CACHE_FILE_NAME);
+        fs.writeFileSync(cacheFile, JSON.stringify(data, null, 2));
+    }
+    catch {
+        // Fail silently - cache is optional
+    }
+}
+/**
+ * Fetch patterns from remote registry with timeout
+ *
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Registry response or null on failure
+ */
+async function fetchFromRegistry(timeoutMs) {
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        const response = await fetch(REGISTRY_URL, {
+            signal: controller.signal,
+            headers: {
+                Accept: 'application/json',
+                'User-Agent': 'lumenflow-core',
+            },
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        if (!isValidRegistryResponse(data)) {
+            return null;
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get agent branch patterns from registry with caching
+ *
+ * Fetches patterns from remote registry, caches locally for 7 days,
+ * and falls back to defaults on failure.
+ *
+ * @param options - Options
+ * @returns Array of agent branch patterns (glob format)
+ *
+ * @example
+ * ```typescript
+ * const patterns = await getAgentPatterns();
+ * // ['claude/*', 'codex/*', 'copilot/*', 'cursor/*', 'agent/*']
+ * ```
+ */
+export async function getAgentPatterns(options = {}) {
+    const { cacheDir = getCacheDir(), timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+    // Check memory cache first (fast path)
+    const now = Date.now();
+    if (memoryCache && now - memoryCacheTime < CACHE_TTL_MS) {
+        return memoryCache;
+    }
+    // Check disk cache
+    const diskCache = readCache(cacheDir);
+    if (diskCache && now - diskCache.fetchedAt < CACHE_TTL_MS) {
+        // Fresh disk cache - use it and update memory cache
+        memoryCache = diskCache.patterns;
+        memoryCacheTime = diskCache.fetchedAt;
+        return diskCache.patterns;
+    }
+    // Cache is stale or missing - try to fetch
+    const registryData = await fetchFromRegistry(timeoutMs);
+    if (registryData) {
+        // Update caches
+        const cacheData = {
+            version: registryData.version,
+            patterns: registryData.patterns,
+            fetchedAt: now,
+        };
+        writeCache(cacheDir, cacheData);
+        memoryCache = registryData.patterns;
+        memoryCacheTime = now;
+        return registryData.patterns;
+    }
+    // Fetch failed - try stale cache as fallback
+    if (diskCache) {
+        memoryCache = diskCache.patterns;
+        memoryCacheTime = diskCache.fetchedAt; // Keep stale time
+        return diskCache.patterns;
+    }
+    // No cache, no network - use defaults
+    return DEFAULT_AGENT_PATTERNS;
+}
+/**
+ * Clear the in-memory cache
+ *
+ * Used primarily for testing.
+ */
+export function clearCache() {
+    memoryCache = null;
+    memoryCacheTime = 0;
+}

package/dist/branch-check.d.ts

@@ -8,12 +8,34 @@
  */
 /**
  * Check if branch is an agent branch that can bypass worktree requirements.
- * Uses the existing config loader (which handles caching/validation).
+ *
+ * Uses the central registry for agent patterns (fetched from lumenflow.dev
+ * with 7-day cache), falling back to config patterns if specified, then
+ * to defaults.
+ *
+ * @param branch - Branch name to check
+ * @returns Promise<true> if branch matches agent patterns
+ *
+ * @example
+ * ```typescript
+ * if (await isAgentBranch('claude/session-123')) {
+ *   // Allow bypass for agent branch
+ * }
+ * ```
+ */
+export declare function isAgentBranch(branch: string | null | undefined): Promise<boolean>;
+/**
+ * Synchronous version of isAgentBranch for backwards compatibility.
+ *
+ * Uses only local config patterns or defaults - does NOT fetch from registry.
+ * Prefer async isAgentBranch() when possible.
  *
  * @param branch - Branch name to check
  * @returns True if branch matches agent patterns
+ *
+ * @deprecated Use async isAgentBranch() instead for registry support
  */
-export declare function isAgentBranch(branch: string | null | undefined): boolean;
+export declare function isAgentBranchSync(branch: string | null | undefined): boolean;
 /**
  * Check if headless mode is allowed (guarded).
  * Requires LUMENFLOW_HEADLESS=1 AND (LUMENFLOW_ADMIN=1 OR CI truthy OR GITHUB_ACTIONS truthy)

package/dist/branch-check.js

@@ -8,8 +8,7 @@
  */
 import micromatch from 'micromatch';
 import { getConfig } from './lumenflow-config.js';
-/** Default agent branch patterns (narrow: just agent/*) */
-const DEFAULT_AGENT_BRANCH_PATTERNS = ['agent/*'];
+import { getAgentPatterns, DEFAULT_AGENT_PATTERNS } from './agent-patterns-registry.js';
 /** Legacy protected branch (always protected regardless of mainBranch setting) */
 const LEGACY_PROTECTED = 'master';
 /**
@@ -36,12 +35,62 @@ function getProtectedBranches() {
 }
 /**
  * Check if branch is an agent branch that can bypass worktree requirements.
- * Uses the existing config loader (which handles caching/validation).
+ *
+ * Uses the central registry for agent patterns (fetched from lumenflow.dev
+ * with 7-day cache), falling back to config patterns if specified, then
+ * to defaults.
+ *
+ * @param branch - Branch name to check
+ * @returns Promise<true> if branch matches agent patterns
+ *
+ * @example
+ * ```typescript
+ * if (await isAgentBranch('claude/session-123')) {
+ *   // Allow bypass for agent branch
+ * }
+ * ```
+ */
+export async function isAgentBranch(branch) {
+    // Fail-closed: no branch = protected
+    if (!branch)
+        return false;
+    // Detached HEAD = protected (fail-closed)
+    if (branch === 'HEAD')
+        return false;
+    // Load config (uses existing loader with caching)
+    const config = getConfig();
+    const protectedBranches = getProtectedBranches();
+    // Protected branches are NEVER bypassed (mainBranch + 'master')
+    if (protectedBranches.includes(branch))
+        return false;
+    // LumenFlow lane branches require worktrees (uses config's laneBranchPrefix)
+    if (getLaneBranchPattern().test(branch))
+        return false;
+    // Get patterns: prefer config override, then registry, then defaults
+    let patterns;
+    if (config?.git?.agentBranchPatterns?.length > 0) {
+        // Config has explicit patterns - use those
+        patterns = config.git.agentBranchPatterns;
+    }
+    else {
+        // Fetch from registry (with caching and fallback to defaults)
+        patterns = await getAgentPatterns();
+    }
+    // Use micromatch for proper glob matching
+    return micromatch.isMatch(branch, patterns);
+}
+/**
+ * Synchronous version of isAgentBranch for backwards compatibility.
+ *
+ * Uses only local config patterns or defaults - does NOT fetch from registry.
+ * Prefer async isAgentBranch() when possible.
  *
  * @param branch - Branch name to check
  * @returns True if branch matches agent patterns
+ *
+ * @deprecated Use async isAgentBranch() instead for registry support
  */
-export function isAgentBranch(branch) {
+export function isAgentBranchSync(branch) {
     // Fail-closed: no branch = protected
     if (!branch)
         return false;
@@ -51,15 +100,16 @@ export function isAgentBranch(branch) {
     // Load config (uses existing loader with caching)
     const config = getConfig();
     const protectedBranches = getProtectedBranches();
-    const patterns = config?.git?.agentBranchPatterns?.length > 0
-        ? config.git.agentBranchPatterns
-        : DEFAULT_AGENT_BRANCH_PATTERNS;
     // Protected branches are NEVER bypassed (mainBranch + 'master')
     if (protectedBranches.includes(branch))
         return false;
     // LumenFlow lane branches require worktrees (uses config's laneBranchPrefix)
     if (getLaneBranchPattern().test(branch))
         return false;
+    // Use config patterns or defaults (no registry fetch in sync version)
+    const patterns = config?.git?.agentBranchPatterns?.length > 0
+        ? config.git.agentBranchPatterns
+        : DEFAULT_AGENT_PATTERNS;
     // Use micromatch for proper glob matching
     return micromatch.isMatch(branch, patterns);
 }

package/dist/cli/is-agent-branch.d.ts

@@ -3,6 +3,8 @@
  * CLI helper for bash hooks to check if branch is an agent branch.
  * Uses the same isAgentBranch() logic as TypeScript code.
  *
+ * Now async to support registry pattern lookup with fetch + cache.
+ *
  * Usage: node dist/cli/is-agent-branch.js [branch-name]
  * Exit codes: 0 = agent branch (allowed), 1 = not agent branch (protected)
  *

package/dist/cli/is-agent-branch.js

@@ -3,13 +3,22 @@
  * CLI helper for bash hooks to check if branch is an agent branch.
  * Uses the same isAgentBranch() logic as TypeScript code.
  *
+ * Now async to support registry pattern lookup with fetch + cache.
+ *
  * Usage: node dist/cli/is-agent-branch.js [branch-name]
  * Exit codes: 0 = agent branch (allowed), 1 = not agent branch (protected)
  *
  * @module cli/is-agent-branch
  */
 import { isAgentBranch } from '../branch-check.js';
-const branch = process.argv[2] || null;
-const result = isAgentBranch(branch);
-// Exit 0 = agent branch (truthy), Exit 1 = not agent branch
-process.exit(result ? 0 : 1);
+async function main() {
+    const branch = process.argv[2] || null;
+    const result = await isAgentBranch(branch);
+    // Exit 0 = agent branch (truthy), Exit 1 = not agent branch
+    process.exit(result ? 0 : 1);
+}
+main().catch((error) => {
+    console.error('Error checking agent branch:', error.message);
+    // Fail-closed: error = not allowed
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -43,6 +43,7 @@ export * from './lumenflow-config.js';
 export * from './lumenflow-config-schema.js';
 export * from './gates-config.js';
 export * from './branch-check.js';
+export * from './agent-patterns-registry.js';
 export * from './lumenflow-home.js';
 export * from './force-bypass-audit.js';
 export { LUMENFLOW_PATHS, BEACON_PATHS } from './wu-constants.js';

package/dist/index.js

@@ -65,6 +65,8 @@ export * from './lumenflow-config-schema.js';
 export * from './gates-config.js';
 // Branch check utilities
 export * from './branch-check.js';
+// WU-1082: Agent patterns registry (fetch + cache)
+export * from './agent-patterns-registry.js';
 // WU-1062: External plan storage
 export * from './lumenflow-home.js';
 // WU-1070: Force bypass audit logging

package/dist/micro-worktree.d.ts

@@ -27,6 +27,7 @@
  * @see {@link tools/wu-edit.mjs} - Spec edits (WU-1274)
  * @see {@link tools/initiative-create.mjs} - Initiative creation (WU-1439)
  */
+import type { GitAdapter } from './git-adapter.js';
 /**
  * Maximum retry attempts for ff-only merge when main moves
  *
@@ -34,6 +35,18 @@
  * concurrently. Each retry fetches latest main and rebases.
  */
 export declare const MAX_MERGE_RETRIES = 3;
+/**
+ * Environment variable name for LUMENFLOW_FORCE bypass
+ *
+ * WU-1081: Exported for use in micro-worktree push operations.
+ */
+export declare const LUMENFLOW_FORCE_ENV = "LUMENFLOW_FORCE";
+/**
+ * Environment variable name for LUMENFLOW_FORCE_REASON audit trail
+ *
+ * WU-1081: Exported for use in micro-worktree push operations.
+ */
+export declare const LUMENFLOW_FORCE_REASON_ENV = "LUMENFLOW_FORCE_REASON";
 /**
  * Default log prefix for micro-worktree operations
  *
@@ -135,6 +148,25 @@ export declare function formatFiles(files: any, worktreePath: any, logPrefix?: s
  * @throws {Error} If merge fails after all retries
  */
 export declare function mergeWithRetry(tempBranchName: any, microWorktreePath: any, logPrefix?: string): Promise<void>;
+/**
+ * Push using refspec with LUMENFLOW_FORCE to bypass pre-push hooks
+ *
+ * WU-1081: Micro-worktree pushes to origin/main need to bypass pre-push hooks
+ * because they operate from temp branches in /tmp directories, which would
+ * otherwise be blocked by hook validation.
+ *
+ * Sets LUMENFLOW_FORCE=1 and LUMENFLOW_FORCE_REASON during the push,
+ * then restores original environment values (even on error).
+ *
+ * @param {GitAdapter} gitAdapter - GitAdapter instance to use for push
+ * @param {string} remote - Remote name (e.g., 'origin')
+ * @param {string} localRef - Local ref to push (e.g., 'tmp/wu-claim/wu-123')
+ * @param {string} remoteRef - Remote ref to update (e.g., 'main')
+ * @param {string} reason - Audit reason for the LUMENFLOW_FORCE bypass
+ * @returns {Promise<void>}
+ * @throws {Error} If push fails (env vars still restored)
+ */
+export declare function pushRefspecWithForce(gitAdapter: GitAdapter, remote: string, localRef: string, remoteRef: string, reason: string): Promise<void>;
 /**
  * Execute an operation in a micro-worktree with full isolation
  *

package/dist/micro-worktree.js

@@ -40,6 +40,18 @@ import { BRANCHES, REMOTES, GIT_REFS, PKG_MANAGER, SCRIPTS, PRETTIER_FLAGS, STDI
  * concurrently. Each retry fetches latest main and rebases.
  */
 export const MAX_MERGE_RETRIES = 3;
+/**
+ * Environment variable name for LUMENFLOW_FORCE bypass
+ *
+ * WU-1081: Exported for use in micro-worktree push operations.
+ */
+export const LUMENFLOW_FORCE_ENV = 'LUMENFLOW_FORCE';
+/**
+ * Environment variable name for LUMENFLOW_FORCE_REASON audit trail
+ *
+ * WU-1081: Exported for use in micro-worktree push operations.
+ */
+export const LUMENFLOW_FORCE_REASON_ENV = 'LUMENFLOW_FORCE_REASON';
 /**
  * Default log prefix for micro-worktree operations
  *
@@ -344,6 +356,51 @@ export async function mergeWithRetry(tempBranchName, microWorktreePath, logPrefi
         }
     }
 }
+/**
+ * Push using refspec with LUMENFLOW_FORCE to bypass pre-push hooks
+ *
+ * WU-1081: Micro-worktree pushes to origin/main need to bypass pre-push hooks
+ * because they operate from temp branches in /tmp directories, which would
+ * otherwise be blocked by hook validation.
+ *
+ * Sets LUMENFLOW_FORCE=1 and LUMENFLOW_FORCE_REASON during the push,
+ * then restores original environment values (even on error).
+ *
+ * @param {GitAdapter} gitAdapter - GitAdapter instance to use for push
+ * @param {string} remote - Remote name (e.g., 'origin')
+ * @param {string} localRef - Local ref to push (e.g., 'tmp/wu-claim/wu-123')
+ * @param {string} remoteRef - Remote ref to update (e.g., 'main')
+ * @param {string} reason - Audit reason for the LUMENFLOW_FORCE bypass
+ * @returns {Promise<void>}
+ * @throws {Error} If push fails (env vars still restored)
+ */
+export async function pushRefspecWithForce(gitAdapter, remote, localRef, remoteRef, reason) {
+    // Save original env values
+    const originalForce = process.env[LUMENFLOW_FORCE_ENV];
+    const originalReason = process.env[LUMENFLOW_FORCE_REASON_ENV];
+    try {
+        // Set LUMENFLOW_FORCE for the push
+        process.env[LUMENFLOW_FORCE_ENV] = '1';
+        process.env[LUMENFLOW_FORCE_REASON_ENV] = reason;
+        // Perform the push
+        await gitAdapter.pushRefspec(remote, localRef, remoteRef);
+    }
+    finally {
+        // Restore original env values
+        if (originalForce === undefined) {
+            delete process.env[LUMENFLOW_FORCE_ENV];
+        }
+        else {
+            process.env[LUMENFLOW_FORCE_ENV] = originalForce;
+        }
+        if (originalReason === undefined) {
+            delete process.env[LUMENFLOW_FORCE_REASON_ENV];
+        }
+        else {
+            process.env[LUMENFLOW_FORCE_REASON_ENV] = originalReason;
+        }
+    }
+}
 /**
  * Execute an operation in a micro-worktree with full isolation
  *
@@ -401,8 +458,9 @@ export async function withMicroWorktree(options) {
         // Step 6: Push to origin (different paths for pushOnly vs standard)
         if (pushOnly) {
             // WU-1435: Push directly to origin/main without touching local main
+            // WU-1081: Use LUMENFLOW_FORCE to bypass pre-push hooks for micro-worktree pushes
             console.log(`${logPrefix} Pushing directly to ${REMOTES.ORIGIN}/${BRANCHES.MAIN} (push-only)...`);
-            await gitWorktree.pushRefspec(REMOTES.ORIGIN, tempBranchName, BRANCHES.MAIN);
+            await pushRefspecWithForce(gitWorktree, REMOTES.ORIGIN, tempBranchName, BRANCHES.MAIN, `micro-worktree push for ${operation} (automated)`);
             console.log(`${logPrefix} ✅ Pushed to ${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
             // Fetch to update remote tracking ref (FETCH_HEAD)
             console.log(`${logPrefix} Fetching ${REMOTES.ORIGIN}/${BRANCHES.MAIN}...`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/core",
-  "version": "1.3.6",
+  "version": "1.4.0",
   "description": "Core WU lifecycle tools for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -91,8 +91,8 @@
     "vitest": "^4.0.17"
   },
   "peerDependencies": {
-    "@lumenflow/memory": "1.3.6",
-    "@lumenflow/initiatives": "1.3.6"
+    "@lumenflow/memory": "1.4.0",
+    "@lumenflow/initiatives": "1.4.0"
   },
   "peerDependenciesMeta": {
     "@lumenflow/memory": {