@harness-forge/cli 1.1.1 → 1.2.0

package/dist/application/recursive/run-structured-analysis.js

@@ -0,0 +1,261 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { ValidationError, ensureDir, exists, readJsonFile, readTextFile, writeTextFile } from "../../shared/index.js";
+import { appendRecursiveTraceEvent } from "../../infrastructure/recursive/trace-logger.js";
+import { loadRecursiveExecutionPolicy, loadRecursiveLanguageCapabilities, loadRecursiveSession, loadRecursiveSessionCapabilities, resolveRecursiveRunPaths, resolveRecursiveSessionPaths, writeRecursiveLanguageCapabilities, writeRecursiveStructuredRun } from "../../infrastructure/recursive/session-store.js";
+import { deriveRecursiveLanguageCapabilities } from "./derive-language-capabilities.js";
+function createRunId() {
+    return `RUN-${Date.now()}`;
+}
+function toPortablePath(value) {
+    return value.replaceAll("\\", "/");
+}
+function hashText(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}
+function createTraceEvent(sessionId, runId, status, notes) {
+    return {
+        eventId: `EVT-${Date.now()}`,
+        sessionId,
+        eventType: "tool-call",
+        occurredAt: new Date().toISOString(),
+        actor: "operator",
+        inputRefs: [runId],
+        outputRefs: [],
+        status,
+        budgetImpact: {
+            iterationsUsed: 1,
+            subcallsUsed: 0
+        },
+        notes
+    };
+}
+async function loadSessionContext(workspaceRoot, sessionId) {
+    const session = await loadRecursiveSession(workspaceRoot, sessionId);
+    if (!session) {
+        throw new ValidationError(`Recursive session not found: ${sessionId}`);
+    }
+    const executionPolicy = await loadRecursiveExecutionPolicy(workspaceRoot, sessionId);
+    if (!executionPolicy) {
+        throw new ValidationError(`Recursive execution policy not found for session ${sessionId}`);
+    }
+    const sessionCapabilities = await loadRecursiveSessionCapabilities(workspaceRoot, sessionId);
+    if (sessionCapabilities) {
+        return { session, executionPolicy, capabilities: sessionCapabilities };
+    }
+    const workspaceCapabilities = (await loadRecursiveLanguageCapabilities(workspaceRoot)) ?? (await deriveRecursiveLanguageCapabilities(workspaceRoot));
+    await writeRecursiveLanguageCapabilities(workspaceRoot, workspaceCapabilities);
+    return { session, executionPolicy, capabilities: workspaceCapabilities };
+}
+async function readSnippetSource(input) {
+    if (input.submissionMode === "stdin") {
+        if (!input.stdinContent?.trim()) {
+            throw new ValidationError("Structured analysis run with --stdin requires snippet content on stdin.");
+        }
+        return {
+            sourceText: input.stdinContent,
+            sourceRef: undefined
+        };
+    }
+    if (!input.sourceFile) {
+        throw new ValidationError("Structured analysis run with --file requires a snippet file path.");
+    }
+    const sourceRef = path.resolve(input.sourceFile);
+    return {
+        sourceText: await readTextFile(sourceRef),
+        sourceRef
+    };
+}
+async function importSnippetModule(snippetPath) {
+    const url = pathToFileURL(snippetPath);
+    url.searchParams.set("run", `${Date.now()}`);
+    return (await import(url.href));
+}
+function normalizeRequestedBehaviors(value) {
+    return [...new Set(value?.requestedBehaviors ?? [])].sort((left, right) => left.localeCompare(right));
+}
+function ensureRequestedBehaviorsAllowed(policy, requestedBehaviors) {
+    if (!policy.allowStructuredRun) {
+        throw new ValidationError(`Structured recursive runs are disabled by policy ${policy.policyId}.`);
+    }
+    const rejectedBehavior = requestedBehaviors.find((behavior) => policy.restrictedBehaviors.includes(behavior));
+    if (rejectedBehavior) {
+        throw new ValidationError(`Structured recursive run requested restricted behavior "${rejectedBehavior}".`);
+    }
+}
+function ensureSubmissionAllowed(policy, submissionMode) {
+    if (!policy.allowedInputs.includes(submissionMode)) {
+        throw new ValidationError(`Structured recursive runs do not allow ${submissionMode} input under policy ${policy.policyId}.`);
+    }
+}
+async function createStructuredContext(workspaceRoot, session, executionPolicy, capabilities, runId) {
+    const sessionPaths = resolveRecursiveSessionPaths(workspaceRoot, session.sessionId);
+    const handleMap = new Map(session.handles.map((handle) => [handle.handleId, handle]));
+    const scratchFile = path.join(sessionPaths.sessionDir, "scratch", `${runId}.md`);
+    await ensureDir(path.dirname(scratchFile));
+    const resolveHandle = (handleId) => {
+        const handle = handleMap.get(handleId);
+        if (!handle) {
+            throw new ValidationError(`Unknown recursive handle: ${handleId}`);
+        }
+        return path.resolve(workspaceRoot, handle.targetRef);
+    };
+    return {
+        sessionId: session.sessionId,
+        workspaceRoot,
+        session,
+        executionPolicy,
+        capabilities,
+        scratchPath: scratchFile,
+        tracePath: sessionPaths.tracePath,
+        handles: session.handles,
+        resolveHandle,
+        async readHandle(handleId) {
+            const resolved = resolveHandle(handleId);
+            if (!(await exists(resolved))) {
+                throw new ValidationError(`Referenced recursive handle is missing on disk: ${handleId}`);
+            }
+            if (resolved.endsWith(".json")) {
+                return readJsonFile(resolved);
+            }
+            return readTextFile(resolved);
+        },
+        async appendScratch(note) {
+            await fs.appendFile(scratchFile, `${note.trim()}\n`, "utf8");
+        },
+        async log(note) {
+            await appendRecursiveTraceEvent(sessionPaths.tracePath, createTraceEvent(session.sessionId, runId, "success", `[structured-run] ${note}`));
+        }
+    };
+}
+async function executeSnippetWithTimeout(fn, timeoutMs) {
+    let timeoutId;
+    try {
+        return await Promise.race([
+            fn(),
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new ValidationError(`Structured recursive run timed out after ${timeoutMs}ms.`)), timeoutMs);
+            })
+        ]);
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+function normalizeSnippetResult(value, runId) {
+    const findings = value?.findings ?? [];
+    const warnings = value?.warnings ?? [];
+    const diagnostics = value?.diagnostics ?? [];
+    const outcome = value?.outcome ?? (findings.length > 0 ? "success" : "degraded");
+    return {
+        runId,
+        outcome,
+        findings,
+        warnings,
+        diagnostics,
+        artifactsRead: value?.artifactsRead ?? [],
+        artifactsWritten: value?.artifactsWritten ?? [],
+        completedAt: new Date().toISOString()
+    };
+}
+function createMetaRecord(input) {
+    return {
+        runId: input.runId,
+        sessionId: input.sessionId,
+        submissionMode: input.submissionMode,
+        sourceRef: input.sourceRef,
+        status: input.status,
+        startedAt: input.startedAt,
+        completedAt: input.completedAt,
+        policyRef: input.policyRef,
+        resultRef: input.resultRef,
+        summary: input.summary,
+        warningCount: input.warningCount,
+        failureReason: input.failureReason,
+        ...(input.requestedBehaviors && input.requestedBehaviors.length > 0 ? { requestedBehaviors: input.requestedBehaviors } : {})
+    };
+}
+export async function runStructuredAnalysis(input) {
+    const { workspaceRoot, sessionId, submissionMode } = input;
+    const { session, executionPolicy, capabilities } = await loadSessionContext(workspaceRoot, sessionId);
+    ensureSubmissionAllowed(executionPolicy, submissionMode);
+    const existingRunCount = (await fs.readdir(resolveRecursiveSessionPaths(workspaceRoot, sessionId).runsDir).catch(() => [])).length;
+    if (existingRunCount >= executionPolicy.budgetSummary.maxRuns) {
+        throw new ValidationError(`Structured recursive run budget exhausted for session ${sessionId}; policy ${executionPolicy.policyId} allows at most ${executionPolicy.budgetSummary.maxRuns} runs.`);
+    }
+    const runId = createRunId();
+    const startedAt = new Date().toISOString();
+    const { sourceText, sourceRef } = await readSnippetSource(input);
+    const artifactPaths = resolveRecursiveRunPaths(workspaceRoot, sessionId, runId);
+    const sessionPaths = resolveRecursiveSessionPaths(workspaceRoot, sessionId);
+    await ensureDir(artifactPaths.runDir);
+    const snippetPath = path.join(artifactPaths.runDir, submissionMode === "stdin" ? "stdin-snippet.mjs" : "snippet.mjs");
+    await writeTextFile(snippetPath, sourceText);
+    try {
+        const snippetModule = await importSnippetModule(snippetPath);
+        const analyzer = snippetModule.analyze ?? snippetModule.default;
+        if (typeof analyzer !== "function") {
+            throw new ValidationError("Structured recursive snippets must export an async analyze(context) function or a default function.");
+        }
+        const requestedBehaviors = normalizeRequestedBehaviors(snippetModule.metadata);
+        ensureRequestedBehaviorsAllowed(executionPolicy, requestedBehaviors);
+        const context = await createStructuredContext(workspaceRoot, session, executionPolicy, capabilities, runId);
+        const rawResult = await executeSnippetWithTimeout(async () => analyzer(context), executionPolicy.budgetSummary.maxDurationMs);
+        const result = normalizeSnippetResult(rawResult, runId);
+        const resultRef = toPortablePath(path.relative(workspaceRoot, artifactPaths.resultPath) || artifactPaths.resultPath);
+        const meta = createMetaRecord({
+            runId,
+            sessionId,
+            submissionMode,
+            sourceRef: sourceRef ?? `sha256:${hashText(sourceText)}`,
+            policyRef: toPortablePath(path.relative(workspaceRoot, sessionPaths.executionPolicyPath)),
+            status: result.outcome === "degraded" ? "degraded" : "success",
+            summary: rawResult?.summary ?? (result.findings[0] ?? "Structured recursive analysis completed."),
+            resultRef,
+            requestedBehaviors,
+            warningCount: result.warnings.length,
+            startedAt,
+            completedAt: result.completedAt
+        });
+        await writeRecursiveStructuredRun(workspaceRoot, sessionId, { meta, result });
+        await appendRecursiveTraceEvent(sessionPaths.tracePath, createTraceEvent(sessionId, runId, "success", `Structured recursive run completed with outcome ${result.outcome}.`));
+        return { meta, result, artifactPaths };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const outcome = error instanceof ValidationError ? "rejection" : "failure";
+        const status = outcome === "rejection" ? "rejection" : "failure";
+        const result = {
+            runId,
+            outcome,
+            findings: [],
+            warnings: [],
+            diagnostics: [message],
+            artifactsRead: [],
+            artifactsWritten: [],
+            completedAt: new Date().toISOString()
+        };
+        const meta = createMetaRecord({
+            runId,
+            sessionId,
+            submissionMode,
+            sourceRef: sourceRef ?? `sha256:${hashText(sourceText)}`,
+            policyRef: toPortablePath(path.relative(workspaceRoot, sessionPaths.executionPolicyPath)),
+            status,
+            summary: "Structured recursive analysis did not complete successfully.",
+            resultRef: toPortablePath(path.relative(workspaceRoot, artifactPaths.resultPath)),
+            warningCount: 0,
+            failureReason: message,
+            startedAt,
+            completedAt: result.completedAt
+        });
+        await writeRecursiveStructuredRun(workspaceRoot, sessionId, { meta, result });
+        await appendRecursiveTraceEvent(sessionPaths.tracePath, createTraceEvent(sessionId, runId, "failed", `Structured recursive run failed: ${message}`));
+        return { meta, result, artifactPaths };
+    }
+}
+//# sourceMappingURL=run-structured-analysis.js.map

package/dist/application/recursive/run-structured-analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-structured-analysis.js","sourceRoot":"","sources":["../../../src/application/recursive/run-structured-analysis.ts"],"names":[],"mappings":"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"}

package/dist/application/runtime/command-catalog.d.ts

@@ -2,10 +2,26 @@ export interface AgentCommandCatalog {
     generatedAt: string;
     packageName: string;
     packageVersion: string;
+    executionModes: Array<{
+        id: string;
+        platform: "any" | "windows" | "posix";
+        commandPrefix: string;
+        whenToUse: string;
+    }>;
+    preferredExecutionOrder: string[];
     cliCommands: Array<{
+        id: string;
         command: string;
         description: string;
     }>;
+    agentSafeCliCommands: Array<{
+        id: string;
+        description: string;
+        variants: Array<{
+            modeId: string;
+            command: string;
+        }>;
+    }>;
     npmScripts: Record<string, string>;
     recommendedAgentCommands: string[];
 }

package/dist/application/runtime/command-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../../src/application/runtime/command-catalog.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,KAAK,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,wBAAwB,EAAE,MAAM,EAAE,CAAC;CACpC;AAED,wBAAsB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA6E/F;AAED,wBAAsB,wBAAwB,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAClG,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC,CAwBD"}
+{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../../src/application/runtime/command-catalog.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,KAAK,CAAC;QACpB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,OAAO,CAAC;QACtC,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IACH,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,WAAW,EAAE,KAAK,CAAC;QACjB,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,oBAAoB,EAAE,KAAK,CAAC;QAC1B,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,KAAK,CAAC;YACd,MAAM,EAAE,MAAM,CAAC;YACf,OAAO,EAAE,MAAM,CAAC;SACjB,CAAC,CAAC;KACJ,CAAC,CAAC;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,wBAAwB,EAAE,MAAM,EAAE,CAAC;CACpC;AAoJD,wBAAsB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAoC/F;AAED,wBAAsB,wBAAwB,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAClG,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC,CAoCD"}

package/dist/application/runtime/command-catalog.js

@@ -1,59 +1,154 @@
 import path from "node:path";
 import { GENERATED_DIR, readJsonFile, writeJsonFile, writeTextFile } from "../../shared/index.js";
+function buildExecutionModes() {
+    return [
+        {
+            id: "workspace-launcher-windows",
+            platform: "windows",
+            commandPrefix: ".\\.hforge\\generated\\bin\\hforge.cmd",
+            whenToUse: "Preferred in installed Windows workspaces when bare hforge is unavailable on PATH."
+        },
+        {
+            id: "workspace-launcher-powershell",
+            platform: "windows",
+            commandPrefix: ".\\.hforge\\generated\\bin\\hforge.ps1",
+            whenToUse: "Use in PowerShell when the CMD launcher is not the preferred shell entrypoint."
+        },
+        {
+            id: "workspace-launcher-posix",
+            platform: "posix",
+            commandPrefix: "./.hforge/generated/bin/hforge",
+            whenToUse: "Preferred in installed POSIX workspaces when bare hforge is unavailable on PATH."
+        },
+        {
+            id: "bare-hforge",
+            platform: "any",
+            commandPrefix: "hforge",
+            whenToUse: "Use when hforge is already available on PATH through shell setup or global install."
+        },
+        {
+            id: "npx-package",
+            platform: "any",
+            commandPrefix: "npx @harness-forge/cli",
+            whenToUse: "Fallback when no local launcher is available yet or when the agent is working before install."
+        }
+    ];
+}
+function buildCliCommands() {
+    return [
+        {
+            id: "interactive-front-door",
+            command: "hforge",
+            description: "Launch the interactive onboarding flow for new workspaces or the project hub for an existing .hforge runtime."
+        },
+        { id: "init-basic", command: "hforge init --root <repo> --json", description: "Initialize the hidden Harness Forge runtime and install-state surfaces for a workspace." },
+        {
+            id: "init-direct",
+            command: "hforge init --root <repo> --agent codex --setup-profile recommended --yes",
+            description: "Initialize a workspace directly without prompts and install one or more selected agent targets."
+        },
+        { id: "bootstrap", command: "hforge bootstrap --root <repo> --yes", description: "Autodetect supported agent runtimes in a repo and install the recommended Harness Forge surfaces." },
+        { id: "install", command: "hforge install --target <target> --root <repo> --yes", description: "Install for one explicit target with selected bundles, languages, frameworks, or capabilities." },
+        { id: "status", command: "hforge status --root <repo> --json", description: "Inspect the current install state." },
+        { id: "refresh", command: "hforge refresh --root <repo> --json", description: "Refresh the shared runtime summary and baseline artifacts for the installed targets." },
+        {
+            id: "update",
+            command: "hforge update --root <repo> --yes",
+            description: "Download the latest Harness Forge package and reapply managed surfaces without discarding preserved runtime state."
+        },
+        {
+            id: "upgrade",
+            command: "hforge upgrade --root <repo> --yes",
+            description: "Alias for the non-destructive update flow that refreshes managed surfaces from the latest package."
+        },
+        { id: "task-list", command: "hforge task list --root <repo> --json", description: "List task-runtime folders and the artifacts currently available for each task." },
+        { id: "task-inspect", command: "hforge task inspect <taskId> --root <repo> --json", description: "Inspect file-interest, impact-analysis, task-pack, and recursive linkage for one task." },
+        { id: "pack-inspect", command: "hforge pack inspect <taskId> --root <repo> --json", description: "Inspect the canonical task-pack artifact for one task." },
+        { id: "review", command: "hforge review --root <repo> --json", description: "Summarize runtime health, decision coverage, and stale task artifacts." },
+        { id: "export", command: "hforge export --root <repo> --json", description: "Export install-state, runtime index, doctor, and audit summaries for review or handoff." },
+        { id: "shell-setup", command: "hforge shell setup --yes", description: "Create user-level shims and update supported shell profiles so bare hforge is available on PATH." },
+        { id: "shell-status", command: "hforge shell status --json", description: "Inspect shell integration status, shim presence, profile wiring, and bare hforge availability." },
+        { id: "commands", command: "hforge commands --json", description: "List CLI commands and npm scripts that agents can use safely." },
+        { id: "recommend", command: "hforge recommend <repo> --json", description: "Inspect a repository and return evidence-backed recommendations." },
+        { id: "scan", command: "hforge scan <repo> --json", description: "Collect a human- or machine-readable baseline scan of a repository." },
+        { id: "cartograph", command: "hforge cartograph <repo> --json", description: "Build a repo map showing services, hotspots, ownership, and validation gaps." },
+        { id: "classify-boundaries", command: "hforge classify-boundaries <repo> --json", description: "Classify service and package boundaries for a repository." },
+        { id: "synthesize-instructions", command: "hforge synthesize-instructions <repo> --target codex --json", description: "Generate target-aware AGENTS and instruction-plan recommendations for a repository." },
+        { id: "target-inspect", command: "hforge target inspect <target> --json", description: "Inspect support, mappings, and capability notes for Codex, Claude Code, Cursor, or OpenCode." },
+        { id: "capabilities", command: "hforge capabilities --target codex --json", description: "Inspect the support matrix for one target or all targets." },
+        { id: "flow-status", command: "hforge flow status --root <repo> --json", description: "Inspect recoverable flow state." },
+        {
+            id: "recursive-plan",
+            command: 'hforge recursive plan "investigate cross-module issue" --task-id TASK-001 --root <repo> --json',
+            description: "Create a durable draft recursive session for difficult work without disturbing ordinary task flows."
+        },
+        {
+            id: "recursive-capabilities",
+            command: "hforge recursive capabilities --root <repo> --json",
+            description: "Inspect the canonical recursive structured-analysis capability map for the current workspace."
+        },
+        {
+            id: "recursive-run-file",
+            command: "hforge recursive run <sessionId> --file <snippet.mjs> --root <repo> --json",
+            description: "Submit one session-scoped structured analysis snippet from a file into a recursive session."
+        },
+        {
+            id: "recursive-run-stdin",
+            command: "hforge recursive run <sessionId> --stdin --root <repo> --json",
+            description: "Submit one session-scoped structured analysis snippet from standard input into a recursive session."
+        },
+        {
+            id: "recursive-runs",
+            command: "hforge recursive runs <sessionId> --root <repo> --json",
+            description: "List durable structured-analysis run records for one recursive session."
+        },
+        {
+            id: "recursive-inspect-run",
+            command: "hforge recursive inspect-run <sessionId> <runId> --root <repo> --json",
+            description: "Inspect one recorded structured-analysis run within a recursive session."
+        },
+        {
+            id: "recursive-inspect",
+            command: "hforge recursive inspect <sessionId> --root <repo> --json",
+            description: "Inspect recursive session identity, budget, handles, and current promotion state."
+        },
+        { id: "observability-summarize", command: "hforge observability summarize --root <repo> --json", description: "Summarize local observability events and effectiveness signals." },
+        { id: "observability-report", command: "hforge observability report <repo> --json", description: "Report local recommendation and maintenance effectiveness signals." },
+        { id: "parallel-plan", command: "hforge parallel plan <tasks.md> --root <repo> --json", description: "Create a parallel worktree shard plan from a task backlog." },
+        { id: "parallel-status", command: "hforge parallel status --root <repo> --json", description: "Inspect the current parallel execution plan status." },
+        { id: "parallel-merge-check", command: "hforge parallel merge-check --root <repo> --json", description: "Check whether the current shard plan is merge-ready." },
+        { id: "doctor", command: "hforge doctor --root <repo> --json", description: "Check installation health and missing managed surfaces." },
+        { id: "audit", command: "hforge audit --root <repo> --json", description: "Audit install state and package surface integrity." },
+        { id: "diff-install", command: "hforge diff-install --root <repo> --json", description: "Compare managed install expectations against the repo." },
+        { id: "template-validate", command: "hforge template validate --json", description: "Validate the shipped task and workflow templates." }
+    ];
+}
+function buildAgentSafeCliCommands(commands) {
+    const executionModes = buildExecutionModes();
+    return commands.map((entry) => {
+        const suffix = entry.command === "hforge" ? "" : entry.command.slice("hforge".length);
+        return {
+            id: entry.id,
+            description: entry.description,
+            variants: executionModes.map((mode) => ({
+                modeId: mode.id,
+                command: `${mode.commandPrefix}${suffix}`
+            }))
+        };
+    });
+}
 export async function loadAgentCommandCatalog(packageRoot) {
     const packageJson = await readJsonFile(path.join(packageRoot, "package.json"));
+    const cliCommands = buildCliCommands();
+    const executionModes = buildExecutionModes();
     return {
         generatedAt: new Date().toISOString(),
         packageName: packageJson.name,
         packageVersion: packageJson.version,
-        cliCommands: [
-            {
-                command: "hforge",
-                description: "Launch the interactive onboarding flow for new workspaces or the project hub for an existing .hforge runtime."
-            },
-            { command: "hforge init --root <repo> --json", description: "Initialize the hidden Harness Forge runtime and install-state surfaces for a workspace." },
-            {
-                command: "hforge init --root <repo> --agent codex --setup-profile recommended --yes",
-                description: "Initialize a workspace directly without prompts and install one or more selected agent targets."
-            },
-            { command: "hforge bootstrap --root <repo> --yes", description: "Autodetect supported agent runtimes in a repo and install the recommended Harness Forge surfaces." },
-            { command: "hforge install --target <target> --root <repo> --yes", description: "Install for one explicit target with selected bundles, languages, frameworks, or capabilities." },
-            { command: "hforge status --root <repo> --json", description: "Inspect the current install state." },
-            { command: "hforge refresh --root <repo> --json", description: "Refresh the shared runtime summary and baseline artifacts for the installed targets." },
-            { command: "hforge task list --root <repo> --json", description: "List task-runtime folders and the artifacts currently available for each task." },
-            { command: "hforge task inspect <taskId> --root <repo> --json", description: "Inspect file-interest, impact-analysis, task-pack, and recursive linkage for one task." },
-            { command: "hforge pack inspect <taskId> --root <repo> --json", description: "Inspect the canonical task-pack artifact for one task." },
-            { command: "hforge review --root <repo> --json", description: "Summarize runtime health, decision coverage, and stale task artifacts." },
-            { command: "hforge export --root <repo> --json", description: "Export install-state, runtime index, doctor, and audit summaries for review or handoff." },
-            { command: "hforge shell setup --yes", description: "Create user-level shims and update supported shell profiles so bare hforge is available on PATH." },
-            { command: "hforge shell status --json", description: "Inspect shell integration status, shim presence, profile wiring, and bare hforge availability." },
-            { command: "hforge commands --json", description: "List CLI commands and npm scripts that agents can use safely." },
-            { command: "hforge recommend <repo> --json", description: "Inspect a repository and return evidence-backed recommendations." },
-            { command: "hforge scan <repo> --json", description: "Collect a human- or machine-readable baseline scan of a repository." },
-            { command: "hforge cartograph <repo> --json", description: "Build a repo map showing services, hotspots, ownership, and validation gaps." },
-            { command: "hforge classify-boundaries <repo> --json", description: "Classify service and package boundaries for a repository." },
-            { command: "hforge synthesize-instructions <repo> --target codex --json", description: "Generate target-aware AGENTS and instruction-plan recommendations for a repository." },
-            { command: "hforge target inspect <target> --json", description: "Inspect support, mappings, and capability notes for Codex, Claude Code, Cursor, or OpenCode." },
-            { command: "hforge capabilities --target codex --json", description: "Inspect the support matrix for one target or all targets." },
-            { command: "hforge flow status --root <repo> --json", description: "Inspect recoverable flow state." },
-            {
-                command: 'hforge recursive plan "investigate cross-module issue" --task-id TASK-001 --root <repo> --json',
-                description: "Create a durable draft recursive session for difficult work without disturbing ordinary task flows."
-            },
-            {
-                command: "hforge recursive inspect <sessionId> --root <repo> --json",
-                description: "Inspect recursive session identity, budget, handles, and current promotion state."
-            },
-            { command: "hforge observability summarize --root <repo> --json", description: "Summarize local observability events and effectiveness signals." },
-            { command: "hforge observability report <repo> --json", description: "Report local recommendation and maintenance effectiveness signals." },
-            { command: "hforge parallel plan <tasks.md> --root <repo> --json", description: "Create a parallel worktree shard plan from a task backlog." },
-            { command: "hforge parallel status --root <repo> --json", description: "Inspect the current parallel execution plan status." },
-            { command: "hforge parallel merge-check --root <repo> --json", description: "Check whether the current shard plan is merge-ready." },
-            { command: "hforge doctor --root <repo> --json", description: "Check installation health and missing managed surfaces." },
-            { command: "hforge audit --root <repo> --json", description: "Audit install state and package surface integrity." },
-            { command: "hforge diff-install --root <repo> --json", description: "Compare managed install expectations against the repo." },
-            { command: "hforge template validate --json", description: "Validate the shipped task and workflow templates." }
-        ],
+        executionModes,
+        preferredExecutionOrder: ["workspace-launcher-windows", "workspace-launcher-powershell", "workspace-launcher-posix", "bare-hforge", "npx-package"],
+        cliCommands,
+        agentSafeCliCommands: buildAgentSafeCliCommands(cliCommands),
         npmScripts: packageJson.scripts ?? {},
         recommendedAgentCommands: [
             "npm run recommend:current",
@@ -84,9 +179,21 @@ export async function writeAgentCommandCatalog(workspaceRoot, packageRoot) {
         `Generated: ${catalog.generatedAt}`,
         `Package: ${catalog.packageName}@${catalog.packageVersion}`,
         "",
+        "## Agent execution order",
+        ...catalog.preferredExecutionOrder.map((modeId) => {
+            const mode = catalog.executionModes.find((entry) => entry.id === modeId);
+            return `- \`${mode.commandPrefix}\` - ${mode.whenToUse}`;
+        }),
+        "",
         "## CLI commands",
         ...catalog.cliCommands.map((entry) => `- \`${entry.command}\` - ${entry.description}`),
         "",
+        "## Agent-safe command variants",
+        ...catalog.agentSafeCliCommands.flatMap((entry) => [
+            `- \`${entry.id}\` - ${entry.description}`,
+            ...entry.variants.map((variant) => `  - [${variant.modeId}] \`${variant.command}\``)
+        ]),
+        "",
         "## Recommended npm scripts",
         ...catalog.recommendedAgentCommands.map((entry) => `- \`${entry}\``),
         "",

package/dist/application/runtime/command-catalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-catalog.js","sourceRoot":"","sources":["../../../src/application/runtime/command-catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command-catalog.js","sourceRoot":"","sources":["../../../src/application/runtime/command-catalog.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/maintenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/maintenance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkFlE"}
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/maintenance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuFlE"}

package/dist/cli/commands/maintenance.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import fs from "node:fs/promises";
 import { scanReferenceInstall } from "../../application/migration/scan-reference-install.js";
 import { reconcileState } from "../../application/install/reconcile-state.js";
+import { updateWorkspace } from "../../application/install/update-workspace.js";
 import { loadInstallState, saveInstallState } from "../../domain/state/install-state.js";
 import { INSTALL_STATE_FILE, DEFAULT_WORKSPACE_ROOT, STATE_DIR, ValidationError } from "../../shared/index.js";
 export function registerMaintenanceCommands(program) {
@@ -55,21 +56,25 @@ export function registerMaintenanceCommands(program) {
         }
         console.log(JSON.stringify({ dryRun: options.dryRun, files }, null, 2));
     });
-    program
-        .command("upgrade")
-        .option("--dry-run", "preview only", false)
-        .option("--root <root>", "workspace root", DEFAULT_WORKSPACE_ROOT)
-        .action(async (options) => {
-        const workspaceRoot = path.resolve(options.root);
-        const state = await loadInstallState(workspaceRoot);
-        const result = {
-            dryRun: options.dryRun,
-            target: state?.installedTargets[0] ?? null,
-            bundles: state?.installedBundles ?? [],
-            recommendation: state ? "Run install again with the current target and bundle set to refresh shipped assets." : "No existing install state found."
-        };
-        console.log(JSON.stringify(result, null, 2));
-    });
+    const registerWorkspaceUpdateCommand = (name) => {
+        program
+            .command(name)
+            .option("--dry-run", "preview only", false)
+            .option("--root <root>", "workspace root", DEFAULT_WORKSPACE_ROOT)
+            .option("--package-tag <tag>", "npm dist-tag or version to install before reapplying managed surfaces", "latest")
+            .option("--yes", "apply the update instead of previewing it", false)
+            .action(async (options) => {
+            const workspaceRoot = path.resolve(options.root);
+            const result = await updateWorkspace({
+                workspaceRoot,
+                packageTag: options.packageTag,
+                dryRun: options.dryRun || !options.yes
+            });
+            console.log(JSON.stringify(result, null, 2));
+        });
+    };
+    registerWorkspaceUpdateCommand("upgrade");
+    registerWorkspaceUpdateCommand("update");
     program
         .command("migrate")
         .option("--root <root>", "workspace root", DEFAULT_WORKSPACE_ROOT)