@open-agent-toolkit/cli 0.2.65 → 0.2.66

package/dist/commands/pjm/remote/shared-storage.d.ts

@@ -0,0 +1,36 @@
+export interface SharedStoragePreview {
+    schemaVersion: 1;
+    digest: string;
+    repositoryFingerprint: string;
+    configTarget: string;
+    targetKind: 'repository' | 'project';
+    projectScope: 'shared' | 'synced' | 'local' | null;
+    currentMode: 'local' | 'shared';
+    proposedMode: 'shared';
+    retainedDataWarning: string;
+    proposedPaths: string[];
+    createdAt: string;
+}
+export declare function parseSharedStoragePreview(value: unknown): SharedStoragePreview;
+export declare function buildSharedStoragePreview(input: Omit<SharedStoragePreview, 'schemaVersion' | 'digest' | 'proposedMode'>): SharedStoragePreview;
+export declare function applySharedStorageTransition(input: {
+    preview: SharedStoragePreview;
+    approval: {
+        previewDigest: string;
+        approvedAt: string;
+        actor: string;
+        source: string;
+    } | null;
+    now: string;
+    maxAgeMs: number;
+    current: {
+        repositoryFingerprint: string;
+        configTarget: string;
+        mode: 'local' | 'shared';
+    };
+    writeSharedConfig(mode: 'shared'): Promise<void>;
+}): Promise<{
+    status: 'applied';
+    movedRecords: false;
+}>;
+//# sourceMappingURL=shared-storage.d.ts.map

package/dist/commands/pjm/remote/shared-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-storage.d.ts","sourceRoot":"","sources":["../../../../src/commands/pjm/remote/shared-storage.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB,EAAE,MAAM,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,YAAY,GAAG,SAAS,CAAC;IACrC,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,IAAI,CAAC;IACnD,WAAW,EAAE,OAAO,GAAG,QAAQ,CAAC;IAChC,YAAY,EAAE,QAAQ,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAkBD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,GACb,oBAAoB,CAgBtB;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,IAAI,CACT,oBAAoB,EACpB,eAAe,GAAG,QAAQ,GAAG,cAAc,CAC5C,GACA,oBAAoB,CAqBtB;AAED,wBAAsB,4BAA4B,CAAC,KAAK,EAAE;IACxD,OAAO,EAAE,oBAAoB,CAAC;IAC9B,QAAQ,EAAE;QACR,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,GAAG,IAAI,CAAC;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE;QACP,qBAAqB,EAAE,MAAM,CAAC;QAC9B,YAAY,EAAE,MAAM,CAAC;QACrB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;KAC1B,CAAC;IACF,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,YAAY,EAAE,KAAK,CAAA;CAAE,CAAC,CA0DtD"}

package/dist/commands/pjm/remote/shared-storage.js

@@ -0,0 +1,110 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { containsSensitiveContentSignal } from './credential-safety.js';
+const SharedStoragePreviewSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    digest: z.string().min(1).max(512),
+    repositoryFingerprint: z.string().min(1).max(512),
+    configTarget: z.string().min(1).max(4_096),
+    targetKind: z.enum(['repository', 'project']),
+    projectScope: z.enum(['shared', 'synced', 'local']).nullable(),
+    currentMode: z.enum(['local', 'shared']),
+    proposedMode: z.literal('shared'),
+    retainedDataWarning: z.string().min(1).max(8_192),
+    proposedPaths: z.array(z.string().min(1).max(4_096)).min(1).max(64),
+    createdAt: z.string().datetime({ offset: true }),
+})
+    .strict();
+export function parseSharedStoragePreview(value) {
+    const preview = SharedStoragePreviewSchema.parse(value);
+    const rebuilt = buildSharedStoragePreview({
+        repositoryFingerprint: preview.repositoryFingerprint,
+        configTarget: preview.configTarget,
+        targetKind: preview.targetKind,
+        projectScope: preview.projectScope,
+        currentMode: preview.currentMode,
+        retainedDataWarning: preview.retainedDataWarning,
+        proposedPaths: preview.proposedPaths,
+        createdAt: preview.createdAt,
+    });
+    if (rebuilt.digest !== preview.digest) {
+        throw new Error('Shared storage preview digest is stale or mismatched.');
+    }
+    return preview;
+}
+export function buildSharedStoragePreview(input) {
+    if (input.targetKind === 'project' && input.projectScope === 'local') {
+        throw new Error('Local project targets cannot use shared operational storage.');
+    }
+    if (!input.repositoryFingerprint ||
+        !input.configTarget ||
+        input.proposedPaths.length === 0) {
+        throw new Error('Shared storage preview requires repository, config target, and proposed paths.');
+    }
+    const body = {
+        schemaVersion: 1,
+        ...input,
+        proposedMode: 'shared',
+    };
+    return { ...body, digest: digest(body) };
+}
+export async function applySharedStorageTransition(input) {
+    if (!input.approval)
+        throw new Error('Shared storage transition requires fresh preview approval.');
+    const rebuilt = buildSharedStoragePreview({
+        repositoryFingerprint: input.preview.repositoryFingerprint,
+        configTarget: input.preview.configTarget,
+        targetKind: input.preview.targetKind,
+        projectScope: input.preview.projectScope,
+        currentMode: input.preview.currentMode,
+        retainedDataWarning: input.preview.retainedDataWarning,
+        proposedPaths: input.preview.proposedPaths,
+        createdAt: input.preview.createdAt,
+    });
+    if (rebuilt.digest !== input.preview.digest ||
+        input.approval.previewDigest !== input.preview.digest) {
+        throw new Error('Shared storage approval is stale or mismatched.');
+    }
+    if (input.current.repositoryFingerprint !==
+        input.preview.repositoryFingerprint ||
+        input.current.configTarget !== input.preview.configTarget ||
+        input.current.mode !== input.preview.currentMode) {
+        throw new Error('Shared storage preview inputs changed before apply.');
+    }
+    const approvedAt = Date.parse(input.approval.approvedAt);
+    const previewAt = Date.parse(input.preview.createdAt);
+    const now = Date.parse(input.now);
+    if (!Number.isFinite(approvedAt) ||
+        !Number.isFinite(previewAt) ||
+        !Number.isFinite(now) ||
+        !Number.isFinite(input.maxAgeMs) ||
+        input.maxAgeMs < 0) {
+        throw new Error('Shared storage approval contains an invalid time.');
+    }
+    if (approvedAt < previewAt) {
+        throw new Error('Shared storage approval predates its preview.');
+    }
+    if (approvedAt > now) {
+        throw new Error('Shared storage approval is dated in the future.');
+    }
+    if (now - approvedAt > input.maxAgeMs) {
+        throw new Error('Shared storage approval is expired.');
+    }
+    if (!isSafeEvidence(input.approval.actor) ||
+        !isSafeEvidence(input.approval.source)) {
+        throw new Error('Shared storage approval evidence is unsafe.');
+    }
+    await input.writeSharedConfig('shared');
+    return { status: 'applied', movedRecords: false };
+}
+function isSafeEvidence(value) {
+    return (value.length > 0 &&
+        value.length <= 255 &&
+        !/[\r\n]/.test(value) &&
+        !value.includes('\0') &&
+        !containsSensitiveContentSignal(value));
+}
+function digest(value) {
+    return `sha256:${createHash('sha256').update(JSON.stringify(value)).digest('hex')}`;
+}

package/dist/commands/pjm/remote/snapshot.d.ts

@@ -0,0 +1,32 @@
+import { type RemoteSnapshotRecord } from './schema.js';
+export interface SanitizableRemoteSnapshot {
+    snapshotId: string;
+    bindingId: string;
+    provider: RemoteSnapshotRecord['provider'];
+    observedAt: string;
+    observedBy: RemoteSnapshotRecord['observedBy'];
+    identity: RemoteSnapshotRecord['identity'];
+    revision: RemoteSnapshotRecord['revision'];
+    issue: {
+        title: string;
+        description: string;
+        priority: string | null;
+        status: string;
+        [key: string]: unknown;
+    };
+    lifecycle: RemoteSnapshotRecord['lifecycle'];
+    extensions?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface SnapshotSanitizationOptions {
+    allowedExtensionKeys?: readonly string[];
+    suppressedCoreFields?: readonly CoreSnapshotField[];
+    suppressedFields?: readonly SnapshotRedaction['field'][];
+}
+type SnapshotRedaction = RemoteSnapshotRecord['redactions'][number];
+type CoreSnapshotField = Extract<SnapshotRedaction['field'], {
+    kind: 'core';
+}>['name'];
+export declare function sanitizeRemoteSnapshot(input: SanitizableRemoteSnapshot, options?: SnapshotSanitizationOptions): RemoteSnapshotRecord;
+export {};
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/commands/pjm/remote/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../../../src/commands/pjm/remote/snapshot.ts"],"names":[],"mappings":"AAIA,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,oBAAoB,CAAC,YAAY,CAAC,CAAC;IAC/C,QAAQ,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAC3C,QAAQ,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAC3C,KAAK,EAAE;QACL,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,SAAS,EAAE,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,oBAAoB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpD,gBAAgB,CAAC,EAAE,SAAS,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;CAC1D;AAOD,KAAK,iBAAiB,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AACpE,KAAK,iBAAiB,GAAG,OAAO,CAC9B,iBAAiB,CAAC,OAAO,CAAC,EAC1B;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CACjB,CAAC,MAAM,CAAC,CAAC;AAEV,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,yBAAyB,EAChC,OAAO,GAAE,2BAAgC,GACxC,oBAAoB,CAiEtB"}

package/dist/commands/pjm/remote/snapshot.js

@@ -0,0 +1,140 @@
+import { containsSensitiveContentSignal, containsSensitiveContentSignalInValue, } from './credential-safety.js';
+import { MAX_PROVIDER_EXTENSION_BYTES, MAX_SNAPSHOT_SUPPRESSION_EVIDENCE, RemoteSnapshotRecordSchema, WHOLE_FIELD_SUPPRESSION_MARKER, } from './schema.js';
+const CORE_SNAPSHOT_FIELD_COUNT = 4;
+const MAX_ALLOWED_EXTENSION_KEYS = MAX_SNAPSHOT_SUPPRESSION_EVIDENCE - CORE_SNAPSHOT_FIELD_COUNT;
+const SCHEMA_SAFE_EXTENSION_KEY = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+export function sanitizeRemoteSnapshot(input, options = {}) {
+    const redactions = [];
+    const pairedSuppression = validateSuppressedFieldReferences(options.suppressedFields ?? [], options.allowedExtensionKeys ?? []);
+    const suppressedCoreFields = validateSuppressedCoreFields([
+        ...(options.suppressedCoreFields ?? []),
+        ...pairedSuppression.core,
+    ]);
+    const issue = {
+        title: sanitizeCoreField('title', input.issue.title, redactions, suppressedCoreFields),
+        description: sanitizeCoreField('description', input.issue.description, redactions, suppressedCoreFields),
+        priority: input.issue.priority === null
+            ? null
+            : sanitizeCoreField('priority', input.issue.priority, redactions, suppressedCoreFields),
+        status: sanitizeCoreField('status', input.issue.status, redactions, suppressedCoreFields),
+    };
+    const extensions = sanitizeExtensions(input.provider, input.extensions, options.allowedExtensionKeys ?? [], redactions, pairedSuppression.extensions);
+    return RemoteSnapshotRecordSchema.parse({
+        recordType: 'snapshot',
+        schemaVersion: 2,
+        snapshotId: input.snapshotId,
+        bindingId: input.bindingId,
+        provider: input.provider,
+        observedAt: input.observedAt,
+        observedBy: input.observedBy,
+        identity: input.identity,
+        revision: input.revision,
+        issue,
+        lifecycle: input.lifecycle,
+        contentRedacted: redactions.length > 0,
+        redactionCount: redactions.length,
+        redactions,
+        extensions,
+    });
+}
+function sanitizeCoreField(field, value, redactions, suppressedCoreFields) {
+    if (suppressedCoreFields.has(field)) {
+        if (value !== WHOLE_FIELD_SUPPRESSION_MARKER) {
+            throw new Error(`Suppressed snapshot field '${field}' must contain only the suppression marker.`);
+        }
+        redactions.push({
+            field: { kind: 'core', name: field },
+            reason: 'sensitive-content',
+            representation: 'whole-field-marker',
+        });
+        return value;
+    }
+    if (!containsSensitiveContentSignal(value))
+        return value;
+    redactions.push({
+        field: { kind: 'core', name: field },
+        reason: 'sensitive-content',
+        representation: 'whole-field-marker',
+    });
+    return WHOLE_FIELD_SUPPRESSION_MARKER;
+}
+function validateSuppressedCoreFields(fields) {
+    const allowed = new Set([
+        'title',
+        'description',
+        'priority',
+        'status',
+    ]);
+    if (fields.length > CORE_SNAPSHOT_FIELD_COUNT ||
+        new Set(fields).size !== fields.length ||
+        fields.some((field) => !allowed.has(field))) {
+        throw new Error('Suppressed snapshot fields must be unique bounded core fields.');
+    }
+    return new Set(fields);
+}
+function validateSuppressedFieldReferences(fields, allowedExtensionKeys) {
+    if (fields.length > MAX_SNAPSHOT_SUPPRESSION_EVIDENCE) {
+        throw new Error('Suppression evidence exceeds the bounded field limit.');
+    }
+    const identities = fields.map((field) => field.kind === 'core' ? `core:${field.name}` : `extension:${field.key}`);
+    if (new Set(identities).size !== identities.length) {
+        throw new Error('Suppression evidence must consume each field once.');
+    }
+    const allowed = new Set(allowedExtensionKeys);
+    const extensions = fields.flatMap((field) => field.kind === 'extension' ? [field.key] : []);
+    if (extensions.some((key) => !allowed.has(key))) {
+        throw new Error('Suppressed adapter extensions must be present in the adapter allowlist.');
+    }
+    return {
+        core: fields.flatMap((field) => field.kind === 'core' ? [field.name] : []),
+        extensions: new Set(extensions),
+    };
+}
+function sanitizeExtensions(provider, extensions, allowedKeys, redactions, suppressedExtensions) {
+    validateExtensionAllowlist(allowedKeys);
+    if (!extensions || allowedKeys.length === 0)
+        return undefined;
+    const retained = {};
+    for (const key of allowedKeys) {
+        if (!Object.hasOwn(extensions, key))
+            continue;
+        const value = extensions[key];
+        if (suppressedExtensions.has(key)) {
+            if (value !== WHOLE_FIELD_SUPPRESSION_MARKER) {
+                throw new Error(`Suppressed adapter extension '${key}' must contain only the suppression marker.`);
+            }
+            retained[key] = value;
+            redactions.push({
+                field: { kind: 'extension', key },
+                reason: 'sensitive-content',
+                representation: 'whole-field-marker',
+            });
+            continue;
+        }
+        if (containsSensitiveContentSignalInValue(value)) {
+            retained[key] = WHOLE_FIELD_SUPPRESSION_MARKER;
+            redactions.push({
+                field: { kind: 'extension', key },
+                reason: 'sensitive-content',
+                representation: 'whole-field-marker',
+            });
+            continue;
+        }
+        retained[key] = value;
+    }
+    if (Object.keys(retained).length === 0)
+        return undefined;
+    const result = { [provider]: retained };
+    if (Buffer.byteLength(JSON.stringify(result), 'utf8') >
+        MAX_PROVIDER_EXTENSION_BYTES) {
+        throw new Error(`Provider extension exceeds ${MAX_PROVIDER_EXTENSION_BYTES} byte limit.`);
+    }
+    return result;
+}
+function validateExtensionAllowlist(allowedKeys) {
+    if (allowedKeys.length > MAX_ALLOWED_EXTENSION_KEYS ||
+        new Set(allowedKeys).size !== allowedKeys.length ||
+        allowedKeys.some((key) => !SCHEMA_SAFE_EXTENSION_KEY.test(key))) {
+        throw new Error('Adapter extension keys must be unique, bounded, and schema-safe.');
+    }
+}

package/dist/commands/pjm/remote/storage-locator.d.ts

@@ -0,0 +1,29 @@
+export type RemoteStorageClass = 'shared' | 'synced' | 'local';
+export interface RemoteStorageTarget {
+    kind: 'backlog' | 'project';
+    scope: RemoteStorageClass;
+    path: string | null;
+}
+export interface ResolveRemoteStorageLocationsInput {
+    repoRoot: string;
+    gitCommonDir: string;
+    repositoryIdentity: string;
+    stateStorage: 'local' | 'shared';
+    target: RemoteStorageTarget;
+}
+export interface RemoteStorageLocations {
+    repositoryFingerprint: string;
+    portable: {
+        storageClass: RemoteStorageClass;
+        bindingsDir: string;
+    };
+    operational: {
+        storageClass: 'local' | 'shared';
+        root: string;
+        bindingsDir: string;
+        operationsDir: string;
+        batchesDir: string;
+    };
+}
+export declare function resolveRemoteStorageLocations(input: ResolveRemoteStorageLocationsInput): RemoteStorageLocations;
+//# sourceMappingURL=storage-locator.d.ts.map

package/dist/commands/pjm/remote/storage-locator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-locator.d.ts","sourceRoot":"","sources":["../../../../src/commands/pjm/remote/storage-locator.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE/D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IAC5B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,OAAO,GAAG,QAAQ,CAAC;IACjC,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE;QACR,YAAY,EAAE,kBAAkB,CAAC;QACjC,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,WAAW,EAAE;QACX,YAAY,EAAE,OAAO,GAAG,QAAQ,CAAC;QACjC,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,kCAAkC,GACxC,sBAAsB,CAyCxB"}

package/dist/commands/pjm/remote/storage-locator.js

@@ -0,0 +1,62 @@
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+export function resolveRemoteStorageLocations(input) {
+    const repoRoot = resolve(input.repoRoot);
+    const gitCommonDir = resolve(input.gitCommonDir);
+    const repositoryFingerprint = fingerprintRepository(input.repositoryIdentity);
+    const localOperationalRoot = join(gitCommonDir, 'oat', 'pjm-remote', repositoryFingerprint);
+    const ownerRemoteRoot = resolveOwnerRemoteRoot(repoRoot, input.target);
+    if (input.stateStorage === 'shared' && input.target.scope === 'local') {
+        throw new Error('Local projects cannot use shared operational storage; choose local state storage.');
+    }
+    const operationalRoot = input.stateStorage === 'shared'
+        ? join(ownerRemoteRoot, 'state')
+        : localOperationalRoot;
+    const portableBindingsDir = input.target.scope === 'local'
+        ? join(localOperationalRoot, 'metadata', 'bindings')
+        : join(ownerRemoteRoot, 'bindings');
+    return {
+        repositoryFingerprint,
+        portable: {
+            storageClass: input.target.scope,
+            bindingsDir: portableBindingsDir,
+        },
+        operational: {
+            storageClass: input.stateStorage,
+            root: operationalRoot,
+            bindingsDir: join(operationalRoot, 'bindings'),
+            operationsDir: join(operationalRoot, 'operations'),
+            batchesDir: join(operationalRoot, 'batches'),
+        },
+    };
+}
+function resolveOwnerRemoteRoot(repoRoot, target) {
+    if (target.kind === 'backlog') {
+        if (target.scope !== 'shared') {
+            throw new Error('Backlog remote metadata must use shared scope.');
+        }
+        return join(repoRoot, '.oat', 'repo', 'pjm', 'remote');
+    }
+    if (!target.path || !isAbsolute(target.path)) {
+        throw new Error('Project remote storage requires an absolute project path.');
+    }
+    const projectPath = resolve(target.path);
+    const relativePath = relative(repoRoot, projectPath);
+    if (relativePath === '..' ||
+        relativePath.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) ||
+        isAbsolute(relativePath)) {
+        throw new Error('Project remote storage path must remain inside the repository.');
+    }
+    return join(projectPath, 'remote');
+}
+function fingerprintRepository(repositoryIdentity) {
+    const normalized = repositoryIdentity
+        .trim()
+        .replace(/\.git$/i, '')
+        .replace(/\/$/, '')
+        .toLowerCase();
+    if (!normalized) {
+        throw new Error('A stable repository identity is required for remote state.');
+    }
+    return createHash('sha256').update(normalized).digest('hex').slice(0, 24);
+}

package/dist/commands/pjm/remote/store.d.ts

@@ -0,0 +1,85 @@
+import { type ExternalActionEnvelope } from './external-action.js';
+import { type RemoteBatchRecord, type RemoteBindingMetadata, type RemoteBindingState, type RemoteOperationOutcome, type RemoteOperationRecord, type RemoteOperationStep, type FieldVerification, type PlannedBindingCreate, type VerifiedDurableRemoteIdentity } from './schema.js';
+import { type SharedStoragePreview } from './shared-storage.js';
+import type { RemoteStorageLocations } from './storage-locator.js';
+export interface RemoteStoreFileHandle {
+    writeFile(data: string): Promise<unknown>;
+    sync(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface RemoteStoreFilesystem {
+    mkdir(path: string, options: {
+        recursive: true;
+        mode: number;
+    }): Promise<unknown>;
+    open(path: string, flags: string, mode?: number): Promise<RemoteStoreFileHandle>;
+    readFile(path: string, encoding: 'utf8'): Promise<string>;
+    readdir(path: string): Promise<string[]>;
+    rename(from: string, to: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    syncDirectory(path: string): Promise<void>;
+}
+export declare const defaultRemoteStoreFilesystem: RemoteStoreFilesystem;
+export interface RemoteSyncStoreDependencies {
+    filesystem: RemoteStoreFilesystem;
+    randomId: () => string;
+}
+export type RemoteOperationState = RemoteOperationRecord['state'];
+export interface RemoteOperationTransition {
+    state: RemoteOperationState;
+    updatedAt: string;
+    approval?: RemoteOperationRecord['approval'];
+    selectedExecution?: RemoteOperationRecord['selectedExecution'];
+    outcome?: RemoteOperationOutcome;
+    appendStep?: RemoteOperationStep;
+    verification?: FieldVerification[];
+    lastSafeStep?: RemoteOperationRecord['lastSafeStep'];
+    retryDisposition?: RemoteOperationRecord['retryDisposition'];
+    appendAttempt?: RemoteOperationRecord['attempts'][number];
+    completeAttempt?: {
+        attemptId: string;
+        completedAt: string;
+        receiptDigest: string;
+    };
+    appendObservation?: RemoteOperationRecord['observations'][number];
+    appendMaterializationStep?: NonNullable<RemoteOperationRecord['materializationSteps']>[number];
+    materializationPlan?: NonNullable<RemoteOperationRecord['materializationPlan']>;
+    verificationHandoff?: NonNullable<RemoteOperationRecord['verificationHandoff']>;
+    currentAction?: NonNullable<RemoteOperationRecord['currentAction']>;
+}
+export interface ConcurrentOperationIntentInspection {
+    bindingState: RemoteBindingState | null;
+    activeOperations: RemoteOperationRecord[];
+    hasConcurrentIntents: boolean;
+}
+export declare class RemoteSyncStore {
+    #private;
+    readonly locations: RemoteStorageLocations;
+    constructor(locations: RemoteStorageLocations, dependencies?: Partial<RemoteSyncStoreDependencies>);
+    readBindingMetadata(bindingId: string): Promise<RemoteBindingMetadata | null>;
+    materializeVerifiedBinding(operationId: string, record: RemoteBindingMetadata, verification: VerifiedDurableRemoteIdentity): Promise<void>;
+    listBindingMetadata(): Promise<RemoteBindingMetadata[]>;
+    updateBindingMetadata(record: RemoteBindingMetadata): Promise<void>;
+    readBindingState(bindingId: string): Promise<RemoteBindingState | null>;
+    writeBindingState(record: RemoteBindingState): Promise<void>;
+    readOperation(operationId: string): Promise<RemoteOperationRecord | null>;
+    readCurrentAction(operationId: string): Promise<ExternalActionEnvelope | null>;
+    writeCurrentAction(operationId: string, action: ExternalActionEnvelope): Promise<void>;
+    writeActionEvidence(operationId: string, action: ExternalActionEnvelope): Promise<ExternalActionEnvelope>;
+    retireCurrentAction(operationId: string, expectedAction: ExternalActionEnvelope): Promise<void>;
+    retireCurrentActionPointerIfPresent(operationId: string, expectedAction: ExternalActionEnvelope): Promise<void>;
+    readAction(operationId: string, stepId: string): Promise<ExternalActionEnvelope | null>;
+    readSharedStoragePreview(): Promise<SharedStoragePreview | null>;
+    writeSharedStoragePreview(preview: SharedStoragePreview): Promise<void>;
+    materializeIntakeBinding(record: RemoteBindingMetadata): Promise<void>;
+    createOperation(record: RemoteOperationRecord): Promise<void>;
+    updateOperation(record: RemoteOperationRecord): Promise<void>;
+    createBindingIntent(intent: PlannedBindingCreate): Promise<void>;
+    listActiveOperations(bindingId: string): Promise<RemoteOperationRecord[]>;
+    detectConcurrentOperationIntents(bindingId: string): Promise<ConcurrentOperationIntentInspection>;
+    transitionOperation(operationId: string, expectedState: RemoteOperationState, update: RemoteOperationTransition): Promise<RemoteOperationRecord>;
+    readBatch(batchId: string): Promise<RemoteBatchRecord | null>;
+    createBatch(record: RemoteBatchRecord): Promise<void>;
+    updateBatch(record: RemoteBatchRecord): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/commands/pjm/remote/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/commands/pjm/remote/store.ts"],"names":[],"mappings":"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"}