@wix/pathgrade 1.0.25 → 1.0.27

package/dist/agents/cursor-scenario.d.ts

@@ -0,0 +1,20 @@
+import type { AgentSessionOptions } from '../types.js';
+import type { AcpToolNameNormalizer } from '../internal/direct-mcp-v2/acp-author-projector.js';
+import { attachAcpAuthorSession, type AcpAuthorSession } from '../internal/direct-mcp-v2/acp-author-session.js';
+import { startScenarioCoordinator, type PublicScenarioRuntimeFactory } from '../internal/direct-mcp-v2/public-scenario-runtime.js';
+import { resolveCursorExecutable } from '../internal/direct-mcp-v2/cursor-profile.js';
+export declare function setCursorScenarioSession(options: AgentSessionOptions, session: AcpAuthorSession): void;
+export declare function getCursorScenarioSession(options: AgentSessionOptions | undefined): AcpAuthorSession | undefined;
+/** Cursor's admitted ACP build exposes MCP calls only as the stable title `MCP: tool`. */
+export declare const normalizeCursorAcpToolName: AcpToolNameNormalizer;
+type CursorScenarioRuntimeDependencies = {
+    attachAcpAuthorSession: typeof attachAcpAuthorSession;
+    resolveCursorExecutable: typeof resolveCursorExecutable;
+    startScenarioCoordinator: typeof startScenarioCoordinator;
+};
+export type CursorScenarioRuntimeFactoryOptions = {
+    requestedModel?: string;
+};
+export declare function createPublicCursorScenarioRuntimeFactory(factoryOptions?: CursorScenarioRuntimeFactoryOptions, dependencyOverrides?: Partial<CursorScenarioRuntimeDependencies>): PublicScenarioRuntimeFactory;
+export declare const startPublicCursorScenarioRuntime: typeof import("../internal/direct-mcp-v2/public-scenario-runtime.js").startPublicClaudeScenarioRuntime;
+export {};

package/dist/agents/cursor-scenario.js

@@ -0,0 +1,96 @@
+import { attachAcpAuthorSession, } from '../internal/direct-mcp-v2/acp-author-session.js';
+import { startScenarioCoordinator, } from '../internal/direct-mcp-v2/public-scenario-runtime.js';
+import { CURSOR_ACP_AUTHOR_DARWIN_ARM64_LOCK, resolveCursorExecutable, } from '../internal/direct-mcp-v2/cursor-profile.js';
+import { mapCursorProviderEnvironment } from '../internal/direct-mcp-v2/cursor-direct-mcp.js';
+const scenarioSessions = new WeakMap();
+export function setCursorScenarioSession(options, session) {
+    if (scenarioSessions.has(options))
+        throw new Error('Cursor scenario session is already configured');
+    scenarioSessions.set(options, session);
+}
+export function getCursorScenarioSession(options) {
+    return options ? scenarioSessions.get(options) : undefined;
+}
+/** Cursor's admitted ACP build exposes MCP calls only as the stable title `MCP: tool`. */
+export const normalizeCursorAcpToolName = (title) => title === 'MCP: tool'
+    ? { action: 'mcp_tool_call', providerToolName: 'cursor_mcp_tool' }
+    : { action: 'unknown', providerToolName: title };
+const defaultDependencies = {
+    attachAcpAuthorSession,
+    resolveCursorExecutable,
+    startScenarioCoordinator,
+};
+export function createPublicCursorScenarioRuntimeFactory(factoryOptions = {}, dependencyOverrides = {}) {
+    if (factoryOptions.requestedModel !== undefined) {
+        throw new Error('Cursor Scenario V2 does not support model overrides until the ACP model field is admitted');
+    }
+    const deps = { ...defaultDependencies, ...dependencyOverrides };
+    return async function startPublicCursorScenarioRuntime(options) {
+        const environment = cursorScenarioEnvironment(options.environment);
+        const resolvedExecutable = await deps.resolveCursorExecutable(environment);
+        const coordinator = await deps.startScenarioCoordinator({
+            ...options,
+            provider: 'cursor',
+            attach: async (context) => deps.attachAcpAuthorSession({
+                provider: 'cursor',
+                context,
+                runtimeLock: CURSOR_ACP_AUTHOR_DARWIN_ARM64_LOCK,
+                resolvedExecutable,
+                cwd: options.workspacePath,
+                environment,
+                scanRoots: cursorScanRoots(options.workspacePath, environment),
+                normalizeToolName: normalizeCursorAcpToolName,
+            }),
+        });
+        let configuredOptions;
+        return {
+            configureSession(sessionOptions) {
+                if (sessionOptions.model) {
+                    throw new Error('Cursor Scenario V2 does not support model overrides until the ACP model field is admitted');
+                }
+                if (configuredOptions && configuredOptions !== sessionOptions) {
+                    throw new Error('Cursor Scenario V2 runtime is already configured for another session');
+                }
+                configuredOptions = sessionOptions;
+                setCursorScenarioSession(sessionOptions, coordinator.attachment);
+            },
+            beginTurn: coordinator.beginTurn,
+            settleTurn: coordinator.settleTurn,
+            failTurn: coordinator.failTurn,
+            evidence: coordinator.evidence,
+            async dispose() {
+                try {
+                    await coordinator.dispose();
+                }
+                finally {
+                    if (configuredOptions)
+                        scenarioSessions.delete(configuredOptions);
+                }
+            },
+        };
+    };
+}
+export const startPublicCursorScenarioRuntime = createPublicCursorScenarioRuntimeFactory();
+function cursorScenarioEnvironment(source) {
+    const environment = mapCursorProviderEnvironment(source);
+    for (const name of [
+        'HOME', 'TMPDIR', 'TMP', 'TEMP',
+        'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME',
+    ]) {
+        if (source[name])
+            environment[name] = source[name];
+    }
+    return environment;
+}
+function cursorScanRoots(workspacePath, environment) {
+    return [...new Set([
+            workspacePath,
+            environment.HOME,
+            environment.TMPDIR,
+            environment.TMP,
+            environment.TEMP,
+            environment.XDG_CONFIG_HOME,
+            environment.XDG_DATA_HOME,
+            environment.XDG_CACHE_HOME,
+        ].filter((path) => typeof path === 'string' && path.length > 0))];
+}

package/dist/agents/cursor.js

@@ -2,6 +2,7 @@ import { BaseAgent, getWorkspacePath } from '../types.js';
 import { TOOL_NAME_MAP, buildSummary, enrichSkillEvents } from '../tool-events.js';
 import { getVisibleAssistantMessage } from '../sdk/visible-turn.js';
 import { prependRuntimePolicies } from '../sdk/runtime-policy.js';
+import { getCursorScenarioSession } from './cursor-scenario.js';
 import { assertUnsupportedLiveMcpSafetyRuntime, mountMcpForCursor, } from '../providers/mcp-runtime-mounting.js';
 /**
  * Cursor tool_call discriminants observed in the discovery spike. Probed in
@@ -150,6 +151,25 @@ export function parseCursorStreamJson(stdout) {
 const CURSOR_EXECUTABLE = 'cursor-agent';
 export class CursorAgent extends BaseAgent {
     async createSession(runtime, runCommand, options) {
+        const scenarioSession = getCursorScenarioSession(options);
+        if (scenarioSession) {
+            if (options?.model) {
+                throw new Error('Cursor Scenario V2 does not support model overrides until the ACP model field is admitted');
+            }
+            let turnNumber = 0;
+            const runScenarioTurn = async (message) => {
+                const appliedRuntimePolicies = turnNumber === 0 ? [...(options?.runtimePolicies ?? [])] : [];
+                const effectiveMessage = appliedRuntimePolicies.length > 0
+                    ? prependRuntimePolicies(message, appliedRuntimePolicies, { agent: 'cursor' })
+                    : message;
+                const result = await scenarioSession.runTurn(effectiveMessage, ++turnNumber);
+                return { ...result, runtimePoliciesApplied: appliedRuntimePolicies };
+            };
+            return {
+                start: async ({ message }) => runScenarioTurn(message),
+                reply: async ({ message }) => runScenarioTurn(message),
+            };
+        }
         const workspacePath = getWorkspacePath(runtime);
         let sessionId;
         return {
@@ -221,6 +241,7 @@ export class CursorAgent extends BaseAgent {
             timedOut: result.timedOut,
             toolEvents,
             runtimePoliciesApplied: appliedRuntimePolicies,
+            ...(options?.model ? { resolvedModel: options.model } : {}),
             ...(parsed.tokenUsage
                 ? { inputTokens: parsed.tokenUsage.inputTokens, outputTokens: parsed.tokenUsage.outputTokens }
                 : {}),

package/dist/agents/opencode/scenario.d.ts

@@ -0,0 +1,25 @@
+import type { AgentSessionOptions, AgentTurnResult } from '../../types.js';
+import { attachAcpAuthorSession, type AttachAcpAuthorSessionOptions } from '../../internal/direct-mcp-v2/acp-author-session.js';
+import { type PublicScenarioRuntimeFactory } from '../../internal/direct-mcp-v2/public-scenario-runtime.js';
+export type OpenCodeScenarioRuntimeFactoryOptions = {
+    opencodeExecutable: string;
+    requestedModel?: string;
+};
+type OpenCodeScenarioRuntimePolicy = {
+    readonly model: string;
+    readonly oauth: boolean;
+    environment(): Record<string, string>;
+    beforeTurn(remainingMs: number): Promise<void>;
+    afterTurn(): Promise<void>;
+};
+export type OpenCodeScenarioRuntimeDependencies = {
+    attachAuthorSession(options: AttachAcpAuthorSessionOptions): ReturnType<typeof attachAcpAuthorSession>;
+    createRuntimePolicy(environment: Record<string, string>, requestedModel?: string): Promise<OpenCodeScenarioRuntimePolicy>;
+    assertCleanManagedHost(): Promise<void>;
+};
+export type OpenCodeScenarioSession = {
+    runTurn(message: string): Promise<AgentTurnResult>;
+};
+export declare function getOpenCodeScenarioSession(options: AgentSessionOptions): OpenCodeScenarioSession | undefined;
+export declare function createPublicOpenCodeScenarioRuntimeFactory(factoryOptions: OpenCodeScenarioRuntimeFactoryOptions, dependencyOverrides?: Partial<OpenCodeScenarioRuntimeDependencies>): PublicScenarioRuntimeFactory;
+export {};

package/dist/agents/opencode/scenario.js

@@ -0,0 +1,195 @@
+import * as path from 'node:path';
+import fs from 'fs-extra';
+import { removeSandboxRoot } from '../../providers/sandbox-lifecycle.js';
+import { attachAcpAuthorSession, } from '../../internal/direct-mcp-v2/acp-author-session.js';
+import { startScenarioCoordinator, } from '../../internal/direct-mcp-v2/public-scenario-runtime.js';
+import { OPENCODE_ACP_DARWIN_ARM64_RUNTIME_LOCK } from '../../internal/direct-mcp-v2/opencode-profile.js';
+import { OPENCODE_PERMISSION, OpenCodeRuntimePolicy } from './runtime-policy.js';
+import { assertCleanManagedOpenCodeHost } from './host-safety.js';
+import { DEFAULT_OPENCODE_MODEL, sanitizeOpenCodeToolName } from './contract.js';
+const defaultDependencies = {
+    attachAuthorSession: attachAcpAuthorSession,
+    createRuntimePolicy: OpenCodeRuntimePolicy.create,
+    assertCleanManagedHost: assertCleanManagedOpenCodeHost,
+};
+const configuredSessions = new WeakMap();
+export function getOpenCodeScenarioSession(options) {
+    return configuredSessions.get(options);
+}
+export function createPublicOpenCodeScenarioRuntimeFactory(factoryOptions, dependencyOverrides = {}) {
+    if (factoryOptions.requestedModel !== undefined) {
+        throw new Error(`OpenCode Scenario V2 does not support model overrides; use the default ${DEFAULT_OPENCODE_MODEL} model.`);
+    }
+    const dependencies = { ...defaultDependencies, ...dependencyOverrides };
+    return async (options) => {
+        const environment = definedEnvironment(options.environment);
+        if (!environment.ANTHROPIC_API_KEY?.trim()) {
+            throw new Error(`OpenCode Scenario V2 currently requires API-key authentication using the default model ${DEFAULT_OPENCODE_MODEL}.`);
+        }
+        await dependencies.assertCleanManagedHost();
+        await assertNoProjectConfig(options.workspacePath);
+        const xdgDirectories = isolatedOpenCodeDirectories(environment);
+        await Promise.all(xdgDirectories.map((directory) => fs.ensureDir(directory)));
+        let coordinator;
+        try {
+            const runtimePolicy = await dependencies.createRuntimePolicy(environment);
+            if (runtimePolicy.oauth || runtimePolicy.model !== DEFAULT_OPENCODE_MODEL) {
+                throw new Error(`OpenCode Scenario V2 currently requires API-key authentication using the default model ${DEFAULT_OPENCODE_MODEL}.`);
+            }
+            const providerEnvironment = buildScenarioEnvironment(environment, runtimePolicy, xdgDirectories);
+            const mcpToolNames = scenarioToolNames(options.artifact);
+            coordinator = await startScenarioCoordinator({
+                artifact: options.artifact,
+                workspacePath: options.workspacePath,
+                environment: {
+                    HOME: environment.HOME,
+                    TMPDIR: path.dirname(options.workspacePath),
+                },
+                onEvidence: options.onEvidence,
+                provider: 'opencode',
+                attach: (context) => dependencies.attachAuthorSession({
+                    provider: 'opencode',
+                    context,
+                    runtimeLock: OPENCODE_ACP_DARWIN_ARM64_RUNTIME_LOCK,
+                    resolvedExecutable: factoryOptions.opencodeExecutable,
+                    cwd: options.workspacePath,
+                    environment: providerEnvironment,
+                    scanRoots: scenarioScanRoots(options.workspacePath, providerEnvironment, xdgDirectories),
+                    normalizeToolName: (title) => normalizeOpenCodeToolName(title, mcpToolNames),
+                }),
+            });
+            let configuredOptions;
+            let disposed = false;
+            let nextTurnNumber = 0;
+            const scenarioSession = {
+                async runTurn(message) {
+                    if (disposed)
+                        throw new Error('OpenCode Scenario V2 session is disposed');
+                    const sessionOptions = configuredOptions;
+                    sessionOptions?.getAbortSignal?.()?.throwIfAborted();
+                    await runtimePolicy.beforeTurn(sessionOptions?.getRemainingMs?.() ?? 0);
+                    try {
+                        sessionOptions?.getAbortSignal?.()?.throwIfAborted();
+                        return await coordinator.attachment.runTurn(message, ++nextTurnNumber);
+                    }
+                    finally {
+                        await runtimePolicy.afterTurn();
+                    }
+                },
+            };
+            const attachedCoordinator = coordinator;
+            return {
+                configureSession(sessionOptions) {
+                    if (disposed)
+                        throw new Error('OpenCode Scenario V2 runtime is disposed');
+                    if (configuredOptions && configuredOptions !== sessionOptions) {
+                        throw new Error('OpenCode Scenario V2 runtime is already configured for another session');
+                    }
+                    configuredOptions = sessionOptions;
+                    configuredSessions.set(sessionOptions, scenarioSession);
+                },
+                beginTurn: attachedCoordinator.beginTurn,
+                settleTurn: attachedCoordinator.settleTurn,
+                failTurn: attachedCoordinator.failTurn,
+                evidence: attachedCoordinator.evidence,
+                async dispose() {
+                    if (disposed)
+                        return;
+                    disposed = true;
+                    const failures = [];
+                    try {
+                        await attachedCoordinator.dispose();
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                    if (configuredOptions)
+                        configuredSessions.delete(configuredOptions);
+                    try {
+                        await Promise.all(xdgDirectories.map((directory) => removeSandboxRoot(directory)));
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                    if (failures.length > 0)
+                        throw new AggregateError(failures, 'OpenCode Scenario V2 cleanup failed');
+                },
+            };
+        }
+        catch (error) {
+            const cleanupErrors = [];
+            try {
+                await coordinator?.dispose();
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+            try {
+                await Promise.all(xdgDirectories.map((directory) => removeSandboxRoot(directory)));
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+            if (cleanupErrors.length > 0) {
+                throw new AggregateError([error, ...cleanupErrors], 'OpenCode Scenario V2 setup and cleanup failed');
+            }
+            throw error;
+        }
+    };
+}
+function definedEnvironment(environment) {
+    return Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined));
+}
+function isolatedOpenCodeDirectories(environment) {
+    if (!environment.HOME)
+        throw new Error('OpenCode Scenario V2 requires a managed HOME');
+    return [
+        path.join(environment.HOME, '.local', 'share'),
+        path.join(environment.HOME, '.config'),
+        path.join(environment.HOME, '.local', 'state'),
+        path.join(environment.HOME, '.cache'),
+    ];
+}
+function buildScenarioEnvironment(environment, runtimePolicy, directories) {
+    const [data, config, state, cache] = directories;
+    const result = {
+        ...environment,
+        XDG_DATA_HOME: data,
+        XDG_CONFIG_HOME: config,
+        XDG_STATE_HOME: state,
+        XDG_CACHE_HOME: cache,
+        ...runtimePolicy.environment(),
+        OPENCODE_PERMISSION,
+    };
+    delete result.OPENCODE_CONFIG_CONTENT;
+    return result;
+}
+async function assertNoProjectConfig(workspacePath) {
+    for (const name of ['opencode.json', 'opencode.jsonc', '.opencode']) {
+        if (await fs.pathExists(path.join(workspacePath, name))) {
+            throw new Error(`OpenCode workspace configuration is not allowed: ${name}`);
+        }
+    }
+}
+function scenarioToolNames(artifact) {
+    return new Set(Object.entries(artifact.canonicalIr.servers).flatMap(([serverId, server]) => Object.keys(server.tools).map((toolId) => `${sanitizeOpenCodeToolName(serverId)}_${sanitizeOpenCodeToolName(toolId)}`)));
+}
+function normalizeOpenCodeToolName(title, mcpToolNames) {
+    if (mcpToolNames.has(title))
+        return { action: 'mcp_tool_call', providerToolName: title };
+    const nativeActions = {
+        bash: 'run_shell', read: 'read_file', write: 'write_file', edit: 'edit_file',
+        grep: 'search_code', glob: 'list_files', list: 'list_files', skill: 'use_skill',
+        todowrite: 'update_todos', lsp: 'search_code',
+    };
+    const action = nativeActions[title.toLowerCase()];
+    return { action: action ?? 'unknown', providerToolName: title };
+}
+function scenarioScanRoots(workspacePath, environment, xdgDirectories) {
+    return [...new Set([
+            path.dirname(workspacePath),
+            workspacePath,
+            environment.HOME,
+            ...xdgDirectories,
+        ].filter((entry) => typeof entry === 'string' && entry.length > 0))];
+}

package/dist/agents/opencode.js

@@ -6,13 +6,14 @@ import { buildSummary, enrichSkillEvents } from '../tool-events.js';
 import { collectSensitiveEnvValues, sanitizePersistenceValue, sanitizeToolEventResult, } from '../tool-event-results.js';
 import { readStagedMcpServers } from '../providers/mcp-config.js';
 import { removeSandboxRoot } from '../providers/sandbox-lifecycle.js';
-import { attachTurnResultSensitiveValues } from '../sdk/turn-result-secrets.js';
+import { attachTurnResultSensitiveValues, cloneTurnResultWithSensitiveValues } from '../sdk/turn-result-secrets.js';
 import { attachOriginalMcpInput } from '../sdk/mcp-event-input.js';
 import { attachToolEventSensitiveValues } from '../sdk/tool-event-secrets.js';
 import { currentOpenCodePlatformKey, OPENCODE_RUNTIME_LOCK, } from './opencode/contract.js';
 import { OpenCodeRuntimePolicy, OPENCODE_PERMISSION } from './opencode/runtime-policy.js';
 import { killOpenCodeProcessGroup, registerOpenCodeProcessGroup, unregisterOpenCodeProcessGroup, } from './opencode/process-groups.js';
 import { assertCleanManagedOpenCodeHost, sha256File } from './opencode/host-safety.js';
+import { getOpenCodeScenarioSession } from './opencode/scenario.js';
 export { assertCleanManagedOpenCodeHost, managedOpenCodeConfigPaths } from './opencode/host-safety.js';
 const OUTPUT_CAP_BYTES = 16 * 1024 * 1024;
 const NATIVE_TOOL_ACTIONS = {
@@ -450,7 +451,9 @@ class OpenCodeSession {
                 throw new Error('OpenCode protocol error: resumed session ID changed');
             }
             this.sessionId = parsed.sessionId;
-            return parsed.result;
+            return cloneTurnResultWithSensitiveValues(parsed.result, {
+                resolvedModel: this.runtimePolicy.model,
+            });
         }
         catch (error) {
             this.failed = true;
@@ -512,11 +515,60 @@ class OpenCodeSession {
         await this.cleanupState();
     }
 }
+class OpenCodeScenarioAgentSession {
+    scenario;
+    started = false;
+    running = false;
+    failed = false;
+    disposed = false;
+    constructor(scenario) {
+        this.scenario = scenario;
+    }
+    start({ message }) {
+        if (this.started)
+            return Promise.reject(new Error('OpenCode session has already started'));
+        this.started = true;
+        return this.execute(message);
+    }
+    reply({ message }) {
+        if (!this.started)
+            return Promise.reject(new Error('OpenCode session has not started'));
+        return this.execute(message);
+    }
+    async execute(message) {
+        if (this.disposed)
+            throw new Error('OpenCode session is disposed');
+        if (this.failed)
+            throw new Error('OpenCode session is unusable after a failed turn');
+        if (this.running)
+            throw new Error('OpenCode does not allow concurrent turns');
+        this.running = true;
+        try {
+            const result = await this.scenario.runTurn(message);
+            if (result.exitCode !== 0 && !/"stopReason"\s*:\s*"cancelled"/.test(result.rawOutput))
+                this.failed = true;
+            return result;
+        }
+        catch (error) {
+            this.failed = true;
+            throw error;
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    async dispose() {
+        this.disposed = true;
+    }
+}
 export class OpenCodeAgent extends BaseAgent {
     async createSession(runtime, _runCommand, options = {}) {
         if (!options.opencodeExecutable) {
             throw new Error('OpenCode requires opencodeExecutable');
         }
+        const scenario = getOpenCodeScenarioSession(options);
+        if (scenario)
+            return new OpenCodeScenarioAgentSession(scenario);
         return new OpenCodeSession(runtime, options);
     }
 }

package/dist/commands/report.d.ts

@@ -24,6 +24,14 @@ export interface ReportOptions {
     noComment?: boolean;
     /** Override the comment-id used in the dedup marker. See `resolveCommentId`. */
     commentId?: string;
+    /** Provider-neutral URL for a richer external report. */
+    detailsUrl?: string;
+    /** Provider-neutral status notice included in the report body. */
+    notice?: string;
+    /** Surface missing context, malformed results, and GitHub API failures. */
+    strict?: boolean;
+    /** Skip a comment update when the pull request has advanced. */
+    expectedHeadSha?: string;
 }
 /**
  * Resolve the comment-id used for the dedup marker.
@@ -33,7 +41,7 @@ export interface ReportOptions {
  */
 export declare function resolveCommentId(explicit?: string): string;
 /**
- * Entry point for `pathgrade report`. Never throws and never sets a
- * failing exit code — even on malformed inputs or network errors.
+ * Entry point for `pathgrade report`. The default display-only mode never
+ * fails CI. Strict mode is intended for orchestrators that own publication.
  */
 export declare function runReport(cwd: string, opts?: ReportOptions): Promise<void>;

package/dist/commands/report.js

@@ -66,8 +66,8 @@ function printMarkdownAndPassRate(markdown, passRate) {
     console.log(String(passRate));
 }
 /**
- * Entry point for `pathgrade report`. Never throws and never sets a
- * failing exit code — even on malformed inputs or network errors.
+ * Entry point for `pathgrade report`. The default display-only mode never
+ * fails CI. Strict mode is intended for orchestrators that own publication.
  */
 export async function runReport(cwd, opts = {}) {
     const resolvedPath = path.resolve(cwd, opts.resultsPath ?? DEFAULT_RESULTS_PATH);
@@ -77,6 +77,9 @@ export async function runReport(cwd, opts = {}) {
     // Branch point: when true, post the comment and print only the pass rate.
     const shouldPost = inCI && !noComment;
     const prContext = shouldPost ? resolvePrContext(process.env) : null;
+    if (opts.strict && shouldPost && !prContext) {
+        throw new Error('pathgrade report: strict PR commenting requires GITHUB_TOKEN, GITHUB_REPOSITORY, and pull-request context');
+    }
     let report = null;
     let loadError = null;
     try {
@@ -95,6 +98,8 @@ export async function runReport(cwd, opts = {}) {
                 await postOrUpdateComment(prContext, {
                     commentId,
                     body: markdown,
+                    strict: opts.strict,
+                    expectedHeadSha: opts.expectedHeadSha,
                 });
                 console.log('0');
             }
@@ -108,15 +113,31 @@ export async function runReport(cwd, opts = {}) {
             await postOrUpdateComment(prContext, {
                 commentId,
                 body: MISSING_RESULTS_BODY,
+                strict: opts.strict,
+                expectedHeadSha: opts.expectedHeadSha,
             });
         }
         // Always emit a pass rate line so downstream capture doesn't explode.
         console.log('0');
+        if (opts.strict)
+            throw new Error(`pathgrade report: ${loadError}`);
         return;
     }
-    const markdown = formatReportMarkdown(report, { commentId });
+    const markdown = formatReportMarkdown(report, {
+        commentId,
+        detailsUrl: opts.detailsUrl,
+        notice: opts.notice,
+    });
     if (prContext) {
-        await postOrUpdateComment(prContext, { commentId, body: markdown });
+        const postResult = await postOrUpdateComment(prContext, {
+            commentId,
+            body: markdown,
+            strict: opts.strict,
+            expectedHeadSha: opts.expectedHeadSha,
+        });
+        if (postResult === 'stale') {
+            console.error('pathgrade report: pull-request head advanced; skipped stale comment update');
+        }
         // Only the pass rate goes to stdout — the markdown lives on the PR.
         console.log(String(report.overall_pass_rate));
         return;

package/dist/internal/direct-mcp-v2/acp-author-projector.d.ts

@@ -0,0 +1,20 @@
+import type { AgentTurnResult } from '../../types.js';
+import { type ToolAction } from '../../tool-events.js';
+import type { ProviderId } from './types.js';
+import type { AcpPromptResult, JsonRpcMessage } from './acp-client.js';
+export declare const ACP_AUTHOR_TRACE_MAX_CHARS: number;
+export type AcpToolName = {
+    action: ToolAction;
+    providerToolName: string;
+};
+export type AcpToolNameNormalizer = (title: string) => AcpToolName;
+export type AcpAuthorProjectionInput = {
+    provider: Extract<ProviderId, 'cursor' | 'opencode'>;
+    terminal: AcpPromptResult;
+    notifications: readonly JsonRpcMessage[];
+    normalizeToolName(title: string): AcpToolName;
+    protectedValues?: readonly string[];
+    sensitiveValues?: readonly string[];
+    turnNumber?: number;
+};
+export declare function projectAcpAuthorTurn(input: AcpAuthorProjectionInput): AgentTurnResult;