@astrosheep/square 0.4.0 → 0.4.1

package/dist/delivery-ledger.d.ts

@@ -0,0 +1,196 @@
+import { type Owner } from './neutral.js';
+import { type VersionObserver } from './file-changes.js';
+export interface DeliveryRoute {
+    readonly kind: string;
+    readonly address: Readonly<Record<string, string>>;
+}
+export interface DeliverySession {
+    readonly owner: Owner;
+    readonly generation: string;
+    readonly state: 'attached' | 'detached' | 'deleted';
+    readonly routes: readonly DeliveryRoute[];
+    readonly at: number;
+}
+export interface DeliveryCard {
+    readonly seq: number;
+    readonly owner: Owner;
+    readonly key: string;
+    readonly text: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly postedAt: number;
+}
+export interface DeliveryCorrelation {
+    readonly token?: string;
+    readonly messageId?: string;
+    readonly payloadHash?: string;
+}
+export interface DeliveryHandoffRef {
+    readonly token: string;
+    readonly owner: Owner;
+    readonly generation: string;
+    readonly payloadHash: string;
+    readonly routeKind: string;
+}
+export type DeliveryOutcome = 'dispatching' | 'accepted' | 'presented' | 'failed' | 'unknown' | 'released';
+export type PresentationOutcome = 'presented' | 'failed' | 'unknown' | 'released';
+export interface DeliveryAttempt {
+    readonly token: string;
+    readonly seq: number;
+    readonly generation: string;
+    readonly track: 'handoff' | 'presentation';
+    readonly routeKind: string | null;
+    readonly outcome: DeliveryOutcome;
+    readonly correlation: DeliveryCorrelation;
+    readonly startedAt: number;
+    readonly expiresAt: number;
+    readonly settledAt?: number;
+}
+export interface DeliveryReceipt {
+    readonly owner: Owner;
+    readonly key: string;
+    readonly at: number;
+}
+export type PostResult = {
+    readonly status: 'posted' | 'duplicate' | 'conflict' | 'unknown-session' | 'deleted-session' | 'suppressed';
+};
+export type SuppressionResult = {
+    readonly id: string;
+    readonly status: 'suppressed' | 'in-custody';
+};
+export interface DeliveryHealth {
+    readonly unknownAttempts: readonly DeliveryAttempt[];
+    readonly repeatedFailures: readonly {
+        readonly owner: Owner;
+        readonly key: string;
+        readonly count: number;
+    }[];
+    readonly sessionsWithoutRoute: readonly Owner[];
+}
+export interface PresentationClaim {
+    readonly cards: readonly DeliveryCard[];
+    readonly attempts: readonly DeliveryAttempt[];
+    /** Recheck immediately before handing text to the external receiver. */
+    current(signal?: AbortSignal): Promise<boolean>;
+    /** Captured custody survives attachment rotation; errors propagate without a false receipt. */
+    settle(outcome: PresentationOutcome): Promise<boolean>;
+}
+export interface DeliveryTransportContext {
+    readonly token: string;
+    readonly deadline: number;
+    readonly signal: AbortSignal;
+    prepare(correlation: DeliveryCorrelation): Promise<boolean>;
+    /** Adapters with awaits before I/O recheck here, then check signal/deadline synchronously. */
+    beforeSend(): Promise<boolean>;
+}
+export type TransportOutcome = 'accepted' | 'presented' | 'failed' | 'unknown' | 'not-capable';
+export interface DeliveryTransport {
+    readonly kind: string;
+    send(card: DeliveryCard, address: Readonly<Record<string, string>>, context: DeliveryTransportContext): Promise<TransportOutcome>;
+}
+export interface LateHandoffSettlement {
+    readonly outcome: TransportOutcome | 'released';
+    readonly persistence: {
+        readonly status: 'recorded' | 'not-recorded';
+    } | {
+        readonly status: 'error';
+        readonly error: unknown;
+    };
+}
+export interface HandoffResult {
+    readonly outcome: TransportOutcome | 'released' | 'not-invoked';
+    readonly token?: string;
+    readonly persistence?: 'recorded' | 'not-recorded';
+    /** Interrupted effects may complete later; this handle never rejects and may stay pending. */
+    readonly lateSettlement?: Promise<LateHandoffSettlement>;
+}
+/** Shared by host and producer callers; an explicit delivery override always wins. */
+export declare function deliveryLedgerLocation(env?: NodeJS.ProcessEnv, homeDir?: string): string;
+/** One user-owned ledger; producers supply finished text and callers choose routes. */
+export declare class DeliveryLedger {
+    private readonly store;
+    private readonly leaseMs;
+    private constructor();
+    static open(options?: {
+        readonly location?: string;
+        readonly clock?: () => number;
+        readonly leaseMs?: number;
+    }): Promise<DeliveryLedger>;
+    close(): Promise<void>;
+    attach(input: {
+        readonly owner: Owner;
+        readonly expectedGeneration: string | null;
+        readonly routes: readonly DeliveryRoute[];
+    }): Promise<DeliverySession | false>;
+    updateRoutes(input: {
+        readonly owner: Owner;
+        readonly generation: string;
+        readonly routes: readonly DeliveryRoute[];
+    }): Promise<boolean>;
+    detach(input: {
+        readonly owner: Owner;
+        readonly generation: string;
+    }): Promise<boolean>;
+    markDeleted(input: {
+        readonly owner: Owner;
+        readonly generation: string;
+    }): Promise<boolean>;
+    private lifecycle;
+    session(owner: Owner): Promise<DeliverySession | undefined>;
+    sessions(): Promise<readonly DeliverySession[]>;
+    pending(owner: Owner, options: {
+        readonly generation: string;
+    }): Promise<readonly DeliveryCard[]>;
+    handoffs(owner: Owner, options: {
+        readonly generation: string;
+    }): Promise<readonly DeliveryAttempt[]>;
+    post(input: {
+        readonly owner: Owner;
+        readonly key: string;
+        readonly text: string;
+        readonly details?: Readonly<Record<string, unknown>>;
+    }): Promise<PostResult>;
+    suppress(input: {
+        readonly owner: Owner;
+        readonly key: string;
+        readonly scope: 'exact' | 'prefix';
+        readonly expiresAt?: number;
+    }): Promise<SuppressionResult>;
+    renewSuppression(input: {
+        readonly owner: Owner;
+        readonly id: string;
+        readonly expiresAt: number;
+    }): Promise<boolean>;
+    releaseSuppression(input: {
+        readonly owner: Owner;
+        readonly id: string;
+    }): Promise<boolean>;
+    cancel(input: {
+        readonly owner: Owner;
+        readonly generation: string;
+    }): Promise<boolean>;
+    receipts(owner: Owner, options?: {
+        readonly keys?: readonly string[];
+        readonly since?: number;
+    }): Promise<readonly DeliveryReceipt[]>;
+    claimPresentation(owner: Owner, options: {
+        readonly generation: string;
+        readonly budgetChars: number;
+        readonly signal?: AbortSignal;
+    }): Promise<PresentationClaim | undefined>;
+    /** Resolve the original prepared handoff, including its stored route kind. */
+    handoff(token: string): Promise<DeliveryHandoffRef | undefined>;
+    guardHandoff(ref: DeliveryHandoffRef): Promise<boolean>;
+    acceptHandoff(ref: DeliveryHandoffRef): Promise<boolean>;
+    /** Confirms the exact existing external effect; never sends or returns text. */
+    observePresentation(handoff: string | DeliveryHandoffRef, options?: {
+        readonly requireCurrent?: boolean;
+    }): Promise<boolean>;
+    health(owner?: Owner): Promise<DeliveryHealth>;
+    /** Subscribe first; read the returned version, inspect state, then await changed(version,...). */
+    observe(owner: Owner): Promise<VersionObserver<string>>;
+    dispatchHandoff(owner: Owner, key: string, transport: DeliveryTransport, options: {
+        readonly generation: string;
+        readonly timeoutMs: number;
+        readonly signal?: AbortSignal;
+    }): Promise<HandoffResult>;
+}

package/dist/delivery-ledger.js

@@ -0,0 +1,268 @@
+import os from 'node:os';
+import path from 'node:path';
+import { validateOwner } from './neutral.js';
+import { observeFileMetadata } from './file-changes.js';
+import { LedgerStore } from './delivery-ledger-sqlite.js';
+function nonempty(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new TypeError('Expected a nonempty string');
+}
+function positive(value) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new RangeError('Expected a positive safe integer');
+}
+function routes(value) {
+    if (!Array.isArray(value))
+        throw new TypeError('Expected routes');
+    const kinds = new Set();
+    for (const route of value) {
+        nonempty(route.kind);
+        if (kinds.has(route.kind))
+            throw new TypeError('Duplicate route kind');
+        kinds.add(route.kind);
+        if (route.address === null || typeof route.address !== 'object' || Array.isArray(route.address)
+            || !Object.values(route.address).every(item => typeof item === 'string'))
+            throw new TypeError('Expected string address fields');
+        if (Object.keys(route).some(key => key !== 'kind' && key !== 'address'))
+            throw new TypeError('Unexpected route field');
+    }
+}
+function correlation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || !Object.entries(value).every(([key, item]) => ['token', 'messageId', 'payloadHash'].includes(key) && typeof item === 'string'))
+        throw new TypeError('Invalid correlation');
+}
+/** Shared by host and producer callers; an explicit delivery override always wins. */
+export function deliveryLedgerLocation(env = process.env, homeDir = os.homedir()) {
+    return env.SQUARE_DELIVERY ?? path.join(homeDir, '.square', 'delivery.v3.sqlite');
+}
+function encodeDetails(details) {
+    const ancestors = new Set();
+    const encode = (value) => {
+        if (value === null || typeof value === 'string' || typeof value === 'boolean'
+            || typeof value === 'number' && Number.isFinite(value))
+            return value;
+        if (typeof value !== 'object' || !value || ancestors.has(value)
+            || !Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+            throw new TypeError('Expected JSON card details');
+        ancestors.add(value);
+        const result = Array.isArray(value) ? Array.from(value, encode)
+            : Object.fromEntries(Object.keys(value).sort().map(key => [key, encode(value[key])]));
+        ancestors.delete(value);
+        return result;
+    };
+    if (!details || typeof details !== 'object' || Array.isArray(details))
+        throw new TypeError('Expected a card details object');
+    return JSON.stringify(encode(details));
+}
+/** One user-owned ledger; producers supply finished text and callers choose routes. */
+export class DeliveryLedger {
+    store;
+    leaseMs;
+    constructor(store, leaseMs) {
+        this.store = store;
+        this.leaseMs = leaseMs;
+    }
+    static async open(options = {}) {
+        const location = options.location ?? deliveryLedgerLocation();
+        if (!path.isAbsolute(location))
+            throw new TypeError('Delivery location must be absolute');
+        const leaseMs = options.leaseMs ?? 30_000;
+        positive(leaseMs);
+        return new DeliveryLedger(await LedgerStore.open(location, options.clock ?? Date.now), leaseMs);
+    }
+    close() { return this.store.close(); }
+    attach(input) {
+        validateOwner(input.owner);
+        routes(input.routes);
+        if (input.expectedGeneration !== null)
+            nonempty(input.expectedGeneration);
+        return this.store.attach(input);
+    }
+    updateRoutes(input) {
+        validateOwner(input.owner);
+        nonempty(input.generation);
+        routes(input.routes);
+        return this.store.updateRoutes(input);
+    }
+    detach(input) { return this.lifecycle(input, 'detached'); }
+    markDeleted(input) { return this.lifecycle(input, 'deleted'); }
+    lifecycle(input, state) {
+        validateOwner(input.owner);
+        nonempty(input.generation);
+        return this.store.lifecycle(input, state);
+    }
+    session(owner) { validateOwner(owner); return this.store.session(owner); }
+    sessions() { return this.store.sessions(); }
+    pending(owner, options) {
+        validateOwner(owner);
+        nonempty(options.generation);
+        return this.store.pendingCards(owner, options.generation);
+    }
+    handoffs(owner, options) {
+        validateOwner(owner);
+        nonempty(options.generation);
+        return this.store.handoffs(owner, options.generation);
+    }
+    post(input) {
+        validateOwner(input.owner);
+        nonempty(input.key);
+        if (typeof input.text !== 'string')
+            throw new TypeError('Expected card text');
+        return this.store.post({ ...input, details: input.details === undefined ? null : encodeDetails(input.details) });
+    }
+    suppress(input) {
+        validateOwner(input.owner);
+        nonempty(input.key);
+        if (!['exact', 'prefix'].includes(input.scope) || input.expiresAt !== undefined && !Number.isFinite(input.expiresAt))
+            throw new TypeError('Invalid suppression');
+        return this.store.suppress(input);
+    }
+    renewSuppression(input) {
+        validateOwner(input.owner);
+        nonempty(input.id);
+        if (!Number.isFinite(input.expiresAt))
+            throw new TypeError('Expected finite suppression expiry');
+        return this.store.renewSuppression(input);
+    }
+    releaseSuppression(input) {
+        validateOwner(input.owner);
+        nonempty(input.id);
+        return this.store.releaseSuppression(input);
+    }
+    cancel(input) {
+        validateOwner(input.owner);
+        nonempty(input.generation);
+        return this.store.cancel(input);
+    }
+    receipts(owner, options = {}) {
+        validateOwner(owner);
+        if (options.keys)
+            options.keys.forEach(nonempty);
+        if (options.since !== undefined && !Number.isFinite(options.since))
+            throw new TypeError('Expected finite receipt time');
+        return this.store.receipts(owner, options);
+    }
+    async claimPresentation(owner, options) {
+        validateOwner(owner);
+        nonempty(options.generation);
+        positive(options.budgetChars);
+        if (options.signal?.aborted)
+            return undefined;
+        const claim = await this.store.claimPresentation(owner, options.generation, options.budgetChars, this.leaseMs, options.signal);
+        if (!claim)
+            return undefined;
+        const tokens = claim.attempts.map(attempt => attempt.token);
+        return { ...claim,
+            current: signal => this.store.current(tokens, signal ?? options.signal),
+            settle: outcome => {
+                if (!['presented', 'failed', 'unknown', 'released'].includes(outcome))
+                    throw new TypeError('Invalid presentation outcome');
+                return this.store.settle(tokens, outcome);
+            },
+        };
+    }
+    /** Resolve the original prepared handoff, including its stored route kind. */
+    handoff(token) {
+        nonempty(token);
+        return this.store.handoff(token);
+    }
+    guardHandoff(ref) { return this.store.guardHandoff(ref); }
+    acceptHandoff(ref) { return this.store.acceptHandoff(ref); }
+    /** Confirms the exact existing external effect; never sends or returns text. */
+    observePresentation(handoff, options) {
+        if (typeof handoff === 'string')
+            nonempty(handoff);
+        return this.store.observePresentation(handoff, options);
+    }
+    health(owner) {
+        if (owner !== undefined)
+            validateOwner(owner);
+        return this.store.health(owner);
+    }
+    /** Subscribe first; read the returned version, inspect state, then await changed(version,...). */
+    observe(owner) {
+        validateOwner(owner);
+        return observeFileMetadata(this.store.location);
+    }
+    async dispatchHandoff(owner, key, transport, options) {
+        validateOwner(owner);
+        nonempty(key);
+        nonempty(options.generation);
+        positive(options.timeoutMs);
+        if (options.signal?.aborted)
+            return { outcome: 'not-invoked' };
+        nonempty(transport.kind);
+        const claim = await this.store.claimHandoff(owner, key, options.generation, transport.kind, Math.max(this.leaseMs, options.timeoutMs), options.signal);
+        if (!claim)
+            return { outcome: 'not-invoked' };
+        const token = claim.attempt.token;
+        const controller = new AbortController();
+        const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+        const deadline = Date.now() + options.timeoutMs;
+        let persistenceFailure;
+        const persist = async (operation) => {
+            try {
+                return await operation;
+            }
+            catch (error) {
+                persistenceFailure = { error };
+                throw error;
+            }
+        };
+        const current = () => persist(this.store.current([token], signal, claim.route));
+        const finish = async (outcome) => {
+            if (!['accepted', 'presented', 'failed', 'unknown', 'not-capable', 'released'].includes(outcome))
+                throw new TypeError('Invalid transport outcome');
+            const recorded = await this.store.settle([token], outcome === 'not-capable' ? 'released' : outcome);
+            if (persistenceFailure)
+                throw persistenceFailure.error;
+            return { outcome, token, persistence: recorded ? 'recorded' : 'not-recorded' };
+        };
+        if (!await current() || signal.aborted || Date.now() >= deadline)
+            return finish('released');
+        let timer;
+        let onAbort;
+        try {
+            const interrupted = new Promise(resolve => {
+                onAbort = () => resolve('unknown');
+                signal.addEventListener('abort', onAbort, { once: true });
+                timer = setTimeout(() => { resolve('unknown'); controller.abort(new Error('Delivery deadline elapsed')); }, options.timeoutMs);
+            });
+            // Invoke synchronously after the final fence; adapters own checks after their own awaits.
+            const effect = (async () => {
+                if (signal.aborted || Date.now() >= deadline)
+                    return 'released';
+                return transport.send(claim.card, claim.route.address, { token, deadline, signal,
+                    beforeSend: current,
+                    prepare: value => { correlation(value); return persist(this.store.prepare(token, value, signal)); },
+                });
+            })().catch(() => 'unknown');
+            const first = await Promise.race([
+                effect.then(outcome => ({ outcome, interrupted: false })),
+                interrupted.then(outcome => ({ outcome, interrupted: true })),
+            ]);
+            if (!first.interrupted)
+                return await finish(first.outcome);
+            const unknown = finish('unknown');
+            // Register before awaiting persistence; even an already completed effect waits for unknown.
+            const lateSettlement = unknown.then(async () => {
+                const outcome = await effect;
+                try {
+                    const result = await finish(outcome);
+                    return { outcome, persistence: { status: result.persistence } };
+                }
+                catch (error) {
+                    return { outcome, persistence: { status: 'error', error } };
+                }
+            }, error => ({ outcome: 'unknown', persistence: { status: 'error', error } }));
+            return { ...await unknown, lateSettlement };
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (onAbort)
+                signal.removeEventListener('abort', onAbort);
+        }
+    }
+}

package/dist/delivery-lifetime.d.ts

@@ -0,0 +1,6 @@
+import type { DeliveryLedger, HandoffResult } from './delivery-ledger.js';
+/** Retire the caller's connection without abandoning an already-invoked effect. */
+export declare function retainDeliveryLedger(ledger: DeliveryLedger): {
+    track(result: HandoffResult): void;
+    close(): Promise<void>;
+};

package/dist/delivery-lifetime.js

@@ -0,0 +1,45 @@
+import { redactCurrentDiagnostic } from './diagnostic-redaction.js';
+/** Retire the caller's connection without abandoning an already-invoked effect. */
+export function retainDeliveryLedger(ledger) {
+    const pending = new Set();
+    let retired = false, closing;
+    const diagnose = (event, result, detail) => {
+        try {
+            const diagnostic = redactCurrentDiagnostic({ event, token: result?.token, outcome: result?.outcome, ...detail });
+            try {
+                console.warn(diagnostic);
+            }
+            catch {
+                process.stderr.write(`${JSON.stringify(diagnostic)}\n`);
+            }
+        }
+        catch { /* Closed diagnostic sinks cannot prevent settlement or resource retirement. */ }
+    };
+    const closeOnce = () => closing ??= ledger.close();
+    const settled = (handle) => {
+        pending.delete(handle);
+        if (retired && !pending.size)
+            void closeOnce().catch(() => diagnose('delivery-ledger-deferred-close-error'));
+    };
+    return {
+        track(result) {
+            const handle = result.lateSettlement;
+            if (!handle || pending.has(handle))
+                return;
+            pending.add(handle);
+            void handle.then(late => {
+                if (late.persistence.status !== 'recorded')
+                    diagnose('delivery-late-settlement', result, { lateOutcome: late.outcome, persistence: late.persistence.status });
+                settled(handle);
+            }, () => {
+                diagnose('delivery-late-settlement-rejected', result);
+                settled(handle);
+            });
+        },
+        async close() {
+            retired = true;
+            if (!pending.size)
+                await closeOnce();
+        },
+    };
+}

package/dist/harness-links.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { isDeepStrictEqual } from 'node:util';
 import crossSpawn from 'cross-spawn';
 import { applyEdits, createScanner, findNodeAtLocation, modify, parse, parseTree } from 'jsonc-parser';
@@ -28,22 +29,33 @@ export function installOpenCodePlugin(homeDir, force = false, run = runOpenCode)
     // Explicit `square install` replaces owned pins/duplicates with one unpinned
     // current-field entry; updating an exact old pin otherwise succeeds unchanged.
     void force;
+    const version = openCodeCommand(homeDir, ['--version'], run, 'version check').trim();
+    const match = /^(\d+)\.\d+\.\d+(?:[-+][\w.-]+)?$/.exec(version);
+    const major = match && Number(match[1]);
+    if (major !== 1 && major !== 2)
+        throw new Error(`Unsupported OpenCode version ${JSON.stringify(version)}; install OpenCode 1.x or 2.x and retry.`);
     const configs = readOpenCodeConfigs(homeDir);
     const entries = configs.flatMap((config) => config.entries);
     const options = entries.map((entry) => entry.options).filter((value) => value !== undefined);
     if (options.some((value) => !isDeepStrictEqual(value, options[0]))) {
         throw new Error('Conflicting Square plugin options in OpenCode configuration; reconcile the owned plugin/plugins entries before installing.');
     }
-    const canonical = options.length ? { package: SQUARE_IDENTITY.packageName, options: options[0] } : SQUARE_IDENTITY.packageName;
+    if (major === 1 && options.length)
+        throw new Error('Square plugin options cannot be translated to OpenCode 1.x; reconcile the owned plugin options before installing.');
+    const canonical = major === 1 ? pathToFileURL(path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'plugins/opencode-v1/index.js')).href
+        : options.length ? { package: SQUARE_IDENTITY.packageName, options: options[0] } : SQUARE_IDENTITY.packageName;
+    if (major === 1 && !fs.existsSync(fileURLToPath(canonical)))
+        throw new Error('Square OpenCode 1.x plugin is missing from this installation; reinstall Square.');
+    const field = major === 1 ? 'plugin' : 'plugins';
     const targets = configs.length ? configs : [{ target: openCodeConfigPaths(homeDir)[0], source: '{}', entries: [] }];
-    const alreadyCanonical = entries.length === 1 && configs[0]?.entries[0]?.field === 'plugins'
+    const alreadyCanonical = entries.length === 1 && configs[0]?.entries[0]?.field === field
         && isDeepStrictEqual(entries[0].value, canonical);
     const changes = alreadyCanonical ? [] : targets.map(({ target, source, entries }, index) => {
         let next = source;
         for (const { field, index } of entries.toReversed())
             next = removeOpenCodeEntry(next, field, index);
         if (index === 0)
-            next = applyEdits(next, modify(next, ['plugins', -1], canonical, {}));
+            next = applyEdits(next, modify(next, [field, -1], canonical, {}));
         return { target, source, next };
     }).filter(({ source, next }) => source !== next);
     // Appending just our element avoids native add's whole-array rewrite, which
@@ -52,6 +64,8 @@ export function installOpenCodePlugin(homeDir, force = false, run = runOpenCode)
         fs.mkdirSync(path.dirname(target), { recursive: true });
         fs.writeFileSync(target, next);
     }
+    if (major === 1)
+        return [SQUARE_IDENTITY.packageName];
     if (!entries.some(({ spec }) => spec === SQUARE_IDENTITY.packageName)) {
         try {
             openCodeCommand(homeDir, ['plugin', 'add', SQUARE_IDENTITY.packageName], run, 'install');
@@ -100,6 +114,7 @@ function readOpenCodeConfigs(homeDir) {
         if (errors.length || typeof config !== 'object' || config === null || Array.isArray(config)) {
             throw new Error(`Invalid OpenCode configuration: ${target}`);
         }
+        const unproven = [];
         const entries = ['plugin', 'plugins'].flatMap((field) => {
             const plugins = config[field];
             if (plugins === undefined)
@@ -108,12 +123,15 @@ function readOpenCodeConfigs(homeDir) {
                 throw new Error(`Invalid OpenCode ${field} configuration: ${target}`);
             return plugins.flatMap((entry, index) => {
                 const spec = openCodePluginSpec(entry);
+                const raw = openCodeRawSpec(entry);
+                if (spec === undefined && raw !== undefined && openCodeV1Root(raw) !== undefined)
+                    unproven.push(raw);
                 const options = Array.isArray(entry) ? entry[1]
                     : typeof entry === 'object' && entry !== null ? entry.options : undefined;
                 return spec === undefined ? [] : [{ field, index, spec, options, value: entry }];
             });
         });
-        return [{ target, source, entries }];
+        return [{ target, source, entries, unproven }];
     });
 }
 export function uninstallOpenCodePlugin(homeDir) {
@@ -148,11 +166,37 @@ function removeOpenCodeEntry(source, field, index) {
         ...(comma === undefined ? [] : [{ offset: comma, length: 1, content: '' }]),
     ]);
 }
-function openCodePluginSpec(entry) {
+function openCodeRawSpec(entry) {
     const spec = typeof entry === 'string' ? entry : Array.isArray(entry) ? entry[0]
         : typeof entry === 'object' && entry !== null && 'package' in entry ? entry.package : undefined;
-    return typeof spec === 'string' && (spec === SQUARE_IDENTITY.packageName || spec.startsWith(`${SQUARE_IDENTITY.packageName}@`))
-        ? spec : undefined;
+    return typeof spec === 'string' ? spec : undefined;
+}
+function openCodeV1Root(spec) {
+    try {
+        const file = fileURLToPath(spec);
+        return file.endsWith(`${path.sep}dist${path.sep}plugins${path.sep}opencode-v1${path.sep}index.js`)
+            ? path.resolve(path.dirname(file), '../../..') : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function openCodePluginSpec(entry) {
+    const spec = openCodeRawSpec(entry);
+    if (spec === undefined)
+        return undefined;
+    if (spec === SQUARE_IDENTITY.packageName || spec.startsWith(`${SQUARE_IDENTITY.packageName}@`))
+        return spec;
+    const root = openCodeV1Root(spec);
+    if (root === undefined)
+        return undefined;
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+        return manifest.name === SQUARE_IDENTITY.packageName ? spec : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
 function parseOpenCodeConfig(stdout) {
     let sources;
@@ -171,6 +215,16 @@ function parseOpenCodeConfig(stdout) {
 /** Config sources prove configuration, not that a running session loaded the plugin. */
 export function verifyOpenCodeRuntime(homeDir, run = runOpenCode) {
     try {
+        const configs = readOpenCodeConfigs(homeDir);
+        const local = configs.flatMap(config => config.entries).filter(entry => entry.spec.startsWith('file:'));
+        const missing = local.find(entry => !fs.existsSync(fileURLToPath(entry.spec)));
+        if (missing)
+            return `✕ OpenCode 1.x plugin file missing: ${missing.spec}; reinstall Square and run square install opencode`;
+        const unproven = configs.flatMap(config => config.unproven)[0];
+        if (unproven)
+            return `○ OpenCode plugin ownership unverified: ${unproven}; inspect it before removing or replacing it`;
+        if (local.length)
+            return '✓ OpenCode 1.x plugin configured (runtime loading not verified)';
         const result = run(homeDir, ['debug', 'config']);
         if (result.status !== 0) {
             const diagnostic = result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`;