@oss-autopilot/core 3.2.0 → 3.3.0

package/dist/core/state.js

@@ -3,12 +3,12 @@
  * Thin coordinator that delegates persistence to state-persistence.ts
  * and scoring logic to repo-score-manager.ts.
  */
-import * as fs from 'fs';
+import * as fs from 'node:fs';
 import { AgentStateSchema } from './state-schema.js';
 import { loadState, saveState, reloadStateIfChanged, createFreshState, atomicWriteFileSync, } from './state-persistence.js';
 import * as repoScoring from './repo-score-manager.js';
 import { debug, warn } from './logger.js';
-import { errorMessage, ConfigurationError, ConcurrencyError } from './errors.js';
+import { errorMessage, ConfigurationError, ConcurrencyError, isTransientNetworkError } from './errors.js';
 import { GistStateStore } from './gist-state-store.js';
 import * as guidelinesStoreModule from './guidelines-store.js';
 import { getStatePath, getStateCachePath } from './paths.js';
@@ -53,13 +53,6 @@ export async function maybeCheckpoint(stateManager, callerModule) {
         warn(callerModule, `Gist checkpoint failed (local mutation succeeded, will retry on next push): ${errorMessage(err)}`);
     }
 }
-/**
- * Singleton manager for persistent agent state stored in ~/.oss-autopilot/state.json.
- *
- * Delegates file I/O to state-persistence.ts and scoring logic to repo-score-manager.ts.
- * Retains lightweight CRUD operations for config, issues, shelving, dismissal,
- * and status overrides.
- */
 export class StateManager {
     state;
     inMemoryOnly;
@@ -68,6 +61,8 @@ export class StateManager {
     _batchDirty = false;
     gistStore = null;
     gistDegraded = false;
+    staleness = null;
+    lastSuccessfulRefreshAt = null;
     /**
      * Create a new StateManager instance.
      * @param inMemoryOnly - When true, state is held only in memory and never read from or
@@ -131,6 +126,16 @@ export class StateManager {
         manager.gistStore = gistStore;
         manager.gistDegraded = result.degraded ?? false;
         manager.inMemoryOnly = false; // re-enable persistence
+        // Seed the staleness marker if bootstrap fell back to the local cache —
+        // a `daily` running on a cron right after this start needs to know.
+        if (result.degraded) {
+            manager.staleness = {
+                source: 'cache',
+                reason: 'initial Gist bootstrap fell back to local cache',
+                lastSuccessfulRefresh: null,
+                detectedAt: new Date().toISOString(),
+            };
+        }
         return manager;
     }
     /**
@@ -345,6 +350,15 @@ export class StateManager {
             const raw = this.gistStore.cachedFiles.get('state.json');
             if (!raw) {
                 warn(MODULE, 'Gist refreshed but state.json missing from cache');
+                // HTTP fetch succeeded but the Gist body is missing state.json — we
+                // still have stale in-memory data, so surface a marker rather than
+                // silently returning false (#1193 review).
+                this.staleness = {
+                    source: 'cache',
+                    reason: 'Gist refresh returned no state.json file',
+                    lastSuccessfulRefresh: this.lastSuccessfulRefreshAt,
+                    detectedAt: new Date().toISOString(),
+                };
                 return false;
             }
             try {
@@ -353,11 +367,41 @@ export class StateManager {
             }
             catch (err) {
                 warn(MODULE, `Failed to parse refreshed Gist state: ${errorMessage(err)}`);
+                // Same reasoning as the missing-file branch: parse failure leaves us
+                // on stale in-memory state, so flag it.
+                this.staleness = {
+                    source: 'cache',
+                    reason: `Gist refresh succeeded but payload was invalid: ${errorMessage(err)}`,
+                    lastSuccessfulRefresh: this.lastSuccessfulRefreshAt,
+                    detectedAt: new Date().toISOString(),
+                };
                 return false;
             }
+            // Successful refresh clears any prior staleness (#1193).
+            this.lastSuccessfulRefreshAt = new Date().toISOString();
+            this.staleness = null;
+        }
+        else if (this.gistStore.lastRefreshError) {
+            // Distinguish "fetch failed" (set marker) from "throttled" (preserve
+            // any existing marker, set nothing new).
+            this.staleness = {
+                source: 'cache',
+                reason: errorMessage(this.gistStore.lastRefreshError),
+                lastSuccessfulRefresh: this.lastSuccessfulRefreshAt,
+                detectedAt: new Date().toISOString(),
+            };
         }
         return refreshed;
     }
+    /**
+     * Returns a staleness marker when the in-memory state diverged from the
+     * canonical Gist (refresh failure or degraded bootstrap), or `null` when
+     * state is current. Commands surface this via their `--json` warnings
+     * envelope (#1193).
+     */
+    getStateStaleness() {
+        return this.staleness;
+    }
     // === Dashboard Data Setters ===
     /**
      * Store the latest daily digest and update the digest timestamp.
@@ -847,11 +891,20 @@ export async function getStateManagerAsync(token) {
         })
             .catch((err) => {
             asyncManagerPromise = null;
-            // Configuration errors (e.g. GistPermissionError) must surface to the user
+            // Configuration errors (e.g. GistPermissionError, GistCorruptError)
+            // must surface — falling back to local-only would silently split state
+            // across machines (#1202).
             if (err instanceof ConfigurationError)
                 throw err;
-            warn(MODULE, `Gist initialization failed, falling back to local-only mode: ${err}`);
-            return getStateManager(); // fall back to sync/local for transient errors
+            // Only fall back on actual network/server errors. Other failures
+            // (auth, schema, concurrency conflicts) indicate the Gist mode is
+            // broken in a way the user needs to address — silently falling back
+            // would write subsequent mutations to the local file while the Gist
+            // marker stays in config, causing permanent cross-machine divergence.
+            if (!isTransientNetworkError(err))
+                throw err;
+            warn(MODULE, `Gist initialization failed (transient network error), falling back to local-only mode: ${err}`);
+            return getStateManager();
         });
         return asyncManagerPromise;
     }
@@ -880,7 +933,7 @@ export async function ensureGistPersistence(token) {
         return;
     let persistence;
     try {
-        const raw = fs.readFileSync(getStatePath(), 'utf-8');
+        const raw = fs.readFileSync(getStatePath(), 'utf8');
         persistence = JSON.parse(raw)?.config?.persistence;
     }
     catch {

package/dist/core/untrusted-content.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Wrap GitHub-sourced text (PR titles, PR bodies, issue bodies, review
+ * comments) in a fenced delimiter so the LLM treats it as data, not
+ * instructions (#1192).
+ *
+ * The contract this module pins, exercised by `untrusted-content.test.ts`
+ * and the prompt-injection corpus:
+ *
+ *  1. Output starts with the open tag and ends with the close tag.
+ *  2. The close-tag literal NEVER appears inside the wrapped body — any
+ *     occurrence in the input is escaped to a sentinel so an attacker
+ *     cannot close the fence early and inject instructions after it.
+ *  3. `extractFromFence(wrapUntrustedContent(x, label))` returns `x`
+ *     unchanged for any input — the wrapping is lossless.
+ *
+ * Consumers should pair this with the agent-side guidance in
+ * `workflows/reference.md` ("Prompt Injection Awareness"), which tells
+ * the LLM to ignore instructions inside `<github-content>` blocks.
+ *
+ * Non-goals:
+ *  - This is NOT a content filter. We do not detect or strip prompt-
+ *    injection payloads; the human-in-the-loop gate on `post`/`claim`
+ *    remains the primary control.
+ */
+export declare const UNTRUSTED_OPEN_TAG_NAME = "github-content";
+export declare const UNTRUSTED_CLOSE_TAG = "</github-content>";
+export interface UntrustedContentMeta {
+    /** GitHub login of the content's author (e.g. PR comment author). */
+    author?: string;
+    /** GitHub author_association (OWNER, MEMBER, CONTRIBUTOR, NONE, ...). */
+    association?: string;
+    /** Free-form provenance label (e.g. "pr-body", "review-comment"). */
+    source?: string;
+}
+/**
+ * Wrap `text` in a `<github-content>` fence labeled with `label` and the
+ * optional metadata. Any occurrence of the close-tag literal inside `text`
+ * is replaced with a zero-width-joined sentinel that round-trips losslessly
+ * via {@link extractFromFence}.
+ */
+export declare function wrapUntrustedContent(text: string, label: string, meta?: UntrustedContentMeta): string;
+/**
+ * Reverse of {@link wrapUntrustedContent}. Extracts the original body text
+ * (un-escaping any sentinel-encoded close tags). Throws if the input is not
+ * a single well-formed fence — callers shouldn't be parsing arbitrary
+ * markdown with this; it's for tests + symmetric reasoning only.
+ */
+export declare function extractFromFence(fenced: string): string;

package/dist/core/untrusted-content.js

@@ -0,0 +1,106 @@
+/**
+ * Wrap GitHub-sourced text (PR titles, PR bodies, issue bodies, review
+ * comments) in a fenced delimiter so the LLM treats it as data, not
+ * instructions (#1192).
+ *
+ * The contract this module pins, exercised by `untrusted-content.test.ts`
+ * and the prompt-injection corpus:
+ *
+ *  1. Output starts with the open tag and ends with the close tag.
+ *  2. The close-tag literal NEVER appears inside the wrapped body — any
+ *     occurrence in the input is escaped to a sentinel so an attacker
+ *     cannot close the fence early and inject instructions after it.
+ *  3. `extractFromFence(wrapUntrustedContent(x, label))` returns `x`
+ *     unchanged for any input — the wrapping is lossless.
+ *
+ * Consumers should pair this with the agent-side guidance in
+ * `workflows/reference.md` ("Prompt Injection Awareness"), which tells
+ * the LLM to ignore instructions inside `<github-content>` blocks.
+ *
+ * Non-goals:
+ *  - This is NOT a content filter. We do not detect or strip prompt-
+ *    injection payloads; the human-in-the-loop gate on `post`/`claim`
+ *    remains the primary control.
+ */
+export const UNTRUSTED_OPEN_TAG_NAME = 'github-content';
+export const UNTRUSTED_CLOSE_TAG = `</${UNTRUSTED_OPEN_TAG_NAME}>`;
+/**
+ * Sentinels used to neutralize any literal open- or close-tag substring
+ * inside the wrapped body. We use HTML entity escapes (`&lt;` / `&gt;`) so
+ * the result is pure ASCII, lints cleanly, and round-trips losslessly. The
+ * `&` itself is escaped first so an input containing the literal text
+ * `&lt;/github-content&gt;` survives the wrap/unwrap round-trip without
+ * collision.
+ */
+const AMP_ESCAPE = '&amp;';
+const CLOSE_TAG_ESCAPE = `&lt;/${UNTRUSTED_OPEN_TAG_NAME}&gt;`;
+const OPEN_TAG_PATTERN = new RegExp(`<${UNTRUSTED_OPEN_TAG_NAME}\\b`, 'g');
+const OPEN_TAG_ESCAPE = `&lt;${UNTRUSTED_OPEN_TAG_NAME}`;
+function escapeAttr(value) {
+    // Newlines/carriage returns can't break out of a quoted attribute (no `"`)
+    // but they visually fragment the open tag in the prompt text the LLM
+    // reads, so encode them as numeric entities for defense-in-depth.
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/\n/g, '&#10;')
+        .replace(/\r/g, '&#13;');
+}
+/**
+ * Wrap `text` in a `<github-content>` fence labeled with `label` and the
+ * optional metadata. Any occurrence of the close-tag literal inside `text`
+ * is replaced with a zero-width-joined sentinel that round-trips losslessly
+ * via {@link extractFromFence}.
+ */
+export function wrapUntrustedContent(text, label, meta = {}) {
+    // Escape order matters for round-trip correctness:
+    //  1. `&` first — so any pre-existing entity in the input gets a literal
+    //     `&amp;` that survives the unwrap pass below.
+    //  2. Close-tag literals — replaced with the entity-escaped form.
+    //  3. Open-tag literals (matched only at boundaries via OPEN_TAG_PATTERN
+    //     so we don't accidentally rewrite the close-tag's `</github-content`).
+    const escapedBody = text
+        .split('&')
+        .join(AMP_ESCAPE)
+        .split(UNTRUSTED_CLOSE_TAG)
+        .join(CLOSE_TAG_ESCAPE)
+        .replace(OPEN_TAG_PATTERN, OPEN_TAG_ESCAPE);
+    const attrs = [`label="${escapeAttr(label)}"`];
+    if (meta.author !== undefined)
+        attrs.push(`author="${escapeAttr(meta.author)}"`);
+    if (meta.association !== undefined)
+        attrs.push(`association="${escapeAttr(meta.association)}"`);
+    if (meta.source !== undefined)
+        attrs.push(`source="${escapeAttr(meta.source)}"`);
+    return `<${UNTRUSTED_OPEN_TAG_NAME} ${attrs.join(' ')}>${escapedBody}${UNTRUSTED_CLOSE_TAG}`;
+}
+/**
+ * Reverse of {@link wrapUntrustedContent}. Extracts the original body text
+ * (un-escaping any sentinel-encoded close tags). Throws if the input is not
+ * a single well-formed fence — callers shouldn't be parsing arbitrary
+ * markdown with this; it's for tests + symmetric reasoning only.
+ */
+export function extractFromFence(fenced) {
+    const openMatch = fenced.match(new RegExp(`^<${UNTRUSTED_OPEN_TAG_NAME}\\b[^>]*>`));
+    if (!openMatch) {
+        throw new Error('extractFromFence: input does not start with a <github-content> open tag');
+    }
+    if (!fenced.endsWith(UNTRUSTED_CLOSE_TAG)) {
+        throw new Error('extractFromFence: input does not end with </github-content>');
+    }
+    const inner = fenced.slice(openMatch[0].length, fenced.length - UNTRUSTED_CLOSE_TAG.length);
+    if (inner.includes(UNTRUSTED_CLOSE_TAG)) {
+        throw new Error('extractFromFence: nested </github-content> found in body — fence escaping is broken');
+    }
+    // Reverse the escapes in opposite order: tag entities first (so an
+    // already-`&amp;`-prefixed entity survives), then unescape `&amp;`.
+    return inner
+        .split(CLOSE_TAG_ESCAPE)
+        .join(UNTRUSTED_CLOSE_TAG)
+        .split(OPEN_TAG_ESCAPE)
+        .join(`<${UNTRUSTED_OPEN_TAG_NAME}`)
+        .split(AMP_ESCAPE)
+        .join('&');
+}

package/dist/core/urls.js

@@ -5,8 +5,8 @@
  * owner/repo characters. Extracted from utils.ts under #1116.
  */
 // Validation patterns for GitHub owner and repo names
-const OWNER_PATTERN = /^[a-zA-Z0-9_-]+$/;
-const REPO_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+const OWNER_PATTERN = /^[\w-]+$/;
+const REPO_PATTERN = /^[\w.-]+$/;
 function isValidOwnerRepo(owner, repo) {
     return OWNER_PATTERN.test(owner) && REPO_PATTERN.test(repo);
 }

package/dist/formatters/json.d.ts

@@ -3,10 +3,9 @@
  * Provides structured output that can be consumed by scripts and plugins
  */
 import { z, type ZodType } from 'zod';
-import type { FetchedPR, DailyDigest, AgentState, RepoGroup, CommentedIssue, ShelvedPRRef } from '../core/types.js';
+import type { FetchedPR, DailyDigest, AgentState, RepoGroup, CommentedIssue, ShelvedPRRef, SearchPriority, CapacityAssessment, ActionableIssue, ActionableIssueType, CompactActionableIssue, ActionMenuItem, ActionMenu } from '../core/types.js';
 import type { ContributionStats } from '../core/stats.js';
 import type { PRCheckFailure } from '../core/pr-monitor.js';
-import type { SearchPriority, CapacityAssessment, ActionableIssue, ActionableIssueType, CompactActionableIssue, ActionMenuItem, ActionMenu } from '../core/types.js';
 import type { CIFormatterDiagnosis, FormatterDetectionResult } from '../core/formatter-detection.js';
 export type { CapacityAssessment, ActionableIssue, ActionableIssueType, CompactActionableIssue, ActionMenuItem, ActionMenu, };
 export type ErrorCode = 'AUTH_REQUIRED' | 'RATE_LIMITED' | 'VALIDATION' | 'CONFIGURATION' | 'NETWORK' | 'NOT_FOUND' | 'STATE_CORRUPTED' | 'CONCURRENCY' | 'UNKNOWN';
@@ -51,18 +50,37 @@ export interface CompactRepoGroup {
  * See `DailyWarning` and issue #1042 for the rationale — keeping this a
  * fixed union so downstream consumers can switch on it without drift.
  */
-export type DailyWarningPhase = 'fetch' | 'repo-scores' | 'analytics' | 'scout-sync' | 'partition' | 'dismiss-filter' | 'gist-checkpoint';
+export type DailyWarningPhase = 'fetch' | 'repo-scores' | 'analytics' | 'scout-sync' | 'partition' | 'dismiss-filter' | 'gist-checkpoint' | 'gist-staleness';
 /**
  * A single non-fatal failure surfaced from the `daily` pipeline. Unlike
  * `PRCheckFailure` (which is scoped to per-PR fetch errors), this covers
  * ancillary fetches that previously demoted to a log-only `warn()` — repo
  * metadata, monthly analytics, scout sync, Gist checkpoint, etc.
+ *
+ * `timestamp` and `details` are optional structured extensions added in
+ * #1193 so staleness warnings can carry `lastSuccessfulRefresh` /
+ * `detectedAt` without bespoke schemas. Existing producers don't need to
+ * supply them.
  */
 export interface DailyWarning {
     phase: DailyWarningPhase;
     operation: string;
     message: string;
+    timestamp?: string;
+    details?: Record<string, unknown>;
 }
+/**
+ * Build a warning entry from a {@link StalenessInfo} marker (#1193).
+ * Co-located with `DailyWarning` so every command (`daily`, `status`,
+ * `comments`) builds the same shape from the same source.
+ */
+export interface StalenessLike {
+    source: string;
+    reason: string;
+    lastSuccessfulRefresh: string | null;
+    detectedAt: string;
+}
+export declare function buildStalenessWarning(info: StalenessLike): DailyWarning;
 export interface DailyOutput {
     digest: DailyDigestCompact;
     capacity: CapacityAssessment;
@@ -139,6 +157,22 @@ export declare const StatusOutputSchema: z.ZodObject<{
     lastRunAt: z.ZodString;
     offline: z.ZodOptional<z.ZodBoolean>;
     lastUpdated: z.ZodOptional<z.ZodString>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            fetch: "fetch";
+            "repo-scores": "repo-scores";
+            analytics: "analytics";
+            "scout-sync": "scout-sync";
+            partition: "partition";
+            "dismiss-filter": "dismiss-filter";
+            "gist-checkpoint": "gist-checkpoint";
+            "gist-staleness": "gist-staleness";
+        }>;
+        operation: z.ZodString;
+        message: z.ZodString;
+        timestamp: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type StatusOutput = z.infer<typeof StatusOutputSchema>;
 export declare const DailyOutputSchema: z.ZodObject<{
@@ -234,9 +268,12 @@ export declare const DailyOutputSchema: z.ZodObject<{
             partition: "partition";
             "dismiss-filter": "dismiss-filter";
             "gist-checkpoint": "gist-checkpoint";
+            "gist-staleness": "gist-staleness";
         }>;
         operation: z.ZodString;
         message: z.ZodString;
+        timestamp: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const CompactDailyOutputSchema: z.ZodObject<{
@@ -327,9 +364,12 @@ export declare const CompactDailyOutputSchema: z.ZodObject<{
             partition: "partition";
             "dismiss-filter": "dismiss-filter";
             "gist-checkpoint": "gist-checkpoint";
+            "gist-staleness": "gist-staleness";
         }>;
         operation: z.ZodString;
         message: z.ZodString;
+        timestamp: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const SearchOutputSchema: z.ZodObject<{
@@ -426,6 +466,14 @@ export declare const InitOutputSchema: z.ZodObject<{
     username: z.ZodString;
     message: z.ZodString;
 }, z.core.$strip>;
+export declare const ManifestOutputSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    cliVersion: z.ZodString;
+    commands: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        localOnly: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const CheckSetupOutputSchema: z.ZodObject<{
     setupComplete: z.ZodBoolean;
     username: z.ZodString;
@@ -791,6 +839,8 @@ export interface CommentsOutput {
         inlineCommentCount: number;
         discussionCommentCount: number;
     };
+    /** Non-fatal warnings (e.g. stale-cache fallback, #1193). Always present; empty on clean runs. */
+    warnings?: DailyWarning[];
 }
 /** Output of the post command */
 export interface PostOutput {

package/dist/formatters/json.js

@@ -3,6 +3,18 @@
  * Provides structured output that can be consumed by scripts and plugins
  */
 import { z } from 'zod';
+export function buildStalenessWarning(info) {
+    return {
+        phase: 'gist-staleness',
+        operation: 'state refresh',
+        message: `Operating on ${info.source} state — Gist refresh failed: ${info.reason}`,
+        timestamp: info.detectedAt,
+        details: {
+            source: info.source,
+            lastSuccessfulRefresh: info.lastSuccessfulRefresh,
+        },
+    };
+}
 /**
  * Strip a full DailyOutput down to the compact subset (#763).
  * Omits summary, repoGroups, and full failures array. Retains a failureCount
@@ -61,6 +73,27 @@ export function compactRepoGroups(groups) {
         prUrls: group.prs.map((pr) => pr.url),
     }));
 }
+// DailyWarning schema lives here (rather than further down with the rest of
+// the daily schemas) so StatusOutputSchema below can reference it directly
+// without `z.lazy()`. The runtime shape is shared across daily / status /
+// comments warnings — see `DailyWarning` interface above.
+const DailyWarningPhaseSchema = z.enum([
+    'fetch',
+    'repo-scores',
+    'analytics',
+    'scout-sync',
+    'partition',
+    'dismiss-filter',
+    'gist-checkpoint',
+    'gist-staleness',
+]);
+const DailyWarningSchema = z.object({
+    phase: DailyWarningPhaseSchema,
+    operation: z.string(),
+    message: z.string(),
+    timestamp: z.string().optional(),
+    details: z.record(z.string(), z.unknown()).optional(),
+});
 export const StatusOutputSchema = z.object({
     stats: z.object({
         mergedPRs: z.number().int().nonnegative(),
@@ -73,6 +106,7 @@ export const StatusOutputSchema = z.object({
     lastRunAt: z.string(),
     offline: z.boolean().optional(),
     lastUpdated: z.string().optional(),
+    warnings: z.array(DailyWarningSchema).optional(),
 });
 // ── Daily output schemas (#1146) ─────────────────────────────────────
 //
@@ -162,20 +196,8 @@ const CompactRepoGroupSchema = z.object({
     repo: z.string(),
     prUrls: z.array(z.string()),
 });
-const DailyWarningPhaseSchema = z.enum([
-    'fetch',
-    'repo-scores',
-    'analytics',
-    'scout-sync',
-    'partition',
-    'dismiss-filter',
-    'gist-checkpoint',
-]);
-const DailyWarningSchema = z.object({
-    phase: DailyWarningPhaseSchema,
-    operation: z.string(),
-    message: z.string(),
-});
+// DailyWarning schemas were hoisted above StatusOutputSchema (#1193) so the
+// status output can reference them without `z.lazy()`.
 export const DailyOutputSchema = z.object({
     digest: DailyDigestCompactSchema,
     capacity: CapacityAssessmentSchema,
@@ -278,6 +300,19 @@ export const InitOutputSchema = z.object({
     username: z.string(),
     message: z.string(),
 });
+// ── #1190: plugin → CLI contract ─────────────────────────────────────
+//
+// Pinned shape lets the plugin's session-start hook verify that the bundled
+// CLI exposes the subcommands the markdown layer expects. Bumping
+// `schemaVersion` is a breaking change to that contract.
+export const ManifestOutputSchema = z.object({
+    schemaVersion: z.literal(1),
+    cliVersion: z.string().regex(/^\d+\.\d+\.\d+/),
+    commands: z.array(z.object({
+        name: z.string(),
+        localOnly: z.boolean(),
+    })),
+});
 export const CheckSetupOutputSchema = z.object({
     setupComplete: z.boolean(),
     username: z.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {