chore(node-sdk): audit providers copilot droid augment cline

Providers use plugins/common.ts, shell-command.ts, and managed-runtime-status; isNodeExecutable recognizes the running executable or a node-named binary.

Claude-Session: https://claude.ai/code/session_01Agoc9bRVE9KL7mmWtey9Vq

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@elydora/sdk",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@elydora/sdk",
-      "version": "2.0.0",
+      "version": "2.0.1",
       "license": "MIT",
       "dependencies": {
         "@decimalturn/toml-patch": "^2.0.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elydora/sdk",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Node.js/TypeScript SDK for the Elydora tamper-evident audit platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/cli.ts

@@ -13,7 +13,8 @@ import {
 import { writePrivateFile } from './secure-files.js';
 import { SUPPORTED_AGENTS } from './plugins/registry.js';
 import type { AgentPlugin, InstallConfig } from './plugins/base.js';
-import { generateHookScript, generateGuardScript } from './plugins/hook-template.js';
+import { generateGuardScript } from './plugins/guard-template.js';
+import { generateHookScript } from './plugins/hook-template.js';
 import { augmentPlugin } from './plugins/augment.js';
 import { claudecodePlugin } from './plugins/claudecode.js';
 import { cursorPlugin } from './plugins/cursor.js';
@@ -50,10 +51,6 @@ const PLUGINS: ReadonlyMap<string, AgentPlugin> = new Map([
   ['qwen', qwenPlugin],
 ]);
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
 function die(message: string): never {
   console.error(`Error: ${message}`);
   process.exit(1);
@@ -137,10 +134,6 @@ Supported agents: ${Array.from(SUPPORTED_AGENTS.keys()).join(', ')}
 `);
 }
 
-// ---------------------------------------------------------------------------
-// Commands
-// ---------------------------------------------------------------------------
-
 async function cmdInstall(args: string[]): Promise<void> {
   const { values } = parseArgs({
     args,
@@ -178,7 +171,6 @@ async function cmdInstall(args: string[]): Promise<void> {
   });
   const baseUrl = values.base_url ?? 'https://api.elydora.com';
 
-  // Validate private key by deriving public key
   let publicKey: string;
   try {
     publicKey = derivePublicKey(privateKey);
@@ -255,7 +247,6 @@ async function cmdUninstall(args: string[]): Promise<void> {
   let agentDir: string;
   let agentDirectoryExists: boolean;
 
-  // If --agent_id not provided, scan ~/.elydora/*/config.json for matching agent_name
   if (agentId) {
     agentDir = resolvePrivateChildDirectory(ELYDORA_DIR, agentId);
     const runtimeRootExists = await requirePhysicalDirectory(ELYDORA_DIR);
@@ -287,10 +278,8 @@ async function cmdUninstall(args: string[]): Promise<void> {
   const plugin = PLUGINS.get(agentName)!;
   const registryEntry = SUPPORTED_AGENTS.get(agentName)!;
 
-  // Uninstall agent-specific config
   await plugin.uninstall(agentId);
 
-  // Remove entire agent directory
   if (agentDirectoryExists) {
     await fsp.rm(agentDir, { recursive: true });
   }
@@ -303,14 +292,12 @@ async function cmdStatus(): Promise<void> {
 
   let anyInstalled = false;
 
-  // Scan ~/.elydora/*/config.json to discover installed agents
   const installedAgents = await discoverInstalledAgents();
 
   for (const [name, plugin] of PLUGINS) {
     const st = await plugin.status();
     const statusIcon = st.installed ? '[installed]' : '[not installed]';
 
-    // Find matching installed agent(s) for this plugin
     const matching = installedAgents.filter((a) => a.agentName === name);
 
     console.log(`  ${st.displayName} (${name}) ${statusIcon}`);
@@ -339,10 +326,6 @@ function cmdAgents(): void {
   console.log('\nUse "elydora install --agent <name>" to install an audit hook.');
 }
 
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
 

src/client.ts

@@ -74,34 +74,19 @@ export class ElydoraClient {
     this.prevChainHash = ZERO_CHAIN_HASH;
   }
 
-  /**
-   * Set the API token used for authenticated API calls.
-   */
   setToken(token: string): void {
     this.token = token;
   }
 
-  /**
-   * Get the current chain hash (useful for debugging/inspection).
-   */
   getChainHash(): string {
     return this.prevChainHash;
   }
 
-  /**
-   * Get the public key derived from the configured private key.
-   */
   getPublicKey(): string {
     return derivePublicKey(this.privateKey);
   }
 
-  // -------------------------------------------------------------------------
+  /** @deprecated Password auth for the SDK CLI path; Console users sign in through Better Auth. */
-  // Auth (static methods — no instance needed)
-  // -------------------------------------------------------------------------
-
-  /**
-   * @deprecated Use Better Auth endpoints directly. See docs.
-   */
   static async register(
     baseUrl: string,
     email: string,
@@ -123,9 +108,7 @@ export class ElydoraClient {
     return handleResponse<AuthRegisterResponse>(res);
   }
 
-  /**
+  /** @deprecated Password auth for the SDK CLI path; Console users sign in through Better Auth. */
-   * @deprecated Use Better Auth endpoints directly. See docs.
-   */
   static async login(
     baseUrl: string,
     email: string,
@@ -141,10 +124,6 @@ export class ElydoraClient {
     return handleResponse<AuthLoginResponse>(res);
   }
 
-  // -------------------------------------------------------------------------
-  // Auth (instance methods — require token)
-  // -------------------------------------------------------------------------
-
   async getMe(): Promise<GetMeResponse> {
     return this.request<GetMeResponse>('GET', '/v1/auth/me');
   }
@@ -157,10 +136,6 @@ export class ElydoraClient {
     return this.request<RotateApiTokenResponse>('POST', '/v1/auth/rotate', {});
   }
 
-  // -------------------------------------------------------------------------
-  // Agent management
-  // -------------------------------------------------------------------------
-
   async registerAgent(request: RegisterAgentRequest): Promise<RegisterAgentResponse> {
     assertIntegrationType(request?.integration_type);
     return this.request<RegisterAgentResponse>('POST', '/v1/agents/register', request);
@@ -195,31 +170,15 @@ export class ElydoraClient {
     await this.request<unknown>('POST', `/v1/agents/${encodeURIComponent(agentId)}/revoke`, { kid, reason });
   }
 
-  // -------------------------------------------------------------------------
+  // Builds, hashes, chains, and signs an EOR locally, then advances prev_chain_hash.
-  // Operations (core)
-  // -------------------------------------------------------------------------
-
-  /**
-   * Construct and sign an Elydora Operation Record (EOR) locally.
-   *
-   * 1. Generate UUIDv7 for operation_id
-   * 2. Generate random nonce (16 bytes, base64url)
-   * 3. Compute payload_hash (SHA-256 of JCS-canonicalized payload)
-   * 4. Compute chain_hash from prev_chain_hash
-   * 5. Construct canonical EOR (minus signature)
-   * 6. Sign JCS-canonicalized EOR with Ed25519
-   * 7. Update internal prev_chain_hash
-   */
   createOperation(params: CreateOperationParams): EOR {
     const operationId = uuidv7();
     const issuedAt = Date.now();
     const nonce = generateNonce();
     const payload = params.payload ?? null;
 
-    // Compute payload hash
     const payloadHash = computePayloadHash(payload);
 
-    // Compute chain hash
     const chainHash = computeChainHash(
       this.prevChainHash,
       payloadHash,
@@ -227,7 +186,6 @@ export class ElydoraClient {
       issuedAt,
     );
 
-    // Construct the EOR without signature for signing
     const eorWithoutSig: Omit<EOR, 'signature'> = {
       op_version: '1.0',
       operation_id: operationId,
@@ -245,11 +203,9 @@ export class ElydoraClient {
       agent_pubkey_kid: this.kid,
     };
 
-    // Sign the JCS-canonicalized EOR (without signature field)
     const canonical = jcsCanonicalise(eorWithoutSig);
     const signature = signEd25519(this.privateKey, Buffer.from(canonical, 'utf-8'));
 
-    // Update internal chain state
     this.prevChainHash = chainHash;
 
     return {
@@ -270,18 +226,10 @@ export class ElydoraClient {
     return this.request<VerifyOperationResponse>('POST', `/v1/operations/${encodeURIComponent(operationId)}/verify`, {});
   }
 
-  // -------------------------------------------------------------------------
-  // Audit
-  // -------------------------------------------------------------------------
-
   async queryAudit(params: AuditQueryRequest): Promise<AuditQueryResponse> {
     return this.request<AuditQueryResponse>('POST', '/v1/audit/query', params);
   }
 
-  // -------------------------------------------------------------------------
-  // Epochs
-  // -------------------------------------------------------------------------
-
   async listEpochs(): Promise<ListEpochsResponse> {
     return this.request<ListEpochsResponse>('GET', '/v1/epochs');
   }
@@ -290,10 +238,6 @@ export class ElydoraClient {
     return this.request<GetEpochResponse>('GET', `/v1/epochs/${encodeURIComponent(epochId)}`);
   }
 
-  // -------------------------------------------------------------------------
-  // Exports
-  // -------------------------------------------------------------------------
-
   async createExport(params: CreateExportRequest): Promise<CreateExportResponse> {
     return this.request<CreateExportResponse>('POST', '/v1/exports', params);
   }
@@ -323,10 +267,6 @@ export class ElydoraClient {
     return res.arrayBuffer();
   }
 
-  // -------------------------------------------------------------------------
-  // JWKS
-  // -------------------------------------------------------------------------
-
   async getJWKS(): Promise<JWKSResponse> {
     const url = `${this.baseUrl}/.well-known/elydora/jwks.json`;
     const res = await fetch(url, {
@@ -336,10 +276,6 @@ export class ElydoraClient {
     return handleResponse<JWKSResponse>(res);
   }
 
-  // -------------------------------------------------------------------------
-  // Health
-  // -------------------------------------------------------------------------
-
   async health(): Promise<HealthResponse> {
     const url = `${this.baseUrl}/v1/health`;
     const res = await fetch(url, {
@@ -355,10 +291,6 @@ export class ElydoraClient {
     return handleResponse<DeepHealthResponse>(res);
   }
 
-  // -------------------------------------------------------------------------
-  // Webhooks
-  // -------------------------------------------------------------------------
-
   async listWebhooks(): Promise<ListWebhooksResponse> {
     return this.request<ListWebhooksResponse>('GET', '/v1/webhooks');
   }
@@ -371,27 +303,15 @@ export class ElydoraClient {
     await this.request<unknown>('DELETE', `/v1/webhooks/${encodeURIComponent(webhookId)}`);
   }
 
-  // -------------------------------------------------------------------------
-  // Members
-  // -------------------------------------------------------------------------
-
   async listMembers(): Promise<ListMembersResponse> {
     return this.request<ListMembersResponse>('GET', '/v1/members');
   }
 
-  // -------------------------------------------------------------------------
-  // Admin events
-  // -------------------------------------------------------------------------
-
   async listAdminEvents(limit?: number): Promise<ListAdminEventsResponse> {
     const query = limit ? `?limit=${limit}` : '';
     return this.request<ListAdminEventsResponse>('GET', `/v1/admin/events${query}`);
   }
 
-  // -------------------------------------------------------------------------
-  // Internal HTTP helpers
-  // -------------------------------------------------------------------------
-
   private async request<T>(
     method: string,
     path: string,
@@ -420,7 +340,6 @@ export class ElydoraClient {
           body: body !== undefined ? JSON.stringify(body) : undefined,
         });
 
-        // Only retry on 429 or 5xx
         if (attempt < this.maxRetries && (res.status === 429 || res.status >= 500)) {
           const retryAfter = res.headers.get('Retry-After');
           const delayMs = retryAfter
@@ -434,7 +353,6 @@ export class ElydoraClient {
       } catch (err) {
         lastError = err instanceof Error ? err : new Error(String(err));
 
-        // Only retry on network errors, not API errors
         if (err instanceof ElydoraError) {
           throw err;
         }
@@ -450,13 +368,8 @@ export class ElydoraClient {
   }
 }
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
 async function handleResponse<T>(res: Response): Promise<T> {
   if (res.ok) {
-    // 204 No Content
     if (res.status === 204) {
       return undefined as T;
     }
@@ -467,7 +380,7 @@ async function handleResponse<T>(res: Response): Promise<T> {
   try {
     errorBody = (await res.json()) as ErrorResponse;
   } catch {
-    // Response body was not valid JSON
+    // non-JSON error body: fall through to the status-only error
   }
 
   if (errorBody?.error) {

src/crypto.ts

@@ -1,18 +1,7 @@
 import crypto from 'node:crypto';
 import { base64urlEncode } from './utils.js';
 
-// ---------------------------------------------------------------------------
+// RFC 8785 JSON Canonicalization Scheme
-// JCS Canonicalization (RFC 8785)
-// ---------------------------------------------------------------------------
-
-/**
- * Canonicalize a JSON value according to JCS (RFC 8785).
- *
- * - Object keys sorted lexicographically by UTF-16 code units
- * - No whitespace
- * - Numbers serialized using ES2015 Number serialization
- * - Strings serialized with minimal escaping per JSON spec
- */
 export function jcsCanonicalise(value: unknown): string {
   if (value === null || value === undefined) {
     return 'null';
@@ -46,30 +35,13 @@ export function jcsCanonicalise(value: unknown): string {
   return JSON.stringify(value);
 }
 
-// ---------------------------------------------------------------------------
-// SHA-256
-// ---------------------------------------------------------------------------
-
-/**
- * Compute SHA-256 of a UTF-8 string or buffer and return base64url.
- */
 export function sha256Base64url(data: string | Buffer): string {
   const input = typeof data === 'string' ? Buffer.from(data, 'utf-8') : data;
   const hash = crypto.createHash('sha256').update(input).digest();
   return base64urlEncode(hash);
 }
 
-// ---------------------------------------------------------------------------
+// chain_hash = SHA-256("prev|payload_hash|operation_id|issued_at")
-// Chain hash computation
-// ---------------------------------------------------------------------------
-
-/**
- * Compute the chain hash for an operation.
- *
- * chain_hash = SHA-256(prev_chain_hash + "|" + payload_hash + "|" + operation_id + "|" + issued_at)
- *
- * All inputs concatenated as UTF-8 strings separated by '|'.
- */
 export function computeChainHash(
   prevChainHash: string,
   payloadHash: string,
@@ -80,13 +52,6 @@ export function computeChainHash(
   return sha256Base64url(input);
 }
 
-// ---------------------------------------------------------------------------
-// Payload hash
-// ---------------------------------------------------------------------------
-
-/**
- * Compute SHA-256 hash of JCS-canonicalized payload, returned as base64url.
- */
 export function computePayloadHash(
   payload: Record<string, unknown> | string | null,
 ): string {
@@ -94,23 +59,11 @@ export function computePayloadHash(
   return sha256Base64url(canonical);
 }
 
-// ---------------------------------------------------------------------------
+// PKCS8 envelope: SEQUENCE { INTEGER 0, SEQUENCE { OID 1.3.101.112 }, OCTET STRING { OCTET STRING seed } }
-// Ed25519 signing
-// ---------------------------------------------------------------------------
-
-// PKCS8 prefix for wrapping a 32-byte Ed25519 seed
 const PKCS8_ED25519_PREFIX = Buffer.from([
-  0x30, 0x2e, // SEQUENCE (46 bytes)
+  0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
-  0x02, 0x01, 0x00, // INTEGER 0
-  0x30, 0x05, // SEQUENCE (5 bytes)
-  0x06, 0x03, 0x2b, 0x65, 0x70, // OID 1.3.101.112 (Ed25519)
-  0x04, 0x22, // OCTET STRING (34 bytes)
-  0x04, 0x20, // OCTET STRING (32 bytes)
 ]);
 
-/**
- * Import a base64url-encoded 32-byte Ed25519 seed as a Node.js KeyObject.
- */
 function importPrivateKey(privateKeyBase64url: string): crypto.KeyObject {
   const seed = Buffer.from(privateKeyBase64url, 'base64url');
   const pkcs8 = Buffer.concat([PKCS8_ED25519_PREFIX, seed]);
@@ -121,37 +74,20 @@ function importPrivateKey(privateKeyBase64url: string): crypto.KeyObject {
   });
 }
 
-/**
- * Sign data with Ed25519 using a base64url-encoded 32-byte seed.
- *
- * @returns base64url-encoded 64-byte signature
- */
 export function signEd25519(privateKeyBase64url: string, data: Buffer): string {
   const keyObject = importPrivateKey(privateKeyBase64url);
   const signature = crypto.sign(null, data, keyObject);
   return base64urlEncode(signature);
 }
 
-/**
- * Derive the Ed25519 public key from a base64url-encoded 32-byte seed.
- *
- * @returns base64url-encoded 32-byte public key
- */
 export function derivePublicKey(privateKeyBase64url: string): string {
   const keyObject = importPrivateKey(privateKeyBase64url);
   const publicKeyObject = crypto.createPublicKey(keyObject);
   const rawPublicKey = publicKeyObject.export({ type: 'spki', format: 'der' });
-  // The raw 32-byte public key is the last 32 bytes of the SPKI DER encoding
+  // The raw key is the last 32 bytes of the SPKI DER encoding.
   const publicKeyBytes = rawPublicKey.subarray(rawPublicKey.length - 32);
   return base64urlEncode(publicKeyBytes);
 }
 
-// ---------------------------------------------------------------------------
+// 32 zero bytes; equals the Backend GENESIS_CHAIN_HASH.
-// Zero chain hash (initial prev_chain_hash for the first operation)
-// ---------------------------------------------------------------------------
-
-/**
- * The initial chain hash value: base64url encoding of 32 zero bytes.
- * Must match the backend's GENESIS_CHAIN_HASH constant exactly.
- */
 export const ZERO_CHAIN_HASH: string = base64urlEncode(Buffer.alloc(32, 0));

src/index.ts

@@ -20,7 +20,6 @@ export {
 } from './utils.js';
 
 export type {
-  // Enums
   AgentStatus,
   KeyStatus,
   ExportStatus,
@@ -29,7 +28,6 @@ export type {
   AdminAction,
   ErrorCode,
 
-  // Entities
   Agent,
   AgentKey,
   Operation,
@@ -41,11 +39,9 @@ export type {
   User,
   Export,
 
-  // Protocol
   EOR,
   EAR,
 
-  // API request/response
   ElydoraClientConfig,
   CreateOperationParams,
   RegisterAgentRequest,
@@ -75,6 +71,7 @@ export type {
   JWKSResponse,
   HealthResponse,
   DeepHealthResponse,
+  Webhook,
   ListWebhooksResponse,
   RegisterWebhookResponse,
   ListMembersResponse,

src/plugins/augment-contract.ts

@@ -1,6 +1,8 @@
 import os from 'node:os';
 import path from 'node:path';
-import { parseStrictJsonObject } from './strict-json.js';
+import { sameAgentId, samePath } from './common.js';
+import { quotePosix, readPosixArgument, type ParsedArgument } from './shell-command.js';
+import { isObject, parseStrictJsonObject, type JsonObject } from './strict-json.js';
 
 export const AGENT_KEY = 'augment';
 export const GUARD_SCRIPT = 'guard.js';
@@ -20,8 +22,6 @@ const SESSION_EVENTS = new Set([
   'PromptSubmit',
 ]);
 
-export type JsonObject = Record<string, unknown>;
-
 export interface AugmentHandler extends JsonObject {
   readonly type: 'command';
   readonly command: string;
@@ -58,23 +58,10 @@ export interface RuntimeContract {
   readonly auditWrapperPath: string;
 }
 
-interface ParsedArgument {
-  readonly value: string;
-  readonly next: number;
-}
-
-export function isObject(value: unknown): value is JsonObject {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function hasOwn(value: JsonObject, key: string): boolean {
   return Object.prototype.hasOwnProperty.call(value, key);
 }
 
-function quotePosix(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
 function quoteWindows(value: string): string {
   return `"${value.replaceAll('"', '\\"')}"`;
 }
@@ -98,42 +85,12 @@ function readWindowsArgument(command: string, start: number): ParsedArgument | u
   return undefined;
 }
 
-const POSIX_APOSTROPHE = `'"'"'`;
-
-function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length;) {
-    if (command.startsWith(POSIX_APOSTROPHE, index)) {
-      value += "'";
-      index += POSIX_APOSTROPHE.length;
-      continue;
-    }
-    if (command[index] === "'") return { value, next: index + 1 };
-    value += command[index];
-    index += 1;
-  }
-  return undefined;
-}
-
 function parseWrapperCommand(command: string): string | undefined {
   const readArgument = process.platform === 'win32' ? readWindowsArgument : readPosixArgument;
   const parsed = readArgument(command, 0);
   return parsed?.next === command.length && parsed.value ? parsed.value : undefined;
 }
 
-function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-function sameAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
-}
-
 export function wrapperPaths(agentDirectory: string): {
   readonly guardPath: string;
   readonly auditPath: string;

src/plugins/augment-installation.ts

@@ -22,18 +22,10 @@ const DISPLAY_NAME = 'Augment Code CLI';
 const SETTINGS_DIRECTORY_LABEL = 'Auggie configuration directory';
 const SETTINGS_LABEL = 'Auggie user settings';
 
-export type AugmentRuntimePaths = ManagedRuntimePaths;
-export type PreparedAugmentInstallation = PreparedManagedInstallation;
-export type { RenameFile };
-
-export function augmentRuntimePaths(config: InstallConfig): AugmentRuntimePaths {
-  return managedRuntimePaths(config, AGENT_KEY, GUARD_SCRIPT, AUDIT_SCRIPT);
-}
-
 export async function preflightAugmentInstallation(
   config: InstallConfig,
   settingsPath: string,
-): Promise<AugmentRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
     hookLocations: [{ directoryLabel: SETTINGS_DIRECTORY_LABEL, filePath: settingsPath }],
@@ -44,13 +36,13 @@ export async function preflightAugmentInstallation(
 export async function prepareAugmentInstallation(
   config: InstallConfig,
   rendered: RenderedAugmentDocument,
-): Promise<PreparedAugmentInstallation> {
+): Promise<PreparedManagedInstallation> {
   if (!rendered.changed && rendered.document.raw === undefined) {
     throw new Error('Auggie hook installation did not produce a settings document');
   }
   const settingsSource = rendered.next ?? rendered.document.raw;
   if (settingsSource === undefined) throw new Error('Auggie hook settings are missing');
-  const paths = augmentRuntimePaths(config);
+  const paths = managedRuntimePaths(config, AGENT_KEY, GUARD_SCRIPT, AUDIT_SCRIPT);
   return prepareManagedInstallation({
     agentKey: AGENT_KEY,
     displayName: DISPLAY_NAME,
@@ -78,7 +70,7 @@ export async function prepareAugmentInstallation(
 }
 
 export async function commitAugmentInstallation(
-  prepared: PreparedAugmentInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/augment-io.ts

@@ -2,9 +2,7 @@ import os from 'node:os';
 import path from 'node:path';
 import {
   AGENT_KEY,
-  AUDIT_SCRIPT,
   AUDIT_WRAPPER,
-  GUARD_SCRIPT,
   GUARD_WRAPPER,
   buildWrapper,
   createAugmentDocument,
@@ -13,15 +11,13 @@ import {
   type RenderedAugmentDocument,
   type RuntimeContract,
 } from './augment-contract.js';
+import { MAX_CONFIG_BYTES, samePath } from './common.js';
 import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
+import { managedRuntimeFilesExist } from './managed-runtime-status.js';
 import {
   commitManagedTransaction,
   prepareManagedFileChange,
 } from './managed-transaction.js';
-import { parseStrictJsonObject, type JsonObject } from './strict-json.js';
-
-const MAX_SECRET_BYTES = 64 * 1024;
-const MAX_CONFIG_BYTES = 512 * 1024;
 
 export function resolveConfigPath(): string {
   return path.join(os.homedir(), '.augment', 'settings.json');
@@ -59,102 +55,21 @@ export async function writeAugmentDocument(rendered: RenderedAugmentDocument): P
   });
 }
 
-function sameAgentId(left: string, right: string): boolean {
+function wrappersValid(contract: RuntimeContract): boolean {
-  return process.platform === 'win32'
+  const agentDirectory = path.dirname(contract.guardPath);
-    ? left.toLowerCase() === right.toLowerCase()
+  return samePath(contract.guardWrapperPath, path.join(agentDirectory, GUARD_WRAPPER))
-    : left === right;
-}
-
-function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-function requireNonEmptyString(value: unknown, field: string, configPath: string): string {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`Elydora runtime config ${field} is invalid: ${configPath}`);
-  }
-  return value;
-}
-
-function validateRuntimeConfig(
-  config: JsonObject,
-  contract: RuntimeContract,
-  configPath: string,
-): void {
-  const supported = new Set(['org_id', 'agent_id', 'kid', 'base_url', 'token', 'agent_name']);
-  const extra = Object.keys(config).find((key) => !supported.has(key));
-  if (extra) throw new Error(`Elydora runtime config has unsupported field "${extra}": ${configPath}`);
-  requireNonEmptyString(config.org_id, 'org_id', configPath);
-  requireNonEmptyString(config.kid, 'kid', configPath);
-  const agentId = requireNonEmptyString(config.agent_id, 'agent_id', configPath);
-  if (!sameAgentId(agentId, contract.agentId) || config.agent_name !== AGENT_KEY) {
-    throw new Error(`Elydora runtime identity does not match Auggie hooks: ${configPath}`);
-  }
-  if (config.token !== undefined) requireNonEmptyString(config.token, 'token', configPath);
-  const rawBaseUrl = requireNonEmptyString(config.base_url, 'base_url', configPath);
-  let baseUrl: URL;
-  try {
-    baseUrl = new URL(rawBaseUrl);
-  } catch (error) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`, {
-      cause: error instanceof Error ? error : new Error(String(error)),
-    });
-  }
-  if (!['http:', 'https:'].includes(baseUrl.protocol)
-    || !baseUrl.hostname
-    || baseUrl.username
-    || baseUrl.password
-    || baseUrl.search
-    || baseUrl.hash) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`);
-  }
-}
-
-function validatePrivateKey(contents: string, keyPath: string): void {
-  const bytes = Buffer.from(contents, 'base64url');
-  if (bytes.length !== 32 || bytes.toString('base64url') !== contents) {
-    throw new Error(`Elydora private key is invalid: ${keyPath}`);
-  }
-}
-
-function validContractPaths(contract: RuntimeContract, agentDirectory: string): boolean {
-  return samePath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))
-    && samePath(contract.guardPath, path.join(agentDirectory, GUARD_SCRIPT))
-    && samePath(contract.auditPath, path.join(agentDirectory, AUDIT_SCRIPT))
-    && samePath(contract.guardWrapperPath, path.join(agentDirectory, GUARD_WRAPPER))
     && samePath(contract.auditWrapperPath, path.join(agentDirectory, AUDIT_WRAPPER));
 }
 
 async function runtimeContractExists(contract: RuntimeContract): Promise<boolean> {
-  const runtimeRoot = path.join(os.homedir(), '.elydora');
+  if (!wrappersValid(contract)) return false;
-  const agentDirectory = path.dirname(contract.guardPath);
+  if (!await managedRuntimeFilesExist(contract, AGENT_KEY)) return false;
-  if (!validContractPaths(contract, agentDirectory)) return false;
+  const [guardWrapper, auditWrapper] = await Promise.all([
-  if (!await inspectPhysicalDirectory(runtimeRoot, 'Elydora runtime directory')) return false;
-  if (!await inspectPhysicalDirectory(agentDirectory, 'Elydora agent runtime directory')) {
-    return false;
-  }
-  const configPath = path.join(agentDirectory, 'config.json');
-  const keyPath = path.join(agentDirectory, 'private.key');
-  const [config, key, guard, audit, guardWrapper, auditWrapper] = await Promise.all([
-    readPhysicalFile(configPath, 'Elydora runtime config', MAX_CONFIG_BYTES),
-    readPhysicalFile(keyPath, 'Elydora private key', MAX_SECRET_BYTES),
-    readPhysicalFile(contract.guardPath, 'Elydora guard runtime'),
-    readPhysicalFile(contract.auditPath, 'Elydora audit runtime'),
     readPhysicalFile(contract.guardWrapperPath, 'Auggie guard wrapper'),
     readPhysicalFile(contract.auditWrapperPath, 'Auggie audit wrapper'),
   ]);
-  if (!config || !key || !guard || !audit || !guardWrapper || !auditWrapper) return false;
+  return guardWrapper?.contents === buildWrapper(contract.guardPath)
-  const parsed = parseStrictJsonObject(config.contents, `Elydora runtime config at ${configPath}`);
+    && auditWrapper?.contents === buildWrapper(contract.auditPath);
-  validateRuntimeConfig(parsed, contract, configPath);
-  validatePrivateKey(key.contents, keyPath);
-  return guard.contents.length > 0
-    && audit.contents.length > 0
-    && guardWrapper.contents === buildWrapper(contract.guardPath)
-    && auditWrapper.contents === buildWrapper(contract.auditPath);
 }
 
 export async function augmentRuntimeFilesExist(

src/plugins/claudecode-contract.ts

@@ -1,5 +1,6 @@
 import os from 'node:os';
 import path from 'node:path';
+import { sameAgentId, samePath } from './common.js';
 import { isObject, parseStrictJsonObject, type JsonObject } from './strict-json.js';
 
 export const AGENT_KEY = 'claudecode';
@@ -76,20 +77,6 @@ interface RuntimeReference {
   readonly scriptPath: string;
 }
 
-function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-function sameAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right;
-}
-
 function requireKnownKeys(value: JsonObject, allowed: readonly string[], label: string): void {
   const keys = new Set(allowed);
   const extra = Object.keys(value).find((key) => !keys.has(key));

src/plugins/claudecode-installation.ts

@@ -7,7 +7,6 @@ import {
 } from './claudecode-contract.js';
 import {
   commitManagedInstallation,
-  managedRuntimePaths,
   preflightManagedInstallation,
   prepareManagedInstallation,
   type ManagedRuntimePaths,
@@ -19,18 +18,10 @@ const DISPLAY_NAME = 'Claude Code';
 const SETTINGS_DIRECTORY_LABEL = 'Claude Code configuration directory';
 const SETTINGS_LABEL = 'Claude Code user settings';
 
-export type ClaudeRuntimePaths = ManagedRuntimePaths;
-export type PreparedClaudeInstallation = PreparedManagedInstallation;
-export type { RenameFile };
-
-export function claudeRuntimePaths(config: InstallConfig): ClaudeRuntimePaths {
-  return managedRuntimePaths(config, AGENT_KEY, GUARD_SCRIPT, AUDIT_SCRIPT);
-}
-
 export async function preflightClaudeInstallation(
   config: InstallConfig,
   settingsPath: string,
-): Promise<ClaudeRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
     hookLocations: [{ directoryLabel: SETTINGS_DIRECTORY_LABEL, filePath: settingsPath }],
@@ -41,7 +32,7 @@ export async function preflightClaudeInstallation(
 export async function prepareClaudeInstallation(
   config: InstallConfig,
   rendered: RenderedClaudeDocument,
-): Promise<PreparedClaudeInstallation> {
+): Promise<PreparedManagedInstallation> {
   if (!rendered.changed && rendered.document.raw === undefined) {
     throw new Error('Claude Code hook installation did not produce a settings document');
   }
@@ -63,7 +54,7 @@ export async function prepareClaudeInstallation(
 }
 
 export async function commitClaudeInstallation(
-  prepared: PreparedClaudeInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/claudecode-io.ts

@@ -10,11 +10,11 @@ import {
   type RenderedClaudeDocument,
 } from './claudecode-contract.js';
 import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
+import { managedRuntimeFilesExist } from './managed-runtime-status.js';
 import {
   commitManagedTransaction,
   prepareManagedFileChange,
 } from './managed-transaction.js';
-import { parseStrictJsonObject, type JsonObject } from './strict-json.js';
 
 export function claudeConfigDirectory(): string {
   const configured = process.env.CLAUDE_CONFIG_DIR;
@@ -58,96 +58,11 @@ export async function writeClaudeDocument(rendered: RenderedClaudeDocument): Pro
   });
 }
 
-function requireNonEmptyString(value: unknown, field: string, configPath: string): string {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`Elydora runtime config ${field} is invalid: ${configPath}`);
-  }
-  return value;
-}
-
-function sameAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right;
-}
-
-function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-function validateRuntimeConfig(
-  config: JsonObject,
-  contract: ClaudeRuntimeContract,
-  configPath: string,
-): void {
-  const supported = new Set(['org_id', 'agent_id', 'kid', 'base_url', 'token', 'agent_name']);
-  const extra = Object.keys(config).find((key) => !supported.has(key));
-  if (extra) throw new Error(`Elydora runtime config has unsupported field "${extra}": ${configPath}`);
-  requireNonEmptyString(config.org_id, 'org_id', configPath);
-  requireNonEmptyString(config.kid, 'kid', configPath);
-  const agentId = requireNonEmptyString(config.agent_id, 'agent_id', configPath);
-  if (!sameAgentId(agentId, contract.agentId) || config.agent_name !== AGENT_KEY) {
-    throw new Error(`Elydora runtime identity does not match Claude Code hooks: ${configPath}`);
-  }
-  if (config.token !== undefined) requireNonEmptyString(config.token, 'token', configPath);
-  const rawBaseUrl = requireNonEmptyString(config.base_url, 'base_url', configPath);
-  let baseUrl: URL;
-  try {
-    baseUrl = new URL(rawBaseUrl);
-  } catch (error) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`, {
-      cause: error instanceof Error ? error : new Error(String(error)),
-    });
-  }
-  if (!['http:', 'https:'].includes(baseUrl.protocol)
-    || !baseUrl.hostname
-    || baseUrl.username
-    || baseUrl.password
-    || baseUrl.search
-    || baseUrl.hash) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`);
-  }
-}
-
-function validatePrivateKey(contents: string, keyPath: string): void {
-  const bytes = Buffer.from(contents, 'base64url');
-  if (bytes.length !== 32 || bytes.toString('base64url') !== contents) {
-    throw new Error(`Elydora private key is invalid: ${keyPath}`);
-  }
-}
-
-async function runtimeContractExists(contract: ClaudeRuntimeContract): Promise<boolean> {
-  const runtimeRoot = path.join(os.homedir(), '.elydora');
-  const agentDirectory = path.dirname(contract.guardPath);
-  if (!samePath(path.dirname(agentDirectory), runtimeRoot)
-    || !samePath(contract.auditPath, path.join(agentDirectory, 'hook.js'))) return false;
-  if (!await inspectPhysicalDirectory(runtimeRoot, 'Elydora runtime directory')) return false;
-  if (!await inspectPhysicalDirectory(agentDirectory, 'Elydora agent runtime directory')) return false;
-
-  const configPath = path.join(agentDirectory, 'config.json');
-  const keyPath = path.join(agentDirectory, 'private.key');
-  const [config, key, guard, audit] = await Promise.all([
-    readPhysicalFile(configPath, 'Elydora runtime config'),
-    readPhysicalFile(keyPath, 'Elydora private key'),
-    readPhysicalFile(contract.guardPath, 'Elydora guard runtime'),
-    readPhysicalFile(contract.auditPath, 'Elydora audit runtime'),
-  ]);
-  if (!config || !key || !guard || !audit) return false;
-  const parsed = parseStrictJsonObject(config.contents, `Elydora runtime config at ${configPath}`);
-  validateRuntimeConfig(parsed, contract, configPath);
-  validatePrivateKey(key.contents, keyPath);
-  return guard.contents.length > 0 && audit.contents.length > 0;
-}
-
 export async function claudeRuntimeFilesExist(
   contracts: readonly ClaudeRuntimeContract[],
 ): Promise<boolean> {
   for (const contract of contracts) {
-    if (await runtimeContractExists(contract)) return true;
+    if (await managedRuntimeFilesExist(contract, AGENT_KEY)) return true;
   }
   return false;
 }

src/plugins/cline-contract.ts

@@ -1,5 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
+import { asError, errorMessage, sameAgentId, samePath } from './common.js';
+import { isObject } from './strict-json.js';
 
 export const AGENT_KEY = 'cline';
 export const GUARD_SCRIPT = 'guard.js';
@@ -33,32 +35,6 @@ export interface ClineRuntimeContract {
   readonly auditPath: string;
 }
 
-type JsonObject = Record<string, unknown>;
-
-function isObject(value: unknown): value is JsonObject {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-export function sameAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
-}
-
 export function resolveHooksDirectory(): string {
   const configuredDirectory = process.env.CLINE_DIR?.trim();
   const clineDirectory = configuredDirectory

src/plugins/cline-installation.ts

@@ -9,8 +9,8 @@ import {
   buildWrapper,
   type ClineHookFile,
   runtimeContract,
-  sameAgentId,
 } from './cline-contract.js';
+import { sameAgentId } from './common.js';
 import {
   commitManagedInstallation,
   preflightManagedInstallation,
@@ -28,10 +28,6 @@ import {
 const DISPLAY_NAME = 'Cline';
 const DIRECTORY_LABEL = 'Cline hooks directory';
 
-export type ClineRuntimePaths = ManagedRuntimePaths;
-export type PreparedClineInstallation = PreparedManagedInstallation;
-export type { RenameFile };
-
 function hookLocations(files: readonly ClineHookFile[]) {
   return files.map((file) => ({
     directoryLabel: DIRECTORY_LABEL,
@@ -42,7 +38,7 @@ function hookLocations(files: readonly ClineHookFile[]) {
 export async function preflightClineInstallation(
   config: InstallConfig,
   files: readonly ClineHookFile[],
-): Promise<ClineRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
     hookLocations: hookLocations(files),
@@ -54,7 +50,7 @@ export async function prepareClineInstallation(
   config: InstallConfig,
   guardFile: ClineHookFile,
   auditFile: ClineHookFile,
-): Promise<PreparedClineInstallation> {
+): Promise<PreparedManagedInstallation> {
   const paths = await preflightClineInstallation(config, [guardFile, auditFile]);
   const guardMetadata = buildMetadata('guard', config.agentId, paths.guardPath);
   const auditMetadata = buildMetadata('audit', config.agentId, paths.auditPath);
@@ -86,7 +82,7 @@ export async function prepareClineInstallation(
 }
 
 export async function commitClineInstallation(
-  prepared: PreparedClineInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/cline-io.ts

@@ -1,21 +1,12 @@
-import os from 'node:os';
 import path from 'node:path';
 import {
   AGENT_KEY,
-  AUDIT_SCRIPT,
-  GUARD_SCRIPT,
   type ClineHookFile,
   type ClineRuntimeContract,
   parseMetadata,
-  sameAgentId,
 } from './cline-contract.js';
-import { generateGuardScript } from './guard-template.js';
-import { generateHookScript } from './hook-template.js';
 import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
-import { parseStrictJsonObject, type JsonObject } from './strict-json.js';
+import { managedRuntimeFilesExist } from './managed-runtime-status.js';
-
-const MAX_SECRET_BYTES = 64 * 1024;
-const MAX_CONFIG_BYTES = 512 * 1024;
 
 export async function readHookFile(filePath: string): Promise<ClineHookFile> {
   const directory = path.dirname(filePath);
@@ -38,91 +29,6 @@ export function requireAvailableHookFile(file: ClineHookFile): void {
   }
 }
 
-function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-function requireString(value: unknown, field: string, configPath: string): string {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`Elydora runtime config ${field} is invalid: ${configPath}`);
-  }
-  return value;
-}
-
-function validateRuntimeConfig(
-  config: JsonObject,
-  contract: ClineRuntimeContract,
-  configPath: string,
-): void {
-  const supported = new Set(['org_id', 'agent_id', 'kid', 'base_url', 'token', 'agent_name']);
-  const extra = Object.keys(config).find((key) => !supported.has(key));
-  if (extra) throw new Error(`Elydora runtime config has unsupported field "${extra}": ${configPath}`);
-  requireString(config.org_id, 'org_id', configPath);
-  requireString(config.kid, 'kid', configPath);
-  const agentId = requireString(config.agent_id, 'agent_id', configPath);
-  if (!sameAgentId(agentId, contract.agentId) || config.agent_name !== AGENT_KEY) {
-    throw new Error(`Elydora runtime identity does not match Cline hooks: ${configPath}`);
-  }
-  if (config.token !== undefined) requireString(config.token, 'token', configPath);
-  const rawBaseUrl = requireString(config.base_url, 'base_url', configPath);
-  let baseUrl: URL;
-  try {
-    baseUrl = new URL(rawBaseUrl);
-  } catch (error) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`, {
-      cause: error instanceof Error ? error : new Error(String(error)),
-    });
-  }
-  if (!['http:', 'https:'].includes(baseUrl.protocol)
-    || !baseUrl.hostname
-    || baseUrl.username
-    || baseUrl.password
-    || baseUrl.search
-    || baseUrl.hash) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`);
-  }
-}
-
-function validatePrivateKey(contents: string, keyPath: string): void {
-  const bytes = Buffer.from(contents, 'base64url');
-  if (bytes.length !== 32 || bytes.toString('base64url') !== contents) {
-    throw new Error(`Elydora private key is invalid: ${keyPath}`);
-  }
-}
-
-function validContractPaths(contract: ClineRuntimeContract): boolean {
-  return samePath(path.dirname(contract.agentDirectory), path.join(os.homedir(), '.elydora'))
-    && samePath(contract.guardPath, path.join(contract.agentDirectory, GUARD_SCRIPT))
-    && samePath(contract.auditPath, path.join(contract.agentDirectory, AUDIT_SCRIPT));
-}
-
 export async function runtimeFilesExist(contract: ClineRuntimeContract): Promise<boolean> {
-  if (!validContractPaths(contract)) return false;
+  return managedRuntimeFilesExist(contract, AGENT_KEY);
-  const runtimeRoot = path.join(os.homedir(), '.elydora');
-  if (!await inspectPhysicalDirectory(runtimeRoot, 'Elydora runtime directory')) return false;
-  if (!await inspectPhysicalDirectory(contract.agentDirectory, 'Elydora agent runtime directory')) {
-    return false;
-  }
-  const configPath = path.join(contract.agentDirectory, 'config.json');
-  const keyPath = path.join(contract.agentDirectory, 'private.key');
-  const [config, key, guard, audit] = await Promise.all([
-    readPhysicalFile(configPath, 'Elydora runtime config', MAX_CONFIG_BYTES),
-    readPhysicalFile(keyPath, 'Elydora private key', MAX_SECRET_BYTES),
-    readPhysicalFile(contract.guardPath, 'Elydora guard runtime'),
-    readPhysicalFile(contract.auditPath, 'Elydora audit runtime'),
-  ]);
-  if (!config || !key || !guard || !audit) return false;
-  const parsed = parseStrictJsonObject(config.contents, `Elydora runtime config at ${configPath}`);
-  validateRuntimeConfig(parsed, contract, configPath);
-  validatePrivateKey(key.contents, keyPath);
-  return guard.contents === generateGuardScript(AGENT_KEY, contract.agentId)
-    && audit.contents === generateHookScript(
-      AGENT_KEY,
-      contract.agentId,
-      { nativePayload: true },
-    );
 }

src/plugins/codex-contract.ts

@@ -1,5 +1,14 @@
 import os from 'node:os';
 import path from 'node:path';
+import { sameAgentId, samePath } from './common.js';
+import {
+  encodedWindowsCommand,
+  isNodeExecutable,
+  parseEncodedWindowsCommand,
+  parseLegacyWindowsCommand,
+  parsePosixCommand,
+  posixSource,
+} from './shell-command.js';
 import { isObject, parseStrictJsonObject, type JsonObject } from './strict-json.js';
 
 export const AGENT_KEY = 'codex';
@@ -33,142 +42,16 @@ export interface RuntimeContract {
   readonly auditPath: string;
 }
 
-interface ParsedArgument {
-  readonly value: string;
-  readonly next: number;
-}
-
-function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-function sameAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right;
-}
-
-function quotePosix(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
-function quotePowerShell(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`;
-}
-
-function windowsPowerShellPath(): string {
-  const configuredRoot = process.platform === 'win32' ? process.env.SystemRoot : undefined;
-  const systemRoot = configuredRoot
-    && path.win32.isAbsolute(configuredRoot)
-    && !/["%\r\n]/.test(configuredRoot)
-    ? configuredRoot
-    : 'C:\\Windows';
-  return path.win32.join(
-    systemRoot,
-    'System32',
-    'WindowsPowerShell',
-    'v1.0',
-    'powershell.exe',
-  );
-}
-
-function windowsCommand(scriptPath: string): string {
-  const source = `& ${quotePowerShell(process.execPath)} ${quotePowerShell(scriptPath)}; exit $LASTEXITCODE`;
-  const encoded = Buffer.from(source, 'utf16le').toString('base64');
-  return `"${windowsPowerShellPath()}" -NoLogo -NoProfile -NonInteractive -EncodedCommand ${encoded}`;
-}
-
 export function buildHandler(scriptPath: string, statusMessage: string): JsonObject {
   return {
     type: 'command',
-    command: `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`,
+    command: posixSource(scriptPath),
-    commandWindows: windowsCommand(scriptPath),
+    commandWindows: encodedWindowsCommand(scriptPath),
     timeout: HOOK_TIMEOUT_SECONDS,
     statusMessage,
   };
 }
 
-function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  const apostrophe = `'"'"'`;
-  let value = '';
-  for (let index = start + 1; index < command.length;) {
-    if (command.startsWith(apostrophe, index)) {
-      value += "'";
-      index += apostrophe.length;
-      continue;
-    }
-    if (command[index] === "'") return { value, next: index + 1 };
-    value += command[index];
-    index += 1;
-  }
-  return undefined;
-}
-
-function parsePosixCommand(command: unknown): readonly [string, string] | undefined {
-  if (typeof command !== 'string') return undefined;
-  const executable = readPosixArgument(command, 0);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPosixArgument(command, executable.next + 1);
-  if (!script || script.next !== command.length) return undefined;
-  return [executable.value, script.value];
-}
-
-function readPowerShellArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length; index += 1) {
-    if (command[index] !== "'") {
-      value += command[index];
-      continue;
-    }
-    if (command[index + 1] === "'") {
-      value += "'";
-      index += 1;
-      continue;
-    }
-    return { value, next: index + 1 };
-  }
-  return undefined;
-}
-
-function parsePowerShellSource(source: string): readonly [string, string] | undefined {
-  if (!source.startsWith('& ')) return undefined;
-  const executable = readPowerShellArgument(source, 2);
-  if (!executable || source[executable.next] !== ' ') return undefined;
-  const script = readPowerShellArgument(source, executable.next + 1);
-  if (!script || source.slice(script.next) !== '; exit $LASTEXITCODE') return undefined;
-  return [executable.value, script.value];
-}
-
-function parseWindowsCommand(command: unknown): readonly [string, string] | undefined {
-  if (typeof command !== 'string') return undefined;
-  const match = /^"([^"\r\n]+)" -NoLogo -NoProfile -NonInteractive -EncodedCommand ([A-Za-z0-9+/]+={0,2})$/.exec(command);
-  if (!match
-    || !path.win32.isAbsolute(match[1])
-    || path.win32.basename(match[1]).toLowerCase() !== 'powershell.exe') return undefined;
-  const encoded = match[2];
-  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) return undefined;
-  const buffer = Buffer.from(encoded, 'base64');
-  if (buffer.toString('base64') !== encoded || buffer.length % 2 !== 0) return undefined;
-  return parsePowerShellSource(buffer.toString('utf16le'));
-}
-
-function parseLegacyWindowsCommand(command: unknown): readonly [string, string] | undefined {
-  if (typeof command !== 'string') return undefined;
-  const match = /^"([^"\r\n]+)" "([^"\r\n]+)"$/.exec(command);
-  return match ? [match[1], match[2]] : undefined;
-}
-
-function isNodeExecutable(filePath: string): boolean {
-  const basename = path.basename(filePath);
-  return basename === 'node' || basename.toLowerCase() === 'node.exe';
-}
-
 function exactHandlerKeys(handler: JsonObject): boolean {
   return Object.keys(handler).sort().join('|')
     === 'command|commandWindows|statusMessage|timeout|type';
@@ -179,8 +62,11 @@ function managedScriptPath(handler: JsonObject, statusMessage: string): string |
     || handler.type !== 'command'
     || handler.timeout !== HOOK_TIMEOUT_SECONDS
     || handler.statusMessage !== statusMessage) return undefined;
+  if (typeof handler.command !== 'string' || typeof handler.commandWindows !== 'string') {
+    return undefined;
+  }
   const posix = parsePosixCommand(handler.command);
-  const windows = parseWindowsCommand(handler.commandWindows)
+  const windows = parseEncodedWindowsCommand(handler.commandWindows)
     ?? parseLegacyWindowsCommand(handler.commandWindows);
   if (!posix || !windows
     || !path.isAbsolute(posix[0])

src/plugins/codex-installation.ts

@@ -7,7 +7,6 @@ import {
 } from './codex-contract.js';
 import {
   commitManagedInstallation,
-  managedRuntimePaths,
   preflightManagedInstallation,
   prepareManagedInstallation,
   type ManagedRuntimePaths,
@@ -19,18 +18,10 @@ const DISPLAY_NAME = 'Codex';
 const HOOKS_DIRECTORY_LABEL = 'Codex hooks directory';
 const HOOKS_LABEL = 'Codex user hooks';
 
-export type CodexRuntimePaths = ManagedRuntimePaths;
-export type PreparedCodexInstallation = PreparedManagedInstallation;
-export type { RenameFile };
-
-export function codexRuntimePaths(config: InstallConfig): CodexRuntimePaths {
-  return managedRuntimePaths(config, AGENT_KEY, GUARD_SCRIPT, AUDIT_SCRIPT);
-}
-
 export async function preflightCodexInstallation(
   config: InstallConfig,
   hooksPath: string,
-): Promise<CodexRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
     hookLocations: [{ directoryLabel: HOOKS_DIRECTORY_LABEL, filePath: hooksPath }],
@@ -41,7 +32,7 @@ export async function preflightCodexInstallation(
 export async function prepareCodexInstallation(
   config: InstallConfig,
   rendered: RenderedDocument,
-): Promise<PreparedCodexInstallation> {
+): Promise<PreparedManagedInstallation> {
   if (!rendered.changed && rendered.document.raw === undefined) {
     throw new Error('Codex hook installation did not produce a configuration document');
   }
@@ -63,7 +54,7 @@ export async function prepareCodexInstallation(
 }
 
 export async function commitCodexInstallation(
-  prepared: PreparedCodexInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/codex-io.ts

@@ -1,6 +1,4 @@
-import { randomUUID } from 'node:crypto';
 import fsp from 'node:fs/promises';
-import type { FileHandle } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import {
@@ -12,20 +10,13 @@ import {
   createDocument,
   parseDocument,
 } from './codex-contract.js';
+import { asError, errorMessage } from './common.js';
 import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
-import { parseStrictJsonObject } from './strict-json.js';
+import { managedRuntimePresent } from './managed-runtime-status.js';
-
+import {
-function asError(error: unknown): Error {
+  commitManagedTransaction,
-  return error instanceof Error ? error : new Error(String(error));
+  prepareManagedFileChange,
-}
+} from './managed-transaction.js';
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function hasCode(error: unknown, code: string): boolean {
-  return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
-}
 
 async function codexHomePath(): Promise<string> {
   const configured = process.env.CODEX_HOME;
@@ -63,135 +54,31 @@ export async function readDocument(): Promise<CodexDocument> {
   return snapshot ? parseDocument(filePath, snapshot.contents) : createDocument(filePath);
 }
 
-async function unlinkOptional(filePath: string): Promise<void> {
-  try {
-    await fsp.unlink(filePath);
-  } catch (error) {
-    if (!hasCode(error, 'ENOENT')) throw error;
-  }
-}
-
-async function writeExclusive(filePath: string, contents: string): Promise<void> {
-  let handle: FileHandle | undefined;
-  try {
-    handle = await fsp.open(filePath, 'wx', 0o600);
-    await handle.writeFile(contents, 'utf-8');
-    await handle.sync();
-    await handle.close();
-    handle = undefined;
-    if (process.platform !== 'win32') await fsp.chmod(filePath, 0o600);
-  } catch (error) {
-    const failures = [asError(error)];
-    if (handle) {
-      try { await handle.close(); } catch (closeError) { failures.push(asError(closeError)); }
-    }
-    try { await unlinkOptional(filePath); } catch (cleanupError) {
-      failures.push(asError(cleanupError));
-    }
-    if (failures.length > 1) throw new AggregateError(failures, 'Stage Codex user hooks');
-    throw new Error(`Stage Codex user hooks: ${errorMessage(error)}`, { cause: failures[0] });
-  }
-}
-
-async function assertUnchanged(document: CodexDocument): Promise<void> {
-  const current = await readPhysicalFile(document.filePath, 'Codex user hooks');
-  if (current?.contents !== document.raw) {
-    throw new Error(`Codex user hooks changed during update: ${document.filePath}`);
-  }
-}
-
-async function ensureHooksDirectory(directory: string): Promise<void> {
-  try {
-    await fsp.mkdir(directory, { recursive: true, mode: 0o700 });
-  } catch (error) {
-    throw new Error(`Create Codex hooks directory at ${directory}: ${errorMessage(error)}`, {
-      cause: asError(error),
-    });
-  }
-  if (!await inspectPhysicalDirectory(directory, 'Codex hooks directory')) {
-    throw new Error(`Codex hooks directory is missing: ${directory}`);
-  }
-}
-
 export async function writeDocument(rendered: RenderedDocument): Promise<void> {
   if (!rendered.changed) return;
-  await assertUnchanged(rendered.document);
+  const change = await prepareManagedFileChange({
-  const directory = path.dirname(rendered.document.filePath);
+    filePath: rendered.document.filePath,
-  await ensureHooksDirectory(directory);
+    label: 'Codex user hooks',
-  if (rendered.next === undefined) {
+    next: rendered.next,
-    try {
+    mode: 0o600,
-      await fsp.unlink(rendered.document.filePath);
+    expectedSource: rendered.document.raw,
-    } catch (error) {
+    verifyExpectedSource: true,
-      if (!hasCode(error, 'ENOENT')) {
+  });
-        throw new Error(
+  if (!change) return;
-          `Remove Codex user hooks at ${rendered.document.filePath}: ${errorMessage(error)}`,
+  await commitManagedTransaction({
-          { cause: asError(error) },
+    displayName: 'Codex',
-        );
+    operation: 'uninstall',
-      }
+    directories: [{
-    }
+      path: path.dirname(rendered.document.filePath),
-    return;
+      label: 'Codex hooks directory',
-  }
+    }],
-
+    changes: [change],
-  const temporaryPath = path.join(
+  });
-    directory,
-    `.${path.basename(rendered.document.filePath)}.${randomUUID()}.tmp`,
-  );
-  let failure: Error | undefined;
-  try {
-    await writeExclusive(temporaryPath, rendered.next);
-    await assertUnchanged(rendered.document);
-    await fsp.rename(temporaryPath, rendered.document.filePath);
-  } catch (error) {
-    failure = new Error(
-      `Write Codex user hooks at ${rendered.document.filePath}: ${errorMessage(error)}`,
-      { cause: asError(error) },
-    );
-  }
-  let cleanupFailure: Error | undefined;
-  try {
-    await unlinkOptional(temporaryPath);
-  } catch (error) {
-    cleanupFailure = new Error(
-      `Clean Codex hook staging file at ${temporaryPath}: ${errorMessage(error)}`,
-      { cause: asError(error) },
-    );
-  }
-  if (failure && cleanupFailure) {
-    throw new AggregateError([failure, cleanupFailure], 'Write Codex user hooks');
-  }
-  if (failure) throw failure;
-  if (cleanupFailure) throw cleanupFailure;
-}
-
-async function physicalFileExists(filePath: string, label: string): Promise<boolean> {
-  return Boolean(await readPhysicalFile(filePath, label));
-}
-
-function sameAgentId(left: unknown, right: string): boolean {
-  return typeof left === 'string' && (process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right);
 }
 
 export async function runtimeFilesExist(contracts: RuntimeContract[]): Promise<boolean> {
   for (const contract of contracts) {
-    const directory = path.dirname(contract.guardPath);
+    if (await managedRuntimePresent(contract, AGENT_KEY)) return true;
-    const configPath = path.join(directory, 'config.json');
-    const snapshot = await readPhysicalFile(configPath, 'Elydora runtime config');
-    if (!snapshot) continue;
-    const config = parseStrictJsonObject(
-      snapshot.contents,
-      `Elydora runtime config at ${configPath}`,
-    );
-    if (config.agent_name !== AGENT_KEY || !sameAgentId(config.agent_id, contract.agentId)) {
-      continue;
-    }
-    const files = await Promise.all([
-      physicalFileExists(contract.guardPath, 'Elydora guard runtime'),
-      physicalFileExists(contract.auditPath, 'Elydora audit runtime'),
-      physicalFileExists(path.join(directory, 'private.key'), 'Elydora private key'),
-    ]);
-    if (files.every(Boolean)) return true;
   }
   return false;
 }

src/plugins/common.ts

@@ -0,0 +1,31 @@
+import path from 'node:path';
+
+export const MAX_SECRET_BYTES = 64 * 1024;
+export const MAX_CONFIG_BYTES = 512 * 1024;
+export const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
+
+export function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function hasCode(error: unknown, code: string): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+}
+
+export function samePath(left: string, right: string): boolean {
+  const normalizedLeft = path.resolve(left);
+  const normalizedRight = path.resolve(right);
+  return process.platform === 'win32'
+    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+    : normalizedLeft === normalizedRight;
+}
+
+export function sameAgentId(left: unknown, right: string): boolean {
+  return typeof left === 'string' && (process.platform === 'win32'
+    ? left.toLowerCase() === right.toLowerCase()
+    : left === right);
+}

src/plugins/copilot-contract.ts

@@ -1,6 +1,14 @@
 import os from 'node:os';
 import path from 'node:path';
+import { sameAgentId, samePath } from './common.js';
 import type { FileSnapshot } from './managed-files.js';
+import {
+  isNodeExecutable,
+  parsePosixCommand,
+  parsePowerShellSource,
+  posixSource,
+  powerShellSource,
+} from './shell-command.js';
 import { validateHooks, type CopilotHooks } from './copilot-schema.js';
 import { parseStrictJsonObject, type JsonObject } from './strict-json.js';
 
@@ -51,122 +59,38 @@ export interface RuntimeContract {
   readonly auditPath: string;
 }
 
-interface ParsedArgument {
-  readonly value: string;
-  readonly next: number;
-}
-
 interface ManagedEntry {
   readonly agentId: string;
   readonly scriptPath: string;
 }
 
-export function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-export function sameAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right;
-}
-
 function agentKey(agentId: string): string {
   return process.platform === 'win32' ? agentId.toLowerCase() : agentId;
 }
 
-function quotePosix(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
-function quotePowerShell(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`;
-}
-
 export function buildHandler(scriptPath: string): JsonObject {
   return {
     type: 'command',
-    bash: `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`,
+    bash: posixSource(scriptPath),
-    powershell: `& ${quotePowerShell(process.execPath)} ${quotePowerShell(scriptPath)}; exit $LASTEXITCODE`,
+    powershell: powerShellSource(scriptPath),
     timeoutSec: HOOK_TIMEOUT_SECONDS,
   };
 }
 
-function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  const apostrophe = `'"'"'`;
-  let value = '';
-  for (let index = start + 1; index < command.length;) {
-    if (command.startsWith(apostrophe, index)) {
-      value += "'";
-      index += apostrophe.length;
-      continue;
-    }
-    if (command[index] === "'") return { value, next: index + 1 };
-    value += command[index];
-    index += 1;
-  }
-  return undefined;
-}
-
-function parseGeneratedBash(command: unknown): readonly [string, string] | undefined {
-  if (typeof command !== 'string') return undefined;
-  const executable = readPosixArgument(command, 0);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPosixArgument(command, executable.next + 1);
-  if (!script || script.next !== command.length) return undefined;
-  return [executable.value, script.value];
-}
-
-function readPowerShellArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length; index += 1) {
-    if (command[index] !== "'") {
-      value += command[index];
-      continue;
-    }
-    if (command[index + 1] === "'") {
-      value += "'";
-      index += 1;
-      continue;
-    }
-    return { value, next: index + 1 };
-  }
-  return undefined;
-}
-
-function parseGeneratedPowerShell(command: unknown): readonly [string, string] | undefined {
-  if (typeof command !== 'string' || !command.startsWith('& ')) return undefined;
-  const executable = readPowerShellArgument(command, 2);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPowerShellArgument(command, executable.next + 1);
-  if (!script || command.slice(script.next) !== '; exit $LASTEXITCODE') return undefined;
-  return [executable.value, script.value];
-}
-
 function exactHandlerKeys(handler: JsonObject): boolean {
   return Object.keys(handler).sort().join(',') === 'bash,powershell,timeoutSec,type';
 }
 
-function nodeExecutable(filePath: string): boolean {
-  if (!path.isAbsolute(filePath)) return false;
-  const name = path.basename(filePath).toLowerCase();
-  return name === 'node' || name === 'node.exe';
-}
-
 function currentManagedScriptPath(handler: JsonObject): string | undefined {
   if (!exactHandlerKeys(handler)
     || handler.type !== 'command'
     || handler.timeoutSec !== HOOK_TIMEOUT_SECONDS) return undefined;
-  const bash = parseGeneratedBash(handler.bash);
+  if (typeof handler.bash !== 'string' || typeof handler.powershell !== 'string') return undefined;
-  const powershell = parseGeneratedPowerShell(handler.powershell);
+  const bash = parsePosixCommand(handler.bash);
+  const powershell = parsePowerShellSource(handler.powershell);
   if (!bash || !powershell
-    || !nodeExecutable(bash[0])
+    || !path.isAbsolute(bash[0])
+    || !isNodeExecutable(bash[0])
     || !samePath(bash[0], powershell[0])
     || !samePath(bash[1], powershell[1])) return undefined;
   return bash[1];

src/plugins/copilot-installation.ts

@@ -6,8 +6,8 @@ import {
   GUARD_SCRIPT,
   type CopilotSources,
   type RenderedDocument,
-  samePath,
 } from './copilot-contract.js';
+import { MAX_SOURCE_BYTES, samePath } from './common.js';
 import { requireHooksEnabled } from './copilot-io.js';
 import {
   commitManagedInstallation,
@@ -26,11 +26,6 @@ import {
 const DISPLAY_NAME = 'GitHub Copilot CLI';
 const DIRECTORY_LABEL = 'GitHub Copilot hooks directory';
 const SOURCE_LABEL = 'GitHub Copilot hook source';
-const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
-
-export type CopilotRuntimePaths = ManagedRuntimePaths;
-export type PreparedCopilotInstallation = PreparedManagedInstallation;
-export type { RenameFile };
 
 function hookLocations(sources: CopilotSources) {
   return [sources.user, ...(sources.legacy ? [sources.legacy] : [])].map((document) => ({
@@ -42,7 +37,7 @@ function hookLocations(sources: CopilotSources) {
 export async function preflightCopilotInstallation(
   config: InstallConfig,
   sources: CopilotSources,
-): Promise<CopilotRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   requireHooksEnabled(sources);
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
@@ -63,7 +58,7 @@ export async function prepareCopilotInstallation(
   config: InstallConfig,
   sources: CopilotSources,
   rendered: readonly RenderedDocument[],
-): Promise<PreparedCopilotInstallation> {
+): Promise<PreparedManagedInstallation> {
   await preflightCopilotInstallation(config, sources);
   const documents = installationDocuments(sources, rendered);
   const prepared = await prepareManagedInstallation({
@@ -107,7 +102,7 @@ export async function prepareCopilotInstallation(
 }
 
 export async function commitCopilotInstallation(
-  prepared: PreparedCopilotInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/copilot-io.ts

@@ -2,34 +2,26 @@ import os from 'node:os';
 import path from 'node:path';
 import {
   AGENT_KEY,
-  AUDIT_SCRIPT,
   CONFIG_FILE,
-  GUARD_SCRIPT,
   type CopilotDocument,
   type CopilotSources,
   type RuntimeContract,
   createDocument,
   parseDocument,
-  sameAgentId,
-  samePath,
 } from './copilot-contract.js';
-import { generateGuardScript } from './guard-template.js';
+import { MAX_SOURCE_BYTES } from './common.js';
-import { generateHookScript } from './hook-template.js';
 import {
   inspectPhysicalDirectory,
   readPhysicalFile,
   type FileSnapshot,
 } from './managed-files.js';
+import { managedRuntimeFilesExist } from './managed-runtime-status.js';
 import {
   parseStrictJsonObject,
   parseStrictJsoncObject,
   type JsonObject,
 } from './strict-json.js';
 
-const MAX_SECRET_BYTES = 64 * 1024;
-const MAX_CONFIG_BYTES = 512 * 1024;
-const MAX_SETTINGS_BYTES = 2 * 1024 * 1024;
-
 export interface CopilotPaths {
   readonly copilotHome: string;
   readonly userHooksDirectory: string;
@@ -98,7 +90,7 @@ async function readHookDocument(
   filePath: string,
   label: string,
 ): Promise<CopilotDocument | undefined> {
-  const snapshot = await readPhysicalFile(filePath, label, MAX_SETTINGS_BYTES);
+  const snapshot = await readPhysicalFile(filePath, label, MAX_SOURCE_BYTES);
   return snapshot ? parseDocument(filePath, snapshot, label) : undefined;
 }
 
@@ -111,7 +103,7 @@ function parseSettings(raw: string, layer: SettingsLayer): JsonObject {
 }
 
 async function readSettingsLayer(layer: SettingsLayer): Promise<ParsedSettingsLayer> {
-  const snapshot = await readPhysicalFile(layer.filePath, layer.label, MAX_SETTINGS_BYTES);
+  const snapshot = await readPhysicalFile(layer.filePath, layer.label, MAX_SOURCE_BYTES);
   if (!snapshot) return layer;
   const root = parseSettings(snapshot.contents, layer);
   if (root.disableAllHooks !== undefined && typeof root.disableAllHooks !== 'boolean') {
@@ -167,86 +159,9 @@ export function requireHooksEnabled(sources: CopilotSources): void {
   }
 }
 
-function requireString(value: unknown, field: string, configPath: string): string {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`Elydora runtime config ${field} is invalid: ${configPath}`);
-  }
-  return value;
-}
-
-function validateRuntimeConfig(
-  config: JsonObject,
-  contract: RuntimeContract,
-  configPath: string,
-): void {
-  const supported = new Set(['org_id', 'agent_id', 'kid', 'base_url', 'token', 'agent_name']);
-  const extra = Object.keys(config).find((key) => !supported.has(key));
-  if (extra) throw new Error(`Elydora runtime config has unsupported field "${extra}": ${configPath}`);
-  requireString(config.org_id, 'org_id', configPath);
-  requireString(config.kid, 'kid', configPath);
-  const agentId = requireString(config.agent_id, 'agent_id', configPath);
-  if (!sameAgentId(agentId, contract.agentId) || config.agent_name !== AGENT_KEY) {
-    throw new Error(`Elydora runtime identity does not match Copilot hooks: ${configPath}`);
-  }
-  if (config.token !== undefined) requireString(config.token, 'token', configPath);
-  const rawBaseUrl = requireString(config.base_url, 'base_url', configPath);
-  let baseUrl: URL;
-  try {
-    baseUrl = new URL(rawBaseUrl);
-  } catch (error) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`, {
-      cause: error instanceof Error ? error : new Error(String(error)),
-    });
-  }
-  if (!['http:', 'https:'].includes(baseUrl.protocol)
-    || !baseUrl.hostname
-    || baseUrl.username
-    || baseUrl.password
-    || baseUrl.search
-    || baseUrl.hash) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`);
-  }
-}
-
-function validatePrivateKey(contents: string, keyPath: string): void {
-  const bytes = Buffer.from(contents, 'base64url');
-  if (bytes.length !== 32 || bytes.toString('base64url') !== contents) {
-    throw new Error(`Elydora private key is invalid: ${keyPath}`);
-  }
-}
-
-function validContractPaths(contract: RuntimeContract): boolean {
-  const agentDirectory = path.dirname(contract.guardPath);
-  return samePath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))
-    && samePath(contract.guardPath, path.join(agentDirectory, GUARD_SCRIPT))
-    && samePath(contract.auditPath, path.join(agentDirectory, AUDIT_SCRIPT));
-}
-
 export async function runtimeFilesExist(contracts: RuntimeContract[]): Promise<boolean> {
   for (const contract of contracts) {
-    if (!validContractPaths(contract)) continue;
+    if (await managedRuntimeFilesExist(contract, AGENT_KEY)) return true;
-    const runtimeRoot = path.join(os.homedir(), '.elydora');
-    const agentDirectory = path.dirname(contract.guardPath);
-    if (!await inspectPhysicalDirectory(runtimeRoot, 'Elydora runtime directory')) continue;
-    if (!await inspectPhysicalDirectory(agentDirectory, 'Elydora agent runtime directory')) continue;
-    const configPath = path.join(agentDirectory, 'config.json');
-    const keyPath = path.join(agentDirectory, 'private.key');
-    const [config, key, guard, audit] = await Promise.all([
-      readPhysicalFile(configPath, 'Elydora runtime config', MAX_CONFIG_BYTES),
-      readPhysicalFile(keyPath, 'Elydora private key', MAX_SECRET_BYTES),
-      readPhysicalFile(contract.guardPath, 'Elydora guard runtime'),
-      readPhysicalFile(contract.auditPath, 'Elydora audit runtime'),
-    ]);
-    if (!config || !key || !guard || !audit) continue;
-    const parsed = parseStrictJsonObject(config.contents, `Elydora runtime config at ${configPath}`);
-    validateRuntimeConfig(parsed, contract, configPath);
-    validatePrivateKey(key.contents, keyPath);
-    if (guard.contents === generateGuardScript(AGENT_KEY, contract.agentId)
-      && audit.contents === generateHookScript(
-        AGENT_KEY,
-        contract.agentId,
-        { nativePayload: true },
-      )) return true;
   }
   return false;
 }

src/plugins/cursor-contract.ts

@@ -1,15 +1,32 @@
 import os from 'node:os';
 import path from 'node:path';
+import { sameAgentId, samePath } from './common.js';
+import type { GuardScriptOptions } from './guard-template.js';
+import type { HookScriptOptions } from './hook-template.js';
+import {
+  isNodeExecutable,
+  parsePosixCommand,
+  parsePowerShellSource,
+  posixSource,
+  powerShellSource,
+} from './shell-command.js';
 import { isObject, parseStrictJsonObject, type JsonObject } from './strict-json.js';
 
-export { isObject, parseStrictJsonObject };
-export type { JsonObject };
-
 export const AGENT_KEY = 'cursor';
 export const CONFIG_FILE = 'hooks.json';
 export const GUARD_SCRIPT = 'guard.js';
 export const AUDIT_SCRIPT = 'hook.js';
 export const HOOK_TIMEOUT_SECONDS = 10;
+export const GUARD_OPTIONS: GuardScriptOptions = {
+  failClosed: true,
+  successOutput: '{"permission":"allow"}\n',
+  denyProtocol: 'cursor',
+};
+export const AUDIT_OPTIONS: HookScriptOptions = {
+  failClosed: true,
+  nativePayload: true,
+  successOutput: '{}\n',
+};
 
 export type CursorHooks = Record<string, JsonObject[]>;
 
@@ -33,37 +50,10 @@ export interface RuntimeContract {
   readonly auditPath: string;
 }
 
-interface ParsedArgument {
-  readonly value: string;
-  readonly next: number;
-}
-
-export function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-function sameAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right;
-}
-
-function quotePosix(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
-function quotePowerShell(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`;
-}
-
 export function buildHandler(scriptPath: string): JsonObject {
   const command = process.platform === 'win32'
-    ? `& ${quotePowerShell(process.execPath)} ${quotePowerShell(scriptPath)}; exit $LASTEXITCODE`
+    ? powerShellSource(scriptPath)
-    : `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`;
+    : posixSource(scriptPath);
   return {
     command,
     timeout: HOOK_TIMEOUT_SECONDS,
@@ -71,68 +61,11 @@ export function buildHandler(scriptPath: string): JsonObject {
   };
 }
 
-function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  const apostrophe = `'"'"'`;
-  let value = '';
-  for (let index = start + 1; index < command.length;) {
-    if (command.startsWith(apostrophe, index)) {
-      value += "'";
-      index += apostrophe.length;
-      continue;
-    }
-    if (command[index] === "'") return { value, next: index + 1 };
-    value += command[index];
-    index += 1;
-  }
-  return undefined;
-}
-
-function parsePosixCommand(command: string): readonly [string, string] | undefined {
-  const executable = readPosixArgument(command, 0);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPosixArgument(command, executable.next + 1);
-  if (!script || script.next !== command.length) return undefined;
-  return [executable.value, script.value];
-}
-
-function readPowerShellArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length; index += 1) {
-    if (command[index] !== "'") {
-      value += command[index];
-      continue;
-    }
-    if (command[index + 1] === "'") {
-      value += "'";
-      index += 1;
-      continue;
-    }
-    return { value, next: index + 1 };
-  }
-  return undefined;
-}
-
-function parsePowerShellCommand(command: string): readonly [string, string] | undefined {
-  if (!command.startsWith('& ')) return undefined;
-  const executable = readPowerShellArgument(command, 2);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPowerShellArgument(command, executable.next + 1);
-  if (!script || command.slice(script.next) !== '; exit $LASTEXITCODE') return undefined;
-  return [executable.value, script.value];
-}
-
 function parseLegacyCommand(command: string): readonly [string, string] | undefined {
   const match = /^(node(?:\.exe)?)\s+"([^"\r\n]+)"$/i.exec(command);
   return match ? [match[1], match[2]] : undefined;
 }
 
-function isNodeExecutable(filePath: string): boolean {
-  const basename = path.basename(filePath);
-  return basename === 'node' || basename.toLowerCase() === 'node.exe';
-}
-
 function managedScriptPath(handler: JsonObject): string | undefined {
   const keys = Object.keys(handler);
   if (keys.length === 3
@@ -140,7 +73,7 @@ function managedScriptPath(handler: JsonObject): string | undefined {
     && handler.timeout === HOOK_TIMEOUT_SECONDS
     && handler.failClosed === true) {
     const parsed = process.platform === 'win32'
-      ? parsePowerShellCommand(handler.command)
+      ? parsePowerShellSource(handler.command)
       : parsePosixCommand(handler.command);
     if (parsed
       && path.isAbsolute(parsed[0])

src/plugins/cursor-installation.ts

@@ -1,7 +1,6 @@
 import type { InstallConfig } from './base.js';
 import {
   commitManagedInstallation,
-  managedRuntimePaths,
   preflightManagedInstallation,
   prepareManagedInstallation,
   type ManagedRuntimePaths,
@@ -10,7 +9,9 @@ import {
 } from './managed-installation.js';
 import {
   AGENT_KEY,
+  AUDIT_OPTIONS,
   AUDIT_SCRIPT,
+  GUARD_OPTIONS,
   GUARD_SCRIPT,
   type RenderedDocument,
 } from './cursor-contract.js';
@@ -20,17 +21,9 @@ const DISPLAY_NAME = 'Cursor';
 const HOOKS_DIRECTORY_LABEL = 'Cursor hooks directory';
 const HOOKS_LABEL = 'Cursor user hooks';
 
-export type CursorRuntimePaths = ManagedRuntimePaths;
-export type PreparedCursorInstallation = PreparedManagedInstallation;
-export type { RenameFile };
-
-export function cursorRuntimePaths(config: InstallConfig): CursorRuntimePaths {
-  return managedRuntimePaths(config, AGENT_KEY, GUARD_SCRIPT, AUDIT_SCRIPT);
-}
-
 export async function preflightCursorInstallation(
   config: InstallConfig,
-): Promise<CursorRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
     hookLocations: [{
@@ -44,7 +37,7 @@ export async function preflightCursorInstallation(
 export async function prepareCursorInstallation(
   config: InstallConfig,
   rendered: RenderedDocument,
-): Promise<PreparedCursorInstallation> {
+): Promise<PreparedManagedInstallation> {
   if (!rendered.changed && rendered.document.raw === undefined) {
     throw new Error('Cursor hook installation did not produce a configuration document');
   }
@@ -61,21 +54,13 @@ export async function prepareCursorInstallation(
       source: hooksSource,
     }],
     config,
-    guardOptions: {
+    guardOptions: GUARD_OPTIONS,
-      failClosed: true,
+    auditOptions: AUDIT_OPTIONS,
-      successOutput: '{"permission":"allow"}\n',
-      denyProtocol: 'cursor',
-    },
-    auditOptions: {
-      failClosed: true,
-      nativePayload: true,
-      successOutput: '{}\n',
-    },
   }, GUARD_SCRIPT, AUDIT_SCRIPT);
 }
 
 export async function commitCursorInstallation(
-  prepared: PreparedCursorInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/cursor-io.ts

@@ -1,237 +1,56 @@
-import { randomUUID } from 'node:crypto';
-import fsp from 'node:fs/promises';
-import type { FileHandle } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import {
   AGENT_KEY,
   CONFIG_FILE,
   type CursorDocument,
-  type JsonObject,
   type RenderedDocument,
   type RuntimeContract,
   createDocument,
-  isObject,
   parseDocument,
-  parseStrictJsonObject,
 } from './cursor-contract.js';
-
+import { readPhysicalFile } from './managed-files.js';
-function errorMessage(error: unknown): string {
+import { managedRuntimePresent } from './managed-runtime-status.js';
-  return error instanceof Error ? error.message : String(error);
+import {
-}
+  commitManagedTransaction,
-
+  prepareManagedFileChange,
-function asError(error: unknown): Error {
+} from './managed-transaction.js';
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-function hasErrorCode(error: unknown, code: string): boolean {
-  return isObject(error) && error.code === code;
-}
 
 export function cursorConfigPath(): string {
   return path.join(os.homedir(), '.cursor', CONFIG_FILE);
 }
 
-async function readOptionalPhysical(filePath: string, label: string): Promise<string | undefined> {
-  let metadata;
-  try {
-    metadata = await fsp.lstat(filePath);
-  } catch (error) {
-    if (hasErrorCode(error, 'ENOENT') || hasErrorCode(error, 'ENOTDIR')) return undefined;
-    throw new Error(`Inspect ${label} at ${filePath}: ${errorMessage(error)}`, {
-      cause: asError(error),
-    });
-  }
-  if (!metadata.isFile() || metadata.isSymbolicLink()) {
-    throw new Error(`${label} path is not a physical file: ${filePath}`);
-  }
-  try {
-    return await fsp.readFile(filePath, 'utf-8');
-  } catch (error) {
-    throw new Error(`Read ${label} at ${filePath}: ${errorMessage(error)}`, {
-      cause: asError(error),
-    });
-  }
-}
-
 export async function readDocument(): Promise<CursorDocument> {
   const filePath = cursorConfigPath();
-  const raw = await readOptionalPhysical(filePath, 'Cursor user hooks');
+  const snapshot = await readPhysicalFile(filePath, 'Cursor user hooks');
-  return raw === undefined ? createDocument(filePath) : parseDocument(filePath, raw);
+  return snapshot ? parseDocument(filePath, snapshot.contents) : createDocument(filePath);
-}
-
-async function ensurePhysicalDirectory(directory: string): Promise<void> {
-  try {
-    await fsp.mkdir(directory, { recursive: true, mode: 0o700 });
-  } catch (error) {
-    throw new Error(`Create Cursor hooks directory at ${directory}: ${errorMessage(error)}`, {
-      cause: asError(error),
-    });
-  }
-  let metadata;
-  try {
-    metadata = await fsp.lstat(directory);
-  } catch (error) {
-    throw new Error(`Inspect Cursor hooks directory at ${directory}: ${errorMessage(error)}`, {
-      cause: asError(error),
-    });
-  }
-  if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
-    throw new Error(`Cursor hooks directory is not a physical directory: ${directory}`);
-  }
-}
-
-async function unlinkOptional(filePath: string): Promise<void> {
-  try {
-    await fsp.unlink(filePath);
-  } catch (error) {
-    if (!hasErrorCode(error, 'ENOENT')) throw error;
-  }
-}
-
-async function writeExclusive(filePath: string, contents: string): Promise<void> {
-  let handle: FileHandle | undefined;
-  try {
-    handle = await fsp.open(filePath, 'wx', 0o600);
-    await handle.writeFile(contents, 'utf-8');
-    await handle.sync();
-    await handle.close();
-    handle = undefined;
-  } catch (error) {
-    const failures = [asError(error)];
-    if (handle) {
-      try {
-        await handle.close();
-      } catch (closeError) {
-        failures.push(asError(closeError));
-      }
-    }
-    try {
-      await unlinkOptional(filePath);
-    } catch (cleanupError) {
-      failures.push(asError(cleanupError));
-    }
-    if (failures.length > 1) {
-      throw new AggregateError(failures, 'Stage Cursor user hooks');
-    }
-    throw new Error(`Stage Cursor user hooks: ${errorMessage(error)}`, { cause: failures[0] });
-  }
-}
-
-async function assertUnchanged(document: CursorDocument): Promise<void> {
-  const current = await readOptionalPhysical(document.filePath, 'Cursor user hooks');
-  if (current !== document.raw) {
-    throw new Error(`Cursor user hooks changed during update: ${document.filePath}`);
-  }
 }
 
 export async function writeDocument(rendered: RenderedDocument): Promise<void> {
   if (!rendered.changed) return;
-  await assertUnchanged(rendered.document);
+  const change = await prepareManagedFileChange({
-  if (rendered.next === undefined) {
+    filePath: rendered.document.filePath,
-    try {
+    label: 'Cursor user hooks',
-      await fsp.unlink(rendered.document.filePath);
+    next: rendered.next,
-    } catch (error) {
+    mode: 0o600,
-      if (!hasErrorCode(error, 'ENOENT')) {
+    expectedSource: rendered.document.raw,
-        throw new Error(
+    verifyExpectedSource: true,
-          `Remove Cursor user hooks at ${rendered.document.filePath}: ${errorMessage(error)}`,
+  });
-          { cause: asError(error) },
+  if (!change) return;
-        );
+  await commitManagedTransaction({
-      }
+    displayName: 'Cursor',
-    }
+    operation: 'uninstall',
-    return;
+    directories: [{
-  }
+      path: path.dirname(rendered.document.filePath),
-
+      label: 'Cursor hooks directory',
-  const directory = path.dirname(rendered.document.filePath);
+    }],
-  await ensurePhysicalDirectory(directory);
+    changes: [change],
-  const temporaryPath = path.join(
-    directory,
-    `.${path.basename(rendered.document.filePath)}.${randomUUID()}.tmp`,
-  );
-  let committed = false;
-  let failure: Error | undefined;
-  try {
-    await writeExclusive(temporaryPath, rendered.next);
-    await assertUnchanged(rendered.document);
-    await fsp.rename(temporaryPath, rendered.document.filePath);
-    committed = true;
-  } catch (error) {
-    failure = new Error(
-      `Write Cursor user hooks at ${rendered.document.filePath}: ${errorMessage(error)}`,
-      { cause: asError(error) },
-    );
-  }
-  let cleanupFailure: Error | undefined;
-  if (!committed) {
-    try {
-      await unlinkOptional(temporaryPath);
-    } catch (error) {
-      cleanupFailure = new Error(
-        `Clean Cursor hook staging file at ${temporaryPath}: ${errorMessage(error)}`,
-        { cause: asError(error) },
-      );
-    }
-  }
-  if (failure && cleanupFailure) {
-    throw new AggregateError([failure, cleanupFailure], 'Write Cursor user hooks');
-  }
-  if (failure) throw failure;
-  if (cleanupFailure) throw cleanupFailure;
-}
-
-export async function physicalFileExists(filePath: string, label: string): Promise<boolean> {
-  let metadata;
-  try {
-    metadata = await fsp.lstat(filePath);
-  } catch (error) {
-    if (hasErrorCode(error, 'ENOENT') || hasErrorCode(error, 'ENOTDIR')) return false;
-    throw new Error(`Inspect ${label} at ${filePath}: ${errorMessage(error)}`, {
-      cause: asError(error),
   });
-  }
-  if (!metadata.isFile() || metadata.isSymbolicLink()) {
-    throw new Error(`${label} path is not a physical file: ${filePath}`);
-  }
-  return true;
-}
-
-export async function requireRuntime(filePath: string, label: string): Promise<void> {
-  if (!filePath) throw new Error(`${label} path is required`);
-  if (!await physicalFileExists(filePath, label)) {
-    throw new Error(`${label} is missing: ${filePath}`);
-  }
-}
-
-async function readRuntimeConfig(filePath: string): Promise<JsonObject | undefined> {
-  const raw = await readOptionalPhysical(filePath, 'Elydora runtime config');
-  if (raw === undefined) return undefined;
-  return parseStrictJsonObject(raw, `Elydora runtime config at ${filePath}`);
-}
-
-function sameAgentId(left: unknown, right: string): boolean {
-  if (typeof left !== 'string') return false;
-  return process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right;
 }
 
 export async function runtimeFilesExist(contracts: RuntimeContract[]): Promise<boolean> {
   for (const contract of contracts) {
-    const runtimeConfig = await readRuntimeConfig(
+    if (await managedRuntimePresent(contract, AGENT_KEY)) return true;
-      path.join(path.dirname(contract.guardPath), 'config.json'),
-    );
-    if (!runtimeConfig
-      || runtimeConfig.agent_name !== AGENT_KEY
-      || !sameAgentId(runtimeConfig.agent_id, contract.agentId)) continue;
-    const files = await Promise.all([
-      physicalFileExists(contract.guardPath, 'Elydora guard runtime'),
-      physicalFileExists(contract.auditPath, 'Elydora audit runtime'),
-      physicalFileExists(
-        path.join(path.dirname(contract.guardPath), 'private.key'),
-        'Elydora private key',
-      ),
-    ]);
-    if (files.every(Boolean)) return true;
   }
   return false;
 }

src/plugins/droid-contract.ts

@@ -1,5 +1,13 @@
 import os from 'node:os';
 import path from 'node:path';
+import { sameAgentId, samePath } from './common.js';
+import {
+  parseLegacyWindowsCommand,
+  parsePosixCommand,
+  parsePowerShellSource,
+  posixSource,
+  powerShellSource,
+} from './shell-command.js';
 import type { JsonObject } from './strict-json.js';
 
 export const AGENT_KEY = 'droid';
@@ -10,7 +18,6 @@ export const TOOL_EVENTS = ['PreToolUse', 'PostToolUse'] as const;
 
 const HANDLER_KEYS = ['command', 'timeout', 'type'];
 const GROUP_KEYS = ['hooks', 'matcher'];
-const WINDOWS_EXIT_SUFFIX = '; exit $LASTEXITCODE';
 
 export type ToolEvent = typeof TOOL_EVENTS[number];
 
@@ -44,26 +51,13 @@ export interface ManagedRemoval {
   readonly removeGroup: boolean;
 }
 
-interface ParsedArgument {
-  readonly value: string;
-  readonly next: number;
-}
-
-function quotePosix(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
-function quotePowerShell(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`;
-}
-
 export function buildCommand(scriptPath: string): string {
   if (!path.isAbsolute(process.execPath) || !path.isAbsolute(scriptPath)) {
     throw new Error('Factory Droid hook commands require absolute executable and script paths');
   }
   return process.platform === 'win32'
-    ? `& ${quotePowerShell(process.execPath)} ${quotePowerShell(scriptPath)}${WINDOWS_EXIT_SUFFIX}`
+    ? powerShellSource(scriptPath)
-    : `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`;
+    : posixSource(scriptPath);
 }
 
 export function buildGroup(scriptPath: string): DroidGroup {
@@ -150,90 +144,13 @@ export function readHookMap(value: unknown, label: string): DroidHookMap {
   return hooks;
 }
 
-function readPowerShellArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length; index += 1) {
-    if (command[index] !== "'") {
-      value += command[index];
-      continue;
-    }
-    if (command[index + 1] === "'") {
-      value += "'";
-      index += 1;
-      continue;
-    }
-    return { value, next: index + 1 };
-  }
-  return undefined;
-}
-
-const POSIX_APOSTROPHE = `'"'"'`;
-
-function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length;) {
-    if (command.startsWith(POSIX_APOSTROPHE, index)) {
-      value += "'";
-      index += POSIX_APOSTROPHE.length;
-      continue;
-    }
-    if (command[index] === "'") return { value, next: index + 1 };
-    value += command[index];
-    index += 1;
-  }
-  return undefined;
-}
-
-function parseTwoArguments(
-  command: string,
-  start: number,
-  readArgument: (command: string, start: number) => ParsedArgument | undefined,
-): readonly [string, string] | undefined {
-  const executable = readArgument(command, start);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readArgument(command, executable.next + 1);
-  if (!script || script.next !== command.length || !executable.value || !script.value) return undefined;
-  return [executable.value, script.value];
-}
-
-function parseLegacyWindowsCommand(command: string): readonly [string, string] | undefined {
-  const match = /^"([^"\r\n]+)" "([^"\r\n]+)"$/.exec(command);
-  return match ? [match[1], match[2]] : undefined;
-}
-
-function parsePowerShellCommand(command: string): readonly [string, string] | undefined {
-  if (!command.startsWith('& ')) return undefined;
-  const executable = readPowerShellArgument(command, 2);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPowerShellArgument(command, executable.next + 1);
-  if (!script
-    || command.slice(script.next) !== WINDOWS_EXIT_SUFFIX
-    || !executable.value
-    || !script.value) return undefined;
-  return [executable.value, script.value];
-}
-
 function parseGeneratedCommand(
   command: string,
   includeLegacy: boolean,
 ): readonly [string, string] | undefined {
-  if (process.platform !== 'win32') return parseTwoArguments(command, 0, readPosixArgument);
+  if (process.platform !== 'win32') return parsePosixCommand(command);
-  const current = parsePowerShellCommand(command);
+  return parsePowerShellSource(command)
-  return current ?? (includeLegacy ? parseLegacyWindowsCommand(command) : undefined);
+    ?? (includeLegacy ? parseLegacyWindowsCommand(command) : undefined);
-}
-
-export function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-export function sameAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
 }
 
 export function managedAgentId(

src/plugins/droid-installation.ts

@@ -1,11 +1,7 @@
 import path from 'node:path';
 import type { InstallConfig } from './base.js';
-import {
+import { MAX_SOURCE_BYTES, samePath } from './common.js';
-  AGENT_KEY,
+import { AGENT_KEY, AUDIT_SCRIPT, GUARD_SCRIPT } from './droid-contract.js';
-  AUDIT_SCRIPT,
-  GUARD_SCRIPT,
-  samePath,
-} from './droid-contract.js';
 import {
   activeDocument,
   installationDocuments,
@@ -31,11 +27,6 @@ import {
 
 const DISPLAY_NAME = 'Factory Droid';
 const DIRECTORY_LABEL = 'Factory Droid user configuration directory';
-const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
-
-export type DroidRuntimePaths = ManagedRuntimePaths;
-export type PreparedDroidInstallation = PreparedManagedInstallation;
-export type { RenameFile };
 
 function sourceLabel(document: DroidDocument): string {
   if (document.kind === 'settings') return 'Factory Droid user settings';
@@ -56,7 +47,7 @@ function hookLocations(sources: DroidSources) {
 export async function preflightDroidInstallation(
   config: InstallConfig,
   sources: DroidSources,
-): Promise<DroidRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   requireHooksEnabled(sources);
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
@@ -92,7 +83,7 @@ export async function prepareDroidInstallation(
   config: InstallConfig,
   sources: DroidSources,
   rendered: readonly RenderedDocument[],
-): Promise<PreparedDroidInstallation> {
+): Promise<PreparedManagedInstallation> {
   await preflightDroidInstallation(config, sources);
   const changed = installationChanges(sources, rendered);
   const prepared = await prepareManagedInstallation({
@@ -124,7 +115,7 @@ export async function prepareDroidInstallation(
 }
 
 export async function commitDroidInstallation(
-  prepared: PreparedDroidInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/droid-io.ts

@@ -1,13 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
-import {
+import { MAX_SOURCE_BYTES } from './common.js';
-  AGENT_KEY,
+import { AGENT_KEY, type RuntimeContract } from './droid-contract.js';
-  AUDIT_SCRIPT,
-  GUARD_SCRIPT,
-  type RuntimeContract,
-  sameAgentId,
-  samePath,
-} from './droid-contract.js';
 import {
   activeDocument,
   createLegacyHookDocument,
@@ -19,15 +13,9 @@ import {
   type DroidDocumentKind,
   type DroidSources,
 } from './droid-config.js';
-import { generateGuardScript } from './guard-template.js';
-import { generateHookScript } from './hook-template.js';
 import { readDroidPolicy } from './droid-policy.js';
 import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
-import { parseStrictJsonObject, type JsonObject } from './strict-json.js';
+import { managedRuntimeFilesExist } from './managed-runtime-status.js';
-
-const MAX_SECRET_BYTES = 64 * 1024;
-const MAX_CONFIG_BYTES = 512 * 1024;
-const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
 
 interface FactoryPaths {
   readonly directory: string;
@@ -96,86 +84,9 @@ export function requireHooksEnabled(sources: DroidSources): void {
   }
 }
 
-function requireString(value: unknown, field: string, configPath: string): string {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`Elydora runtime config ${field} is invalid: ${configPath}`);
-  }
-  return value;
-}
-
-function validateRuntimeConfig(
-  config: JsonObject,
-  contract: RuntimeContract,
-  configPath: string,
-): void {
-  const supported = new Set(['org_id', 'agent_id', 'kid', 'base_url', 'token', 'agent_name']);
-  const extra = Object.keys(config).find((key) => !supported.has(key));
-  if (extra) throw new Error(`Elydora runtime config has unsupported field "${extra}": ${configPath}`);
-  requireString(config.org_id, 'org_id', configPath);
-  requireString(config.kid, 'kid', configPath);
-  const agentId = requireString(config.agent_id, 'agent_id', configPath);
-  if (!sameAgentId(agentId, contract.agentId) || config.agent_name !== AGENT_KEY) {
-    throw new Error(`Elydora runtime identity does not match Factory Droid hooks: ${configPath}`);
-  }
-  if (config.token !== undefined) requireString(config.token, 'token', configPath);
-  const rawBaseUrl = requireString(config.base_url, 'base_url', configPath);
-  let baseUrl: URL;
-  try {
-    baseUrl = new URL(rawBaseUrl);
-  } catch (error) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`, {
-      cause: error instanceof Error ? error : new Error(String(error)),
-    });
-  }
-  if (!['http:', 'https:'].includes(baseUrl.protocol)
-    || !baseUrl.hostname
-    || baseUrl.username
-    || baseUrl.password
-    || baseUrl.search
-    || baseUrl.hash) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`);
-  }
-}
-
-function validatePrivateKey(contents: string, keyPath: string): void {
-  const bytes = Buffer.from(contents, 'base64url');
-  if (bytes.length !== 32 || bytes.toString('base64url') !== contents) {
-    throw new Error(`Elydora private key is invalid: ${keyPath}`);
-  }
-}
-
-function validContractPaths(contract: RuntimeContract): boolean {
-  const agentDirectory = path.dirname(contract.guardPath);
-  return samePath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))
-    && samePath(contract.guardPath, path.join(agentDirectory, GUARD_SCRIPT))
-    && samePath(contract.auditPath, path.join(agentDirectory, AUDIT_SCRIPT));
-}
-
 export async function runtimeFilesExist(contracts: RuntimeContract[]): Promise<boolean> {
   for (const contract of contracts) {
-    if (!validContractPaths(contract)) continue;
+    if (await managedRuntimeFilesExist(contract, AGENT_KEY)) return true;
-    const runtimeRoot = path.join(os.homedir(), '.elydora');
-    const agentDirectory = path.dirname(contract.guardPath);
-    if (!await inspectPhysicalDirectory(runtimeRoot, 'Elydora runtime directory')) continue;
-    if (!await inspectPhysicalDirectory(agentDirectory, 'Elydora agent runtime directory')) continue;
-    const configPath = path.join(agentDirectory, 'config.json');
-    const keyPath = path.join(agentDirectory, 'private.key');
-    const [config, key, guard, audit] = await Promise.all([
-      readPhysicalFile(configPath, 'Elydora runtime config', MAX_CONFIG_BYTES),
-      readPhysicalFile(keyPath, 'Elydora private key', MAX_SECRET_BYTES),
-      readPhysicalFile(contract.guardPath, 'Elydora guard runtime'),
-      readPhysicalFile(contract.auditPath, 'Elydora audit runtime'),
-    ]);
-    if (!config || !key || !guard || !audit) continue;
-    const parsed = parseStrictJsonObject(config.contents, `Elydora runtime config at ${configPath}`);
-    validateRuntimeConfig(parsed, contract, configPath);
-    validatePrivateKey(key.contents, keyPath);
-    if (guard.contents === generateGuardScript(AGENT_KEY, contract.agentId)
-      && audit.contents === generateHookScript(
-        AGENT_KEY,
-        contract.agentId,
-        { nativePayload: true },
-      )) return true;
   }
   return false;
 }

src/plugins/droid-policy.ts

@@ -1,11 +1,10 @@
 import fsp from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { hasCode, MAX_SOURCE_BYTES } from './common.js';
 import { inspectPhysicalDirectory, readPhysicalFile, type FileSnapshot } from './managed-files.js';
 import { parseStrictJsoncObject, type JsonObject } from './strict-json.js';
 
-const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
-
 interface PolicyLocation {
   readonly filePath: string;
   readonly label: string;
@@ -37,10 +36,6 @@ export interface DroidPolicyState {
   readonly preconditions: readonly DroidPolicyPrecondition[];
 }
 
-function hasCode(error: unknown, code: string): boolean {
-  return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
-}
-
 function optionalBoolean(root: JsonObject, field: string, label: string): boolean | undefined {
   const value = root[field];
   if (value !== undefined && typeof value !== 'boolean') {

src/plugins/gemini-command.ts

@@ -1,58 +1,25 @@
 import os from 'node:os';
 import path from 'node:path';
-
+import { samePath } from './common.js';
-interface ParsedArgument {
+import {
-  readonly value: string;
+  decodePowerShellSource,
-  readonly next: number;
+  encodePowerShellSource,
-}
+  isNodeExecutable,
+  isPowerShellExecutable,
+  parsePosixCommand,
+  parsePowerShellSource,
+  posixSource,
+  quotePowerShell,
+  windowsPowerShellPath,
+} from './shell-command.js';
 
 export interface GeminiRuntimeReference {
   readonly agentId: string;
   readonly scriptPath: string;
 }
 
-export function sameGeminiPath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-export function sameGeminiAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right;
-}
-
-function quotePosix(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
-function quotePowerShell(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`;
-}
-
-function windowsPowerShellPath(): string {
-  const configuredRoot = process.env.SystemRoot;
-  const systemRoot = configuredRoot
-    && path.win32.isAbsolute(configuredRoot)
-    && !/["%\r\n]/.test(configuredRoot)
-    ? configuredRoot
-    : 'C:\\Windows';
-  return path.win32.join(
-    systemRoot,
-    'System32',
-    'WindowsPowerShell',
-    'v1.0',
-    'powershell.exe',
-  );
-}
-
 function windowsCommand(scriptPath: string): string {
-  const source = `& ${quotePowerShell(process.execPath)} ${quotePowerShell(scriptPath)}; exit $LASTEXITCODE`;
+  return `& ${quotePowerShell(windowsPowerShellPath())} -NoLogo -NoProfile -NonInteractive -EncodedCommand ${encodePowerShellSource(scriptPath)}`;
-  const encoded = Buffer.from(source, 'utf16le').toString('base64');
-  return `& ${quotePowerShell(windowsPowerShellPath())} -NoLogo -NoProfile -NonInteractive -EncodedCommand ${encoded}`;
 }
 
 export function buildGeminiCommand(scriptPath: string): string {
@@ -61,74 +28,15 @@ export function buildGeminiCommand(scriptPath: string): string {
   }
   return process.platform === 'win32'
     ? windowsCommand(scriptPath)
-    : `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`;
+    : posixSource(scriptPath);
-}
-
-function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  const apostrophe = `'"'"'`;
-  let value = '';
-  for (let index = start + 1; index < command.length;) {
-    if (command.startsWith(apostrophe, index)) {
-      value += "'";
-      index += apostrophe.length;
-      continue;
-    }
-    if (command[index] === "'") return { value, next: index + 1 };
-    value += command[index];
-    index += 1;
-  }
-  return undefined;
-}
-
-function parsePosixCommand(command: string): readonly [string, string] | undefined {
-  const executable = readPosixArgument(command, 0);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPosixArgument(command, executable.next + 1);
-  if (!script || script.next !== command.length) return undefined;
-  return [executable.value, script.value];
-}
-
-function readPowerShellArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length; index += 1) {
-    if (command[index] !== "'") {
-      value += command[index];
-      continue;
-    }
-    if (command[index + 1] === "'") {
-      value += "'";
-      index += 1;
-      continue;
-    }
-    return { value, next: index + 1 };
-  }
-  return undefined;
-}
-
-function parsePowerShellSource(source: string): readonly [string, string] | undefined {
-  if (!source.startsWith('& ')) return undefined;
-  const executable = readPowerShellArgument(source, 2);
-  if (!executable || source[executable.next] !== ' ') return undefined;
-  const script = readPowerShellArgument(source, executable.next + 1);
-  if (!script || source.slice(script.next) !== '; exit $LASTEXITCODE') return undefined;
-  return [executable.value, script.value];
 }
 
 function parseWindowsCommand(command: string): readonly [string, string] | undefined {
-  if (!command.startsWith('& ')) return undefined;
+  const match = /^& ('(?:[^']|'')+') -NoLogo -NoProfile -NonInteractive -EncodedCommand ([A-Za-z0-9+/]+={0,2})$/.exec(command);
-  const powershell = readPowerShellArgument(command, 2);
+  if (!match) return undefined;
-  if (!powershell
+  const powershell = parsePowerShellSource(`& ${match[1]} ''; exit $LASTEXITCODE`);
-    || !path.win32.isAbsolute(powershell.value)
+  if (!powershell || !isPowerShellExecutable(powershell[0])) return undefined;
-    || path.win32.basename(powershell.value).toLowerCase() !== 'powershell.exe') return undefined;
+  return decodePowerShellSource(match[2]);
-  const prefix = ' -NoLogo -NoProfile -NonInteractive -EncodedCommand ';
-  if (!command.startsWith(prefix, powershell.next)) return undefined;
-  const encoded = command.slice(powershell.next + prefix.length);
-  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) return undefined;
-  const buffer = Buffer.from(encoded, 'base64');
-  if (buffer.length % 2 !== 0 || buffer.toString('base64') !== encoded) return undefined;
-  return parsePowerShellSource(buffer.toString('utf16le'));
 }
 
 function parseLegacyCommand(command: string): readonly [string, string] | undefined {
@@ -136,11 +44,6 @@ function parseLegacyCommand(command: string): readonly [string, string] | undefi
   return match ? ['node', match[1]] : undefined;
 }
 
-function isNodeExecutable(filePath: string): boolean {
-  const basename = path.basename(filePath).toLowerCase();
-  return basename === 'node' || basename === 'node.exe';
-}
-
 export function geminiRuntimeReference(
   command: string,
   scriptName: string,
@@ -155,7 +58,7 @@ export function geminiRuntimeReference(
     || path.basename(parsed[1]) !== scriptName) return undefined;
   if (parsed[0] !== 'node' && !path.isAbsolute(parsed[0])) return undefined;
   const agentDirectory = path.dirname(parsed[1]);
-  if (!sameGeminiPath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))) {
+  if (!samePath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))) {
     return undefined;
   }
   const agentId = path.basename(agentDirectory);

src/plugins/gemini-contract.ts

@@ -1,9 +1,11 @@
+import { sameAgentId } from './common.js';
 import {
   buildGeminiCommand,
   geminiRuntimeReference,
-  sameGeminiAgentId,
   type GeminiRuntimeReference,
 } from './gemini-command.js';
+import type { GuardScriptOptions } from './guard-template.js';
+import type { HookScriptOptions } from './hook-template.js';
 import { isObject, type JsonObject } from './strict-json.js';
 
 export const AGENT_KEY = 'gemini';
@@ -14,6 +16,8 @@ export const GUARD_HOOK_NAME = 'elydora-guard';
 export const AUDIT_HOOK_NAME = 'elydora-audit';
 export const HOOK_TIMEOUT_MS = 10_000;
 export const MANAGED_EVENTS = ['BeforeTool', 'AfterTool'] as const;
+export const GUARD_OPTIONS: GuardScriptOptions = { successOutput: '{}\n' };
+export const AUDIT_OPTIONS: HookScriptOptions = { nativePayload: true, successOutput: '{}\n' };
 
 const KNOWN_EVENTS = new Set([
   'BeforeTool',
@@ -248,7 +252,7 @@ export function managedGeminiRemovals(
       const handlerIndexes = group.hooks.flatMap((handler, handlerIndex) => {
         const reference = managedReference(handler, scriptName, hookName, true);
         return reference
-          && (agentId === undefined || sameGeminiAgentId(reference.agentId, agentId))
+          && (agentId === undefined || sameAgentId(reference.agentId, agentId))
           ? [handlerIndex]
           : [];
       });

src/plugins/gemini-installation.ts

@@ -1,7 +1,9 @@
 import type { InstallConfig } from './base.js';
 import {
   AGENT_KEY,
+  AUDIT_OPTIONS,
   AUDIT_SCRIPT,
+  GUARD_OPTIONS,
   GUARD_SCRIPT,
 } from './gemini-contract.js';
 import type { RenderedGeminiDocument } from './gemini-config.js';
@@ -18,14 +20,10 @@ const DISPLAY_NAME = 'Gemini CLI';
 const SETTINGS_DIRECTORY_LABEL = 'Gemini CLI configuration directory';
 const SETTINGS_LABEL = 'Gemini CLI user settings';
 
-export type GeminiRuntimePaths = ManagedRuntimePaths;
-export type PreparedGeminiInstallation = PreparedManagedInstallation;
-export type { RenameFile };
-
 export async function preflightGeminiInstallation(
   config: InstallConfig,
   settingsPath: string,
-): Promise<GeminiRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
     hookLocations: [{ directoryLabel: SETTINGS_DIRECTORY_LABEL, filePath: settingsPath }],
@@ -36,7 +34,7 @@ export async function preflightGeminiInstallation(
 export async function prepareGeminiInstallation(
   config: InstallConfig,
   rendered: RenderedGeminiDocument,
-): Promise<PreparedGeminiInstallation> {
+): Promise<PreparedManagedInstallation> {
   const settingsSource = rendered.next ?? rendered.document.raw;
   if (settingsSource === undefined) throw new Error('Gemini CLI hook settings are missing');
   return prepareManagedInstallation({
@@ -50,13 +48,13 @@ export async function prepareGeminiInstallation(
       source: settingsSource,
     }],
     config,
-    guardOptions: { successOutput: '{}\n' },
+    guardOptions: GUARD_OPTIONS,
-    auditOptions: { nativePayload: true, successOutput: '{}\n' },
+    auditOptions: AUDIT_OPTIONS,
   }, GUARD_SCRIPT, AUDIT_SCRIPT);
 }
 
 export async function commitGeminiInstallation(
-  prepared: PreparedGeminiInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/gemini-io.ts

@@ -2,7 +2,9 @@ import os from 'node:os';
 import path from 'node:path';
 import {
   AGENT_KEY,
+  AUDIT_OPTIONS,
   CONFIG_FILE,
+  GUARD_OPTIONS,
   type GeminiRuntimeContract,
 } from './gemini-contract.js';
 import {
@@ -11,13 +13,12 @@ import {
   type GeminiDocument,
   type RenderedGeminiDocument,
 } from './gemini-config.js';
-import { sameGeminiAgentId, sameGeminiPath } from './gemini-command.js';
 import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
+import { managedRuntimeFilesExist } from './managed-runtime-status.js';
 import {
   commitManagedTransaction,
   prepareManagedFileChange,
 } from './managed-transaction.js';
-import { parseStrictJsonObject, type JsonObject } from './strict-json.js';
 
 export function geminiConfigurationDirectory(): string {
   const configuredHome = process.env.GEMINI_CLI_HOME;
@@ -64,86 +65,15 @@ export async function writeGeminiDocument(rendered: RenderedGeminiDocument): Pro
   });
 }
 
-function requireNonEmptyString(value: unknown, field: string, configPath: string): string {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`Elydora runtime config ${field} is invalid: ${configPath}`);
-  }
-  return value;
-}
-
-function validateRuntimeConfig(
-  config: JsonObject,
-  contract: GeminiRuntimeContract,
-  configPath: string,
-): void {
-  const supported = new Set(['org_id', 'agent_id', 'kid', 'base_url', 'token', 'agent_name']);
-  const extra = Object.keys(config).find((key) => !supported.has(key));
-  if (extra) {
-    throw new Error(`Elydora runtime config has unsupported field "${extra}": ${configPath}`);
-  }
-  requireNonEmptyString(config.org_id, 'org_id', configPath);
-  requireNonEmptyString(config.kid, 'kid', configPath);
-  const agentId = requireNonEmptyString(config.agent_id, 'agent_id', configPath);
-  if (!sameGeminiAgentId(agentId, contract.agentId) || config.agent_name !== AGENT_KEY) {
-    throw new Error(`Elydora runtime identity does not match Gemini CLI hooks: ${configPath}`);
-  }
-  if (config.token !== undefined) requireNonEmptyString(config.token, 'token', configPath);
-  const rawBaseUrl = requireNonEmptyString(config.base_url, 'base_url', configPath);
-  let baseUrl: URL;
-  try {
-    baseUrl = new URL(rawBaseUrl);
-  } catch (error) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`, {
-      cause: error instanceof Error ? error : new Error(String(error)),
-    });
-  }
-  if (!['http:', 'https:'].includes(baseUrl.protocol)
-    || !baseUrl.hostname
-    || baseUrl.username
-    || baseUrl.password
-    || baseUrl.search
-    || baseUrl.hash) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`);
-  }
-}
-
-function validatePrivateKey(contents: string, keyPath: string): void {
-  const bytes = Buffer.from(contents, 'base64url');
-  if (bytes.length !== 32 || bytes.toString('base64url') !== contents) {
-    throw new Error(`Elydora private key is invalid: ${keyPath}`);
-  }
-}
-
-async function runtimeContractExists(contract: GeminiRuntimeContract): Promise<boolean> {
-  const runtimeRoot = path.join(os.homedir(), '.elydora');
-  const agentDirectory = path.dirname(contract.guardPath);
-  if (!sameGeminiPath(path.dirname(agentDirectory), runtimeRoot)
-    || !sameGeminiPath(contract.auditPath, path.join(agentDirectory, 'hook.js'))) return false;
-  if (!await inspectPhysicalDirectory(runtimeRoot, 'Elydora runtime directory')) return false;
-  if (!await inspectPhysicalDirectory(agentDirectory, 'Elydora agent runtime directory')) {
-    return false;
-  }
-
-  const configPath = path.join(agentDirectory, 'config.json');
-  const keyPath = path.join(agentDirectory, 'private.key');
-  const [config, key, guard, audit] = await Promise.all([
-    readPhysicalFile(configPath, 'Elydora runtime config'),
-    readPhysicalFile(keyPath, 'Elydora private key'),
-    readPhysicalFile(contract.guardPath, 'Elydora guard runtime'),
-    readPhysicalFile(contract.auditPath, 'Elydora audit runtime'),
-  ]);
-  if (!config || !key || !guard || !audit) return false;
-  const parsed = parseStrictJsonObject(config.contents, `Elydora runtime config at ${configPath}`);
-  validateRuntimeConfig(parsed, contract, configPath);
-  validatePrivateKey(key.contents, keyPath);
-  return guard.contents.length > 0 && audit.contents.length > 0;
-}
-
 export async function geminiRuntimeFilesExist(
   contracts: readonly GeminiRuntimeContract[],
 ): Promise<boolean> {
   for (const contract of contracts) {
-    if (await runtimeContractExists(contract)) return true;
+    const exists = await managedRuntimeFilesExist(contract, AGENT_KEY, {
+      guardOptions: GUARD_OPTIONS,
+      auditOptions: AUDIT_OPTIONS,
+    });
+    if (exists) return true;
   }
   return false;
 }

src/plugins/hook-template.ts

@@ -1,8 +1,5 @@
 import { PROTECTED_RUNTIME_READER } from './runtime-reader-template.js';
 
-export { generateGuardScript } from './guard-template.js';
-export type { GuardScriptOptions } from './guard-template.js';
-
 export interface HookScriptOptions {
   readonly failClosed?: boolean;
   readonly nativePayload?: boolean;
@@ -38,6 +35,8 @@ const KEY_PATH = path.join(ELYDORA_DIR, AGENT_ID, 'private.key');
 const CHAIN_STATE_PATH = path.join(ELYDORA_DIR, AGENT_ID, 'chain-state.json');
 const ERROR_LOG_PATH = path.join(ELYDORA_DIR, AGENT_ID, 'error.log');
 const ZERO_CHAIN_HASH = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA';
+const MAX_CHAIN_ATTEMPTS = 5;
+const SUBMIT_BUDGET_MS = 4000;
 
 ${PROTECTED_RUNTIME_READER}
 
@@ -165,6 +164,81 @@ function writeChainState(chainHash) {
   writeProtectedJson(CHAIN_STATE_PATH, 'Chain state', { prev_chain_hash: chainHash });
 }
 
+function lockOwnerAlive(lockPath) {
+  let owner;
+  try {
+    owner = Number.parseInt(fs.readFileSync(lockPath, 'utf-8'), 10);
+  } catch (error) {
+    if (!hasRuntimeErrorCode(error, 'ENOENT')) throw error;
+    return false;
+  }
+  if (!Number.isInteger(owner) || owner <= 0) return false;
+  try {
+    process.kill(owner, 0);
+    return true;
+  } catch (error) {
+    if (hasRuntimeErrorCode(error, 'ESRCH')) return false;
+    return true;
+  }
+}
+
+function withChainLock(update) {
+  const lockPath = CHAIN_STATE_PATH + '.lock';
+  const deadline = performance.now() + 1000;
+  for (;;) {
+    let descriptor;
+    try {
+      descriptor = fs.openSync(lockPath, 'wx', 0o600);
+      fs.writeSync(descriptor, String(process.pid));
+    } catch (error) {
+      if (!hasRuntimeErrorCode(error, 'EEXIST')) throw error;
+      if (lockOwnerAlive(lockPath)) {
+        if (performance.now() > deadline) throw new Error('Chain state lock timed out: ' + lockPath);
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        continue;
+      }
+      let age = 0;
+      try { age = Date.now() - fs.statSync(lockPath).mtimeMs; } catch (statError) {
+        if (!hasRuntimeErrorCode(statError, 'ENOENT')) throw statError;
+      }
+      if (age > 5000) {
+        const reclaimed = lockPath + '.' + process.pid + '.stale';
+        try {
+          fs.renameSync(lockPath, reclaimed);
+          fs.unlinkSync(reclaimed);
+        } catch (reclaimError) {
+          if (!hasRuntimeErrorCode(reclaimError, 'ENOENT')) throw reclaimError;
+        }
+        continue;
+      }
+      if (performance.now() > deadline) throw new Error('Chain state lock timed out: ' + lockPath);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+      continue;
+    }
+    try {
+      return update();
+    } finally {
+      let current = null;
+      try {
+        current = fs.lstatSync(lockPath);
+      } catch (statError) {
+        if (!hasRuntimeErrorCode(statError, 'ENOENT')) throw statError;
+      }
+      const own = fs.fstatSync(descriptor);
+      fs.closeSync(descriptor);
+      if (current && current.ino === own.ino && current.dev === own.dev) fs.unlinkSync(lockPath);
+    }
+  }
+}
+
+function advanceChainState(fromHash, toHash) {
+  return withChainLock(() => {
+    if (readChainState() !== fromHash) return false;
+    writeChainState(toHash);
+    return true;
+  });
+}
+
 function readConfigAndKey() {
   const raw = readProtectedFile(
     CONFIG_PATH,
@@ -219,27 +293,43 @@ async function readHookInput() {
   return value;
 }
 
-async function submitOperation(hookData, runtime) {
+async function postOperation(operation, runtime, deadline) {
-  const toolEvent = hookData.tool_result && typeof hookData.tool_result === 'object'
+  const remaining = deadline - performance.now();
-    ? hookData.tool_result
+  if (remaining <= 0) throw new Error('Audit API retry budget exhausted');
-    : hookData.tool_call && typeof hookData.tool_call === 'object'
+  const controller = new AbortController();
-      ? hookData.tool_call
+  const timeout = setTimeout(() => controller.abort(), Math.min(5000, remaining));
-      : {};
+  try {
-  const toolName = hookData.tool_name || hookData.toolName || hookData.name ||
+    const headers = { 'Content-Type': 'application/json', Accept: 'application/json' };
-    toolEvent.name || 'unknown';
+    if (runtime.config.token) headers.Authorization = 'Bearer ' + runtime.config.token;
-  const toolInput = hookData.tool_input || hookData.toolInput || hookData.input ||
+    const response = await fetch(runtime.baseUrl + '/v1/operations', {
-    hookData.parameters || toolEvent.input || {};
+      method: 'POST',
-  const sessionId = hookData.conversation_id || hookData.session_id || hookData.sessionId ||
+      headers,
-    hookData.session || hookData.taskId || 'unknown';
+      body: JSON.stringify(operation),
-  const previousHash = readChainState();
+      signal: controller.signal,
+    });
+    if (response.ok) return { accepted: true };
+    const responseBody = await response.text();
+    if (response.status === 400 && responseBody) {
+      let failure;
+      try { failure = JSON.parse(responseBody); } catch (error) {
+        throw new Error('Audit API returned invalid error JSON: ' + error.message);
+      }
+      if (failure.error && failure.error.code === 'PREV_HASH_MISMATCH') {
+        const match = String(failure.error.message || '').match(
+          /Expected prev_chain_hash "([A-Za-z0-9_-]{43})"/,
+        );
+        if (match) return { accepted: false, expected: match[1] };
+      }
+    }
+    throw new Error('Audit API returned HTTP ' + response.status);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function buildOperation(runtime, payload, payloadHash, toolName, sessionId, previousHash) {
   const operationId = uuidv7();
   const issuedAt = Date.now();
-  const payload = NATIVE_PAYLOAD ? hookData : {
-    tool_name: toolName,
-    tool_input: toolInput,
-    session_id: sessionId,
-  };
-  const payloadHash = computePayloadHash(payload);
   const chainHash = computeChainHash(previousHash, payloadHash, operationId, issuedAt);
   const unsigned = {
     op_version: '1.0',
@@ -261,41 +351,42 @@ async function submitOperation(hookData, runtime) {
     runtime.privateKey,
     Buffer.from(jcsCanonicalise(unsigned), 'utf-8'),
   );
-  const operation = { ...unsigned, chain_hash: chainHash, signature };
+  return { operation: { ...unsigned, chain_hash: chainHash, signature }, chainHash };
-  const controller = new AbortController();
+}
-  const timeout = setTimeout(() => controller.abort(), 5000);
+
-  try {
+async function submitOperation(hookData, runtime) {
-    const headers = { 'Content-Type': 'application/json', Accept: 'application/json' };
+  const toolEvent = hookData.tool_result && typeof hookData.tool_result === 'object'
-    if (runtime.config.token) headers.Authorization = 'Bearer ' + runtime.config.token;
+    ? hookData.tool_result
-    const response = await fetch(runtime.baseUrl + '/v1/operations', {
+    : hookData.tool_call && typeof hookData.tool_call === 'object'
-      method: 'POST',
+      ? hookData.tool_call
-      headers,
+      : {};
-      body: JSON.stringify(operation),
+  const toolName = hookData.tool_name || hookData.toolName || hookData.name ||
-      signal: controller.signal,
+    toolEvent.name || 'unknown';
-    });
+  const toolInput = hookData.tool_input || hookData.toolInput || hookData.input ||
-    if (response.ok) {
+    hookData.parameters || toolEvent.input || {};
-      writeChainState(chainHash);
+  const sessionId = hookData.conversation_id || hookData.session_id || hookData.sessionId ||
+    hookData.session || hookData.taskId || 'unknown';
+  const payload = NATIVE_PAYLOAD ? hookData : {
+    tool_name: toolName,
+    tool_input: toolInput,
+    session_id: sessionId,
+  };
+  const payloadHash = computePayloadHash(payload);
+  const deadline = performance.now() + SUBMIT_BUDGET_MS;
+  let previousHash = readChainState();
+  for (let attempt = 1; ; attempt += 1) {
+    const built = buildOperation(runtime, payload, payloadHash, toolName, sessionId, previousHash);
+    const result = await postOperation(built.operation, runtime, deadline);
+    if (result.accepted) {
+      advanceChainState(previousHash, built.chainHash);
       return;
     }
-    const responseBody = await response.text();
+    advanceChainState(previousHash, result.expected);
-    if (response.status === 400 && responseBody) {
+    logError(new Error('Chain hash resynced to server: ' + result.expected));
-      let failure;
+    if (attempt >= MAX_CHAIN_ATTEMPTS) {
-      try { failure = JSON.parse(responseBody); } catch (error) {
+      throw new Error('Audit API rejected prev_chain_hash ' + attempt + ' times');
-        throw new Error('Audit API returned invalid error JSON: ' + error.message);
     }
-      if (failure.error && failure.error.code === 'PREV_HASH_MISMATCH') {
+    previousHash = readChainState();
-        const match = String(failure.error.message || '').match(
-          /Expected prev_chain_hash "([A-Za-z0-9_-]{43})"/,
-        );
-        if (match) {
-          writeChainState(match[1]);
-          logError(new Error('Chain hash resynced to server: ' + match[1]));
-        }
-      }
-    }
-    throw new Error('Audit API returned HTTP ' + response.status);
-  } finally {
-    clearTimeout(timeout);
   }
 }
 

src/plugins/managed-files.ts

@@ -1,8 +1,7 @@
 import { constants } from 'node:fs';
 import fsp from 'node:fs/promises';
 import type { FileHandle } from 'node:fs/promises';
-
+import { asError, errorMessage, hasCode, MAX_SOURCE_BYTES } from './common.js';
-const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
 
 export interface FileSnapshot {
   readonly contents: string;
@@ -11,18 +10,6 @@ export interface FileSnapshot {
   readonly mode: number;
 }
 
-function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function hasCode(error: unknown, code: string): boolean {
-  return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
-}
-
 export async function readPhysicalFile(
   filePath: string,
   label: string,

src/plugins/managed-installation.ts

@@ -2,6 +2,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { ensurePrivateDirectory, resolvePrivateChildDirectory } from '../runtime-paths.js';
 import type { InstallConfig } from './base.js';
+import { MAX_CONFIG_BYTES, MAX_SECRET_BYTES, sameAgentId, samePath } from './common.js';
 import { generateGuardScript, type GuardScriptOptions } from './guard-template.js';
 import { generateHookScript, type HookScriptOptions } from './hook-template.js';
 import {
@@ -19,9 +20,6 @@ import {
 } from './managed-transaction.js';
 import { parseStrictJsonObject } from './strict-json.js';
 
-const MAX_SECRET_BYTES = 64 * 1024;
-const MAX_CONFIG_BYTES = 512 * 1024;
-
 export interface ManagedRuntimePaths {
   readonly runtimeRoot: string;
   readonly agentDirectory: string;
@@ -79,14 +77,6 @@ interface RuntimeArtifactLocation {
 
 export type { RenameFile };
 
-export function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
 function validateInstallConfig(config: InstallConfig, agentKey: string): void {
   for (const [field, value] of [
     ['agentName', config.agentName],
@@ -146,12 +136,6 @@ export function managedRuntimePaths(
   };
 }
 
-function sameAgentId(left: unknown, right: string): boolean {
-  return typeof left === 'string' && (process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right);
-}
-
 async function validateRuntimeIdentity(
   paths: ManagedRuntimePaths,
   agentKey: string,

src/plugins/managed-runtime-status.ts

@@ -2,12 +2,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { generateGuardScript, type GuardScriptOptions } from './guard-template.js';
 import { generateHookScript, type HookScriptOptions } from './hook-template.js';
+import { MAX_CONFIG_BYTES, MAX_SECRET_BYTES, sameAgentId, samePath } from './common.js';
 import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
-import { samePath } from './managed-installation.js';
 import { parseStrictJsonObject, type JsonObject } from './strict-json.js';
 
-const MAX_SECRET_BYTES = 64 * 1024;
-const MAX_CONFIG_BYTES = 512 * 1024;
 const GUARD_SCRIPT = 'guard.js';
 const AUDIT_SCRIPT = 'hook.js';
 
@@ -22,10 +20,6 @@ export interface ManagedRuntimeStatusOptions {
   readonly auditOptions?: HookScriptOptions;
 }
 
-function sameAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
-}
-
 function requireString(value: unknown, field: string, configPath: string): string {
   if (typeof value !== 'string' || value.trim().length === 0) {
     throw new Error(`Elydora runtime config ${field} is invalid: ${configPath}`);
@@ -117,3 +111,24 @@ export async function managedRuntimeFilesExist(
       options.auditOptions ?? { nativePayload: true },
     );
 }
+
+// Presence-only check: identity mismatch reports false; parse failures still throw.
+export async function managedRuntimePresent(
+  contract: ManagedRuntimeContract,
+  agentKey: string,
+): Promise<boolean> {
+  const agentDirectory = path.dirname(contract.guardPath);
+  const configPath = path.join(agentDirectory, 'config.json');
+  const snapshot = await readPhysicalFile(configPath, 'Elydora runtime config', MAX_CONFIG_BYTES);
+  if (!snapshot) return false;
+  const config = parseStrictJsonObject(snapshot.contents, `Elydora runtime config at ${configPath}`);
+  if (config.agent_name !== agentKey || !sameAgentId(config.agent_id, contract.agentId)) {
+    return false;
+  }
+  const files = await Promise.all([
+    readPhysicalFile(contract.guardPath, 'Elydora guard runtime'),
+    readPhysicalFile(contract.auditPath, 'Elydora audit runtime'),
+    readPhysicalFile(path.join(agentDirectory, 'private.key'), 'Elydora private key', MAX_SECRET_BYTES),
+  ]);
+  return files.every(Boolean);
+}

src/plugins/managed-transaction.ts

@@ -2,14 +2,13 @@ import { randomUUID } from 'node:crypto';
 import fsp from 'node:fs/promises';
 import type { FileHandle } from 'node:fs/promises';
 import path from 'node:path';
+import { asError, errorMessage, hasCode, MAX_SOURCE_BYTES } from './common.js';
 import {
   inspectPhysicalDirectory,
   readPhysicalFile,
   type FileSnapshot,
 } from './managed-files.js';
 
-const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
-
 export interface ManagedChangeSpec {
   readonly filePath: string;
   readonly label: string;
@@ -60,18 +59,6 @@ interface StagedChange {
 
 export type RenameFile = (source: string, destination: string) => Promise<void>;
 
-function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function hasCode(error: unknown, code: string): boolean {
-  return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
-}
-
 function targetKey(filePath: string): string {
   const resolved = path.resolve(filePath);
   return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
@@ -113,16 +100,20 @@ export async function prepareManagedFileChange(
   };
 }
 
-async function assertUnchanged(change: ManagedFileChange, operationName: string): Promise<void> {
+function sameSnapshot(current: FileSnapshot | undefined, original: FileSnapshot | undefined): boolean {
-  const current = await readPhysicalFile(change.filePath, change.label, change.maximumBytes);
+  if (!current || !original) return !current && !original;
-  if ((!current && change.original)
+  return current.contents === original.contents
-    || (current && !change.original)
+    && current.device === original.device
-    || (current && change.original && (
+    && current.inode === original.inode;
-      current.contents !== change.original.contents
+}
-      || current.device !== change.original.device
+
-      || current.inode !== change.original.inode
+async function assertUnchanged(
-    ))) {
+  target: ManagedFilePrecondition,
-    throw new Error(`${change.label} changed during ${operationName}: ${change.filePath}`);
+  operationName: string,
+): Promise<void> {
+  const current = await readPhysicalFile(target.filePath, target.label, target.maximumBytes);
+  if (!sameSnapshot(current, target.original)) {
+    throw new Error(`${target.label} changed during ${operationName}: ${target.filePath}`);
   }
 }
 
@@ -131,20 +122,7 @@ async function assertPreconditions(
   operationName: string,
 ): Promise<void> {
   for (const condition of transaction.preconditions ?? []) {
-    const current = await readPhysicalFile(
+    await assertUnchanged(condition, operationName);
-      condition.filePath,
-      condition.label,
-      condition.maximumBytes,
-    );
-    if ((!current && condition.original)
-      || (current && !condition.original)
-      || (current && condition.original && (
-        current.contents !== condition.original.contents
-        || current.device !== condition.original.device
-        || current.inode !== condition.original.inode
-      ))) {
-      throw new Error(`${condition.label} changed during ${operationName}: ${condition.filePath}`);
-    }
   }
 }
 
@@ -285,11 +263,7 @@ async function assertCommittedUnchanged(staged: StagedChange): Promise<void> {
     }
     return;
   }
-  const committed = staged.committedSnapshot;
+  if (!current || !sameSnapshot(current, staged.committedSnapshot)) {
-  if (!current || !committed
-    || current.contents !== committed.contents
-    || current.device !== committed.device
-    || current.inode !== committed.inode) {
     throw new Error(
       `${staged.change.label} changed during transaction recovery: ${staged.change.filePath}`,
     );

src/plugins/opencode-contract.ts

@@ -1,7 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import type { HookScriptOptions } from './hook-template.js';
-import { samePath } from './managed-installation.js';
+import { samePath } from './common.js';
 import { parseStrictJsonObject } from './strict-json.js';
 
 export const AGENT_KEY = 'opencode';

src/plugins/shell-command.ts

@@ -0,0 +1,128 @@
+import path from 'node:path';
+import { samePath } from './common.js';
+
+export interface ParsedArgument {
+  readonly value: string;
+  readonly next: number;
+}
+
+export type CommandParts = readonly [executable: string, script: string];
+
+const POSIX_APOSTROPHE = `'"'"'`;
+const POWERSHELL_EXIT_SUFFIX = '; exit $LASTEXITCODE';
+const ENCODED_COMMAND_FLAGS = '-NoLogo -NoProfile -NonInteractive -EncodedCommand';
+
+export function quotePosix(value: string): string {
+  return `'${value.replaceAll("'", POSIX_APOSTROPHE)}'`;
+}
+
+export function quotePowerShell(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+export function windowsPowerShellPath(): string {
+  const configuredRoot = process.platform === 'win32' ? process.env.SystemRoot : undefined;
+  const systemRoot = configuredRoot
+    && path.win32.isAbsolute(configuredRoot)
+    && !/["%\r\n]/.test(configuredRoot)
+    ? configuredRoot
+    : 'C:\\Windows';
+  return path.win32.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+}
+
+export function posixSource(scriptPath: string): string {
+  return `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`;
+}
+
+export function powerShellSource(scriptPath: string): string {
+  return `& ${quotePowerShell(process.execPath)} ${quotePowerShell(scriptPath)}${POWERSHELL_EXIT_SUFFIX}`;
+}
+
+export function encodePowerShellSource(scriptPath: string): string {
+  return Buffer.from(powerShellSource(scriptPath), 'utf16le').toString('base64');
+}
+
+export function encodedWindowsCommand(scriptPath: string): string {
+  return `"${windowsPowerShellPath()}" ${ENCODED_COMMAND_FLAGS} ${encodePowerShellSource(scriptPath)}`;
+}
+
+// The running executable, or a binary named node (node.exe case-insensitive on Windows).
+export function isNodeExecutable(filePath: string): boolean {
+  if (samePath(filePath, process.execPath)) return true;
+  const basename = path.basename(filePath);
+  return basename === 'node' || basename.toLowerCase() === 'node.exe';
+}
+
+export function isPowerShellExecutable(filePath: string): boolean {
+  return path.win32.isAbsolute(filePath)
+    && path.win32.basename(filePath).toLowerCase() === 'powershell.exe';
+}
+
+export function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
+  if (command[start] !== "'") return undefined;
+  let value = '';
+  for (let index = start + 1; index < command.length;) {
+    if (command.startsWith(POSIX_APOSTROPHE, index)) {
+      value += "'";
+      index += POSIX_APOSTROPHE.length;
+      continue;
+    }
+    if (command[index] === "'") return { value, next: index + 1 };
+    value += command[index];
+    index += 1;
+  }
+  return undefined;
+}
+
+export function parsePosixCommand(command: string): CommandParts | undefined {
+  const executable = readPosixArgument(command, 0);
+  if (!executable || command[executable.next] !== ' ') return undefined;
+  const script = readPosixArgument(command, executable.next + 1);
+  if (!script || script.next !== command.length) return undefined;
+  return [executable.value, script.value];
+}
+
+function readPowerShellArgument(command: string, start: number): ParsedArgument | undefined {
+  if (command[start] !== "'") return undefined;
+  let value = '';
+  for (let index = start + 1; index < command.length; index += 1) {
+    if (command[index] !== "'") {
+      value += command[index];
+      continue;
+    }
+    if (command[index + 1] === "'") {
+      value += "'";
+      index += 1;
+      continue;
+    }
+    return { value, next: index + 1 };
+  }
+  return undefined;
+}
+
+export function parsePowerShellSource(source: string): CommandParts | undefined {
+  if (!source.startsWith('& ')) return undefined;
+  const executable = readPowerShellArgument(source, 2);
+  if (!executable || source[executable.next] !== ' ') return undefined;
+  const script = readPowerShellArgument(source, executable.next + 1);
+  if (!script || source.slice(script.next) !== POWERSHELL_EXIT_SUFFIX) return undefined;
+  return [executable.value, script.value];
+}
+
+export function decodePowerShellSource(encoded: string): CommandParts | undefined {
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) return undefined;
+  const buffer = Buffer.from(encoded, 'base64');
+  if (buffer.toString('base64') !== encoded || buffer.length % 2 !== 0) return undefined;
+  return parsePowerShellSource(buffer.toString('utf16le'));
+}
+
+export function parseEncodedWindowsCommand(command: string): CommandParts | undefined {
+  const match = /^"([^"\r\n]+)" -NoLogo -NoProfile -NonInteractive -EncodedCommand ([A-Za-z0-9+/]+={0,2})$/.exec(command);
+  if (!match || !isPowerShellExecutable(match[1])) return undefined;
+  return decodePowerShellSource(match[2]);
+}
+
+export function parseLegacyWindowsCommand(command: string): CommandParts | undefined {
+  const match = /^"([^"\r\n]+)" "([^"\r\n]+)"$/.exec(command);
+  return match ? [match[1], match[2]] : undefined;
+}

src/types.ts

@@ -1,7 +1,3 @@
-// ---------------------------------------------------------------------------
-// Enums / status types
-// ---------------------------------------------------------------------------
-
 export type AgentStatus = 'active' | 'frozen' | 'revoked';
 export type KeyStatus = 'active' | 'retired' | 'revoked';
 export type ExportStatus = 'queued' | 'running' | 'done' | 'failed';
@@ -37,13 +33,16 @@ export type AdminAction =
   | 'agent.register' | 'agent.update' | 'agent.freeze' | 'agent.unfreeze'
   | 'agent.revoke' | 'agent.delete' | 'key.revoke' | 'export.create'
   | 'org.create' | 'org.update'
-  | 'member.invite' | 'member.remove' | 'member.role_change'
+  | 'member.invite' | 'invitation.cancel' | 'member.remove' | 'member.role_change'
-  | 'agent.assign' | 'agent.unassign';
+  | 'agent.assign' | 'agent.unassign'
+  | 'webhook.register' | 'webhook.delete';
 export type ErrorCode =
   | 'INVALID_SIGNATURE'
   | 'UNKNOWN_AGENT'
   | 'KEY_REVOKED'
+  | 'KEY_RETIRED'
   | 'AGENT_FROZEN'
+  | 'AGENT_REVOKED'
   | 'TTL_EXPIRED'
   | 'REPLAY_DETECTED'
   | 'PREV_HASH_MISMATCH'
@@ -55,10 +54,6 @@ export type ErrorCode =
   | 'NOT_FOUND'
   | 'VALIDATION_ERROR';
 
-// ---------------------------------------------------------------------------
-// Entities
-// ---------------------------------------------------------------------------
-
 export interface Agent {
   readonly agent_id: string;
   readonly org_id: string;
@@ -168,10 +163,6 @@ export interface Export {
   readonly completed_at: number | null;
 }
 
-// ---------------------------------------------------------------------------
-// Protocol types
-// ---------------------------------------------------------------------------
-
 export interface EOR {
   readonly op_version: '1.0';
   readonly operation_id: string;
@@ -205,10 +196,6 @@ export interface EAR {
   readonly elydora_signature: string;
 }
 
-// ---------------------------------------------------------------------------
-// API request/response types
-// ---------------------------------------------------------------------------
-
 export interface RegisterAgentRequest {
   readonly agent_id: string;
   readonly integration_type: IntegrationType;
@@ -238,6 +225,7 @@ export interface SubmitOperationResponse {
 export interface GetOperationResponse {
   readonly operation: Operation;
   readonly receipt?: Receipt;
+  readonly payload?: Record<string, unknown> | string;
 }
 
 export interface VerifyOperationResponse {
@@ -327,15 +315,22 @@ export interface DeleteAgentResponse {
   readonly deleted: boolean;
 }
 
+export interface Webhook {
+  readonly webhook_id: string;
+  readonly org_id: string;
+  readonly endpoint_url: string;
+  readonly events: string[];
+  readonly status: 'active' | 'disabled';
+  readonly created_at: number;
+  readonly updated_at: number;
+}
+
 export interface ListWebhooksResponse {
-  readonly webhooks: unknown[];
+  readonly webhooks: Webhook[];
 }
 
 export interface RegisterWebhookResponse {
-  readonly webhook_id: string;
+  readonly webhook: Webhook;
-  readonly endpoint_url: string;
-  readonly events: string[];
-  readonly created_at: number;
 }
 
 export interface ListMembersResponse {
@@ -357,16 +352,26 @@ export interface DeepHealthResponse {
   readonly status: 'healthy' | 'degraded';
   readonly version: string;
   readonly protocol_version: string;
+  readonly capabilities: Record<string, string>;
   readonly timestamp: number;
   readonly dependencies: {
-    readonly d1: { status: 'ok' | 'failed'; latency_ms: number; error?: string };
+    readonly d1: { status: 'ok' | 'failed'; latency_ms: number };
-    readonly r2: { status: 'ok' | 'failed'; latency_ms: number; error?: string };
+    readonly auth_storage: { status: 'ok' | 'failed'; latency_ms: number; contract_phase?: 'expand' | 'contract' };
-    readonly kv: { status: 'ok' | 'failed'; latency_ms: number; error?: string };
+    readonly r2: { status: 'ok' | 'failed'; latency_ms: number };
+    readonly kv: { status: 'ok' | 'failed'; latency_ms: number };
   };
 }
 
 export interface GetMeResponse {
-  readonly user: User;
+  readonly user: Omit<User, 'org_id'> & {
+    readonly org_id: string | null;
+    readonly onboarding_completed: boolean;
+  };
+  readonly current_organization: {
+    readonly org_id: string | null;
+    readonly ba_org_id: string | null;
+    readonly role: RbacRole;
+  };
 }
 
 export interface IssueApiTokenResponse {
@@ -385,6 +390,7 @@ export interface HealthResponse {
   readonly status: string;
   readonly version: string;
   readonly protocol_version: string;
+  readonly capabilities: Record<string, string>;
   readonly timestamp: number;
 }
 
@@ -421,10 +427,6 @@ export interface ErrorResponse {
   };
 }
 
-// ---------------------------------------------------------------------------
-// Client configuration
-// ---------------------------------------------------------------------------
-
 export interface ElydoraClientConfig {
   readonly orgId: string;
   readonly agentId: string;

src/utils.ts

@@ -1,17 +1,10 @@
 import crypto from 'node:crypto';
 
-/**
+// UUIDv7 (RFC 9562): 48-bit ms timestamp, version 7, variant 10, 74 random bits
- * Generate a UUIDv7 (time-ordered UUID per RFC 9562).
- *
- * Layout (128 bits):
- *   48-bit Unix timestamp (ms) | 4-bit version (7) | 12-bit rand_a
- *   2-bit variant (10) | 62-bit rand_b
- */
 export function uuidv7(): string {
   const now = Date.now();
   const random = crypto.randomBytes(10);
 
-  // Bytes 0-5: 48-bit timestamp (ms)
   const bytes = Buffer.alloc(16);
   bytes[0] = (now / 2 ** 40) & 0xff;
   bytes[1] = (now / 2 ** 32) & 0xff;
@@ -20,11 +13,9 @@ export function uuidv7(): string {
   bytes[4] = (now / 2 ** 8) & 0xff;
   bytes[5] = now & 0xff;
 
-  // Bytes 6-7: version (0111) + 12 bits random
   bytes[6] = 0x70 | (random[0]! & 0x0f);
   bytes[7] = random[1]!;
 
-  // Bytes 8-15: variant (10) + 62 bits random
   bytes[8] = 0x80 | (random[2]! & 0x3f);
   bytes[9] = random[3]!;
   bytes[10] = random[4]!;
@@ -44,25 +35,16 @@ export function uuidv7(): string {
   );
 }
 
-/**
- * Generate a random nonce: 16 random bytes, base64url encoded.
- */
 export function generateNonce(): string {
   const bytes = crypto.randomBytes(16);
   return base64urlEncode(bytes);
 }
 
-/**
- * Encode a Buffer or Uint8Array to base64url (no padding, RFC 4648 section 5).
- */
 export function base64urlEncode(data: Buffer | Uint8Array): string {
   const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
   return buf.toString('base64url');
 }
 
-/**
- * Decode a base64url string (no padding) to a Buffer.
- */
 export function base64urlDecode(input: string): Buffer {
   return Buffer.from(input, 'base64url');
 }

test/claudecode-runtime.test.mjs

@@ -1,5 +1,7 @@
 import assert from 'node:assert/strict';
+import { existsSync, utimesSync, writeFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+import http from 'node:http';
 import path from 'node:path';
 import test from 'node:test';
 import {
@@ -143,3 +145,196 @@ test('Claude runtime failures stay observable while guard and audit delivery rem
     await fixture.close();
   }
 });
+
+function mismatchServer(respond) {
+  const submissions = [];
+  const server = http.createServer((request, response) => {
+    let raw = '';
+    request.on('data', (chunk) => { raw += chunk; });
+    request.on('end', () => {
+      if (request.url !== '/v1/operations') {
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ agent: { status: 'active' } }));
+        return;
+      }
+      submissions.push(JSON.parse(raw));
+      const reply = respond(submissions) ?? mismatch(String(submissions.length).padStart(43, 'A'), 'x');
+      const send = () => {
+        response.writeHead(reply.status, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify(reply.body));
+      };
+      if (api.slow) setTimeout(send, 2600); else send();
+    });
+  });
+  const api = { submissions, slow: false };
+  return new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve(Object.assign(api, {
+    baseUrl: 'http://127.0.0.1:' + server.address().port,
+    close: () => new Promise((done) => { server.closeAllConnections?.(); server.close(done); }),
+  }))));
+}
+
+function mismatch(expected, actual) {
+  return {
+    status: 400,
+    body: { error: { code: 'PREV_HASH_MISMATCH', message: 'Expected prev_chain_hash "' + expected + '", got "' + actual + '".' } },
+  };
+}
+
+test('Claude audit retries a rejected prev_chain_hash with the server value', async () => {
+  const expected = 'Rxlf4j36C3KvIQ3hWuOkX698BR5iDypUFuB70JjEuvM';
+  const api = await mismatchServer((submissions) => (submissions.length === 1
+    ? mismatch(expected, submissions[0].prev_chain_hash)
+    : { status: 202, body: { receipt: { seq_no: 2 } } }));
+  const fixture = await createFixture({ baseUrl: api.baseUrl });
+  try {
+    assert.equal((await fixture.install()).code, 0);
+    const { settings } = await readSettings(fixture.settingsPath);
+    const audit = managedHandler(settings, 'PostToolUse');
+    const result = await runClaudeHook(
+      audit,
+      JSON.stringify(officialPayload('PostToolUse', { tool_response: { stdout: 'ok' } })),
+      fixture,
+    );
+    assert.equal(result.code, 0, result.stderr);
+    assert.equal(api.submissions.length, 2);
+    assert.equal(api.submissions[1].prev_chain_hash, expected);
+    assert.notEqual(api.submissions[1].operation_id, api.submissions[0].operation_id);
+    assert.notEqual(api.submissions[1].nonce, api.submissions[0].nonce);
+    const state = JSON.parse(await readFile(path.join(fixture.agentDir, 'chain-state.json'), 'utf-8'));
+    assert.equal(state.prev_chain_hash, api.submissions[1].chain_hash);
+    assert.match(await readFile(path.join(fixture.agentDir, 'error.log'), 'utf-8'), /resynced to server: Rxlf/);
+  } finally {
+    await fixture.close();
+    await api.close();
+  }
+});
+
+test('Claude audit stops after five rejected prev_chain_hash attempts', async () => {
+  const api = await mismatchServer((submissions) => (
+    mismatch(String(submissions.length).padStart(43, 'A'), submissions.at(-1).prev_chain_hash)
+  ));
+  const fixture = await createFixture({ baseUrl: api.baseUrl });
+  try {
+    assert.equal((await fixture.install()).code, 0);
+    const { settings } = await readSettings(fixture.settingsPath);
+    const audit = managedHandler(settings, 'PostToolUse');
+    const result = await runClaudeHook(
+      audit,
+      JSON.stringify(officialPayload('PostToolUse', { tool_response: { stdout: 'ok' } })),
+      fixture,
+    );
+    assert.equal(result.code, 0, result.stderr);
+    assert.equal(api.submissions.length, 5);
+    assert.equal(api.submissions[4].prev_chain_hash, '4'.padStart(43, 'A'));
+    assert.match(await readFile(path.join(fixture.agentDir, 'error.log'), 'utf-8'), /rejected prev_chain_hash 5 times/);
+  } finally {
+    await fixture.close();
+    await api.close();
+  }
+});
+
+test('Claude audit stops retrying when the submit budget is spent', async () => {
+  const api = await mismatchServer(() => null);
+  api.slow = true;
+  const fixture = await createFixture({ baseUrl: api.baseUrl });
+  try {
+    assert.equal((await fixture.install()).code, 0);
+    const { settings } = await readSettings(fixture.settingsPath);
+    const audit = managedHandler(settings, 'PostToolUse');
+    const started = Date.now();
+    const result = await runClaudeHook(
+      audit,
+      JSON.stringify(officialPayload('PostToolUse', { tool_response: { stdout: 'ok' } })),
+      fixture,
+    );
+    const elapsed = Date.now() - started;
+    assert.equal(result.code, 0, result.stderr);
+    assert.ok(elapsed < 7000, `hook ran ${elapsed}ms`);
+    assert.ok(api.submissions.length >= 2 && api.submissions.length <= 3, `${api.submissions.length} submissions`);
+    assert.match(await readFile(path.join(fixture.agentDir, 'error.log'), 'utf-8'), /aborted|retry budget exhausted/i);
+  } finally {
+    await fixture.close();
+    await api.close();
+  }
+});
+
+test('Claude audit does not regress a chain head advanced by a concurrent hook', async () => {
+  const newerHead = 'B'.repeat(43);
+  let statePath;
+  const api = await mismatchServer(() => {
+    writeFileSync(statePath, JSON.stringify({ prev_chain_hash: newerHead }), { mode: 0o600 });
+    return { status: 202, body: { receipt: { seq_no: 1 } } };
+  });
+  const fixture = await createFixture({ baseUrl: api.baseUrl });
+  try {
+    assert.equal((await fixture.install()).code, 0);
+    statePath = path.join(fixture.agentDir, 'chain-state.json');
+    const { settings } = await readSettings(fixture.settingsPath);
+    const audit = managedHandler(settings, 'PostToolUse');
+    const result = await runClaudeHook(
+      audit,
+      JSON.stringify(officialPayload('PostToolUse', { tool_response: { stdout: 'ok' } })),
+      fixture,
+    );
+    assert.equal(result.code, 0, result.stderr);
+    assert.equal(api.submissions[0].prev_chain_hash, 'A'.repeat(43));
+    const state = JSON.parse(await readFile(statePath, 'utf-8'));
+    assert.equal(state.prev_chain_hash, newerHead);
+  } finally {
+    await fixture.close();
+    await api.close();
+  }
+});
+
+test('Claude audit clears a stale chain-state lock and proceeds', async () => {
+  const api = await mismatchServer(() => ({ status: 202, body: { receipt: { seq_no: 1 } } }));
+  const fixture = await createFixture({ baseUrl: api.baseUrl });
+  try {
+    assert.equal((await fixture.install()).code, 0);
+    const lockPath = path.join(fixture.agentDir, 'chain-state.json.lock');
+    writeFileSync(lockPath, '', { mode: 0o600 });
+    const stale = new Date(Date.now() - 10_000);
+    utimesSync(lockPath, stale, stale);
+    const { settings } = await readSettings(fixture.settingsPath);
+    const audit = managedHandler(settings, 'PostToolUse');
+    const result = await runClaudeHook(
+      audit,
+      JSON.stringify(officialPayload('PostToolUse', { tool_response: { stdout: 'ok' } })),
+      fixture,
+    );
+    assert.equal(result.code, 0, result.stderr);
+    assert.equal(api.submissions.length, 1);
+    assert.equal(existsSync(lockPath), false);
+    const state = JSON.parse(await readFile(path.join(fixture.agentDir, 'chain-state.json'), 'utf-8'));
+    assert.equal(state.prev_chain_hash, api.submissions[0].chain_hash);
+  } finally {
+    await fixture.close();
+    await api.close();
+  }
+});
+
+test('Claude audit does not reclaim a chain-state lock whose owner is alive', async () => {
+  const api = await mismatchServer(() => ({ status: 202, body: { receipt: { seq_no: 1 } } }));
+  const fixture = await createFixture({ baseUrl: api.baseUrl });
+  try {
+    assert.equal((await fixture.install()).code, 0);
+    const lockPath = path.join(fixture.agentDir, 'chain-state.json.lock');
+    writeFileSync(lockPath, String(process.pid), { mode: 0o600 });
+    const stale = new Date(Date.now() - 10_000);
+    utimesSync(lockPath, stale, stale);
+    const { settings } = await readSettings(fixture.settingsPath);
+    const audit = managedHandler(settings, 'PostToolUse');
+    const result = await runClaudeHook(
+      audit,
+      JSON.stringify(officialPayload('PostToolUse', { tool_response: { stdout: 'ok' } })),
+      fixture,
+    );
+    assert.equal(result.code, 0, result.stderr);
+    assert.equal(api.submissions.length, 1);
+    assert.equal(existsSync(lockPath), true);
+    assert.match(await readFile(path.join(fixture.agentDir, 'error.log'), 'utf-8'), /lock timed out/);
+  } finally {
+    await fixture.close();
+    await api.close();
+  }
+});

test/guard-template.test.mjs

@@ -6,7 +6,7 @@ import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
 
-import { generateGuardScript } from '../dist/plugins/hook-template.js';
+import { generateGuardScript } from '../dist/plugins/guard-template.js';
 
 const AGENT_ID = 'agent-1';